Codegraph Roadmap

Current version: 3.4.1 | Status: Active development | Updated: 2026-03-26

Codegraph is a strong local-first code graph CLI. This roadmap describes planned improvements across thirteen phases -- closing gaps with commercial code intelligence platforms while preserving codegraph's core strengths: fully local, open source, zero cloud dependency by default.

LLM strategy: All LLM-powered features are optional enhancements. Everything works without an API key. When configured (OpenAI, Anthropic, Ollama, or any OpenAI-compatible endpoint), users unlock richer semantic search and natural language queries.

Overview

Phase	Theme	Key Deliverables	Status
1	Rust Core	Rust parsing engine via napi-rs, parallel parsing, incremental tree-sitter, JS orchestration layer	Complete (v1.3.0)
2	Foundation Hardening	Parser registry, complete MCP, test coverage, enhanced config, multi-repo MCP	Complete (v1.5.0)
2.5	Analysis Expansion	Complexity metrics, community detection, flow tracing, co-change, manifesto, boundary rules, check, triage, audit, batch, hybrid search	Complete (v2.7.0)
2.7	Deep Analysis & Graph Enrichment	Dataflow analysis, intraprocedural CFG, AST node storage, expanded node/edge types, extractors refactoring, CLI consolidation, interactive viewer, exports command, normalizeSymbol	Complete (v3.0.0)
3	Architectural Refactoring (Vertical Slice)	Unified AST analysis framework, command/query separation, repository pattern, queries.js decomposition, composable MCP, CLI commands, domain errors, builder pipeline, presentation layer, domain grouping, curated API, unified graph model, qualified names, CLI composability	Complete (v3.1.5)
4	Resolution Accuracy	Dead role sub-categories, receiver type tracking, interface/trait implementation edges, resolution precision/recall benchmarks, `package.json` exports field, monorepo workspace resolution	Complete (v3.3.1)
5	TypeScript Migration	Project setup, core type definitions, leaf -> core -> orchestration module migration, test migration	Complete (v3.4.0)
6	Native Analysis Acceleration	Rust extraction for AST/CFG/dataflow/complexity; batch SQLite inserts; incremental rebuilds; native DB write pipeline to close the WASM parity gap on full builds	In Progress (7 of 12 done, 1 partial)
7	Expanded Language Support	Parser abstraction layer, 23 new languages in 4 batches (11 → 34), dual-engine support	Planned
8	Runtime & Extensibility	Event-driven pipeline, unified engine strategy, subgraph export filtering, transitive confidence, query caching, configuration profiles, pagination, plugin system	Planned
9	Quality, Security & Technical Debt	Supply-chain security, test quality gates, architectural debt cleanup	Planned
10	Intelligent Embeddings	LLM-generated descriptions, enhanced embeddings, build-time semantic metadata, module summaries	Planned
11	Natural Language Queries	`ask` command, conversational sessions, LLM-narrated graph queries, onboarding tools	Planned
12	GitHub Integration & CI	Reusable GitHub Action, LLM-enhanced PR review, visual impact graphs, SARIF output	Planned
13	Advanced Features	Dead code detection, monorepo, agentic search, refactoring analysis	Planned

Dependency graph

Phase 1 (Rust Core)
  |-->  Phase 2 (Foundation Hardening)
         |-->  Phase 2.5 (Analysis Expansion)
                |-->  Phase 2.7 (Deep Analysis & Graph Enrichment)
                       |-->  Phase 3 (Architectural Refactoring)
                              |-->  Phase 4 (Resolution Accuracy)
                                     |-->  Phase 5 (TypeScript Migration)
                                            |-->  Phase 6 (Native Analysis Acceleration)
                                            |-->  Phase 7 (Expanded Language Support)
                                            |-->  Phase 8 (Runtime & Extensibility)
                                            |-->  Phase 9 (Quality, Security & Technical Debt)
                                            |-->  Phase 10 (Intelligent Embeddings)  -->  Phase 11 (Natural Language Queries)
                                            |-->  Phase 12 (GitHub Integration & CI) <-- Phase 10 (risk_score, side_effects)
Phases 1-12 -->  Phase 13 (Advanced Features)

Phase 1 -- Rust Core ✅

Status: Complete -- shipped in v1.3.0

Goal: Move the CPU-intensive parsing and graph engine to Rust, keeping JS for CLI orchestration, MCP, and embeddings. This unlocks parallel parsing, incremental tree-sitter, lower memory usage, and optional standalone binary distribution.

1.1 -- Rust Workspace & napi-rs Setup ✅

Bootstrap the Rust side of the project.

Create crates/codegraph-core/ with a Cargo workspace
Set up napi-rs to compile Rust -> .node native addon
Configure CI matrix for prebuilt binaries: linux-x64, darwin-arm64, darwin-x64, win32-x64
Add npm optionalDependencies for platform-specific packages (same pattern as SWC/esbuild)
Fallback to existing JS/WASM path if native addon is unavailable

Result: npm install pulls a prebuilt binary; no Rust toolchain required for end users.

1.2 -- Native tree-sitter Parsing ✅

Replace WASM-based parsing with native tree-sitter in Rust.

Link tree-sitter grammars natively (no more .wasm files)
Implement file parsing with rayon for multi-core parallelism
Expose parseFiles(filePaths) to JS via napi-rs, returning extracted symbols/imports/calls
Benchmark: target 10-50x improvement over WASM on large codebases

Result: Parsing thousands of files uses all CPU cores. The grammars/ directory and build:wasm step are no longer needed.

Affected files: src/parser.js (becomes a thin JS wrapper over native addon)

1.3 -- Incremental Parsing ✅

Leverage native tree-sitter's edit + re-parse API.

Track previous parse trees in memory for open/watched files
On file change, apply edits to the existing tree and re-parse only the changed regions
Integrate with codegraph watch for near-instant incremental rebuilds

Result: Watch mode re-parses only changed lines instead of entire files.

Affected files: src/watcher.js, src/parser.js

1.4 -- Import Resolution & Graph Algorithms in Rust ✅

Move the hot-path graph logic to Rust.

Port the 6-level import resolution priority system with confidence scoring
Port cycle detection (currently src/cycles.js) to Rust
Keep SQLite operations in JS (better-sqlite3 is already fast and synchronous)
Expose resolveImports() and detectCycles() to JS via napi-rs

Result: Import resolution and cycle detection run in Rust with full type safety. Complex state machines benefit from Rust's type system.

1.5 -- Graceful Degradation & Migration ✅

Ensure the transition is seamless.

Keep the existing JS/WASM parser as a fallback when the native addon is unavailable
Auto-detect at startup: native addon available -> use Rust path; otherwise -> WASM path
No breaking changes to CLI, MCP, or programmatic API
Add --engine native|wasm flag for explicit selection
Migrate existing tests to validate both engines produce identical output

Result: Zero breaking changes. Users get faster parsing automatically; nothing else changes.

Phase 2 -- Foundation Hardening ✅

Status: Complete -- shipped in v1.5.0

Goal: Fix structural issues that make subsequent phases harder.

2.1 -- Language Parser Registry ✅

Replace scattered parser init/selection logic with a single declarative registry.

✅ Create a LANGUAGE_REGISTRY array mapping each language to { id, extensions, grammarFile, extractor, required }
✅ Refactor createParsers() to iterate the registry instead of individual try/catch blocks (returns Map<string, Parser|null>)
✅ Refactor getParser() to use registry extension lookup via _extToLang Map
✅ Refactor wasmExtractSymbols() to dispatch extractors via entry.extractor
✅ Auto-generate EXTENSIONS from registry (re-exported from parser.js via SUPPORTED_EXTENSIONS)

Result: Adding a new language becomes a single registry entry + extractor function.

Affected files: src/parser.js, src/constants.js

2.2 -- Complete MCP Server ✅

Expose all CLI capabilities through MCP, going from 5 -> 11 tools.

New tool	Wraps	Description
✅ `fn_deps`	`fnDepsData`	Function-level dependency chain
✅ `fn_impact`	`fnImpactData`	Function-level blast radius
✅ `diff_impact`	`diffImpactData`	Git diff impact analysis
✅ `semantic_search`	`searchData`	Embedding-powered search
✅ `export_graph`	export functions	DOT/Mermaid/JSON export
✅ `list_functions`	--	List functions in a file or by pattern

Affected files: src/mcp.js

2.3 -- Test Coverage Gaps ✅

Add tests for currently untested modules.

New test file	Coverage
✅ `tests/unit/mcp.test.js`	All MCP tools (mock stdio transport)
✅ `tests/unit/config.test.js`	Config loading, defaults, env overrides, apiKeyCommand
✅ `tests/integration/cli.test.js`	End-to-end CLI smoke tests
✅ `tests/unit/*.test.js`	Unit tests for 8 core modules (coverage 62% -> 75%)

2.4 -- Enhanced Configuration ✅

New configuration options in .codegraphrc.json:

{
  "embeddings": { "model": "minilm", "llmProvider": null },
  "llm": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "baseUrl": null,
    "apiKey": null,
    "apiKeyCommand": "op read op://vault/openai/api-key"
  },
  "search": { "defaultMinScore": 0.2, "rrfK": 60, "topK": 15 },
  "ci": { "failOnCycles": false, "impactThreshold": null }
}

✅ Environment variable fallbacks: CODEGRAPH_LLM_PROVIDER, CODEGRAPH_LLM_API_KEY, CODEGRAPH_LLM_MODEL
✅ apiKeyCommand -- shell out to external secret managers (1Password, Bitwarden, Vault, pass, macOS Keychain) at runtime via execFileSync (no shell injection). Priority: command output > env var > file config > defaults. Graceful fallback on failure.

Affected files: src/config.js

2.5 -- Multi-Repo MCP ✅

Support querying multiple codebases from a single MCP server instance.

✅ Registry file at ~/.codegraph/registry.json mapping repo names to their .codegraph/graph.db paths
✅ Add optional repo parameter to all 11 MCP tools to target a specific repository
✅ New list_repos MCP tool (12th tool) to enumerate registered repositories
✅ Auto-registration: codegraph build adds the current project to the registry
✅ New CLI commands: codegraph registry list|add|remove for manual management
✅ Default behavior: when repo is omitted, use the local .codegraph/graph.db (backwards compatible)

New files: src/registry.js Affected files: src/mcp.js, src/cli.js, src/builder.js, src/index.js

Phase 2.5 -- Analysis Expansion ✅

Status: Complete -- shipped across v2.0.0 -> v2.7.0

Goal: Build a comprehensive analysis toolkit on top of the graph -- complexity metrics, community detection, risk triage, architecture boundary enforcement, CI validation, and hybrid search. This phase emerged organically as features were needed and wasn't in the original roadmap.

2.5.1 -- Complexity Metrics ✅

Per-function complexity analysis using language-specific AST rules.

✅ Cognitive complexity, cyclomatic complexity, max nesting depth for 8 languages
✅ Halstead metrics (vocabulary, volume, difficulty, effort, bugs)
✅ LOC, SLOC, comment lines per function
✅ Maintainability Index (MI) computation
✅ Native Rust engine support for all complexity metrics
✅ CLI: codegraph complexity [target] with --sort, --limit, --kind options
✅ function_complexity DB table for persistent storage

New file: src/complexity.js (2,163 lines)

2.5.2 -- Community Detection & Drift ✅

Louvain community detection at file or function level.

✅ Graphology-based Louvain algorithm for community assignment
✅ Modularity score computation
✅ Drift analysis: identify split/merge candidates between communities
✅ CLI: codegraph communities with --level file|function

New file: src/communities.js (310 lines)

2.5.3 -- Structure & Role Classification ✅

Directory structure graph with node role classification.

✅ Directory nodes and edges with cohesion, density, fan-in/fan-out metrics
✅ Node role classification: entry, core, utility, adapter, leaf, dead
✅ Framework entry point detection (route:, event:, command: prefixes)
✅ Hotspot detection: high fan-in x high complexity
✅ Module boundary analysis: high-cohesion directories with cross-boundary imports
✅ CLI: codegraph structure, codegraph hotspots, codegraph roles

New file: src/structure.js (668 lines)

2.5.4 -- Execution Flow Tracing ✅

Forward BFS from framework entry points through callees to leaves.

✅ Entry point enumeration with type classification
✅ Forward BFS trace with cycle detection
✅ CLI: codegraph flow [name] with --list and --depth options

New file: src/flow.js (362 lines)

2.5.5 -- Temporal Coupling (Co-change Analysis) ✅

Git history analysis for temporal file coupling.

✅ Jaccard similarity computation from commit history
✅ co_changes, co_change_meta, file_commit_counts DB tables
✅ Per-file and global co-change queries
✅ CLI: codegraph co-change [file]

New file: src/cochange.js (502 lines)

2.5.6 -- Manifesto Rule Engine ✅

Configurable rule engine with warn/fail thresholds for function, file, and graph rules.

✅ Function rules: cognitive, cyclomatic, nesting depth
✅ File rules: imports, exports, LOC, fan-in, fan-out
✅ Graph rules: cycles, boundary violations
✅ Configurable via .codegraphrc.json manifesto section
✅ CLI: codegraph manifesto with table format

New file: src/manifesto.js (511 lines)

2.5.7 -- Architecture Boundary Rules ✅

Architecture enforcement using glob patterns and presets.

✅ Presets: hexagonal, layered, clean, onion
✅ Custom boundary definitions with allow/deny rules
✅ Violation detection from DB edges
✅ Integration with manifesto and check commands

New file: src/boundaries.js (347 lines)

2.5.8 -- CI Validation Predicates (`check`) ✅

Structured pass/fail checks for CI pipelines.

✅ checkNoNewCycles -- cycle predicate
✅ checkMaxBlastRadius -- blast radius predicate
✅ checkNoSignatureChanges -- signature stability predicate
✅ checkNoBoundaryViolations -- architecture predicate
✅ Composable result objects with pass/fail semantics
✅ MCP tool: check
✅ CLI: codegraph check [ref] with exit code 0/1

New file: src/check.js (433 lines)

2.5.9 -- Composite Analysis Commands ✅

High-level commands that compose multiple analysis steps.

✅ Audit: explain + impact + health + manifesto breaches in one call
✅ Batch: run same query against multiple targets for multi-agent dispatch
✅ Triage: risk-ranked audit queue using normalized fan-in, complexity, churn, MI signals

New files: src/audit.js (424 lines), src/batch.js (91 lines), src/triage.js (274 lines)

2.5.10 -- Hybrid Search ✅

BM25 keyword search + semantic vector search with RRF fusion.

✅ FTS5 full-text index on node names and source previews
✅ BM25 keyword search via ftsSearchData()
✅ Hybrid search with configurable RRF fusion via hybridSearchData()
✅ Three search modes: hybrid (default), semantic, keyword
✅ 8 embedding model options (minilm, jina-small/base/code, nomic/v1.5, bge-large)

Affected file: src/embedder.js (grew from 525 -> 1,113 lines)

2.5.11 -- Supporting Infrastructure ✅

Cross-cutting utilities added during the expansion.

✅ Pagination: offset/limit with MCP defaults per command (src/paginate.js, 106 lines)
✅ Snapshot: SQLite DB backup/restore via VACUUM INTO (src/snapshot.js, 150 lines)
✅ CODEOWNERS: ownership integration for boundary analysis (src/owners.js, 360 lines)
✅ Branch Compare: structural diff between git refs (src/branch-compare.js, 569 lines)
✅ Change Journal: NDJSON event log for watch mode (src/change-journal.js, 131 lines)
✅ Journal: change journal validation/management (src/journal.js, 110 lines)
✅ Update Check: npm registry polling with 24h cache (src/update-check.js, 161 lines)

2.5.12 -- MCP Tool Expansion ✅

MCP grew from 12 -> 25 tools, covering all new analysis capabilities.

New tool	Wraps
✅ `structure`	`structureData`
✅ `node_roles`	`rolesData`
✅ `hotspots`	`hotspotsData`
✅ `co_changes`	`coChangeData`
✅ `execution_flow`	`flowData`
✅ `list_entry_points`	`listEntryPointsData`
✅ `complexity`	`complexityData`
✅ `manifesto`	`manifestoData`
✅ `communities`	`communitiesData`
✅ `code_owners`	`ownersData`
✅ `audit`	`auditData`
✅ `batch_query`	`batchData`
✅ `triage`	`triageData`
✅ `branch_compare`	`branchCompareData`
✅ `check`	`checkData`

Affected file: src/mcp.js (grew from 354 -> 1,212 lines)

Phase 2.7 -- Deep Analysis & Graph Enrichment ✅

Status: Complete -- shipped as v3.0.0 across PRs #254-#285

Goal: Add deeper static analysis capabilities (dataflow, control flow graphs, AST querying), enrich the graph model with sub-declaration node types and structural edges, refactor extractors into per-language modules, consolidate the CLI surface area, and introduce interactive visualization. This phase emerged from competitive analysis against Joern and Narsil-MCP.

2.7.1 -- Dataflow Analysis ✅

Define-use chain extraction tracking how data flows between functions.

✅ Three edge types: flows_to (parameter flow), returns (call return assignment), mutates (parameter-derived mutations)
✅ Confidence scoring (1.0 param, 0.9 call return, 0.8 destructured)
✅ Scope-stack AST walk with function-level tracking
✅ Forward BFS impact analysis via return value consumers
✅ Path finding through dataflow edges
✅ Opt-in via build --dataflow (dynamic import, only loaded when flag passed)
✅ DB migration v10: dataflow table with source, target, kind, param_index, expression, confidence
✅ JS/TS/TSX only (MVP -- language-specific scope analysis)
✅ CLI: codegraph dataflow <name> with --impact mode for transitive data-dependent blast radius
✅ MCP tool: dataflow with edges and impact modes (path mode removed during CLI consolidation PR #263)

New file: src/dataflow.js (1,187 lines)

2.7.2 -- Expanded Node Types (Phase 1) ✅

Extend the graph model with sub-declaration node kinds.

✅ 3 new node kinds: parameter, property, constant
✅ Tiered constants: CORE_SYMBOL_KINDS (10), EXTENDED_SYMBOL_KINDS (3), EVERY_SYMBOL_KIND (13)
✅ Backward-compatible alias: ALL_SYMBOL_KINDS = CORE_SYMBOL_KINDS
✅ parent_id column on nodes table (DB migration v11) linking children to parent definitions
✅ All 9 WASM extractors updated to emit children arrays
✅ CLI: codegraph children <name>
✅ MCP tool: symbol_children with extended kind enum

Affected files: All extractors, src/builder.js, src/queries.js, src/db.js

2.7.3 -- Expanded Edge Types (Phase 2) ✅

Structural edges for richer graph relationships.

✅ 3 new edge kinds: contains (parent→child), parameter_of (param→function), receiver (method call receiver)
✅ Tiered constants: CORE_EDGE_KINDS (6), STRUCTURAL_EDGE_KINDS (3), EVERY_EDGE_KIND (9)
✅ Structural edges excluded from moduleMapData() coupling counts
✅ MCP tool enums updated to include new edge kinds

Affected files: src/builder.js, src/queries.js

2.7.4 -- Intraprocedural Control Flow Graph (CFG) ✅

Basic-block control flow graph construction from function ASTs.

✅ makeCfgRules(overrides) factory with per-language defaults and validation
✅ CFG_RULES Map covering all 9 languages (JS/TS, Python, Go, Rust, Java, C#, PHP, Ruby)
✅ Handles: if/else, for/while/do-while, switch, try/catch/finally, break/continue (with labels), return/throw
✅ Opt-in via build --cfg (dynamic import)
✅ DB migration v12: cfg_blocks and cfg_edges tables
✅ DOT and Mermaid export: cfgToDOT(), cfgToMermaid()
✅ CLI: codegraph cfg <name> with --format text|dot|mermaid
✅ MCP tool: cfg

New file: src/cfg.js (1,451 lines)

2.7.5 -- Stored Queryable AST Nodes ✅

Persist and query selected AST node types for pattern-based codebase exploration.

✅ 6 AST node kinds: call, new, string, regex, throw, await
✅ AST_NODE_KINDS constant
✅ Pattern matching via SQL GLOB with auto-wrapping for substring search
✅ Parent resolution via narrowest enclosing definition
✅ Always-on extraction during build (post-parse, before complexity to preserve _tree)
✅ DB migration v13: ast_nodes table with indexes on kind, name, file, parent
✅ CLI: codegraph ast [pattern] with -k, -f, -T, -j
✅ MCP tool: ast_query

New file: src/ast.js (392 lines)

2.7.6 -- Extractors Refactoring ✅

Split per-language extractors from monolithic parser.js into dedicated modules.

✅ New src/extractors/ directory with 11 files (3,023 lines total)
✅ One file per language: javascript.js (892), csharp.js (311), php.js (322), java.js (290), rust.js (295), ruby.js (277), go.js (237), python.js (284), hcl.js (95)
✅ Shared utilities in helpers.js (nodeEndLine(), findChild())
✅ Barrel export via index.js
✅ Consistent return schema: { definitions, calls, imports, classes, exports }
✅ All extractors support extended node kinds (parameter, property, constant)
✅ parser.js reduced to thin WASM fallback with LANGUAGE_REGISTRY (404 lines)

New directory: src/extractors/

2.7.7 -- normalizeSymbol Utility ✅

Stable JSON schema for symbol output across all query functions.

✅ normalizeSymbol(row, db, hashCache) returns 7-field shape: { name, kind, file, line, endLine, role, fileHash }
✅ File hash caching for efficient batch operations
✅ Adopted by dataflow, context, where, query, and other functions

Affected file: src/queries.js

2.7.8 -- Interactive Graph Viewer ✅

Self-contained HTML visualization with vis-network.

✅ File-level and function-level graph modes
✅ Layout switching (hierarchical, force, radial), physics toggle, search
✅ Color by kind/role/community/complexity (configurable)
✅ Size by uniform/fan-in/complexity
✅ Clustering by community or directory
✅ Drill-down with seed strategies (all, top-fanin, entry)
✅ Detail panel with metrics, callers, callees on node click
✅ Risk overlays (dead-code, high-blast-radius, low-MI)
✅ Configuration via .plotDotCfg / .plotDotCfg.json with deep merge defaults
✅ CLI: codegraph plot with --functions, --config, --color-by, --size-by, --cluster-by, --overlay

New file: src/viewer.js (948 lines)

2.7.9 -- Exports Command ✅

Per-symbol consumer analysis for file exports.

✅ exportsData(file) returns each exported symbol with its consumers (who calls it and from where)
✅ CLI: codegraph exports <file>
✅ MCP tool: file_exports
✅ Integrated into batch command system

Affected file: src/queries.js

2.7.10 -- Export Format Expansion ✅

Three new graph export formats for external tooling integration.

✅ GraphML (XML format for graph tools like yEd, Gephi)
✅ GraphSON (Gremlin/TinkerPop server format)
✅ Neo4j CSV (bulk loader format for Neo4j import)

Affected file: src/export.js (681 lines)

2.7.11 -- CLI Consolidation ✅

First CLI surface area reduction -- 5 commands merged into existing ones.

✅ hotspots → folded into triage --level file|directory
✅ manifesto → merged into check (no args = manifesto, --rules for both)
✅ explain → replaced by audit --quick
✅ batch-query → use batch where instead
✅ query --path → standalone path <from> <to> command (deprecation notice on old syntax)
✅ MCP tools unchanged for backward compatibility

Affected file: src/cli.js

2.7.12 -- MCP Tool Consolidation & Expansion ✅

MCP tools were both consolidated and expanded, resulting in a net change from 25 → 30 tools (31 in multi-repo mode).

Added:

New tool	Wraps
✅ `cfg`	`cfgData`
✅ `ast_query`	`astQueryData`
✅ `dataflow`	`dataflowData` (edges + impact modes)
✅ `file_exports`	`exportsData`
✅ `symbol_children`	`childrenData`

Removed (PR #263 consolidation):

Removed tool	Replacement
`fn_deps`	`query` with `deps` mode
`symbol_path`	`query` with `path` mode
`list_entry_points`	`execution_flow` with `list` mode

Plus updated enums on existing tools (edge_kinds, symbol kinds).

Affected file: src/mcp.js (grew from 1,212 -> 1,370 lines)

2.7 Summary

Metric	Before (v2.7.0 baseline)	After (v3.0.0)	Delta
Source modules	35	50	+15
Total source lines	17,830	26,277	+47%
DB tables	9	13	+4
DB migrations	v9	v13	+4
MCP tools	25	30	+5 (net: +8 added, -3 consolidated)
CLI commands	45	39	-6 (net: +7 added, -5 consolidated, -8 merged)
Node kinds	10	13	+3
Edge kinds	6	9	+3
Test files	59	70	+11

Phase 3 -- Architectural Refactoring ✅

Status: Complete -- started in v3.1.1, finished in v3.1.5

Goal: Restructure the codebase for modularity, testability, and long-term maintainability. These are internal improvements -- no new user-facing features, but they make every subsequent phase easier to build and maintain.

Architecture pattern: Vertical Slice Architecture. Each CLI command is a natural vertical slice — thin command entry point → domain logic → data access → formatted output. This avoids the overhead of layered patterns (Hexagonal, Clean Architecture) that would create abstractions with only one implementation, while giving clear boundaries and independent testability per feature. The target end-state directory structure:

src/
  commands/              # Thin CLI entry points (one per command)
  domain/                # Core logic grouped by feature
    graph/               # builder, resolve, cycles, watcher
    analysis/            # symbol-lookup, impact, dependencies, module-map, context, exports, roles
    search/              # embedder, semantic search, hybrid
  ast-analysis/          # Unified visitor framework (already in place)
  db/                    # Repository, migrations, query-builder, connection
  extractors/            # Per-language tree-sitter extractors (already in place)
  mcp/                   # MCP server, tool registry, per-tool handlers
  presentation/          # Output formatting: viewer, export (DOT/Mermaid/JSON), result-formatter, table, sequence-renderer
  infrastructure/        # Config, logger, native loader, pagination, test-filter, errors
  shared/                # Constants, normalize, generators

Key principles:

Commands are thin — parse args, call domain, format output. No business logic in CLI layer
Domain modules don't import presentation — they return data, callers decide format
Shared kernel stays flat — db/, infrastructure/, shared/ are cross-cutting
No premature abstractions — no interfaces/ports for single implementations

Context: Phases 2.5 and 2.7 added 38 modules and grew the codebase from 5K to 26,277 lines without introducing shared abstractions. The dual-function anti-pattern was replicated across 19 modules. Three independent AST analysis engines (complexity, CFG, dataflow) totaling 4,801 lines share the same fundamental pattern but no infrastructure. Raw SQL is scattered across 25+ modules touching 13 tables. The priority ordering has been revised based on actual growth patterns -- the new #1 priority is the unified AST analysis framework.

3.1 -- Unified AST Analysis Framework ★ Critical ✅

Unify the independent AST analysis engines (complexity, CFG, dataflow) plus AST node storage into a shared visitor framework. These four modules independently implement the same pattern: per-language rules map → AST walk → collect data → write to DB → query → format.

Completed: All 4 analyses (complexity, CFG, dataflow, AST-store) now run in a single DFS walk via walkWithVisitors. The CFG visitor rewrite (#392) eliminated the Mode A/B split, replaced the 813-line buildFunctionCFG with a node-level visitor, and derives cyclomatic complexity directly from CFG structure (E - N + 2). cfg.js reduced from 1,242 → 518 lines.

src/
  ast-analysis/
    visitor.js                 # Shared DFS walker with pluggable visitor hooks
    engine.js                  # Orchestrates all analyses in one coordinated pass
    metrics.js                 # Halstead, MI, LOC/SLOC (extracted from complexity.js)
    visitor-utils.js           # Shared helpers (functionName, extractParams, etc.)
    visitors/
      complexity-visitor.js    # Cognitive/cyclomatic/nesting + Halstead
      cfg-visitor.js           # Basic-block + edge construction via DFS hooks
      ast-store-visitor.js     # new/throw/await/string/regex extraction
      dataflow-visitor.js      # Scope stack + define-use chains
    shared.js                  # findFunctionNode, rule factories, ext mapping
    rules/                     # Per-language rule files (unchanged)

✅ Shared DFS walker with enterNode/exitNode/enterFunction/exitFunction hooks, skipChildren per-visitor, nesting/scope tracking
✅ Complexity visitor (cognitive, cyclomatic, max nesting, Halstead) — file-level and function-level modes
✅ AST-store visitor (new/throw/await/string/regex extraction)
✅ Dataflow visitor (define-use chains, arg flows, mutations, scope stack)
✅ Engine orchestrator: unified pre-walk stores results as pre-computed data on symbols, then delegates to existing buildXxx for DB writes
✅ builder.js → single runAnalyses call replaces 4 sequential blocks + WASM pre-parse
✅ Extracted pure computations to metrics.js (Halstead derived math, LOC, MI)
✅ Extracted shared helpers to visitor-utils.js (from dataflow.js)
✅ CFG visitor rewrite — node-level DFS visitor replaces statement-level buildFunctionCFG, Mode A/B split eliminated (#392)
✅ Cyclomatic complexity derived from CFG (E - N + 2) — single source of truth for control flow metrics (#392)

Affected files: src/complexity.js, src/cfg.js, src/dataflow.js, src/ast.js → split into src/ast-analysis/

3.2 -- Command/Query Separation ★ Critical ✅

CLI display wrappers extracted from all 19 analysis modules into dedicated src/commands/ files. Shared infrastructure (result-formatter.js, test-filter.js) moved to src/infrastructure/. *Data() functions remain in original modules — MCP dynamic imports unchanged. ~1,059 lines of CLI formatting code separated from analysis logic (#373, #393).

src/
  commands/                    # One file per command (16 files)
    audit.js, batch.js, cfg.js, check.js, cochange.js, communities.js,
    complexity.js, dataflow.js, flow.js, branch-compare.js, manifesto.js,
    owners.js, sequence.js, structure.js, triage.js, query.js (barrel re-export)

  infrastructure/
    result-formatter.js         # Shared formatting: JSON, NDJSON dispatch
    test-filter.js              # Shared --no-tests / isTestFile logic

✅ queries.js CLI wrappers → queries-cli.js (15 functions)
✅ Shared result-formatter.js (outputResult for JSON/NDJSON dispatch)
✅ Shared test-filter.js (isTestFile predicate)
✅ CLI wrappers extracted from remaining 15 modules into src/commands/ (#393)
✅ Per-command src/commands/ directory structure (#393)
✅ src/infrastructure/ directory for shared utilities (#393)
⏭️ CommandRunner shared lifecycle — deferred (command files vary too much for a single pattern today)

Affected files: All 19 modules with dual-function pattern, src/cli.js, src/mcp.js

3.3 -- Repository Pattern for Data Access ★ Critical ✅

v3.1.1 progress: src/db/ directory created with repository.js (134 lines), query-builder.js (280 lines), and migrations.js (312 lines). All db usage across the codebase wrapped in try/finally for reliable db.close() (#371, #384, #383).

v3.1.2 progress: repository.js split into src/db/repository/ directory with 10 domain files (nodes, edges, build-stmts, complexity, cfg, dataflow, cochange, embeddings, graph-read, barrel). Raw SQL migrated from 14 src/ modules into repository layer. connection.js already complete (89 lines handling open/close/WAL/pragma/locks/readonly).

v3.1.3 progress: Extracted cachedStmt utility into src/db/repository/cached-stmt.js — reusable prepared statement caching for hot-path repository functions (#417, #402).

✅ src/db/ directory structure created
✅ repository/ — domain-split repository (nodes, edges, build-stmts, complexity, cfg, dataflow, cochange, embeddings, graph-read)
✅ query-builder.js — lightweight SQL builder (280 lines)
✅ migrations.js — schema migrations extracted (312 lines)
✅ connection.js — connection setup (open, WAL mode, pragma tuning, readonly, locks)
✅ All db usage wrapped in try/finally for reliable db.close()
✅ Migrate remaining raw SQL from 14 modules into Repository

src/
  db/
    connection.js              # Open, WAL mode, pragma tuning
    migrations.js              # Schema versions (currently 15 migrations)
    query-builder.js           # Lightweight SQL builder for common filtered queries
    repository/
      index.js                 # Barrel re-export
      nodes.js                 # Node lookups: getNodeId, findFileNodes, bulkNodeIdsByFile, etc.
      edges.js                 # Edge queries: findCallees, findCallers, import/hierarchy edges
      build-stmts.js           # Cascade purge: purgeFileData, purgeFilesData
      complexity.js            # function_complexity table reads
      cfg.js                   # cfg_blocks/cfg_edges reads + deletes
      dataflow.js              # dataflow table checks
      cochange.js              # co_changes/co_change_meta reads
      embeddings.js            # embeddings/embedding_meta reads
      graph-read.js            # Cross-table reads for export/communities

Affected files: src/db.js barrel updated, raw SQL extracted from queries.js, builder.js, watcher.js, structure.js, complexity.js, cfg.js, dataflow.js, ast.js, ast-analysis/engine.js, embedder.js, sequence.js, communities.js

3.4 -- Decompose queries.js (3,395 Lines) ✅

v3.1.1 progress: queries.js reduced from 3,395 → 2,490 lines by extracting all CLI formatting to queries-cli.js (3.2). Symbol kind constants extracted to kinds.js (49 lines) (#378).

✅ CLI formatting separated → queries-cli.js (via 3.2)
✅ kinds.js — symbol kind constants extracted
✅ Split remaining queries.js data functions into src/analysis/ modules
✅ Extract shared/normalize.js, shared/generators.js

Split into pure analysis modules that return data and share no formatting concerns.

src/
  analysis/
    symbol-lookup.js           # queryNameData, whereData, listFunctionsData, childrenData
    impact.js                  # impactAnalysisData, fnImpactData, diffImpactData
    dependencies.js            # fileDepsData, fnDepsData, pathData
    module-map.js              # moduleMapData, statsData
    context.js                 # contextData, explainData
    exports.js                 # exportsData
    roles.js                   # rolesData

  shared/
    constants.js               # CORE_SYMBOL_KINDS, EXTENDED_SYMBOL_KINDS, EVERY_SYMBOL_KIND,
                               # CORE_EDGE_KINDS, STRUCTURAL_EDGE_KINDS, EVERY_EDGE_KIND,
                               # VALID_ROLES, FALSE_POSITIVE_NAMES, AST_NODE_KINDS
    normalize.js               # normalizeSymbol, isTestFile, kindIcon
    generators.js              # iterListFunctions, iterRoles, iterWhere

Note: Phase 2.7 introduced tiered constants (CORE_/EXTENDED_/EVERY_) and normalizeSymbol() — the right abstractions, just in the wrong file. Moving them to shared/ is the first step.

Affected files: src/queries.js -> split into src/analysis/ + src/shared/

3.5 -- Composable MCP Tool Registry ✅

Replaced the monolithic 1,470-line mcp.js (31 tools in one switch dispatch) with self-contained tool modules.

src/
  mcp.js                       # 2-line re-export shim (preserves public API)
  mcp/
    index.js                   # Re-exports: TOOLS, buildToolList, startMCPServer
    server.js                  # MCP server setup, transport, lifecycle, dispatch
    tool-registry.js           # BASE_TOOLS schemas, buildToolList(), TOOLS constant
    middleware.js              # effectiveLimit/effectiveOffset pagination helpers
    tools/
      index.js                 # Barrel: Map<name, { name, handler }> for all 31 tools
      query.js ... ast-query.js  # { name, handler } -- one per tool (31 files)

Adding a new MCP tool = adding a file + one line in the barrel. No other files change.

Affected files: src/mcp.js -> split into src/mcp/

3.6 -- CLI Command Objects ✅

Monolithic 1,525-line src/cli.js split into src/cli/ with auto-discovery of command modules. 40 independently testable command files in src/cli/commands/, each exporting { name, description, options, queryOpts, validate, execute }. Shared utilities extracted to src/cli/shared/ (query options, output formatting). src/cli/index.js provides registerCommand() + discoverCommands() — new commands are added by dropping a file into commands/. src/cli.js reduced to an 8-line thin wrapper (#427).

src/
  cli.js                         # 8-line thin wrapper → cli/index.js
  cli/
    index.js                     # Commander setup, registerCommand(), discoverCommands()
    shared/
      output.js                  # --json, --ndjson, table, plain text
      options.js                 # Shared options (--no-tests, --json, --db, etc.)
    commands/                    # 40 files, one per command
      build.js                   # { name, description, options, validate, execute }
      ...

Affected files: src/cli.js -> split into src/cli/

3.7 -- Curated Public API Surface ✅

Reduced index.js from ~190 named exports (243 lines) to 48 curated exports (57 lines). CLI formatters, internal DB utilities, parser internals, infrastructure helpers, and implementation-detail constants removed from the public surface. package.json exports field updated to expose ./cli entry point.

What's exported:

31 *Data() query functions — one per command (e.g. queryNameData, contextData, auditData, cfgData)
4 graph building — buildGraph, loadConfig, findCycles, buildEmbeddings
3 export formats — exportDOT, exportJSON, exportMermaid
3 search — searchData, multiSearchData, hybridSearchData
4 constants — EVERY_SYMBOL_KIND, EVERY_EDGE_KIND, EXTENSIONS, IGNORE_DIRS

What's removed: CLI display wrappers (commands/*.js, queries-cli.js), internal DB functions (fanInJoinSQL, NodeQuery, etc.), parser internals (parseFileAuto, disposeParsers), infrastructure (outputResult, isTestFile), registry management, snapshot internals, pagination helpers, implementation-detail constants (COMPLEXITY_RULES, HALSTEAD_RULES, etc.), and lower-level analysis functions. All remain importable via direct paths.

Affected files: src/index.js, package.json

Removed: Decompose complexity.js — Subsumed by 3.1. The standalone complexity decomposition from the previous revision is now part of the unified AST analysis framework (3.1). The complexity.js per-language rules become ast-analysis/rules/complexity/{lang}.js alongside CFG and dataflow rules.

3.8 -- Domain Error Hierarchy ✅

Structured domain errors replace ad-hoc error handling across the codebase. 8 error classes in src/errors.js: CodegraphError, ParseError, DbError, ConfigError, ResolutionError, EngineError, AnalysisError, BoundaryError. The CLI catches domain errors and formats for humans; MCP returns structured { isError, code } responses.

class CodegraphError extends Error { constructor(message, { code, file, cause }) { ... } }
class ParseError extends CodegraphError { code = 'PARSE_FAILED' }
class DbError extends CodegraphError { code = 'DB_ERROR' }
class ConfigError extends CodegraphError { code = 'CONFIG_INVALID' }
class ResolutionError extends CodegraphError { code = 'RESOLUTION_FAILED' }
class EngineError extends CodegraphError { code = 'ENGINE_UNAVAILABLE' }
class AnalysisError extends CodegraphError { code = 'ANALYSIS_FAILED' }
class BoundaryError extends CodegraphError { code = 'BOUNDARY_VIOLATION' }

✅ src/errors.js — 8 domain error classes with code, file, cause fields
✅ CLI top-level catch formats domain errors for humans
✅ MCP returns structured error responses
✅ Domain errors adopted across config, boundaries, triage, and query modules

New file: src/errors.js

3.9 -- Builder Pipeline Architecture ✅

Refactored buildGraph() from a monolithic mega-function into explicit, independently testable pipeline stages. src/builder.js is now a 12-line barrel re-export. src/builder/pipeline.js orchestrates 9 stages via PipelineContext. Each stage is a separate file in src/builder/stages/.

src/
  builder.js                    # 12-line barrel re-export
  builder/
    context.js                  # PipelineContext — shared state across stages
    pipeline.js                 # Orchestrator: setup → stages → timing
    helpers.js                  # batchInsertNodes, collectFiles, fileHash, etc.
    incremental.js              # Incremental build logic
    stages/
      collect-files.js          # Discover source files
      detect-changes.js         # Incremental: hash comparison, removed detection
      parse-files.js            # Parse via native/WASM engine
      insert-nodes.js           # Batch-insert nodes, children, contains/parameter_of edges
      resolve-imports.js        # Import resolution with aliases
      build-edges.js            # Call edges, class edges, barrel resolution
      build-structure.js        # Directory/file hierarchy
      run-analyses.js           # Complexity, CFG, dataflow, AST store
      finalize.js               # Build meta, timing, db close

✅ PipelineContext shared state replaces function parameters
✅ 9 sequential stages, each independently testable
✅ src/builder.js reduced to barrel re-export
✅ Timing tracked per-stage in ctx.timing

Affected files: src/builder.js → split into src/builder/

3.10 -- Embedder Subsystem Extraction ✅

Restructured embedder.js (1,113 lines) into a standalone src/embeddings/ subsystem with pluggable stores and search strategies.

src/
  embeddings/
    index.js                   # Public API
    models.js                  # 8 model definitions, batch sizes, loading
    generator.js               # Source -> text preparation -> batch embedding
    stores/
      sqlite-blob.js           # Current O(n) cosine similarity
      fts5.js                  # BM25 keyword search
    search/
      semantic.js              # Vector similarity
      keyword.js               # FTS5 BM25
      hybrid.js                # RRF fusion
    strategies/
      structured.js            # Structured text preparation
      source.js                # Raw source preparation

The pluggable store interface enables future O(log n) ANN search (e.g., hnswlib-node) when symbol counts reach 50K+.

✅ Extracted into src/embeddings/ with index.js, models.js, generator.js (v3.1.4, #433)
✅ Pluggable stores: sqlite-blob.js, fts5.js
✅ Search engines: semantic.js, keyword.js, hybrid.js
✅ Text preparation strategies: structured.js, source.js

Affected files: src/embedder.js -> split into src/embeddings/

3.11 -- Unified Graph Model ✅

Unified the four parallel graph representations into a shared in-memory CodeGraph model. The src/graph/ directory contains the model, 3 builders, 6 algorithms, and 2 classifiers. Algorithms are composable — run community detection on the dependency graph, the temporal graph, or a merged graph.

src/
  graph/
    index.js                   # Barrel re-export
    model.js                   # CodeGraph class: nodes Map, directed/undirected adjacency
    builders/
      index.js                 # Barrel
      dependency.js            # Build from SQLite call/import edges
      structure.js             # Build from file/directory hierarchy
      temporal.js              # Build from git co-change history
    algorithms/
      index.js                 # Barrel
      bfs.js                   # Breadth-first traversal
      shortest-path.js         # Dijkstra path finding
      tarjan.js                # Strongly connected components / cycle detection
      louvain.js               # Community detection
      centrality.js            # Fan-in/fan-out, betweenness centrality
    classifiers/
      index.js                 # Barrel
      roles.js                 # Node role classification (hub, utility, leaf, etc.)
      risk.js                  # Composite risk scoring

✅ CodeGraph in-memory model with nodes Map, successors/predecessors adjacency
✅ 3 builders: dependency (SQLite edges), structure (file hierarchy), temporal (git co-changes)
✅ 6 algorithms: BFS, shortest-path, Tarjan SCC, Louvain community, centrality
✅ 2 classifiers: role classification, risk scoring
✅ structure.js, communities.js, cycles.js, triage.js, viewer.js refactored to use graph model

Affected files: src/structure.js, src/cochange.js, src/communities.js, src/cycles.js, src/triage.js, src/viewer.js

3.12 -- Qualified Names & Hierarchical Scoping ✅

Phase 2.7 progress: parent_id column, contains edges, parameter_of edges, and childrenData() query now model one-level parent-child relationships.

Node model enriched with qualified_name, scope, and visibility columns (migration v15). Enables direct lookups like "all methods of class X" via findNodesByScope() and qualified name resolution via findNodeByQualifiedName() — no edge traversal needed.

ALTER TABLE nodes ADD COLUMN qualified_name TEXT;  -- 'DateHelper.format', 'freeFunction.x'
ALTER TABLE nodes ADD COLUMN scope TEXT;            -- 'DateHelper', null for top-level
ALTER TABLE nodes ADD COLUMN visibility TEXT;       -- 'public' | 'private' | 'protected'
CREATE INDEX idx_nodes_qualified_name ON nodes(qualified_name);
CREATE INDEX idx_nodes_scope ON nodes(scope);

✅ Migration v15: qualified_name, scope, visibility columns + indexes
✅ batchInsertNodes expanded to 9 columns (name, kind, file, line, end_line, parent_id, qualified_name, scope, visibility)
✅ insert-nodes.js computes qualified_name and scope during insertion: methods get scope from class prefix, children get parent.child qualified names
✅ Visibility extraction for all 8 language extractors:
- JS/TS: accessibility_modifier nodes + # private field detection
- Java/C#/PHP: modifiers/visibility_modifier AST nodes via shared extractModifierVisibility()
- Python: convention-based (__name → private, _name → protected)
- Go: capitalization convention (uppercase → public, lowercase → private)
- Rust: visibility_modifier child (pub → public, else private)
✅ findNodesByScope(db, scopeName, opts) — query by scope with optional kind/file filters
✅ findNodeByQualifiedName(db, qualifiedName) — direct lookup without edge traversal
✅ childrenData() returns qualifiedName, scope, visibility for parent and children
✅ Integration tests covering qualified_name, scope, visibility, and childrenData output

Affected files: src/db/migrations.js, src/db/repository/nodes.js, src/builder/helpers.js, src/builder/stages/insert-nodes.js, src/extractors/*.js, src/extractors/helpers.js, src/analysis/symbol-lookup.js

3.13 -- Testing Pyramid with InMemoryRepository ✅

The repository pattern (3.3) enables true unit testing. InMemoryRepository provides an in-memory backend that implements the same interface as SqliteRepository, enabling fast unit tests without SQLite.

✅ InMemoryRepository at src/db/repository/in-memory-repository.js (v3.1.4, #444)
✅ Pure unit tests for graph algorithms (pass adjacency list, assert result)
✅ Pure unit tests for risk/confidence scoring (pass parameters, assert score)
✅ Migrate existing integration tests that only need query data to use InMemoryRepository

3.14 -- Presentation Layer Extraction ✅

Separated all output formatting from domain logic into src/presentation/. Domain functions return plain data objects; presentation functions are pure transforms: data → formatted string. Commands wire the two together.

src/
  presentation/
    viewer.js              # Interactive terminal viewer (tree rendering, color, layout)
    export.js              # DOT, Mermaid, JSON, SVG graph serialization
    table.js               # Tabular CLI output (used by complexity, stats, etc.)
    sequence-renderer.js   # Mermaid sequence diagram formatting (from sequence.js)
    result-formatter.js    # Structured result formatting (moved from infrastructure/)
    colors.js              # Shared color/style utilities

✅ Extract rendering logic from viewer.js (v3.1.4, #443)
✅ Extract serialization from export.js — DOT/Mermaid/JSON writers become pure data → string transforms
✅ Extract table formatting helpers used across queries-cli.js, complexity, stats
✅ Move result-formatter.js from infrastructure/ to presentation/
✅ Extract Mermaid rendering from sequence.js into sequence-renderer.js

Affected files: src/viewer.js, src/export.js, src/sequence.js, src/infrastructure/result-formatter.js

3.15 -- Domain Directory Grouping ✅

Completed: src/ reorganized into domain/, features/, and presentation/ layers (#456, #458). Three post-reorganization issues (circular imports, barrel exports, path corrections) resolved in #459. MCP server import path fixed in #466. Complexity/CFG/dataflow analysis restored after the move in #469.

src/domain/
  graph/                 # builder.js, resolve.js, cycles.js, watcher.js, journal.js, change-journal.js
  analysis/              # symbol-lookup.js, impact.js, dependencies.js, module-map.js,
                         # context.js, exports.js, roles.js
  search/                # embedder subsystem (models, generator, stores, search strategies)
  parser.js              # tree-sitter WASM wrapper + LANGUAGE_REGISTRY
  queries.js             # Query functions (symbol search, file deps, impact analysis)

✅ Move builder pipeline modules to domain/graph/ (#456)
✅ Move decomposed query modules (from 3.4) to domain/analysis/ (#456)
✅ Move embedder subsystem (from 3.10) to domain/search/ (#456)
✅ Move remaining flat files (features/, presentation/, infrastructure/, shared/) into subdirectories (#458)
✅ Update all import paths across codebase (#456, #458, #459)

Prerequisite: 3.2, 3.4, 3.9, 3.10 should be complete before this step — it organizes the results of those decompositions.

3.16 -- CLI Composability ✅

Completed: openGraph(opts) helper eliminates DB-open/close boilerplate across CLI commands. resolveQueryOpts(opts) extracts the 5 repeated option fields into one call, refactoring 20 command files. Universal output formatter extended with --table (auto-column aligned) and --csv (RFC 4180 with nested object flattening) output formats (#461).

✅ openGraph() helper — single helper returning { db, rootDir, config } with engine selection, config loading, and cleanup (#461)
✅ Universal output formatter — outputResult() extended with --table and --csv formats; resolveQueryOpts() extracts repeated option fields (#461)

Affected files: src/cli/commands/*.js, src/cli/shared/, src/presentation/result-formatter.js

Phase 4 -- Resolution Accuracy ✅

Status: Complete -- all 6 sub-phases shipped across v3.2.0 → v3.3.1

Goal: Close the most impactful gaps in call graph accuracy before investing in type safety or native acceleration. The entire value proposition — blast radius, impact analysis, dependency chains — rests on the call graph. These targeted improvements make the graph trustworthy.

Why before TypeScript: These fixes operate on the existing JS codebase and produce measurable accuracy gains immediately. TypeScript types will further improve resolution later, but receiver tracking, dead role fixes, and precision benchmarks don't require types to implement.

4.1 -- Fix "Dead" Role Sub-categories ✅

The coarse dead role is now sub-classified into four categories: dead-leaf (parameters, properties, constants), dead-entry (CLI commands, MCP tools, route/handler files), dead-ffi (cross-language FFI — .rs, .c, .go, etc.), and dead-unresolved (genuinely unreferenced callables). The --role dead filter matches all sub-roles for backward compatibility. Risk weights are tuned per sub-role. VALID_ROLES, DEAD_SUB_ROLES exported from shared/kinds.js. Stats, MCP node_roles, CLI roles/triage all updated.

4.2 -- Receiver Type Tracking for Method Dispatch ✅

The single highest-impact resolution improvement. Previously obj.method() resolved to ANY exported method in scope — no receiver type tracking. This missed repository pattern calls (repo.findCallers()), builder chains, and visitor dispatch.

Implemented:

✅ Upgraded typeMap from Map<string, string> to Map<string, {type, confidence}> across all 8 language extractors
✅ Graded confidence per type source: 1.0 constructor (new Foo()), 0.9 type annotation / typed parameter, 0.7 factory method (Foo.create())
✅ Factory pattern extraction: JS/TS (Foo.create()), Go (NewFoo(), &Struct{}, Struct{}), Python (Foo(), Foo.create())
✅ Edge builder uses type map for precise ClassName.method qualified-name lookup in both JS fallback and native supplement paths
✅ Receiver edges carry type-source confidence instead of hardcoded 0.9/0.7
✅ setIfHigher logic ensures highest-confidence assignment wins per variable
✅ Incremental build path updated to consume new format
✅ Backwards-compatible: typeof entry === 'string' guards handle mixed old/new formats

Affected files: src/domain/graph/builder/stages/build-edges.js, src/domain/graph/builder/incremental.js, src/extractors/*.js (all 8 languages)

4.3 -- Interface and Trait Implementation Tracking ✅

Extract implements/extends/trait-impl relationships from tree-sitter AST and store as implements edges. When an interface signature changes, all implementors appear in impact analysis.

Implemented:

✅ codegraph implementations <interface> command — all concrete types implementing a given interface/trait
✅ codegraph interfaces <class> command — what a type implements (inverse query)
✅ Covers: TypeScript interfaces, Java interfaces/abstract classes, Go interfaces (structural matching), Rust traits, C# interfaces, PHP interfaces, Ruby module inclusion
✅ fn-impact and diff-impact include implementors in blast radius by default (--include-implementations, on by default)
✅ bfsTransitiveCallers seeds interface/trait nodes with their implementors and traverses them transitively
✅ contextData includes implementors for interface/trait nodes and implements for class/struct nodes
✅ Go structural interface matching: post-extraction pass matches struct method sets against interface method sets (file-local)
✅ C# base type disambiguation: post-walk pass reclassifies extends entries as implements when target is a known same-file interface; also fixed base_list lookup (findChild fallback for tree-sitter-c-sharp grammar)
✅ DB layer: findImplementors(db, nodeId) and findInterfaces(db, nodeId) with cached prepared statements
✅ MCP tools: implementations and interfaces tools registered in tool registry
✅ TypeScript type definitions updated: ImplementationsResult, InterfacesResult, Repository.findImplementors/findInterfaces
✅ Integration tests: 13 tests covering implementationsData, interfacesData, contextData with implementation info, and fnImpactData with/without implementors

Affected files: src/extractors/go.js, src/extractors/csharp.js, src/domain/graph/builder/stages/build-edges.js, src/domain/analysis/impact.js, src/domain/analysis/implementations.js, src/db/repository/edges.js, src/cli/commands/implementations.js, src/cli/commands/interfaces.js, src/mcp/tools/implementations.js, src/mcp/tools/interfaces.js, src/presentation/queries-cli/inspect.js, src/types.ts

4.4 -- Call Resolution Precision/Recall Benchmark Suite ✅

Hand-annotated fixture projects per language with expected-edges.json manifests. Benchmark runner compares codegraph's resolved edges against expected, reports precision and recall. CI gate fails if metrics drop below baseline. Child-process isolation prevents state leaks between benchmark runs.

✅ tests/benchmarks/resolution/ with per-language fixtures and expected-edges manifests
✅ Benchmark runner with precision/recall reporting per language and resolution mode
✅ CI gate on accuracy regression
✅ Child-process isolation for benchmark builds (#512)

New directory: tests/benchmarks/resolution/ (#507)

4.5 -- `package.json` Exports Field Resolution ✅

Import resolution now reads package.json exports field for conditional exports, subpath patterns, and package self-references. Falls back to filesystem probing only when exports is absent.

✅ Parse package.json exports field during import resolution
✅ Support subpath patterns ("./lib/*": "./src/*.js")
✅ Support conditional exports ("import", "require", "default")
✅ Fallback to filesystem probing when exports field is absent

Affected files: src/domain/graph/resolve.js (#509)

4.6 -- Monorepo Workspace Resolution ✅

npm workspaces (package.json workspaces), pnpm-workspace.yaml, and lerna.json are now recognized. Internal package imports (@myorg/utils) resolve to actual source files with high confidence (0.95).

Scope note: This phase covers the resolution layer only — detecting workspace packages and resolving internal imports to source files. Full monorepo graph support (package node type, cross-package edges, build --workspace flag) is deferred to Phase 13.2.

✅ Detect workspace root and enumerate workspace packages
✅ Resolve internal package imports to actual source files within the monorepo
✅ High confidence (0.95) for workspace-resolved imports

Affected files: src/domain/graph/resolve.js, src/infrastructure/config.js (#509)

Phase 5 -- TypeScript Migration ✅

Status: Complete — all 271 source files migrated to TypeScript, 0 .js files remaining (v3.4.0)

Goal: Migrate the codebase from plain JavaScript to TypeScript, leveraging the clean module boundaries established in Phase 3. Incremental module-by-module migration starting from leaf modules inward.

Why after Phase 4: The resolution accuracy work (Phase 4) operates on the existing JS codebase and produces immediate accuracy gains. TypeScript migration builds on Phase 3's clean module boundaries to add type safety across the entire codebase. Every subsequent phase benefits from types: MCP schema auto-generation, API contracts, refactoring safety. The Phase 4 resolution improvements (receiver tracking, interface edges) establish the resolution model that TypeScript types will formalize.

Note: Migration is complete as of v3.4.0. All 271 source files are TypeScript. The migration proceeded leaf-inward: shared utilities → core domain → graph algorithms → builder stages → search → CLI layer → AST analysis → features → presentation → MCP tools → tests.

5.1 -- Project Setup ✅

TypeScript project configured with strict mode, ES module output, path aliases, incremental compilation, and dist/ build output with source maps. Biome configured for .ts files. package.json exports point to compiled output.

✅ typescript devDependency, tsconfig.json with strict mode
✅ Build pipeline emitting to dist/ with source maps
✅ tsc --noEmit CI type-checking gate
✅ Incremental compilation enabled

Affected files: package.json, biome.json, new tsconfig.json (#508)

5.2 -- Core Type Definitions ✅

Comprehensive TypeScript type definitions for the entire domain model — symbols, edges, nodes, config, queries, analysis results, MCP tools, and all Phase 3 abstractions.

✅ SymbolNode, Edge, SymbolKind, EdgeKind, ASTNodeKind types
✅ Repository, Engine, ASTVisitor, Extractor, Command interfaces
✅ Config, query options, analysis result types
✅ Narrowed edge kind types and ExtendedSymbolKind method

New file: src/types.ts (#516)

5.3 -- Leaf Module Migration ✅

Migrate modules with no or minimal internal dependencies. All 29 modules migrated.

Migrated (29): shared/errors, shared/kinds, shared/normalize, shared/paginate, shared/constants, shared/file-utils, shared/generators, shared/hierarchy, infrastructure/logger, infrastructure/config, infrastructure/native, infrastructure/registry, infrastructure/update-check, infrastructure/result-formatter, infrastructure/test-filter, db/repository/* (14 files), db/connection, db/index, db/migrations, db/query-builder, domain/analysis/* (9 files), presentation/colors, presentation/table — via #553, #566

5.4 -- Core Module Migration ✅

All core domain modules migrated: builder stages, search subsystem, graph utilities, incremental rebuild logic.

Migrated: db/repository/*.ts (14 files), domain/parser.ts, domain/graph/resolve.ts, extractors/*.ts (11 files), domain/graph/builder.ts + context.ts + helpers.ts + pipeline.ts, domain/graph/watcher.ts, domain/search/ (all files), graph/ (all files), domain/queries.ts, domain/graph/builder/stages/ (all 9 stages), domain/graph/{cycles,journal,change-journal}.ts

Key PRs: #554, #570, #579

5.5 -- Orchestration & Public API Migration ✅

All orchestration, features, presentation, MCP, and CLI modules migrated — including 48 CLI command handlers.

Migrated: cli.ts + cli/ (all 55 files), index.ts, ast-analysis/ (all 18 files), features/ (all 20 files), presentation/ (all 28 files), mcp/ + mcp/tools/ (all files). All stale .js counterparts deleted.

Key PRs: #555, #558, #580, #581

5.6 -- Test Migration ✅

All test files migrated from .js to .ts. Vitest TypeScript integration verified. tsc --noEmit succeeds with zero errors. No any escape hatches except at FFI boundaries (napi-rs addon, tree-sitter WASM).

Key PRs: #588

Phase 6 -- Native Analysis Acceleration

Goal: Make --engine native meaningfully faster than WASM across every build phase. At the start of this phase, only 3 of 10 build phases (parse, resolve imports, build edges) ran in Rust — the other 7 executed identical JavaScript regardless of engine. The extraction side (6.1–6.3, 6.6) is done — Rust extracts AST nodes, CFG, dataflow, and complexity during the parse phase, and the JS visitors are bypassed on native builds. But the DB-writing phases that consume that extracted data still run identical JS code on both engines, so native full builds show little-to-no speedup over WASM on most phases.

Why its own phase: This is a substantial Rust engineering effort — porting JS visitors to crates/codegraph-core/, fixing a data loss bug in incremental rebuilds, and optimizing the 1-file rebuild path. With TypeScript types (Phase 5) defining the interface contracts, the Rust ports can target well-typed boundaries. The Phase 3 module boundaries make each phase a self-contained target.

Current state (full-build: v3.3.1, 442 files · 1-file: v3.4.0, 473 files):

Phase	Native (full)	WASM (full)	Speedup	Native (1-file)	WASM (1-file)	Status
Parse	601ms	2123ms	3.5×	57ms	201ms	Rust ✅ — real speedup
Build edges	108ms	167ms	1.5×	21ms	15ms	Rust ✅ — modest; native slower on 1-file
Resolve imports	12ms	13ms	~same	2ms	2ms	Rust ✅ — no meaningful difference
AST nodes	393ms	397ms	~same	0.2ms	0.2ms	Extraction done ✅; DB write not optimized (6.9)
CFG	161ms	155ms	Rust slower	0.1ms	0.1ms	Extraction done ✅; DB write not optimized (6.10)
Dataflow	125ms	129ms	~same	0.1ms	0.2ms	Extraction done ✅; DB write not optimized (6.10)
Insert nodes	206ms	201ms	~same	8ms	8ms	JS batching ✅; no native advantage (6.11)
Complexity	171ms	216ms	1.3×	0.1ms	0.1ms	Rust pre-computation ✅; modest speedup
Roles	52ms	52ms	~same	54ms	55ms	JS batching ✅; no native advantage (6.12)
Structure	22ms	21ms	~same	26ms	24ms	JS ✅ — already fast
Total	2.7s	5.0s	1.85×	466ms	611ms	Parse carries most of the speedup

Note: Phase totals above sum to ~1.85s (native) / ~3.47s (WASM) for full builds and ~168ms / ~305ms for 1-file rebuilds. The remaining time is spent in phases not listed here: startup/initialization, dependency resolution setup, build-dependencies, finalize (orphan cleanup, unused-export marking), and CLI overhead.

Key insight: The 1.85× native speedup comes almost entirely from the Parse phase (3.5×). The other 9 phases combined show negligible native advantage because they execute the same JS/SQL code regardless of engine. The Rust extraction work (6.1–6.3, 6.6) successfully bypasses the JS visitors on native, but the DB insertion loops that store AST nodes, CFG edges, dataflow edges, and complexity rows are identical — they iterate over the extracted data in JS either way. To unlock real native speedup on these phases, the DB writes themselves need to move to Rust or be radically restructured.

Note: The dataflowMs, cfgMs, astMs, and complexityMs timings on full builds measure the DB edge/node-building phase, not the visitor walk. On 1-file rebuilds the JS visitor is fully bypassed (0.1–0.2ms) because the data was extracted during parse.

6.1 -- AST Node Extraction in Rust ✅

Complete. All 6 AST node types (call, new, string, regex, throw, await) are extracted in Rust during the native parse phase. The JS ast-store visitor is bypassed when symbols.astNodes is already an array. Parity validated via tests/engines/ast-parity.test.ts.

Key PRs: #340, #361, #591

6.2 -- CFG Construction in Rust ✅

Complete. crates/codegraph-core/src/cfg.rs computes per-function CFG blocks and edges for all 11 languages. Definition.cfg is populated during native parse. The JS CFG visitor is bypassed when d.cfg?.blocks exists. Parity validated via tests/engines/cfg-parity.test.ts.

Key PRs: #342, #344

6.3 -- Dataflow Analysis in Rust ✅

Complete. crates/codegraph-core/src/dataflow.rs implements extract_dataflow() with full scope tracking, binding resolution, and confidence scoring for all 11 languages. FileSymbols.dataflow is populated when include_dataflow=true. The JS dataflow visitor is bypassed when symbols.dataflow exists. Parity validated via tests/engines/dataflow-parity.test.ts (13 tests across Go, Rust, Ruby).

6.4 -- Batch SQLite Inserts ✅

Complete (JS-side approach). Batch inserts use better-sqlite3 multi-value INSERT statements with cached prepared statements (keyed by chunk size to avoid recompilation). Chunk size tuned to 500 rows. Export marking uses batched UPDATE ... WHERE (name=? AND kind=? AND file=? AND line=?) OR ... instead of per-export UPDATEs. The insert-nodes stage shares bulkNodeIdsByFile maps between children and edge phases. A Rust-side approach was evaluated but JS-side batching proved sufficient — the bottleneck is SQLite I/O, not JS↔native boundary crossings.

Result: Native full-build insertMs 429ms → 310ms (−28%) as of 6.4; further reduced to 206ms after v3.3.1 optimizations.

Key PRs: #361, #434

6.5 -- Role Classification & Structure Optimization ✅

Complete (JS-side approach). Role classification stays JS/SQL-based — the bottleneck is SQL query execution, not classification logic (which is simple median-threshold comparisons). The optimization replaces row-by-row UPDATE nodes SET role = ? WHERE id = ? (one statement per node, ~10k nodes) with batch UPDATE nodes SET role = ? WHERE id IN (...) grouped by role (~10 statements total). This eliminates ~10k SQLite B-tree lookups in favor of ~10 set-based updates.

Structure building is unchanged — at 22ms it's already fast.

Result: Native full-build rolesMs 268ms → 192ms (−28%) as of 6.5; further reduced to 52ms after v3.3.1 optimizations. Native 1-file rebuild rolesMs 301ms → 36ms (−88%) as of 6.5; further reduced to 9ms via 6.8 incremental path (PR #622).

6.6 -- Complete Complexity Pre-computation ✅

Complete. crates/codegraph-core/src/complexity.rs computes cognitive, cyclomatic, max nesting, Halstead, and LOC metrics for every function during native parse. Definition.complexity is populated for all functions/methods. The JS complexity visitor is bypassed when !d.complexity check passes. MI is computed JS-side from the pre-computed components.

6.7 -- Fix Incremental Rebuild Data Loss on Native Engine ✅

Complete. The original bug (analysis data silently lost on native 1-file rebuilds) is fixed. The prerequisites (6.1–6.3) are done — native parse now returns complete AST nodes, CFG blocks, and dataflow edges in FileSymbols. The unified analysis engine (src/ast-analysis/engine.ts) skips per-visitor creation when native data exists, and buildDataflowEdges/buildCFGData/buildComplexityMetrics all check for pre-computed data before falling back to WASM. Edge parity on incremental rebuilds is validated via tests/engines/ and CI (#539, #542).

Key PRs: #469, #533, #539, #542

6.8 -- Incremental Rebuild Performance (partial)

Partially complete. Roles classification is fully optimized (255ms → 9ms via incremental path with edge-neighbour expansion, PR #622). Structure batching and finalize skip are also done. Compound DB indexes restored query performance after TS migration (PR #632). Current native 1-file rebuild is ~466ms (v3.4.0, 473 files) — down from ~802ms but still above the sub-100ms target.

Done:

Incremental roles (255ms → 9ms): Only reclassify nodes from changed files + edge neighbours using indexed correlated subqueries. Global medians for threshold consistency. Parity-tested against full rebuild. Note: The benchmark table shows ~54ms for 1-file roles because the standard benchmark runs the full roles phase; the 9ms incremental path (PR #622) is used only when the builder detects a 1-file incremental rebuild
Structure batching: Replace N+1 per-file queries with 3 batch queries regardless of file count
Finalize skip: Skip advisory queries (orphaned embeddings, unused exports) during incremental builds
DB index regression: Compound indexes on nodes/edges tables restored after TS migration (PR #632)

Remaining:

Incremental edge rebuild: Only rebuild edges involving the changed file's symbols (currently edgesMs ~21ms on native, ~15ms on WASM — native is slower on 1-file)
Parse overhead: Native parse of 1 file takes ~57ms (vs 201ms WASM) — investigate tree-sitter incremental parsing to push below 10ms
Structure/roles on 1-file: Both still take ~25ms and ~54ms respectively on 1-file rebuilds — the full-build optimizations (6.5) don't apply to the incremental path
Benchmark target: Sub-100ms native 1-file rebuilds (current ~466ms on 473 files)

Key PRs: #622, #632

Affected files: src/domain/graph/builder/stages/build-structure.ts, src/domain/graph/builder/stages/build-edges.ts, src/domain/graph/builder/pipeline.ts

6.9 -- AST Node DB Write Optimization

Not started. Native extraction (6.1) successfully produces AST nodes in Rust, but the astMs full-build phase is 393ms native vs 397ms WASM — no speedup. The bottleneck is the JS loop that iterates over extracted AST nodes and inserts them into SQLite. The Rust extraction saves ~0ms because it merely shifts when the work happens (parse phase vs visitor phase), not how much work happens.

Plan:

Batch AST node inserts in Rust via napi-rs: Pass the raw AST node array directly from Rust to a native SQLite bulk-insert function, bypassing the JS iteration loop entirely. Use rusqlite with a single multi-row INSERT per chunk
Merge AST inserts into the parse phase: Instead of extracting AST nodes to a JS array and then writing them in a separate phase, write them directly to SQLite during the Rust parse walk — eliminates the intermediate array allocation and JS↔native boundary crossing
Target: astMs < 50ms on native full builds (current 393ms), representing a real 8× speedup over WASM

Affected files: crates/codegraph-core/src/lib.rs, crates/codegraph-core/src/ast_nodes.rs, src/domain/graph/builder/stages/build-ast-data.ts

6.10 -- CFG & Dataflow DB Write Optimization

Not started. Same problem as 6.9 — Rust extraction works (6.2, 6.3), but the DB write phases are identical JS code on both engines. CFG: 161ms native vs 155ms WASM (Rust is slower). Dataflow: 125ms native vs 129ms WASM (~same).

Plan:

Batch CFG/dataflow edge inserts in Rust: Same approach as 6.9 — pass extracted CFG blocks and dataflow edges directly to rusqlite bulk inserts from the Rust side, bypassing JS iteration
Investigate CFG native regression: Profile why native CFG is 4% slower than WASM on full builds — likely JS↔native serialization overhead for the cfg.blocks structure that exceeds the extraction savings
Combine with parse phase: Like 6.9, consider writing CFG edges and dataflow edges to SQLite during the Rust parse walk rather than accumulating them for a later JS phase
Target: cfgMs + dataflowMs < 50ms combined on native full builds (current 286ms)

Affected files: crates/codegraph-core/src/cfg.rs, crates/codegraph-core/src/dataflow.rs, src/domain/graph/builder/stages/build-ast-data.ts

6.11 -- Native Insert Nodes Pipeline

Not started. The insert-nodes phase (6.4) was optimized with JS-side batching, but native shows no advantage over WASM: 206ms native vs 201ms WASM. This is the single largest phase after parse on native builds.

Plan:

Rust-side SQLite writes via rusqlite: Move the entire insert-nodes loop to Rust — receive the FileSymbols[] array in Rust and write nodes, children, and edge stubs directly to SQLite without crossing back to JS
Parallel file processing: Use Rayon to parallelize node insertion across files with per-file transactions (SQLite WAL mode supports concurrent readers)
Eliminate intermediate JS objects: Currently Rust → napi-rs → JS objects → better-sqlite3 → SQLite. The new path would be Rust → rusqlite → SQLite directly
Target: insertMs < 50ms on native full builds (current 206ms)

Affected files: crates/codegraph-core/src/lib.rs, src/domain/graph/builder/stages/insert-nodes.ts

6.12 -- Native Roles & Edge Build Optimization

Not started. Roles: 52ms native ≈ 52ms WASM on full builds, 54ms on 1-file rebuilds (incremental optimization from 6.5/6.8 doesn't cover this path). Build edges: 108ms native vs 167ms WASM (1.5× — modest, but native is slower on 1-file: 21ms vs 15ms).

Plan:

Roles — move SQL to Rust: The role classification logic (median-threshold fan-in/fan-out comparisons) is simple but issues ~10 UPDATE ... WHERE id IN (...) statements. Moving this to Rust with rusqlite eliminates JS↔SQLite round-trips and allows the fan-in/fan-out aggregation + classification to happen in a single Rust function
Build edges — fix 1-file regression: Profile why native 1-file edge building (21ms) is 40% slower than WASM (15ms). Likely cause: napi-rs deserialization overhead for the caller/callee lookup data that exceeds the savings on small workloads
Build edges — Rust-side batch: For full builds, move the edge resolution loop to Rust to avoid per-edge JS↔native boundary crossings
Target: rolesMs < 15ms, edgesMs < 30ms on native full builds

Affected files: crates/codegraph-core/src/lib.rs, src/domain/graph/builder/stages/build-edges.ts, src/graph/classifiers/roles.ts

Phase 7 -- Expanded Language Support

Goal: Support every major programming language that has a mature tree-sitter grammar available in both WASM (npm) and Rust (crates.io). This takes codegraph from 11 to 34 languages, covering every actively-used language where dependency and call-graph analysis is meaningful.

Why after Phase 6: The native analysis acceleration work (Phase 6) establishes the dual-engine pipeline that new language grammars plug into. Adding languages before the engine is complete would mean porting extractors twice. With Phase 6 done, each new language needs only a LANGUAGE_REGISTRY entry + extractor function, and both engines support it automatically.

7.1 -- Parser Abstraction Layer

Extract shared patterns from existing extractors into reusable helpers to reduce per-language boilerplate from ~200 lines to ~80 lines.

Helper	Purpose
`findParentNode(node, typeNames)`	Walk parent chain to find enclosing class/struct
`extractBodyMethods(bodyNode, parentName)`	Extract method definitions from a body block
`normalizeImportPath(importText)`	Cross-language import path normalization

New file: src/parser-utils.js

7.2 -- Batch 1: High Demand

Major languages with official or widely-adopted tree-sitter grammars (millions of crate downloads).

Language	Extensions	Grammar	Org	Notes
C	`.c`, `.h`	`tree-sitter-c`	Official	3.9M crate downloads
C++	`.cpp`, `.hpp`, `.cc`, `.cxx`	`tree-sitter-cpp`	Official	4.1M crate downloads
Kotlin	`.kt`, `.kts`	`tree-sitter-kotlin`	`fwcd/`	Major Android/multiplatform language
Swift	`.swift`	`tree-sitter-swift`	`alex-pinkus/`	iOS/macOS ecosystem
Scala	`.scala`, `.sc`	`tree-sitter-scala`	Official	JVM ecosystem, 1.5M crate downloads
Bash	`.sh`, `.bash`	`tree-sitter-bash`	Official	2.6M crate downloads

7.3 -- Batch 2: Growing Ecosystems

Actively maintained grammars with both npm and Rust packages available.

Language	Extensions	Grammar	Org	Notes
Elixir	`.ex`, `.exs`	`tree-sitter-elixir`	`elixir-lang/`	Official Elixir org, 1.2M crate downloads
Lua	`.lua`	`tree-sitter-lua`	`tree-sitter-grammars/`	Neovim ecosystem, 1.2M crate downloads
Dart	`.dart`	`tree-sitter-dart`	Third-party	Flutter/mobile ecosystem
Zig	`.zig`	`tree-sitter-zig`	`tree-sitter-grammars/`	Growing systems language
Haskell	`.hs`	`tree-sitter-haskell`	Official	1.0M crate downloads
OCaml	`.ml`, `.mli`	`tree-sitter-ocaml`	Official	ML family, mature grammar

7.4 -- Batch 3: Functional & BEAM

Languages with solid tree-sitter grammars and active communities.

Language	Extensions	Grammar	Org	Notes
F#	`.fs`, `.fsx`, `.fsi`	`tree-sitter-fsharp`	`ionide/`	.NET functional, Ionide community
Gleam	`.gleam`	`tree-sitter-gleam`	`gleam-lang/`	Official Gleam org, fastest-growing BEAM language
Clojure	`.clj`, `.cljs`, `.cljc`	`tree-sitter-clojure`	Third-party	JVM Lisp, active community
Julia	`.jl`	`tree-sitter-julia`	Official	Scientific computing
R	`.r`, `.R`	`tree-sitter-r`	`r-lib/`	Statistical computing, 135K crate downloads; WASM built from repo
Erlang	`.erl`, `.hrl`	`tree-sitter-erlang`	`WhatsApp/`	BEAM VM; WASM built from repo

7.5 -- Batch 4: Specialized

Language	Extensions	Grammar	Org	Notes
Solidity	`.sol`	`tree-sitter-solidity`	Third-party	Smart contracts, 787K crate downloads
Objective-C	`.m`	`tree-sitter-objc`	`tree-sitter-grammars/`	Apple legacy, 121K crate downloads
CUDA	`.cu`, `.cuh`	`tree-sitter-cuda`	`tree-sitter-grammars/`	C++ superset for GPU/ML, both npm + crate
Groovy	`.groovy`, `.gvy`	`tree-sitter-groovy`	Third-party	JVM, Gradle build scripts
Verilog/SystemVerilog	`.v`, `.sv`	`tree-sitter-verilog`	Official	HDL, 33K crate downloads

For languages where the npm package is name-squatted or missing (R, Erlang), WASM binaries can be built from the grammar repo via tree-sitter build --wasm.

Phase 8 -- Runtime & Extensibility

Goal: Harden the runtime for large codebases and open the platform to external contributors. These items were deferred from Phase 3 -- they depend on the clean module boundaries and domain layering established there, and benefit from TypeScript's type safety (Phase 5) for safe refactoring of cross-cutting concerns like caching, streaming, and plugin contracts.

Why after TypeScript Migration: Several of these items introduce new internal contracts (plugin API, cache interface, streaming protocol, engine strategy). Defining those contracts in TypeScript from the start avoids a second migration pass and gives contributors type-checked extension points (Phase 5).

8.1 -- Event-Driven Pipeline

Replace the synchronous build/analysis pipeline with an event/streaming architecture. Enables progress reporting, cancellation tokens, and bounded memory usage on large repositories (10K+ files).

Introduce a lightweight EventBus (or Node EventEmitter subclass) that pipeline stages publish to: file:parsed, resolve:complete, build:progress, build:error
CLI subscribes for progress bars and cancellation (Ctrl-C gracefully stops in-flight parsing)
MCP subscribes for streaming partial results back to the client
Programmatic API consumers can attach custom listeners (logging, metrics, CI reporters)
Back-pressure support: slow consumers don't block the pipeline; events are buffered up to a configurable high-water mark

Affected files: src/domain/graph/builder.js, src/cli/, src/mcp/

8.2 -- Unified Engine Interface (Strategy Pattern)

Replace scattered engine.name === 'native' / engine === 'wasm' branching throughout the codebase with a formal Strategy pattern. Each engine implements a common ParsingEngine interface with methods like parse(file), batchParse(files), supports(language), and capabilities().

Define a ParsingEngine interface (TypeScript) with clear input/output contracts
Implement NativeEngine and WasmEngine adapters behind this interface
The auto strategy delegates to native first, falls back to WASM per-language based on supports() checks
Remove all engine-name string comparisons from calling code -- callers interact only with the interface
Less critical now that native is the primary path, but eliminates a class of branching bugs and simplifies adding future engines (e.g., LSP-backed parsing)

Affected files: src/infrastructure/native.js, src/domain/parser.js, src/domain/graph/builder.js

8.3 -- Subgraph Export Filtering

Add focus and depth controls to codegraph export so users can produce usable visualizations of specific subsystems rather than the entire graph.

codegraph export --focus src/domain/graph/builder.js --depth 2 --format mermaid
codegraph export --focus "buildGraph" --depth 3 --format dot

--focus <file|symbol>: center the export on a specific file or symbol node
--depth <N>: include only nodes within N hops of the focus (default: 2)
--direction <in|out|both>: control traversal direction (callers, callees, or both)
Combine with existing --format flags (DOT, Mermaid, GraphML, Neo4j)
Large-graph safety: warn if the subgraph exceeds 500 nodes and suggest reducing depth

Affected files: src/features/export.js, src/presentation/export.js

8.4 -- Transitive Import-Aware Confidence

Improve import resolution accuracy by walking the import graph before falling back to proximity heuristics. Currently the 6-level priority system uses directory proximity as a strong signal, but this can mis-resolve when a symbol is re-exported through an index file several directories away.

Before proximity fallback, trace the transitive import chain: if file A imports from barrel B which re-exports from C, resolve directly to C
Track re-export chains in a lightweight in-memory graph built during the resolve phase
Confidence scores account for chain length (direct import = 1.0, one re-export hop = 0.95, two hops = 0.9, etc.)
Handles circular re-exports gracefully (cycle detection with visited set)

Affected files: src/domain/graph/resolve.js

8.5 -- Query Result Caching

Add an LRU/TTL cache layer between the analysis/query functions and the SQLite repository. With 34+ MCP tools that often run overlapping queries within a session, caching eliminates redundant DB round-trips.

Implement a QueryCache with configurable max entries (default: 1000) and TTL (default: 60s)
Cache key: deterministic hash of query name + parameters
Automatic invalidation on build (cache cleared when graph is rebuilt)
Optional --no-cache flag for debugging and benchmarking
Cache hit/miss stats exposed via codegraph stats and debug logging
MCP sessions benefit most -- typical tool sequences (context → fn-impact → file-deps) share intermediate results

Affected files: src/domain/analysis/, src/db/index.js

8.6 -- Configuration Profiles

Support named configuration profiles for monorepos and multi-service projects where different parts of the codebase need different settings.

{
  "profiles": {
    "backend": { "include": ["services/api/**"], "engine": "native", "boundaries": "onion" },
    "frontend": { "include": ["packages/web/**"], "engine": "wasm", "boundaries": false },
    "shared": { "include": ["packages/shared/**"], "check": { "maxCycles": 0 } }
  }
}

--profile <name> flag on all CLI commands
Profiles inherit from the base .codegraphrc.json and override specific fields
Each profile can specify its own include/exclude globs, engine preference, boundary rules, and check thresholds
MCP respects the active profile when scoping tool results

Affected files: src/infrastructure/config.js, src/cli/

8.7 -- Pagination Standardization

Standardize SQL-level LIMIT/OFFSET pagination across all repository queries and surface it consistently through the CLI and MCP.

All repository query methods accept { limit, offset } options with sensible defaults
CLI commands support --limit and --offset flags (or --page / --per-page for convenience)
MCP tools accept limit and offset parameters; responses include total count and hasMore flag
Eliminates ad-hoc in-memory slicing that currently happens in some query paths
Large result sets are bounded by default (e.g., 100 rows) to prevent accidental memory blowups in MCP

Affected files: src/shared/paginate.js, src/db/index.js, src/domain/analysis/, src/mcp/

8.8 -- Plugin System for Custom Commands

Allow users to extend codegraph with custom commands by dropping a JS/TS module into ~/.codegraph/plugins/ (global) or .codegraph/plugins/ (project-local).

Plugin contract:

export const meta = {
  name: 'my-command',
  description: 'Does something custom',
  args: [{ name: 'target', required: true, description: 'Symbol or file to analyze' }],
};

export function data(db: Database, args: ParsedArgs, config: Config): object {
  // Access the full codegraph DB and config
  // Return a plain object -- the framework handles formatting
}

Auto-discovered at startup; registered as CLI subcommands and (optionally) MCP tools
Plugins receive the open DB handle, parsed arguments, and resolved config
Output goes through the universal formatter (--json, --table, etc.) automatically
Plugin errors are isolated -- a failing plugin doesn't crash the main process
codegraph plugins list shows installed plugins with their source (global vs project)
Low priority until there's user demand for extensibility beyond the built-in commands

Affected files: src/cli/, src/mcp/, new src/infrastructure/plugins.js

8.9 -- Developer Experience & Onboarding

Lower the barrier to first successful use. Today codegraph requires manual install, manual config, and prior knowledge of which command to run next.

codegraph init -- interactive wizard that detects the project (languages, framework, monorepo), suggests .codegraphrc.json config, and auto-writes MCP settings for the detected editor (Claude Code, Cursor, VS Code, Zed)
Surface benchmark numbers in README -- headline performance numbers (parse time, build time, query latency) already exist internally; surface them prominently in the README so users see concrete numbers before installing
npx @optave/codegraph support -- zero-install path; ensure the package works correctly when invoked via npx without prior npm install (handle WASM grammar bootstrapping, native addon fallback)
Pre-built editor configs -- ship ready-to-use MCP/extension configs for Cursor, VS Code, and Zed (not just Claude Code); include in docs/editors/ with one-command setup instructions
Guided CLI output -- after each command, suggest the logical next step (e.g. "Next: try codegraph context <symbol> to see full context"); suppressible via --quiet or config

Affected files: new src/cli/commands/init.js, docs/benchmarks/, docs/editors/, src/presentation/result-formatter.js

8.10 -- Confidence Annotations on Query Output

Every query output should communicate its known limitations. When fn-impact shows a blast radius of 5 functions, it should note how many method-dispatch calls may be missing.

Add confidence and resolution_stats fields to all *Data() function return values
Format: { resolved: N, unresolved_method_calls: M, confidence: 0.XX }
CLI displays as a footer line: "5 affected functions (confidence: 82%, 3 unresolved method calls in scope)"
MCP tools include the fields in JSON responses

Affected files: src/domain/analysis/*.js, src/presentation/result-formatter.js

8.11 -- Shell Completion

Commander supports shell completion but it's not implemented. Basic UX gap for a CLI tool with 40+ commands.

Generate bash/zsh/fish completion scripts via Commander's built-in support
codegraph completion bash|zsh|fish outputs the script
Document in README

Affected files: src/cli/index.js

Phase 9 -- Quality, Security & Technical Debt

Goal: Harden the CI pipeline with supply-chain security, enforce test quality gates, and clean up technical debt identified by architectural audits. These items were originally scoped under Phase 5 (TypeScript Migration) but are independent of the migration itself.

9.1 -- Supply-Chain Security & Audit

Gap: No npm audit in CI pipeline. No supply-chain attestation (SLSA/SBOM). No formal security audit history.

Deliverables:

CI npm audit -- add npm audit --omit=dev step to CI pipeline; fail on critical/high vulnerabilities
SBOM generation -- produce CycloneDX or SPDX SBOM on each release via @cyclonedx/cyclonedx-npm or similar
SLSA provenance -- enable SLSA Level 2+ build provenance using actions/attest-build-provenance in the publish workflow; attach attestation to npm packages
Security audit log -- maintain docs/security/AUDIT_LOG.md documenting past audits, dependency reviews, and remediation history

Affected files: .github/workflows/ci.yml, .github/workflows/publish.yml, docs/security/

9.2 -- CI Test Quality & Coverage Gates

Gaps:

No coverage thresholds enforced in CI (coverage report runs locally only)
Embedding tests in separate workflow requiring HuggingFace token
312 setTimeout/sleep instances in tests — potential flakiness under load
No dependency audit step in CI (see also 9.1)

Deliverables:

Coverage gate -- add vitest --coverage to CI with minimum threshold (e.g. 80% lines/branches); fail the pipeline when coverage drops below the threshold
Unified test workflow -- merge embedding tests into the main CI workflow using a securely stored HF_TOKEN secret; eliminate the separate workflow
Timer cleanup -- audit and reduce setTimeout/sleep usage in tests; replace with deterministic waits (event-based, polling with backoff, or vi.useFakeTimers()) to reduce flakiness
Dependency audit step is covered by 9.1 deliverable 1.

Affected files: .github/workflows/ci.yml, vitest.config.js, tests/

9.3 -- Kill List (Technical Debt Cleanup)

Items to remove or rework, identified by architectural audit:

Remove Maintainability Index computation — The 1991 Coleman-Oman formula (171 - 5.2ln(V) - 0.23G - 16.2*ln(LOC)) was validated on Fortran and C, not modern languages with closures, async/await, and higher-order functions. Microsoft deprecated their MI implementation in 2023. Remove from ast-analysis/metrics.js and complexity output, or replace with a validated metric
Scope Halstead metrics to imperative code — Halstead operator/operand counting is meaningless for JSX, template literals, HCL, and declarative code. Either scope to imperative code blocks or remove
Migrate custom graph/model.js to graphology — graphology is already a runtime dependency. The custom model reimplements addNode, addEdge, successors, predecessors, inDegree, outDegree — all available natively in graphology. Migrate during the TypeScript migration to avoid maintaining two graph representations
Skip WASM loading on platforms with native binaries — On supported platforms (darwin-arm64, linux-x64, win32-x64), WASM should not be loaded at all. Currently loadNative() is checked on every call in resolve.js

Phase 10 -- Intelligent Embeddings

Goal: Dramatically improve semantic search quality by embedding natural-language descriptions instead of raw code.

Phase 10.3 (Hybrid Search) was completed early during Phase 2.5 -- FTS5 BM25 + semantic search with RRF fusion is already shipped in v2.7.0.

10.1 -- LLM Description Generator

For each function/method/class node, generate a concise natural-language description:

"Validates a JWT token against the provided secret and algorithm options.
 Params: token (string), options (object with secret, algorithms).
 Returns: boolean. Throws on expired tokens.
 Called by: authenticateRequest, verifySession.
 Calls: jwt.verify, validateOptions."

How it works:

Read source code from line to end_line
Extract existing JSDoc/docstring/comments if present
Query caller/callee relationships from the graph DB
Build a prompt combining code + context + relationships
Call configured LLM (OpenAI, Anthropic, Ollama, or any OpenAI-compatible API)
Batch processing with rate limiting and progress bar
Store descriptions in a new descriptions column on the nodes table

Fallback when no LLM configured: Use existing raw-code embedding (current behavior, unchanged).

Incremental: Only regenerate descriptions for nodes whose file hash changed.

New file: src/describer.js

10.2 -- Enhanced Embedding Pipeline

When descriptions exist, embed the description text instead of raw code
Keep raw code as fallback when no description is available
Add --use-descriptions flag to codegraph embed (default: true when descriptions exist)
Store embedding source type in embedding_meta (code vs description)

Expected improvement: ~12% better semantic similarity for natural-language queries.

Affected files: src/embedder.js

10.3 -- Hybrid Search ✅ Completed in Phase 2.5

Shipped in v2.7.0. FTS5 BM25 keyword search + semantic vector search with RRF fusion. Three search modes: hybrid (default), semantic, keyword.

10.4 -- Build-time Semantic Metadata

Enrich nodes with LLM-generated metadata beyond descriptions. Computed incrementally at build time (only for changed nodes), stored as columns on the nodes table.

Column	Content	Example
`side_effects`	Mutation/IO tags	`"writes DB"`, `"sends email"`, `"mutates state"`
`complexity_notes`	Responsibility count, cohesion rating	`"3 responsibilities, low cohesion -- consider splitting"`
`risk_score`	Fragility metric from graph centrality + LLM assessment	`0.82` (high fan-in + complex logic)

MCP tool: assess <name> -- returns complexity rating + specific concerns
Cascade invalidation: when a node changes, mark dependents for re-enrichment

Depends on: 8.1 (LLM provider abstraction)

10.5 -- Module Summaries

Aggregate function descriptions + dependency direction into file-level narratives.

module_summaries table -- one entry per file, re-rolled when any contained node changes
MCP tool: explain_module <file> -- returns module purpose, key exports, role in the system
naming_conventions metadata per module -- detected patterns (camelCase, snake_case, verb-first), flag outliers

Depends on: 8.1 (function-level descriptions must exist first)

Full spec: See llm-integration.md for detailed architecture, infrastructure table, and prompt design.

Phase 11 -- Natural Language Queries

Goal: Allow developers to ask questions about their codebase in plain English.

11.1 -- Query Engine

codegraph ask "How does the authentication flow work?"

Pipeline:

Embed the question using the same model as search
Retrieve top-K relevant functions/classes via hybrid search
For each result, fetch caller/callee context from the graph
Build a prompt with the question + retrieved code + graph context
Send to configured LLM for answer generation
Stream response to stdout

Context assembly strategy:

Full source of top 5 matches
Signatures of top 15 matches
1-hop caller/callee names for each match
Total context budget: ~8K tokens (configurable)

Requires: LLM API key configured (no fallback -- this is inherently an LLM feature).

New file: src/nlquery.js

11.2 -- Conversational Sessions

Multi-turn conversations with session memory.

codegraph ask "How does auth work?" --session my-session
codegraph ask "What about the token refresh?" --session my-session
codegraph sessions list
codegraph sessions clear

Store conversation history in SQLite table sessions
Include prior Q&A pairs in subsequent prompts

11.3 -- MCP Integration

New MCP tool: ask_codebase -- natural language query via MCP.

Enables AI coding agents (Claude Code, Cursor, etc.) to ask codegraph questions about the codebase.

Affected files: src/mcp.js

11.4 -- LLM-Narrated Graph Queries

Graph traversal + LLM narration for questions that require both structural data and natural-language explanation. Each query walks the graph first, then sends the structural result to the LLM for narration.

Query	Graph operation	LLM adds
`trace_flow <entry>`	BFS from entry point to leaves	Sequential narrative: "1. handler validates -> 2. calls createOrder -> 3. writes DB"
`trace_upstream <name>`	Recursive caller walk	Ranked suspects: "most likely cause is X because it modifies the same state"
`effect_analysis <name>`	Full callee tree walk, aggregate `side_effects`	"Calling X will: write to DB (via Y), send email (via Z)"
`dependency_path <A> <B>`	Shortest path(s) between two symbols	Narrates each hop: "A imports X from B because A needs to validate tokens"

Pre-computed flow_narratives table caches results for key entry points at build time, invalidated when any node in the chain changes.

Depends on: 8.4 (side_effects metadata), 8.1 (descriptions for narration context)

11.5 -- Onboarding & Navigation Tools

Help new contributors and AI agents orient in an unfamiliar codebase.

entry_points query -- graph finds roots (high fan-out, low fan-in) + LLM ranks by importance
onboarding_guide command -- generates a reading order based on dependency layers
MCP tool: get_started -- returns ordered list: "start here, then read this, then this"
change_plan <description> -- LLM reads description, graph identifies relevant modules, returns touch points and test coverage gaps

Depends on: 10.5 (module summaries for context), 11.1 (query engine)

Phase 12 -- GitHub Integration & CI

Goal: Bring codegraph's analysis into pull request workflows.

Note: Phase 2.5 delivered codegraph check (CI validation predicates with exit code 0/1), which provides the foundation for GitHub Action integration. The boundary violation, blast radius, and cycle detection predicates are already available.

12.1 -- Reusable GitHub Action

A reusable GitHub Action that runs on PRs:

codegraph build on the repository
codegraph diff-impact against the PR's base branch
codegraph check --staged to run CI predicates (cycles, blast radius, signatures, boundaries)
Posts a PR comment summarizing:
- Number of affected functions and files
- New cycles introduced (if any)
- Boundary violations
- Top impacted functions with caller counts

Configuration via .codegraphrc.json:

{ "ci": { "failOnCycles": true, "impactThreshold": 50 } }

Fail conditions: Configurable -- fail if new cycles or impact exceeds threshold.

New file: .github/actions/codegraph-ci/action.yml

12.2 -- PR Review Integration

codegraph review --pr <number>

Requires gh CLI. For each changed function:

Fetch PR diff via gh pr diff
Run diff-impact on the diff
Check: blast radius (caller count), contract changes (signature/return type), test coverage for affected callers
Generate review summary (optionally LLM-enhanced)
Post as PR comment via gh pr comment

LLM-enhanced mode (when LLM provider configured):

Risk labels per node: low (cosmetic / internal), medium (behavior change), high (breaking / public API)
Review focus ranking: rank affected files by risk x blast radius -- "review this file first"
Critical path highlighting: shortest path from a changed function to a high-fan-in entry point
Test coverage gaps: cross-reference affected code with test file graph edges

New file: src/github.js

12.3 -- Visual Impact Graphs for PRs

Extend the existing diff-impact --format mermaid foundation with CI automation and LLM annotations.

CI automation (GitHub Action):

codegraph build . (incremental, fast on CI cache)
codegraph diff-impact $BASE_REF --format mermaid -T to generate the graph
Post as PR comment -- GitHub renders Mermaid natively in markdown
Update on new pushes (edit the existing comment)

LLM-enriched annotations (when provider configured):

For each changed function: one-line summary of WHAT changed (from diff hunks)
For each affected caller: WHY it's affected -- what behavior might change downstream
Node colors shift from green -> yellow -> red based on risk labels
Overall PR risk score (aggregate of node risks weighted by centrality)

Historical context overlay:

Annotate nodes with churn data: "this function changed 12 times in the last 30 days"
Highlight fragile nodes: high churn + high fan-in = high breakage risk
Track blast radius trends: "this PR's blast radius is 2x larger than your average"

Depends on: 11.1 (GitHub Action), 8.4 (risk_score, side_effects)

12.4 -- SARIF Output

Note: SARIF output could be delivered as early as Phase 8 for IDE integration, since it only requires serializing existing cycle/check data into the SARIF JSON schema.

Add SARIF output format for cycle detection. SARIF integrates with GitHub Code Scanning, showing issues inline in the PR.

Affected files: src/export.js

12.5 -- Auto-generated Docstrings

codegraph annotate
codegraph annotate --changed-only

LLM-generated docstrings aware of callers, callees, and types. Diff-aware: only regenerate for functions whose code or dependencies changed. Stores in docstrings column on nodes table -- does not modify source files unless explicitly requested.

Depends on: 8.1 (LLM provider abstraction), 8.4 (side effects context)

Phase 13 -- Advanced Features

13.1 -- Dead Code Detection

codegraph dead
codegraph dead --exclude-exports --exclude-tests

Find functions/methods/classes with zero incoming edges (never called). Filters for exports, test files, and entry points.

Note: Phase 2.5 added role classification (dead role in structure.js) and Phase 2.7 added AST node storage (ast_query can find unreferenced exports). This extends those foundations with a dedicated command, smarter filtering, and cross-reference with exports command data.

Affected files: src/queries.js

13.2 -- Cross-Repository Support (Monorepo)

Support multi-package monorepos with cross-package edges.

Detect workspace root (package.json workspaces, pnpm-workspace.yaml, lerna.json)
Resolve internal package imports (e.g., @myorg/utils) to actual source files
Add package column to nodes table
codegraph build --workspace to scan all packages
Impact analysis across package boundaries

13.3 -- Agentic Search

Recursive reference-following search that traces connections.

codegraph agent-search "payment processing"

Pipeline:

Initial semantic search for the query
For top results, fetch 1-hop neighbors from the graph
Re-rank neighbors by relevance to the original query
Follow the most relevant references (up to configurable depth)
Return the full chain of related code

Use case: "Find everything related to payment processing" -> finds payment functions -> follows to validation -> follows to database layer -> returns complete picture.

Requires: LLM for relevance re-ranking (optional -- degrades to BFS without LLM).

New file: src/agentic-search.js

13.4 -- Refactoring Analysis

LLM-powered structural analysis that identifies refactoring opportunities. The graph provides the structural data; the LLM interprets it.

Command	Graph operation	LLM adds
`split_analysis <file>`	Cluster tightly-coupled functions within a file	Proposed split, cross-boundary edges, circular import risk
`extraction_candidates`	Find high fan-in, low internal coupling functions	Rank by utility: "pure helper" vs "has side effects, risky to move"
`signature_impact <name>`	All call sites from graph edges	Suggested new signature, adapter pattern if needed, call sites to update
`lint-names`	Detect naming patterns per module	Flag outliers against detected conventions (camelCase, snake_case, verb-first)
`hotspots`	High fan-in + high fan-out + on many paths	Ranked fragility report with explanations, `risk_score` per node
`boundary_analysis`	Graph clustering (tightly-coupled groups spanning modules)	Reorganization suggestions: "these 4 functions in 3 files all deal with auth"

Note: hotspots and boundary_analysis already have data foundations from Phase 2.5 (structure.js hotspots, boundaries.js evaluation). This phase adds LLM interpretation on top.

Depends on: 10.4 (risk_score, complexity_notes), 10.5 (module summaries)

13.5 -- Auto-generated Docstrings

codegraph annotate
codegraph annotate --changed-only

Depends on: 8.1 (LLM provider abstraction), 8.4 (side effects context)

Full spec: See llm-integration.md for detailed architecture, infrastructure tables, and prompt design for all LLM-powered features.

Verification Strategy

Each phase includes targeted verification:

Phase	Verification
1	Benchmark native vs WASM parsing on a large repo, verify identical output from both engines
2	`npm test`, manual MCP client test for all tools, config loading tests
2.5	All 59 test files pass; integration tests for every new command; engine parity tests
2.7	All 70 test files pass; CFG + AST + dataflow integration tests; extractors produce identical output to pre-refactoring inline extractors (shipped as v3.0.0)
3	All existing tests pass; each refactored module produces identical output to the pre-refactoring version; unit tests for pure analysis modules; InMemoryRepository tests
4	Hand-annotated fixture projects with expected call edges; precision ≥85%, recall ≥80% for JS/TS; dead role sub-categories produce correct classifications on codegraph's own codebase
5	`tsc --noEmit` passes with zero errors; all existing tests pass after migration; no runtime behavior changes
6	Native full-build time reduced from ~1,400ms to ~700ms; 1-file rebuild complexity/CFG/dataflow data verified non-empty on native engine
7	Event pipeline emits progress events; plugin system loads and executes a sample plugin; confidence annotations appear on query output
8	Compare `codegraph search` quality before/after descriptions; verify `side_effects` and `risk_score` populated for LLM-enriched builds
9	`codegraph ask "How does import resolution work?"` against codegraph itself; verify `trace_flow` and `get_started` produce coherent narration
10	Parse sample files for each new language, verify definitions/calls/imports
11	Test PR in a fork, verify GitHub Action comment with Mermaid graph and risk labels is posted
12	`hotspots` returns ranked list with LLM commentary; `split_analysis` produces actionable output; dead code detection filters correctly

Full integration test after all phases:

codegraph build .
codegraph embed --describe        # LLM-enhanced descriptions
codegraph search "middleware error handling"
codegraph ask "How does routing work?"
codegraph trace_flow handleRequest # LLM-narrated execution flow
codegraph hotspots                 # Fragility report with risk scores
codegraph diff-impact HEAD~5
codegraph review --pr 42           # LLM-enhanced PR review

Watch List

Technology changes to monitor that may unlock future improvements.

node:sqlite (Node.js built-in) -- primary target. Zero native dependencies, eliminates C++ addon breakage on Node major releases (better-sqlite3 already broken on Node 24/25). Currently Stability 1.1 (Active Development) as of Node 25.x. Adopt when it reaches Stability 2, or use as a fallback alongside better-sqlite3 (dual-engine pattern like native/WASM parsing). Backed by the Node.js project -- no startup risk.
libsql (SQLite fork by Turso) -- monitor only. Drop-in better-sqlite3 replacement with built-in DiskANN vector search. However, Turso is pivoting engineering focus to Limbo (full Rust SQLite rewrite), leaving libsql as legacy. Pre-1.0 (v0.5.x) with uncertain long-term maintenance. Low switching cost (API-compatible, data is standard SQLite), but not worth adopting until the Turso/Limbo situation clarifies.

Contributing

Want to help? Contributions to any phase are welcome. See CONTRIBUTING for setup instructions.

If you're interested in working on a specific phase, open an issue to discuss the approach before starting.

Uh oh!

FilesExpand file tree

ROADMAP.md

Latest commit

History

ROADMAP.md

File metadata and controls

Codegraph Roadmap

Overview

Dependency graph

Phase 1 -- Rust Core ✅

1.1 -- Rust Workspace & napi-rs Setup ✅

1.2 -- Native tree-sitter Parsing ✅

1.3 -- Incremental Parsing ✅

1.4 -- Import Resolution & Graph Algorithms in Rust ✅

1.5 -- Graceful Degradation & Migration ✅

Phase 2 -- Foundation Hardening ✅

2.1 -- Language Parser Registry ✅

2.2 -- Complete MCP Server ✅

2.3 -- Test Coverage Gaps ✅

2.4 -- Enhanced Configuration ✅

2.5 -- Multi-Repo MCP ✅

Phase 2.5 -- Analysis Expansion ✅

2.5.1 -- Complexity Metrics ✅

2.5.2 -- Community Detection & Drift ✅

2.5.3 -- Structure & Role Classification ✅

2.5.4 -- Execution Flow Tracing ✅

2.5.5 -- Temporal Coupling (Co-change Analysis) ✅

2.5.6 -- Manifesto Rule Engine ✅

2.5.7 -- Architecture Boundary Rules ✅

2.5.8 -- CI Validation Predicates (check) ✅

2.5.9 -- Composite Analysis Commands ✅

2.5.10 -- Hybrid Search ✅

2.5.11 -- Supporting Infrastructure ✅

2.5.12 -- MCP Tool Expansion ✅

Phase 2.7 -- Deep Analysis & Graph Enrichment ✅

2.7.1 -- Dataflow Analysis ✅

2.7.2 -- Expanded Node Types (Phase 1) ✅

2.7.3 -- Expanded Edge Types (Phase 2) ✅

2.7.4 -- Intraprocedural Control Flow Graph (CFG) ✅

2.7.5 -- Stored Queryable AST Nodes ✅

2.7.6 -- Extractors Refactoring ✅

2.7.7 -- normalizeSymbol Utility ✅

2.7.8 -- Interactive Graph Viewer ✅

2.7.9 -- Exports Command ✅

2.7.10 -- Export Format Expansion ✅

2.7.11 -- CLI Consolidation ✅

2.7.12 -- MCP Tool Consolidation & Expansion ✅

2.7 Summary

Phase 3 -- Architectural Refactoring ✅

3.1 -- Unified AST Analysis Framework ★ Critical ✅

3.2 -- Command/Query Separation ★ Critical ✅

3.3 -- Repository Pattern for Data Access ★ Critical ✅

3.4 -- Decompose queries.js (3,395 Lines) ✅

3.5 -- Composable MCP Tool Registry ✅

3.6 -- CLI Command Objects ✅

3.7 -- Curated Public API Surface ✅

3.8 -- Domain Error Hierarchy ✅

3.9 -- Builder Pipeline Architecture ✅

3.10 -- Embedder Subsystem Extraction ✅

3.11 -- Unified Graph Model ✅

3.12 -- Qualified Names & Hierarchical Scoping ✅

3.13 -- Testing Pyramid with InMemoryRepository ✅

3.14 -- Presentation Layer Extraction ✅

3.15 -- Domain Directory Grouping ✅

3.16 -- CLI Composability ✅

Phase 4 -- Resolution Accuracy ✅

4.1 -- Fix "Dead" Role Sub-categories ✅

4.2 -- Receiver Type Tracking for Method Dispatch ✅

4.3 -- Interface and Trait Implementation Tracking ✅

4.4 -- Call Resolution Precision/Recall Benchmark Suite ✅

4.5 -- package.json Exports Field Resolution ✅

4.6 -- Monorepo Workspace Resolution ✅

Phase 5 -- TypeScript Migration ✅

5.1 -- Project Setup ✅

5.2 -- Core Type Definitions ✅

5.3 -- Leaf Module Migration ✅

5.4 -- Core Module Migration ✅

5.5 -- Orchestration & Public API Migration ✅

5.6 -- Test Migration ✅

2.5.8 -- CI Validation Predicates (`check`) ✅

4.5 -- `package.json` Exports Field Resolution ✅