codesight - Moses Yebei

Technical Briefing: codesight

Overview

codesight is an AI context generator that reduces token waste in AI-assisted development workflows. It analyzes codebases and generates structured knowledge bases, working with Claude Code, Cursor, Copilot, Codex, and similar tools. The repository contains 438 files across TypeScript, JSON, Python, and other languages, with 149 tests and 14 MCP tools. Primary entry point is src/index.ts.

What It Does

codesight generates a persistent .codesight/wiki/ knowledge base from AST analysis, avoiding LLM calls entirely. It supports 30+ framework detectors and 14 ORM parsers across TypeScript, Python, Go, Rust, Java, PHP, and other languages. TypeScript projects receive full AST precision; other languages use regex-based detection. Commands include --wiki, --mcp, --blast, and --profile for tool-specific optimization.

How It Is Wired

Execution flows through src/index.ts which orchestrates the pipeline. The import graph contains 84 internal modules with 192 edges and 2 circular dependencies. Key modules:

src/types (Ca: 49, Ce: 0) — hub module with 49 dependents; stability risk
src/core (Ca: 3, Ce: 19, instability: 0.86) — high churn point
src/scanner (Ca: 17, Ce: 1, instability: 0.06) — scanner module
src/mcp-server (Ca: 0, Ce: 17, instability: 1) — MCP tool server

Oversized files exceed 1,190 lines (src/scanner.ts, src/detectors/routes.ts, src/detectors/schema.ts). Four files have max indentation depth of 8 (src/ast/extract-python.ts, plugins/ast/python/src/lib.rs, plugins/ast/golang/main.go). Import cycles exist between src/plugins/skills/index.ts and src/plugins/skills/formatter.ts. Six duplicated 6-line blocks appear across 22 files, primarily in plugin runtimes.

How To Use It

Install via npx codesight in any project root. No configuration or API keys required. Commands documented in README:

npx codesight --wiki                       # Generate wiki knowledge base
npx codesight --mcp                        # Start as MCP server (14 tools)
npx codesight --blast src/lib/db.ts        # Show blast radius for a file
npx codesight --profile claude-code        # Generate optimized config

Setup requires no environment variables or keys per the README. The --native-ast flag enables AST plugins for additional languages (see docs/wasm-plugins.md).

Code Health & Issues

Findings from static analysis of 87 code files:

HIGH — Pin third-party GitHub Actions to commit SHA (.github/workflows): dtolnay/rust-toolchain@stable, swatinem/rust-cache@v2, pnpm/action-setup@v4, softprops/action-gh-release@v2 all use version tags that can shift. Fix: replace @vN with 40-character commit SHAs.

HIGH — Workflows push to default branch without pull request (.github/workflows/codesight.yml): git push lands on the deploying branch with no test gate. Fix: push to a bot branch and open a pull request, or restrict to tag refs.

MEDIUM — Declare least-privilege permissions for GITHUB_TOKEN (2 workflows declare no permissions): token inherits repository default, enabling push or release operations from within CI. Fix: add permissions: contents: read at workflow top and widen per job as needed.

MEDIUM — Enable Dependabot or Renovate (5 manifests, no update bot): unpatched advisories until manual audit. Fix: commit .github/dependabot.yml covering package ecosystems and github-actions.

MEDIUM — Pin container base image by digest (tests/fixtures/repotype-microservices-docker/auth/Dockerfile): node:20 is mutable. Fix: use image:tag@sha256:<digest> and enable Dependabot Docker ecosystem.

MEDIUM — Gate pull requests on dependency vulnerability scan (no dependency scan in CI): known-vulnerable packages may reach build uncaught. Fix: add dependency-review-action on pull_request or osv-scanner on push and schedule.

MEDIUM — Set persist-credentials: false on checkout (.github/workflows/ast-plugins.yml): token remains in .git/config for later steps. Fix: add with: persist-credentials: false and pass explicit token only to pushing step.

MEDIUM — Add non-root USER to image (tests/fixtures/repotype-microservices-docker/auth/Dockerfile): no USER directive; root process against every mounted volume. Fix: create unprivileged user, chown needed paths, end Dockerfile with USER.

LOW — Set timeout-minutes on workflow jobs (4 jobs declare no timeout): wedged step runs to six-hour platform default. Fix: add realistic timeout-minutes per job.

LOW — Add repository convention files: missing .editorconfig, .gitattributes, formatter config. Fix: add .editorconfig, .gitattributes with text=auto eol=lf, and formatter configuration.

The Bottom Line

codesight delivers practical token savings by generating structured codebase context from AST analysis rather than LLM inference. The tool works immediately via npx across 25+ OSS projects and 14 languages. However, the codebase shows stability risks from its own hub module (src/types), oversized files exceeding 1,190 lines, import cycles in plugin skills, and Action pinning gaps that should be addressed before recommending adoption in production CI pipelines. Teams comfortable with TypeScript tooling and aware of the measured health findings will see the most value.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

438 files

TypeScript212
JSON79
Python26
Markdown23
YAML13
TOML6

ReactDjangoFastAPIExpressDockerKubernetesTerraform

Module dependencies

The 10 most depended-upon modules of 84, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_types["types"] n1_src_scanner["scanner"] n2_src_ast_loader["loader"] n3_src_plugins_terraform_types["types"] n4_src_plugins_githooks_types["types"] n5_src_detectors_routes["routes"] n6_src_plugins_cicd_types["types"] n7_src_core["core"] n8_src_detectors_schema["schema"] n9_src_detectors_components["components"] n7_src_core --> n1_src_scanner n7_src_core --> n5_src_detectors_routes n7_src_core --> n8_src_detectors_schema n7_src_core --> n9_src_detectors_components n7_src_core --> n0_src_types n9_src_detectors_components --> n1_src_scanner n9_src_detectors_components --> n2_src_ast_loader n9_src_detectors_components --> n0_src_types n5_src_detectors_routes --> n1_src_scanner n5_src_detectors_routes --> n2_src_ast_loader n5_src_detectors_routes --> n0_src_types n8_src_detectors_schema --> n1_src_scanner n8_src_detectors_schema --> n2_src_ast_loader n8_src_detectors_schema --> n0_src_types n1_src_scanner --> n0_src_types

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium6

low2

Pin third-party GitHub Actions to a commit SHAhigh4 occurrences

.github/workflows

dtolnay/rust-toolchain@stable, swatinem/rust-cache@v2, pnpm/action-setup@v4, softprops/action-gh-release@v2

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Open a pull request instead of pushing to the default branchhigh

.github/workflows/codesight.yml

git push

Automated commits land on the branch that deploys, with no test having run against the result.

Fix: Push to a bot branch and open a pull request, or restrict the push to a tag ref.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/test.yml

2 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

5 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

tests/fixtures/repotype-microservices-docker/auth/Dockerfile

node:20

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ast-plugins.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

tests/fixtures/repotype-microservices-docker/auth/Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/ast-plugins.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.