Repository Intelligence

v0.11.2 — local-first repository intelligence and living documentation for TypeScript/JavaScript, Python, Java, C#, and Go.

Repository Intelligence is a VS Code extension and CLI that indexes source code locally, builds an evidence-backed repository model, tracks code changes, and maintains documentation inside the repository. AI prose is optional; when OpenAI is enabled, only selected/redacted context is sent using the user's API key.

Hybrid retrieval

Repository Q&A and documentation context now use deterministic hybrid retrieval with Reciprocal Rank Fusion (RRF). Independent channels rank exact symbol/path matches, SQLite FTS lexical hits, graph-proximate entities, semantic-artifact evidence, and entities changed in the latest indexed ChangeSet. The fused ranking is then bounded by the existing context budget and completeness rules.

The current semantic channel is local and deterministic; it uses repository semantic artifacts rather than vector embeddings. A future embedding/vector channel can be added as another rank source without replacing the fusion contract.

Analysis trust model

Repository Intelligence now persists unresolved relationship gaps and completeness summaries alongside graph edges. Consumers can distinguish a proven absence from a lower-bound graph with dynamic, external, ambiguous, or unsupported relationships. TypeScript additionally emits deeper compiler-backed/runtime-aware relationship facts for overrides, constructor injection, Nest-style routes/providers, middleware/handlers, event subscriptions/publications, persistence/query calls, and captured property reads/writes. See COMPLETENESS_TRACKING.md and TYPESCRIPT_RELATIONSHIPS.md.

What the current foundation implements

• Deterministic repository IR for files, symbols, relationships, semantic artifacts, and documentation dependencies.
• Explicit dependency-DAG analysis runtime with validated phase dependencies, deterministic topological execution, and downstream invalidation closure.
• Structural indexing now uses one DAG for full and incremental runs: project discovery → invalidation planning → TypeScript analysis / polyglot analysis → snapshot assembly.
• Derived intelligence also runs as a DAG: framework/API facts + execution flows + graph communities → semantic understanding → repository capabilities, with security analysis independent.
• Structured API intelligence for FastAPI, Express, NestJS, and Next.js, including routes, handlers, middleware/dependencies, authentication hints, request/response types where statically available, and evidence.
• First-class modules/capabilities with owned files/symbols, API surface, cross-module dependencies, tests, and evidence.
• First-class graph-based component/community detection that uses weighted repository relationships to infer architectural groupings while preserving workspace/package boundaries as separate evidence.
• Industrial documentation families stored in the repository: architecture, API, modules/capabilities, security, and developer onboarding.
• Human-aware managed Markdown sections: machine prose is replaceable while an explicit human-maintained block is preserved across regeneration.
• Evidence-scoped generation and validation so generated claims remain tied to known source evidence.
• Local post-commit/pre-push stale-document regeneration through the Git hook workflow. Save-time regeneration remains optional and is disabled by default.
• CI freshness validation only. GitHub Actions never generate or commit documentation.
• Local append-only repository history in .repo-intel/history.jsonl recording successful index changes against Git HEAD.
• Incremental file capture plus dependency-scoped TypeScript/JavaScript re-analysis. Changed import-connected components are refreshed while disconnected compiler projects can be reused; compiler-config changes conservatively trigger full structural analysis.
• Normalized local sql.js persistence with row-level updates for changed files/symbols/edges and full-text search maintenance. sql.js still exports the final SQLite image atomically.
• Project-aware TypeScript discovery for nested tsconfig/jsconfig files, repository-local relative extends, project-reference metadata, and nearest-config file ownership.

Documentation produced

The managed documentation is repository-native and can include:

docs/
  architecture.md
  api.md
  modules.md
  security.md
  onboarding.md

Architecture uses stable sections for overview, system context, components, dependencies, runtime flows, deployment, and detected subsystems. API documentation includes an API overview plus one managed section per detected endpoint. Module documentation includes an overview plus one section per detected capability/module.

When a new module or endpoint is added, the repository diff marks only relevant documentation sections stale. The recommended workflow regenerates them locally during the pre-push check after the developer has committed code, so the resulting Markdown can be reviewed and committed explicitly.

Inside each generated section, Repository Intelligence owns a generated sub-block and preserves a human-maintained sub-block. Human notes therefore survive later regenerations rather than being treated as disposable generated prose.

Privacy model

Repository indexing and persistence are local. Repository source is not uploaded to a central indexing service. With AI enabled, Repository Intelligence builds a bounded evidence packet, redacts sensitive material, and sends only that selected context directly to the configured provider.

OpenAI is available as a BYOK hosted provider. API keys are stored in VS Code SecretStorage. Offline evidence mode and local Ollama/compatible-provider adapters are also supported.

VS Code

Requires desktop VS Code 1.95+ and a trusted filesystem workspace.

Primary commands:

• Repository Intelligence: Open Dashboard
• Repository Intelligence: Ask Question
• Repository Intelligence: Update Documentation
• Repository Intelligence: Re-index Repository
• Repository Intelligence: Generate Architecture Document
• Repository Intelligence: Generate API Document
• Repository Intelligence: Generate Modules Document
• Repository Intelligence: Generate Security Document
• Repository Intelligence: Generate Developer Onboarding Document
• Repository Intelligence: Check Documentation Freshness
• Repository Intelligence: Enable Pre-Push Check

Relevant settings:

{
  "repoIntel.provider": "openai",
  "repoIntel.model": "YOUR_OPENAI_MODEL",
  "repoIntel.contextChars": 24000,
  "repoIntel.autoUpdateDocumentation": false,
  "repoIntel.prePushPolicy": "auto-update"
}

Run Repository Intelligence: Configure Provider / Set Provider API Key from the extension flow to store the API key securely rather than putting it in source or settings.

CLI

After building:

node dist/cli.js index --root /path/to/repository
node dist/cli.js search "authentication" --root /path/to/repository
node dist/cli.js ask "How does authentication work?" --root /path/to/repository
node dist/cli.js architecture --root /path/to/repository
node dist/cli.js api --root /path/to/repository
node dist/cli.js modules --root /path/to/repository
node dist/cli.js security --root /path/to/repository
node dist/cli.js onboarding --root /path/to/repository

For OpenAI CLI use, provide the configured provider/model and RI_API_KEY; do not commit secrets.

Language and framework depth

TypeScript/JavaScript remains the reference analyzer because it uses the TypeScript compiler API. Compiler programs are now separated by captured nested config boundaries instead of treating the repository as one root project, and repository-local relative extends chains are inherited. Python, Java, C#, and Go still use conservative non-executing structural analyzers. Framework/API intelligence is explicitly implemented for FastAPI, Express, NestJS, and Next.js.

The tool never executes repository code, compiler plugins, build scripts, or dependency initialization while indexing.

Scale and incremental behavior

The scanner caps remain 10,000 source files, 100 MiB captured source, and 2 MiB per file. Ordinary incremental updates reuse unchanged source bytes, re-analyze the changed TypeScript import-connected component instead of the whole repository, reuse disconnected project graph state, and update changed persistence rows. TypeScript compiler-config changes intentionally fall back to full structural analysis because they can change global resolution semantics. 200k LOC remains an engineering target, not a benchmark claim; production-scale benchmarking and longer-lived compiler-program reuse are still required.

Build and test

Node.js 20.11+ is required.

npm ci
npm run check
npm test
npm run build
npm run package

npm run package creates repository-intelligence-0.11.2.vsix locally.

Test status for this implementation

The full verification suite passes on Node.js 20 and Node.js 24. npm test runs TypeScript checking, builds the extension, and executes all Node test files. Run npm ci && npm test before merging or packaging.

Known boundaries

• Express/NestJS/FastAPI/Next.js extraction is static and conservative; dynamic route construction, Next.js rewrites/middleware, re-exported handlers, and runtime method dispatch can remain partially unresolved.
• TypeScript analysis is compiler-backed but intentionally does not execute repository dependencies or arbitrary project code. Repository-local relative tsconfig extends is supported; package-based config presets are currently reported as a limitation rather than loaded from dependencies.
• Project-reference metadata is captured, but the analyzer does not yet model TypeScript build-mode/reference output semantics or maintain persistent watch programs between extension events.
• Non-TS languages do not yet have compiler-equivalent semantic depth.
• Search is deterministic lexical/symbol/graph retrieval; vector embeddings are not required.
• Evidence validation proves references exist; it does not prove every natural-language interpretation is semantically true. Generated documentation should remain reviewable in normal code review.

Documentation generation guardrails

Managed documentation uses document-specific generation contracts rather than one generic prompt. Architecture, API, module/capability, security, and onboarding sections each define required engineering topics and strict evidence rules. Generated claims are tagged to approved topics and rendered under stable Markdown subheadings.

The provider is instructed to treat repository text as untrusted data, cite every factual claim, avoid inventing routes/status codes/authentication/deployment/configuration, distinguish static analysis from runtime behavior, avoid secret disclosure, and turn unsupported required topics into explicit evidence gaps rather than generic filler. API prompts additionally forbid assuming an endpoint is public merely because local authentication middleware was not detected; security prompts never certify controls or compliance.

Ask Agent response design

The Ask Agent investigates a refreshed, immutable repository snapshot using read-only LangChain tools for source, search, graphs, architecture, behavior, security, changes, and analysis gaps. It retains bounded conversation context for the current extension session and supports activity events, provisional answer streaming, cancellation, and exact source references. Recommendations are supplied only when requested.

Ask opens as a conversation with a composer anchored at the bottom. Press Enter to send or Shift+Enter for a new line. Follow-ups retain the conversation, Stop cancels an investigation, and New conversation clears it. Streaming follows the latest message unless you scroll up; use Latest to return. Investigation activity, sources, and limitations can be expanded in place.

The Ask Agent uses task-specific evidence-only prompt contracts. Every AI answer must lead with a concise Answer claim, followed only by question-relevant sections such as flow, impact, locations, API behavior, security controls, or change guidance. The webview renders this structured response directly; retrieved source excerpts are not dumped into the main answer. Cited source locations and material limitations are available in collapsed panels and citations remain clickable.

Ask defaults to 12 model calls, 24 tool executions, a 120-second investigation timeout, and a 100,000-character payload limit (a serialized character budget, not a model token limit). Discovery ignores common question words and prioritizes relevant files/symbols. Repeated and overlapping reads return only newly uncovered source lines plus stable references to earlier evidence. Reads are bounded to 240 lines / 12,000 source characters and report continuation coordinates. At 80% of the payload budget, Ask replaces the growing transcript with an evidence working set and continues with tools if all supplied evidence still fits. Only exhausted call budgets or an evidence working set that cannot fit force tool-free partial synthesis. Conversation history yields to source evidence; final citations must belong to the supplied working set. Local diagnostics record payload components, tool-result growth, wire bytes, compaction decisions, and stop reasons.

Diagnostics and observability

Repository Intelligence writes structured, local JSONL diagnostics to .repo-intel/logs/repository-intelligence.jsonl and rotates them automatically. Every user operation receives a correlation/operation ID that follows it across the VS Code extension, worker, scanner/analyzer, storage, Ask Agent/provider, documentation generation, and failure boundaries. Entries include severity, component, event name, duration, safe metadata, and stack traces for errors.

Open Repository Intelligence: Open Diagnostics (or Dashboard → Diagnostics) to filter by severity/component, search messages or operation IDs, inspect expandable error details, open the raw JSONL file, or open the VS Code Output channel. repoIntel.logLevel, repoIntel.logMaxFileMB, and repoIntel.logRetentionFiles control verbosity and retention. API keys, authorization/token/password/secret-like fields and token-shaped strings are redacted before logs are persisted; oversized values are truncated. Logs stay local and .repo-intel/ is Git-ignored.

Execution/process discovery

Execution/process discovery is now a first-class derived-analysis DAG phase. Detected endpoints, conventional entrypoints, and registered/subscribed handlers seed bounded, branch-aware graph traversal across high-signal runtime relationships. Every flow carries evidence, confidence, termination reasons, unresolved gaps, and truncation state. Semantic artifacts consume these flows rather than rebuilding a single arbitrary call chain. See EXECUTION_FLOW_DISCOVERY.md.

Relationship intelligence

The structural DAG now includes a shared language-neutral relationship resolution phase. Language frontends contribute symbols and normalized relationship facts; repository-wide linking happens afterward through one conservative resolver. The Repository IR also has a formal core relationship vocabulary spanning structural, call/reference, type-system, DI, runtime, messaging, persistence, architecture, component, and execution-flow relationships. See RELATIONSHIP_RESOLUTION.md.