v3.0.1 Patch

Post-release fixes and dataflow multi-language expansion. This patch extends dataflow analysis (flows_to, returns, mutates edges) from JS/TS-only to all 11 supported languages, enables --cfg and --dataflow by default on builds, closes several native/WASM engine parity gaps, and fixes miscellaneous issues found during v3.0.0 dogfooding.

Features

• dataflow: extend dataflow analysis to all supported languages (Python, Go, Rust, Java, C#, PHP, Ruby, Terraform) (221a791)
• builder: enable --cfg and --dataflow by default on builds (#312)

Bug Fixes

• native: close engine parity gap between native and WASM (#292) (#309)
• native: extract new/throw/await/string/regex AST nodes in native engine (#306) (#314)
• native: bump native engine version to 3.0.0 (#305) (#310)
• queries: include role-based entry points in flow --list (#313)
• benchmark: handle missing WASM grammars gracefully in benchmark scripts (#311)
• ci: prevent duplicate benchmark PRs on stable releases (#304)

Documentation

• document dataflow multi-language support in README (851f060)
• mark resolved bugs and suggestions in dogfood reports (#316)
• add dogfood report for v3.0.0 (#307)
• update build performance, query, and incremental benchmarks for 3.0.0 (#298, #299, #300)

Chores

• ci: include Cargo.toml in publish version bump commit (#315)
• ci: replace npm ci with npm install in benchmark and license workflows (#308)

v3.0.0

Dataflow analysis, intraprocedural CFG, AST node storage, expanded node/edge types, and a streamlined CLI surface. This release introduces three new analysis dimensions — dataflow tracking (flows_to, returns, mutates edges), intraprocedural control flow graphs for all 11 supported languages, and stored queryable AST nodes (calls, new, string, regex, throw, await). The type system expands with parameter, property, and constant node kinds plus contains, parameter_of, and receiver edge kinds, enabling structural queries without reading source. Export gains GraphML, GraphSON, and Neo4j CSV formats plus an interactive HTML viewer (codegraph plot). A stable normalizeSymbol utility standardizes JSON output across all commands. The CLI surface is streamlined by consolidating redundant commands into fewer, more capable ones.

⚠ BREAKING CHANGES

• mcp: MCP tools fn_deps, symbol_path, and list_entry_points removed — use query with deps/path modes and execution_flow with list mode instead (d874aa5)
• cli: commands fn and path removed — use query instead; query --path replaced by standalone path <from> <to> (d874aa5)
• cli: commands batch-query, hotspots, manifesto, and explain removed — use batch, triage --level, check, and audit --quick respectively (4f08082)

Features

• cli: add dataflow analysis — build --dataflow extracts flows_to, returns, mutates edges tracking data movement through functions (JS/TS MVP), with dataflow command, MCP tool, and batch support (#254)
• cli: add intraprocedural control flow graph (CFG) — build --cfg constructs basic-block CFGs from tree-sitter AST, cfg command with text/DOT/Mermaid output (#274)
• cli: extend CFG to all supported languages — Python, Go, Rust, Java, C#, Ruby, PHP with per-language CFG_RULES and cross-language processIf/processSwitch/processTryCatch (#283)
• cli: add stored queryable AST nodes — persist calls, new, string, regex, throw, await nodes in ast_nodes table, queryable via ast command with SQL GLOB pattern matching (#279)
• cli: expand node types with parameter, property, constant kinds and parent_id column for sub-declaration queries across all 9 WASM extractors (#270)
• cli: add expanded edge types — contains (file→definition, parent→child), parameter_of (inverse), receiver (method-call dispatch) (#279)
• cli: add exports <file> command — per-symbol consumer analysis with re-export detection and counts (#269)
• export: add GraphML, GraphSON, Neo4j CSV formats and interactive HTML viewer (codegraph plot) with hierarchical/force/radial layouts, complexity overlays, and drill-down (#268)
• cli: add normalizeSymbol utility for stable 7-field JSON schema across all query and search commands (#267)
• cli: add batch-query multi-command mode with splitTargets() for comma-separated expansion and multiBatchData() for mixed-command orchestration (#256)
• queries: expose fileHash in where and query JSON output (#257)
• builder: add scoped rebuild for parallel agents (#269)

Bug Fixes

• queries: correct reexport query direction and add exports integration tests (#276)
• parser: correct extractor line counts and duplicate section numbering (fa7eee8)
• triage: map triage sort values to valid hotspot metrics (a1583cb)
• complexity: fix C# language ID mismatch (c_sharp → csharp) in COMPLEXITY_RULES, HALSTEAD_RULES, and COMMENT_PREFIXES (#283)
• dataflow: handle spread args, optional chaining, and reassignment in dataflow extraction (#254)

Refactoring

• consolidate MCP tools — reduce surface from 32 to 29 by merging fn_deps/symbol_path/list_entry_points into query and execution_flow (#263)
• consolidate CLI — remove 5 redundant commands (batch-query, hotspots, manifesto, explain, query --path) in favor of unified alternatives (#280)
• consolidate MCP tools to match CLI changes from PR #280 (cbda266)
• consolidate CFG rules with defaults factory and validation (#284)
• align dataflow.js with normalizeSymbol and ALL_SYMBOL_KINDS (#285)

Documentation

• add architecture audit and roadmap for v2.7.0 (5fe0a82)
• add competitive deep-dives for Joern and Narsil-MCP (#260, #262, #264, #265)
• add one-PR-one-concern rule to git conventions (#281)
• update references to consolidated CLI commands (#282)
• add TypeScript migration as Phase 4 in roadmap (#255)
• add Claude Code MCP registration to recommended practices (#273)

Chores

• add CLA Assistant workflow (#244)
• add pre-commit diff-impact hook (#271)
• remove stale benchmark files from generated/ (#275)

v2.6.0

CI validation, architecture boundaries, CODEOWNERS, multi-agent support, and incremental build reliability. This release adds a check command for CI validation predicates (complexity, coverage, staleness gates), architecture boundary enforcement via manifesto rules with an onion-architecture preset, CODEOWNERS integration for ownership queries, codegraph snapshot for DB backup/restore, hybrid BM25 + semantic search via FTS5, composite audit and triage commands for risk-driven workflows, and batch querying for multi-agent dispatch. It also fixes several incremental rebuild bugs — EISDIR crashes on directory nodes, dropped barrel-file edges, orphaned complexity rows — and adds configurable drift detection to warn when incremental results diverge from full rebuilds.

Features

• cli: add check command — CI validation predicates for complexity, coverage, staleness, and custom thresholds (0a4c1bf)
• cli: add audit command — composite risk audit combining explain + impact + health in one call (6530d27)
• cli: add triage command — composite risk audit queue for prioritized review (98b509f)
• cli: add codegraph snapshot for DB backup and restore (8d7416b)
• cli: add codegraph owners — CODEOWNERS integration for ownership queries (36c6fdb)
• manifesto: add architecture boundary rules to manifesto engine (79b9f32)
• boundaries: add onion architecture preset to boundary rules (c47ae76)
• embedder: add hybrid BM25 + semantic search via FTS5 for combined keyword and vector ranking (db3d3a3)
• batch: add batch querying for multi-agent dispatch (850ef3e)
• mcp: expose check as MCP tool (3c36ef7)

Bug Fixes

• builder: filter directory nodes from reverse-deps query to prevent EISDIR on incremental rebuilds (#241)
• builder: load unchanged barrel files into reexportMap so barrel-resolved edges aren't dropped during incremental rebuilds (#241)
• builder: purge function_complexity table on full rebuild — prevents orphaned rows accumulating across --no-incremental rebuilds (#239)
• builder: add node/edge count drift detection after incremental builds — warns when counts drift >20% and suggests --no-incremental (#240)
• builder: make drift threshold configurable via build.driftThreshold config (default 0.2) and include actual percentages in warning (#240)
• complexity: improve missing-data message — suggest --no-incremental rebuild instead of implying no graph exists (#240)
• skill: support dev build tarball installs in dogfood skill — branch Phase 0/4b pre-flight based on -dev. version detection (#233)
• ci: add --strip flag to sync-native-versions.js removing platform optionalDependencies in dev builds, fixing npm install failures (#241)
• ci: sync Cargo.toml version with package.json and automate via version script (#241)
• owners: add CODEOWNERS parse cache and tighten email validation (f35c797)
• bench: add timeout and remove redundant stdio option (978b590)
• ci: save all benchmark reports and use git-based dev versioning (267cabe)
• docs: correct ~20 inaccurate cells in feature comparison tables (572268d)
• docs: correct remaining MCP tool count in README (24/25 → 26/27) (262874a)

Testing

• add barrel-project fixture and incremental-parity test for edge consistency across rebuild modes (#241)

Refactoring

• organize generated/ into benchmarks/ and dogfood/ subdirs (35bfa3c)

Dependencies

• bump web-tree-sitter from 0.26.5 to 0.26.6 (70f26c0)
• bump tree-sitter-cli from 0.26.5 to 0.26.6 (161c2a0)
• bump @modelcontextprotocol/sdk from 1.26.0 to 1.27.1 (1385207)
• consolidate Dependabot bumps (Actions + commitlint v20) (d48be1a)

v2.5.1

Critical fix: recover missing branch-compare command and broken programmatic API. The branch-compare command and its implementation file were never committed in v2.5.0, causing codegraph branch-compare to crash and import('@optave/codegraph') to fail entirely due to a top-level re-export of the missing module. This patch recovers the full implementation (568 lines), adds an export guard test to prevent regressions, and introduces --dry-run for registry prune.

Bug Fixes

• cli: recover branch-compare implementation — command was registered in cli.js and index.js but src/branch-compare.js was never committed, crashing both the CLI command and the entire programmatic API (2ee10d4, 3d1224d)
• registry: add --dry-run flag to registry prune — preview what would be removed without deleting entries (2ee10d4)
• bench: remove unnecessary shell: true from execFileSync — minor security hardening (14d03ce)
• docs: correct dogfood benchmark data from stale v2.4.0 native binary — native complexity was reported as 2.2x slower than WASM when it's actually 47x faster (3d1224d)
• skill: add native binary version check to dogfood benchmark phase to prevent stale binary misreports (3d1224d)

Testing

• add index-exports unit test — validates all re-exports in index.js resolve without ERR_MODULE_NOT_FOUND (2ee10d4)
• add branch-compare integration tests (7 tests, 192 lines) (3d1224d)
• add registry prune --dry-run unit tests (2ee10d4)

Documentation

• update build performance benchmarks for 2.5.0 (eb52074)
• add dogfood report for v2.5.0 (3d1224d)
• reframe Principle 5 from library-first to CLI-first identity (3d1224d)

v2.5.0

Complexity analysis, community detection, execution flow tracing, and manifesto rule engine. This release adds a full code quality suite — cognitive, cyclomatic, Halstead, and Maintainability Index metrics for all 11 supported languages — with native Rust parity for maximum performance. Louvain community detection surfaces module boundaries and drift. A configurable manifesto rule engine enables CI-gated quality thresholds. Execution flow tracing lets you follow call paths through the codebase. Dev builds now publish as GitHub pre-releases instead of npm.

Features

• cli: add cognitive & cyclomatic complexity metrics with per-function and file-level analysis (35f6176)
• cli: add Halstead metrics (volume, difficulty, effort, bugs) and Maintainability Index (452d9e9)
• cli: add multi-language complexity analysis — extend metrics to all 11 supported languages (b1166e0)
• cli: add execution flow tracing — flow command and MCP tools for tracing call paths (bc33f3b)
• cli: add path command for shortest-path queries between symbols (ef0ea81)
• communities: add Louvain community detection for module boundary analysis and drift detection (f3e36ad)
• manifesto: add configurable pass/fail rule engine with warn/fail thresholds for CI gates (5a7d039)
• native: add Halstead, LOC, and MI metrics to Rust native engine — full metrics parity across all 8 extractors (44fe899)
• embedder: interactive install prompt for @huggingface/transformers when missing (8e717b2)
• builder: add build metadata tracking and excludeTests config shorthand (f65b364)
• structure: add file limit to structure tool to reduce token usage (2c565fa)
• ci: publish dev builds as GitHub pre-releases instead of npm (70c7627)
• ci: benchmark dev/release versioning and npm source resolution (5d532a6)

Performance

• native: eliminate WASM re-parse for native complexity + build optimizations (b8c8ca7)
• native: native complexity computation for all languages with phase breakdown benchmarks (231e941)

Bug Fixes

• builder: incremental rebuild drops edges from unchanged files (9c3e3ba)
• queries: scope-aware caller selection for nested functions (72497dc)
• complexity: sanitize threshold values in complexity SQL queries (c5ca1f2)
• builder: upgrade build metadata failure log from debug to warn (1c60b88)
• cli: embed --db flag, DB locking, prerelease check, build logging improvements (6a700b2)
• native: add win32 native binary to optionalDependencies, fix embedder crashes (f026c6a)
• hooks: hook resilience for git ops, regex bypass, and worktree isolation (2459cfc)
• ci: benchmark uses stale native addon from npm (83f2d4e)
• ci: preserve hand-written notes in benchmark report regeneration (2d79f18)
• ci: benchmark script regex + workflow branch naming (53fc34f)
• ci: harden benchmark workflow against transient npm failures (1b97fb9)
• ci: isolate publish concurrency by event type (529bf6f)
• ci: use npx for license-checker to avoid intermittent 403 errors (84e8e38)
• ci: force-add gitignored DEPENDENCIES.json in release workflow (fe22813)
• ci: add error handling to dev release pruning step (fe45512)

Refactoring

• simplify redundant unwrap_or pattern in complexity.rs (150c3eb)

Testing

• add unit tests for interactive install prompt (cc7c3e1)

Documentation

• complexity, communities, manifesto across all docs (8f12f66)
• correct engine parity section — 100% parity confirmed (55c8ee3)
• update build performance benchmarks (550b3b5, ea6b050, 15e893c)

v2.4.0

Co-change analysis, node roles, faster parsing, and richer Mermaid output. This release adds git co-change analysis to surface files that change together, classifies nodes by architectural role (entry/core/utility/adapter/dead/leaf), replaces the manual AST walk with tree-sitter's Query API for significantly faster JS/TS/TSX extraction, and enhances Mermaid export with subgraphs, edge labels, node shapes, and styling.

Features

• cli: add git co-change analysis — surfaces files that frequently change together using Jaccard similarity on git history (61785f7)
• cli: add node role classification — automatically labels nodes as entry, core, utility, adapter, dead, or leaf based on graph topology (165f6ca)
• cli: add --json to search, --file glob filter, --exclude to prune, exclude worktrees from vitest (00ed205)
• cli: add update notification after commands — checks npm for newer versions and displays an upgrade hint (eb3ccdf)
• export: enhance Mermaid export with subgraphs, edge labels, node shapes, and styling (ae301c0)

Performance

• parser: replace manual AST walk with tree-sitter Query API for JS/TS/TSX extraction (fb6a139)
• builder: avoid disk reads for line counts during incremental rebuild (7b538bc)

Bug Fixes

• builder: preserve structure data during incremental builds (7377fd9)
• embedder: make embed command respect config embeddings.model (77ffffc)
• embedder: use DEFAULT_MODEL as single source of truth for embed default (832fa49)
• embedder: add model disposal to prevent ONNX memory leak (383e899)
• export: escape quotes in Mermaid labels (1c4ca34)
• queries: recompute Jaccard from total file counts during incremental co-change analysis (e2a771b)
• queries: collect all distinct edge kinds per pair instead of keeping only first (4f40eee)
• queries: skip keys without :: separator in role lookup (0c10e23)
• resolve: use indexOf for :: split to handle paths with colons (b9d6ae4)
• validate glob patterns and exclude names, clarify regex escaping (6cf191f)
• clean up regex escaping and remove unsupported brace from glob detection (ab0d3a0)
• ci: prevent benchmark updater from deleting README subsections (bd1682a)
• ci: add --allow-same-version to npm version in publish workflow (9edaf15)

Refactoring

• reuse coChangeForFiles in diffImpactData (aef1787)

Testing

• add query vs walk parity tests for JS/TS/TSX extractors (e68f6a7)

Chores

• configure bge-large as default embedding model (c21c387)

Documentation

• add co-change analysis to README and mark backlog #9 done (f977f9c)
• reorganize docs — move guides to docs/guides/, roadmap into docs/ (ad423b7)
• move roadmap files into docs/roadmap/ (693a8aa)
• add Plan Mode Default working principle to CLAUDE.md (c682f38)

v2.3.0

Smarter embeddings, richer CLI output, and robustness fixes. This release introduces graph-enriched embedding strategies that use dependency context instead of raw source code, adds config-level test exclusion and recursive explain depth, outputs Mermaid diagrams from diff-impact, filters low-confidence edges from exports, and fixes numerous issues found through dogfooding.

Features

• embeddings: graph-enriched embedding strategy — uses callers/callees from the dependency graph instead of raw source (~100 tokens vs ~360 avg), with context window overflow detection and --strategy flag (c5dcd59)
• cli: add excludeTests config option with --include-tests CLI override (56135e7)
• cli: add --depth option to explain for recursive dependency exploration (56135e7)
• cli: add coupling score column to map command output (56135e7)
• cli: add Mermaid output to diff-impact command for visual impact diagrams (d2d767f)
• export: add --min-confidence filter (default 0.5) to DOT/Mermaid/JSON exports (08057f0)
• skill: add /dogfood skill for automated release validation — install, test, compare engines, generate report (c713ce6)
• ci: add query, incremental, and embedding regression benchmarks (0fd1967, e012426)

Performance

• parser: reduce WASM boundary crossings in JS extractor for faster parsing (d4ef6da)

Bug Fixes

• cli: graceful error for cycles, export, embed when no graph.db exists (3f56644)
• embedder: fix splitIdentifier lowercasing that broke camelCase search relevance (dd71a64)
• embedder: change default model to minilm (public, no auth required) with clear error guidance (08057f0)
• embedder: split camelCase/snake_case identifiers in embedding text for better search relevance (08057f0)
• builder: invalidate embeddings when nodes are deleted during incremental rebuild (08057f0)
• builder: handle concurrent file edits and symlink loops in watcher/builder (6735967)
• builder: use busy-wait sleep instead of Atomics.wait for broader compatibility (24f8ab1)
• builder: move engine status messages from stdout to stderr (56135e7)
• structure: treat . as no filter in structureData() (08057f0)
• hooks: add missing shebangs to husky hooks for Windows compatibility (b1e012c)
• hooks: track mv/git mv/cp commands in session edit log (cfe633b)
• ci: use PR instead of direct push for green-path version pin (beddf94)
• ci: skip dev publish when merging release version bump PR (ceb4c9a)

Refactoring

• cli: rename --include-test-source to --with-test-source for clarity (242066f)
• builder: lazy-load node:os to reduce startup overhead (603ee55)

Testing

• add readFileSafe and symlink loop detection tests (5ae1cde)
• add embedding strategy benchmark and tests (56a0517, b8ce77c)

Documentation

• add STABILITY.md with anticipated stability policy (d3dcad5)
• add LLM integration feature planning document (3ac5138)
• add feature backlog and reorganize planning docs into roadmap/ (088b797)
• reorganize README — lead with problem and value, not competition (545aa0f)
• add benchmarks section to CONTRIBUTING.md (8395059)

v2.2.1 - Patch: Default model requires auth

• Change default embedding model from jina-code to nomic-v1.5 in src/embedder.js, src/config.js, src/cli.js, and README.md
• jina-code is gated on HuggingFace and crashes without HF_TOKEN, making codegraph embed fail out-of-the-box
• nomic-v1.5 is public, same 768d dimensions, improved quality, 8192 token context
• Updated config defaults and test expectations to match

v2.2.0

New query commands, smarter call resolution, and full --no-tests coverage. This release adds explain, where, and context commands for richer code exploration, introduces three-tier incremental change detection, improves call resolution accuracy, and extends the --no-tests flag to every query command.

Features

• cli: add codegraph explain <file|function> command — structural summary without an LLM (ff72655)
• cli: add codegraph where <name> command — fast symbol lookup for definition and usage (7fafbaa)
• cli: add codegraph context <name> command — full function context (source, deps, callers) in one call (3fa88b4)
• cli: add graph quality score to stats command (130a52a)
• cli: add --no-tests flag to all remaining query commands for consistent test file filtering (937b60f)
• parser: extract symbols from Commander/Express/Event callback patterns (2ac24ef)
• builder: three-tier incremental change detection — skip unchanged, reparse modified, clean removed (4b50af1)
• hooks: add remind-codegraph hook to nudge agents before editing (e6ddeea)
• ci: automated performance benchmarks per release (f79d6f2)
• ci: add workflow_dispatch trigger for retrying failed stable releases (8d4f0cb)

Bug Fixes

• resolve: improve call resolution accuracy with scoped fallback, dedup, and built-in skip (3a11191)
• parser: add receiver field to call sites to eliminate false positive edges (b08c2b2)
• queries: statsData fully filters test nodes and edges when --no-tests is set (2f9730a)
• mcp: fix file/kind parameter handling in MCP handlers (d5af194)
• mcp: use schema objects for setRequestHandler instead of string literals (fa0d358)
• security: add path traversal guard and debug logging to file read helpers (93a9bcf)
• hooks: fix Claude Code hooks for Windows and add branch name validation (631e27a)
• hooks: add required hookSpecificOutput fields for context injection (d51a3a4)
• hooks: guard-git hook validates branch name on gh pr create (c9426fa)
• ci: rewrite Claude Code workflow for working automated PR reviews (1ed4121)
• ci: move publish artifacts to $RUNNER_TEMP to prevent repo contamination (d9849fa)
• ci: make publish workflow resilient to partial failures (5dd5b00)
• ci: validate version input in workflow_dispatch (73a1e6b)
• fix default embedding model in README and enforce LF line endings (c852707)
• exclude dev dependencies from DEPENDENCIES.md (63c6923)

Documentation

• add AI Agent Guide with 6-step workflow, command reference, and MCP mapping (5965fb4)
• rewrite adding-a-language guide for LANGUAGE_REGISTRY architecture (8504702)
• add Codegraph vs Narsil-MCP and GitNexus comparison sections to README (aac963c)
• update CLAUDE.md dogfooding section to follow recommended practices (04dbfe6)
• update Claude Code hooks section with enrichment pattern and Windows notes (4987de9)

v.2.1.0

Parser refactor, unified publish pipeline, and quality-of-life improvements. This release splits the monolithic parser into per-language extractor files, consolidates the dev and stable publish workflows into a single pipeline, adds the codegraph stats command, and hardens native engine path handling and registry management.

Features

• cli: add codegraph stats command for graph health overview — node/edge counts, language breakdown, staleness check (12f89fa)
• registry: add TTL-based pruning for idle entries — stale repos auto-removed on access (5e8c41b)
• ci: consolidate dev + stable publish into a single publish.yml workflow with automatic channel detection (bf1a16b)
• ci: add embedding regression test with real ML model validation and dedicated weekly workflow (5730a65)
• ci: add worktree workflow hooks (guard-git.sh, track-edits.sh) for parallel session safety (e16dfeb)

Bug Fixes

• hooks: replace jq with node in hooks for Windows compatibility (ac0b198)
• native: throw on explicit --engine native when addon is unavailable instead of silently falling back (02b931d)
• native: normalize import paths to remove . and .. segments in native engine (5394078)
• native: add JS-side path.normalize() defense-in-depth for native resolve (e1222df)
• registry: auto-prune stale entries and skip temp dir registration (d0f3e97)
• tests: isolate CLI tests from real registry via CODEGRAPH_REGISTRY_PATH env var (dea0c3a)
• ci: prevent publish crash on pre-existing tags (6906448)
• ci: harden publish workflow version resolution (1571f2a)
• ci: use PR-based version bumps to avoid pushing directly to protected main branch (3aab964)

Refactoring

• parser: split monolithic parser.js extractors into per-language files under src/extractors/ (92b2d23)
• parser: rename generic walk to language-specific names in all extractors (6ed1f59)

Documentation

• expand competitive analysis from 21 to 135+ tools (0a679aa)
• add competitive analysis and foundation principles (21a6708)
• reposition around always-fresh graph + optional LLM enhancement (a403acc)
• add parallel sessions rules to CLAUDE.md (1435803)