…etup-node-6

Bump actions/setup-node from 4 to 6

- structure: treat `.` as no filter in structureData() (#1)
- builder: invalidate embeddings when nodes are deleted during build,
  warn about orphaned embeddings after rebuild (#2)
- embedder: change default model to minilm (public, no auth required),
  catch auth/download errors with clear guidance (#3)
- embedder: split camelCase/snake_case identifiers in embedding text
  for better search relevance (search quality note)
- export: add --min-confidence filter (default 0.5) to DOT/Mermaid/JSON
  exports, filtering spurious low-confidence edges (#4)
- dogfood report: annotate all bugs as fixed

Impact: 8 functions changed, 8 affected

- Create docs/use-cases/titan-paradigm.md — maps Johannes R.'s multi-agent
  codebase cleanup architecture (RECON, GAUNTLET, GLOBAL SYNC, STATE MACHINE)
  to codegraph commands, roadmap items, and post-LLM-integration recommendations

- Update roadmap/BACKLOG.md: mark #4 (node classification), #9 (git change
  coupling), #1 (dead code), #2 (shortest path), #12 (execution flow) as DONE;
  add 6 new Titan Paradigm-inspired items (#21-#26): composite audit, batch
  querying, triage priority queue, change validation predicates, graph
  snapshots, MCP orchestration tools

- Update README.md: add roles + co-change to features table, differentiators,
  commands section, agent template, common flags, comparison table; update MCP
  tool count 18 → 19

- Update docs/recommended-practices.md: update MCP tool count and tool list,
  add roles/co-change/path to CLAUDE.md template and developer workflow, add
  "Understand architectural roles" and "Surface hidden coupling" sections,
  add co-change step to setup checklist

- Add full examples with real output for roles, co-change, and path to
  docs/examples/CLI.md and docs/examples/MCP.md

- Update GitHub repo description with new capabilities

- Create docs/use-cases/titan-paradigm.md — maps Johannes R.'s multi-agent
  codebase cleanup architecture (RECON, GAUNTLET, GLOBAL SYNC, STATE MACHINE)
  to codegraph commands, roadmap items, and post-LLM-integration recommendations

- Update roadmap/BACKLOG.md: mark #4 (node classification), #9 (git change
  coupling), #1 (dead code), #2 (shortest path), #12 (execution flow) as DONE;
  add 6 new Titan Paradigm-inspired items (#21-#26): composite audit, batch
  querying, triage priority queue, change validation predicates, graph
  snapshots, MCP orchestration tools

- Update README.md: add roles + co-change to features table, differentiators,
  commands section, agent template, common flags, comparison table; update MCP
  tool count 18 → 19

- Update docs/recommended-practices.md: update MCP tool count and tool list,
  add roles/co-change/path to CLAUDE.md template and developer workflow, add
  "Understand architectural roles" and "Surface hidden coupling" sections,
  add co-change step to setup checklist

- Add full examples with real output for roles, co-change, and path to
  docs/examples/CLI.md and docs/examples/MCP.md

- Update GitHub repo description with new capabilities

* feat: add codegraph path for A→B symbol pathfinding

Add `codegraph path <from> <to>` — BFS shortest-path search on the
call graph. Given two symbol names, finds the shortest call chain
with hop count, intermediate nodes, edge kinds, and alternate path
count. Supports --reverse, --max-depth, --kinds, --from-file/--to-file,
-T, -j, -k flags. Exposed as symbol_path MCP tool.

Impact: 4 functions changed, 3 affected

* docs: add Titan Paradigm use case, update docs with roles/co-change/path

- Create docs/use-cases/titan-paradigm.md — maps Johannes R.'s multi-agent
  codebase cleanup architecture (RECON, GAUNTLET, GLOBAL SYNC, STATE MACHINE)
  to codegraph commands, roadmap items, and post-LLM-integration recommendations

- Update roadmap/BACKLOG.md: mark #4 (node classification), #9 (git change
  coupling), #1 (dead code), #2 (shortest path), #12 (execution flow) as DONE;
  add 6 new Titan Paradigm-inspired items (#21-#26): composite audit, batch
  querying, triage priority queue, change validation predicates, graph
  snapshots, MCP orchestration tools

- Update README.md: add roles + co-change to features table, differentiators,
  commands section, agent template, common flags, comparison table; update MCP
  tool count 18 → 19

- Update docs/recommended-practices.md: update MCP tool count and tool list,
  add roles/co-change/path to CLAUDE.md template and developer workflow, add
  "Understand architectural roles" and "Surface hidden coupling" sections,
  add co-change step to setup checklist

- Add full examples with real output for roles, co-change, and path to
  docs/examples/CLI.md and docs/examples/MCP.md

- Update GitHub repo description with new capabilities

* docs: restore Architecture Refactoring phase, fix references

- Restore Phase 3 (Architectural Refactoring) to ROADMAP
- Renumber phases 4-8 and all cross-references
- Fix MCP tool count per Greptile review

* fix: correct MCP tool counts and backlog ID collisions

Address Greptile review comments on #121:
- Update MCP tool counts from 18/19 to 21 (22 in multi-repo mode)
  across README, recommended-practices, dogfood skill, titan-paradigm
- Add missing execution_flow and list_entry_points to tool enumeration
- Renumber new backlog items 21-26 → 27-32 to avoid collision with
  existing items 21-22

* feat: add token savings benchmark (codegraph vs raw navigation)

Adds a benchmark suite that measures how much codegraph reduces token
usage when AI agents navigate the Next.js codebase (~4k TS files).

- scripts/token-benchmark-issues.js: 5 real Next.js PRs as test cases
- scripts/token-benchmark.js: runner using Claude Agent SDK (baseline
  vs codegraph MCP), with --perf flag for build/query benchmarks
- scripts/update-token-report.js: JSON → markdown report generator
- docs/benchmarks/: methodology docs and placeholder report

Impact: 21 functions changed, 7 affected

* feat: extend benchmarks with incremental builds and expanded query coverage

benchmark.js now measures no-op rebuilds, 1-file rebuilds, and query
latency (fn-deps, fn-impact, path, roles) alongside full builds.
update-benchmark-report.js renders new Incremental Rebuilds and Query
Latency sections in BUILD-BENCHMARKS.md and adds incremental/query rows
to the README performance table. All new fields are additive for backward
compatibility.

Impact: 5 functions changed, 2 affected

* ci: include version in automated benchmark commits and PRs

Extract version from benchmark result JSON and include it in branch
names, commit messages, PR titles, and PR bodies across all 4 benchmark
jobs (build, embedding, query, incremental).

* fix: update remaining 19-tool references to 21-tool in README

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

* feat: add codegraph path for A→B symbol pathfinding

Add `codegraph path <from> <to>` — BFS shortest-path search on the
call graph. Given two symbol names, finds the shortest call chain
with hop count, intermediate nodes, edge kinds, and alternate path
count. Supports --reverse, --max-depth, --kinds, --from-file/--to-file,
-T, -j, -k flags. Exposed as symbol_path MCP tool.

Impact: 4 functions changed, 3 affected

* docs: add Titan Paradigm use case, update docs with roles/co-change/path

- Create docs/use-cases/titan-paradigm.md — maps Johannes R.'s multi-agent
  codebase cleanup architecture (RECON, GAUNTLET, GLOBAL SYNC, STATE MACHINE)
  to codegraph commands, roadmap items, and post-LLM-integration recommendations

- Update roadmap/BACKLOG.md: mark #4 (node classification), #9 (git change
  coupling), #1 (dead code), #2 (shortest path), #12 (execution flow) as DONE;
  add 6 new Titan Paradigm-inspired items (#21-#26): composite audit, batch
  querying, triage priority queue, change validation predicates, graph
  snapshots, MCP orchestration tools

- Update README.md: add roles + co-change to features table, differentiators,
  commands section, agent template, common flags, comparison table; update MCP
  tool count 18 → 19

- Update docs/recommended-practices.md: update MCP tool count and tool list,
  add roles/co-change/path to CLAUDE.md template and developer workflow, add
  "Understand architectural roles" and "Surface hidden coupling" sections,
  add co-change step to setup checklist

- Add full examples with real output for roles, co-change, and path to
  docs/examples/CLI.md and docs/examples/MCP.md

- Update GitHub repo description with new capabilities

* docs: restore Architecture Refactoring phase, fix references

- Restore Phase 3 (Architectural Refactoring) to ROADMAP
- Renumber phases 4-8 and all cross-references
- Fix MCP tool count per Greptile review

* fix: correct MCP tool counts and backlog ID collisions

Address Greptile review comments on #121:
- Update MCP tool counts from 18/19 to 21 (22 in multi-repo mode)
  across README, recommended-practices, dogfood skill, titan-paradigm
- Add missing execution_flow and list_entry_points to tool enumeration
- Renumber new backlog items 21-26 → 27-32 to avoid collision with
  existing items 21-22

* feat: add token savings benchmark (codegraph vs raw navigation)

Adds a benchmark suite that measures how much codegraph reduces token
usage when AI agents navigate the Next.js codebase (~4k TS files).

- scripts/token-benchmark-issues.js: 5 real Next.js PRs as test cases
- scripts/token-benchmark.js: runner using Claude Agent SDK (baseline
  vs codegraph MCP), with --perf flag for build/query benchmarks
- scripts/update-token-report.js: JSON → markdown report generator
- docs/benchmarks/: methodology docs and placeholder report

Impact: 21 functions changed, 7 affected

* feat: extend benchmarks with incremental builds and expanded query coverage

benchmark.js now measures no-op rebuilds, 1-file rebuilds, and query
latency (fn-deps, fn-impact, path, roles) alongside full builds.
update-benchmark-report.js renders new Incremental Rebuilds and Query
Latency sections in BUILD-BENCHMARKS.md and adds incremental/query rows
to the README performance table. All new fields are additive for backward
compatibility.

Impact: 5 functions changed, 2 affected

* ci: include version in automated benchmark commits and PRs

Extract version from benchmark result JSON and include it in branch
names, commit messages, PR titles, and PR bodies across all 4 benchmark
jobs (build, embedding, query, incremental).

* fix: update remaining 19-tool references to 21-tool in README

* docs: remove "viral" from titan paradigm LinkedIn reference

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

* feat: add codegraph path for A→B symbol pathfinding

Add `codegraph path <from> <to>` — BFS shortest-path search on the
call graph. Given two symbol names, finds the shortest call chain
with hop count, intermediate nodes, edge kinds, and alternate path
count. Supports --reverse, --max-depth, --kinds, --from-file/--to-file,
-T, -j, -k flags. Exposed as symbol_path MCP tool.

Impact: 4 functions changed, 3 affected

* docs: add Titan Paradigm use case, update docs with roles/co-change/path

- Create docs/use-cases/titan-paradigm.md — maps Johannes R.'s multi-agent
  codebase cleanup architecture (RECON, GAUNTLET, GLOBAL SYNC, STATE MACHINE)
  to codegraph commands, roadmap items, and post-LLM-integration recommendations

- Update roadmap/BACKLOG.md: mark #4 (node classification), #9 (git change
  coupling), #1 (dead code), #2 (shortest path), #12 (execution flow) as DONE;
  add 6 new Titan Paradigm-inspired items (#21-#26): composite audit, batch
  querying, triage priority queue, change validation predicates, graph
  snapshots, MCP orchestration tools

- Update README.md: add roles + co-change to features table, differentiators,
  commands section, agent template, common flags, comparison table; update MCP
  tool count 18 → 19

- Update docs/recommended-practices.md: update MCP tool count and tool list,
  add roles/co-change/path to CLAUDE.md template and developer workflow, add
  "Understand architectural roles" and "Surface hidden coupling" sections,
  add co-change step to setup checklist

- Add full examples with real output for roles, co-change, and path to
  docs/examples/CLI.md and docs/examples/MCP.md

- Update GitHub repo description with new capabilities

* docs: restore Architecture Refactoring phase, fix references

- Restore Phase 3 (Architectural Refactoring) to ROADMAP
- Renumber phases 4-8 and all cross-references
- Fix MCP tool count per Greptile review

* fix: correct MCP tool counts and backlog ID collisions

Address Greptile review comments on #121:
- Update MCP tool counts from 18/19 to 21 (22 in multi-repo mode)
  across README, recommended-practices, dogfood skill, titan-paradigm
- Add missing execution_flow and list_entry_points to tool enumeration
- Renumber new backlog items 21-26 → 27-32 to avoid collision with
  existing items 21-22

* feat: add token savings benchmark (codegraph vs raw navigation)

Adds a benchmark suite that measures how much codegraph reduces token
usage when AI agents navigate the Next.js codebase (~4k TS files).

- scripts/token-benchmark-issues.js: 5 real Next.js PRs as test cases
- scripts/token-benchmark.js: runner using Claude Agent SDK (baseline
  vs codegraph MCP), with --perf flag for build/query benchmarks
- scripts/update-token-report.js: JSON → markdown report generator
- docs/benchmarks/: methodology docs and placeholder report

Impact: 21 functions changed, 7 affected

* feat: extend benchmarks with incremental builds and expanded query coverage

benchmark.js now measures no-op rebuilds, 1-file rebuilds, and query
latency (fn-deps, fn-impact, path, roles) alongside full builds.
update-benchmark-report.js renders new Incremental Rebuilds and Query
Latency sections in BUILD-BENCHMARKS.md and adds incremental/query rows
to the README performance table. All new fields are additive for backward
compatibility.

Impact: 5 functions changed, 2 affected

* ci: include version in automated benchmark commits and PRs

Extract version from benchmark result JSON and include it in branch
names, commit messages, PR titles, and PR bodies across all 4 benchmark
jobs (build, embedding, query, incremental).

* fix: update remaining 19-tool references to 21-tool in README

* docs: remove "viral" from titan paradigm LinkedIn reference

* fix: use endLine for scope-aware caller selection in nested functions

Nested/closure functions (e.g. nodeId inside exportMermaid) were
incorrectly classified as [dead] because the caller selection loop
picked the last definition where line <= call.line, creating self-call
edges that got filtered out. Now uses endLine to find the innermost
enclosing scope, so calls within an outer function correctly attribute
the outer function as caller rather than the nested function itself.

Fixes false-positive [dead] for nodeId in branch-compare.js, export.js,
and queries.js.

Impact: 1 functions changed, 17 affected

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

* feat: add codegraph path for A→B symbol pathfinding

Add `codegraph path <from> <to>` — BFS shortest-path search on the
call graph. Given two symbol names, finds the shortest call chain
with hop count, intermediate nodes, edge kinds, and alternate path
count. Supports --reverse, --max-depth, --kinds, --from-file/--to-file,
-T, -j, -k flags. Exposed as symbol_path MCP tool.

Impact: 4 functions changed, 3 affected

* docs: add Titan Paradigm use case, update docs with roles/co-change/path

- Create docs/use-cases/titan-paradigm.md — maps Johannes R.'s multi-agent
  codebase cleanup architecture (RECON, GAUNTLET, GLOBAL SYNC, STATE MACHINE)
  to codegraph commands, roadmap items, and post-LLM-integration recommendations

- Update roadmap/BACKLOG.md: mark #4 (node classification), #9 (git change
  coupling), #1 (dead code), #2 (shortest path), #12 (execution flow) as DONE;
  add 6 new Titan Paradigm-inspired items (#21-#26): composite audit, batch
  querying, triage priority queue, change validation predicates, graph
  snapshots, MCP orchestration tools

- Update README.md: add roles + co-change to features table, differentiators,
  commands section, agent template, common flags, comparison table; update MCP
  tool count 18 → 19

- Update docs/recommended-practices.md: update MCP tool count and tool list,
  add roles/co-change/path to CLAUDE.md template and developer workflow, add
  "Understand architectural roles" and "Surface hidden coupling" sections,
  add co-change step to setup checklist

- Add full examples with real output for roles, co-change, and path to
  docs/examples/CLI.md and docs/examples/MCP.md

- Update GitHub repo description with new capabilities

* docs: restore Architecture Refactoring phase, fix references

- Restore Phase 3 (Architectural Refactoring) to ROADMAP
- Renumber phases 4-8 and all cross-references
- Fix MCP tool count per Greptile review

* fix: correct MCP tool counts and backlog ID collisions

Address Greptile review comments on #121:
- Update MCP tool counts from 18/19 to 21 (22 in multi-repo mode)
  across README, recommended-practices, dogfood skill, titan-paradigm
- Add missing execution_flow and list_entry_points to tool enumeration
- Renumber new backlog items 21-26 → 27-32 to avoid collision with
  existing items 21-22

* feat: add token savings benchmark (codegraph vs raw navigation)

Adds a benchmark suite that measures how much codegraph reduces token
usage when AI agents navigate the Next.js codebase (~4k TS files).

- scripts/token-benchmark-issues.js: 5 real Next.js PRs as test cases
- scripts/token-benchmark.js: runner using Claude Agent SDK (baseline
  vs codegraph MCP), with --perf flag for build/query benchmarks
- scripts/update-token-report.js: JSON → markdown report generator
- docs/benchmarks/: methodology docs and placeholder report

Impact: 21 functions changed, 7 affected

* feat: extend benchmarks with incremental builds and expanded query coverage

benchmark.js now measures no-op rebuilds, 1-file rebuilds, and query
latency (fn-deps, fn-impact, path, roles) alongside full builds.
update-benchmark-report.js renders new Incremental Rebuilds and Query
Latency sections in BUILD-BENCHMARKS.md and adds incremental/query rows
to the README performance table. All new fields are additive for backward
compatibility.

Impact: 5 functions changed, 2 affected

* ci: include version in automated benchmark commits and PRs

Extract version from benchmark result JSON and include it in branch
names, commit messages, PR titles, and PR bodies across all 4 benchmark
jobs (build, embedding, query, incremental).

* fix: update remaining 19-tool references to 21-tool in README

* docs: remove "viral" from titan paradigm LinkedIn reference

* fix: use endLine for scope-aware caller selection in nested functions

Nested/closure functions (e.g. nodeId inside exportMermaid) were
incorrectly classified as [dead] because the caller selection loop
picked the last definition where line <= call.line, creating self-call
edges that got filtered out. Now uses endLine to find the innermost
enclosing scope, so calls within an outer function correctly attribute
the outer function as caller rather than the nested function itself.

Fixes false-positive [dead] for nodeId in branch-compare.js, export.js,
and queries.js.

Impact: 1 functions changed, 17 affected

* feat: add cognitive & cyclomatic complexity metrics

Compute per-function complexity during build via single-traversal DFS
of tree-sitter ASTs: cognitive (SonarSource), cyclomatic (McCabe), and
max nesting depth. Stores results in new function_complexity table
(migration v8) and surfaces them in stats, context, explain, and a
dedicated `complexity` CLI command + MCP tool.

Adds manifesto config section with warn thresholds (cognitive: 15,
cyclomatic: 10, maxNesting: 4) seeding the future rule engine.

Phase 1 supports JS/TS/TSX; unsupported languages are skipped gracefully.

Impact: 18 functions changed, 32 affected

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

…folder

Move COMPETITIVE_ANALYSIS.md into generated/competitive/ and add a
comprehensive feature-by-feature comparison against joernio/joern
(our #1-ranked competitor). Covers parsing, graph model, query language,
performance, installation, AI/MCP integration, security analysis,
developer productivity, and ecosystem across 100+ individual features.
Update FOUNDATION.md reference to the new path.

Re-evaluate all architectural recommendations against the actual
codebase as it grew from v1.4.0 (5K lines, 12 modules) to v2.6.0
(17,830 lines, 35 modules).

Architecture audit:
- Reprioritize: dual-function anti-pattern across 15 modules is now #1
  (was analysis/formatting split at #3)
- Downgrade parser plugin system from #1 to #20 (parser.js shrank to
  404 lines after native engine took over)
- Add 3 new recommendations: decompose complexity.js (2,163 lines),
  unified graph model for structure/cochange/communities, pagination
  standardization
- Update all metrics and line counts to current state

Roadmap:
- Add Phase 2.5 (Analysis Expansion) documenting 18 modules shipped
  across v2.0.0-v2.6.0 (complexity, communities, structure, flow,
  cochange, manifesto, boundaries, check, audit, batch, triage,
  hybrid search, owners, snapshot, etc.)
- Mark Phase 5.3 (Hybrid Search) as completed early in Phase 2.5
- Update Phase 3 priorities based on revised architecture analysis
- Update version to 2.6.0, language count to 11, phase count to 10
- Add Phase 8 note referencing check command foundation from 2.5

* docs: add competitive deep-dive for Joern and reorganize competitive folder

Move COMPETITIVE_ANALYSIS.md into generated/competitive/ and add a
comprehensive feature-by-feature comparison against joernio/joern
(our #1-ranked competitor). Covers parsing, graph model, query language,
performance, installation, AI/MCP integration, security analysis,
developer productivity, and ecosystem across 100+ individual features.
Update FOUNDATION.md reference to the new path.

* fix: update broken links to moved COMPETITIVE_ANALYSIS.md

README.md and docs/roadmap/BACKLOG.md still referenced the old path
at generated/COMPETITIVE_ANALYSIS.md after the file was moved to
generated/competitive/COMPETITIVE_ANALYSIS.md in #260.

* docs: add competitive deep-dive for Joern and reorganize competitive folder

Move COMPETITIVE_ANALYSIS.md into generated/competitive/ and add a
comprehensive feature-by-feature comparison against joernio/joern
(our #1-ranked competitor). Covers parsing, graph model, query language,
performance, installation, AI/MCP integration, security analysis,
developer productivity, and ecosystem across 100+ individual features.
Update FOUNDATION.md reference to the new path.

* fix: update broken links to moved COMPETITIVE_ANALYSIS.md

README.md and docs/roadmap/BACKLOG.md still referenced the old path
at generated/COMPETITIVE_ANALYSIS.md after the file was moved to
generated/competitive/COMPETITIVE_ANALYSIS.md in #260.

* docs: add Joern-inspired feature candidates with BACKLOG-style grading

Append a new "Joern-Inspired Feature Candidates" section to the Joern
competitive deep-dive. Lists 11 actionable features extracted from
Parsing & Language Support, Graph Model & Analysis Depth, and Query
Language & Interface sections — assessed with the same tier/grading
system used in BACKLOG.md (zero-dep, foundation-aligned, problem-fit,
breaking).

Tier 1 non-breaking: call-chain slicing, type-informed resolution,
error-tolerant parsing, regex filtering, Kotlin, Swift, script execution.
Tier 1 breaking: expanded node/edge types, intraprocedural CFG, stored AST.
Not adopted: 9 features with FOUNDATION.md reasoning.
Cross-references BACKLOG IDs 14 and 7.

Re-evaluate all architectural recommendations against the actual
codebase as it grew from v1.4.0 (5K lines, 12 modules) to v2.6.0
(17,830 lines, 35 modules).

Architecture audit:
- Reprioritize: dual-function anti-pattern across 15 modules is now #1
  (was analysis/formatting split at #3)
- Downgrade parser plugin system from #1 to #20 (parser.js shrank to
  404 lines after native engine took over)
- Add 3 new recommendations: decompose complexity.js (2,163 lines),
  unified graph model for structure/cochange/communities, pagination
  standardization
- Update all metrics and line counts to current state

Roadmap:
- Add Phase 2.5 (Analysis Expansion) documenting 18 modules shipped
  across v2.0.0-v2.6.0 (complexity, communities, structure, flow,
  cochange, manifesto, boundaries, check, audit, batch, triage,
  hybrid search, owners, snapshot, etc.)
- Mark Phase 5.3 (Hybrid Search) as completed early in Phase 2.5
- Update Phase 3 priorities based on revised architecture analysis
- Update version to 2.6.0, language count to 11, phase count to 10
- Add Phase 8 note referencing check command foundation from 2.5

Re-evaluate all architectural recommendations against the actual
codebase as it grew from v1.4.0 (5K lines, 12 modules) to v2.6.0
(17,830 lines, 35 modules).

Architecture audit:
- Reprioritize: dual-function anti-pattern across 15 modules is now #1
  (was analysis/formatting split at #3)
- Downgrade parser plugin system from #1 to #20 (parser.js shrank to
  404 lines after native engine took over)
- Add 3 new recommendations: decompose complexity.js (2,163 lines),
  unified graph model for structure/cochange/communities, pagination
  standardization
- Update all metrics and line counts to current state

Roadmap:
- Add Phase 2.5 (Analysis Expansion) documenting 18 modules shipped
  across v2.0.0-v2.6.0 (complexity, communities, structure, flow,
  cochange, manifesto, boundaries, check, audit, batch, triage,
  hybrid search, owners, snapshot, etc.)
- Mark Phase 5.3 (Hybrid Search) as completed early in Phase 2.5
- Update Phase 3 priorities based on revised architecture analysis
- Update version to 2.6.0, language count to 11, phase count to 10
- Add Phase 8 note referencing check command foundation from 2.5

Re-evaluate all architectural recommendations against the actual
codebase as it grew from v1.4.0 (5K lines, 12 modules) to v2.6.0
(17,830 lines, 35 modules).

Architecture audit:
- Reprioritize: dual-function anti-pattern across 15 modules is now #1
  (was analysis/formatting split at #3)
- Downgrade parser plugin system from #1 to #20 (parser.js shrank to
  404 lines after native engine took over)
- Add 3 new recommendations: decompose complexity.js (2,163 lines),
  unified graph model for structure/cochange/communities, pagination
  standardization
- Update all metrics and line counts to current state

Roadmap:
- Add Phase 2.5 (Analysis Expansion) documenting 18 modules shipped
  across v2.0.0-v2.6.0 (complexity, communities, structure, flow,
  cochange, manifesto, boundaries, check, audit, batch, triage,
  hybrid search, owners, snapshot, etc.)
- Mark Phase 5.3 (Hybrid Search) as completed early in Phase 2.5
- Update Phase 3 priorities based on revised architecture analysis
- Update version to 2.6.0, language count to 11, phase count to 10
- Add Phase 8 note referencing check command foundation from 2.5

* docs: add competitive deep-dive for Joern and reorganize competitive folder

Move COMPETITIVE_ANALYSIS.md into generated/competitive/ and add a
comprehensive feature-by-feature comparison against joernio/joern
(our optave#1-ranked competitor). Covers parsing, graph model, query language,
performance, installation, AI/MCP integration, security analysis,
developer productivity, and ecosystem across 100+ individual features.
Update FOUNDATION.md reference to the new path.

* fix: update broken links to moved COMPETITIVE_ANALYSIS.md

README.md and docs/roadmap/BACKLOG.md still referenced the old path
at generated/COMPETITIVE_ANALYSIS.md after the file was moved to
generated/competitive/COMPETITIVE_ANALYSIS.md in optave#260.

…#264)

* docs: add competitive deep-dive for Joern and reorganize competitive folder

Move COMPETITIVE_ANALYSIS.md into generated/competitive/ and add a
comprehensive feature-by-feature comparison against joernio/joern
(our optave#1-ranked competitor). Covers parsing, graph model, query language,
performance, installation, AI/MCP integration, security analysis,
developer productivity, and ecosystem across 100+ individual features.
Update FOUNDATION.md reference to the new path.

* fix: update broken links to moved COMPETITIVE_ANALYSIS.md

README.md and docs/roadmap/BACKLOG.md still referenced the old path
at generated/COMPETITIVE_ANALYSIS.md after the file was moved to
generated/competitive/COMPETITIVE_ANALYSIS.md in optave#260.

* docs: add Joern-inspired feature candidates with BACKLOG-style grading

Append a new "Joern-Inspired Feature Candidates" section to the Joern
competitive deep-dive. Lists 11 actionable features extracted from
Parsing & Language Support, Graph Model & Analysis Depth, and Query
Language & Interface sections — assessed with the same tier/grading
system used in BACKLOG.md (zero-dep, foundation-aligned, problem-fit,
breaking).

Tier 1 non-breaking: call-chain slicing, type-informed resolution,
error-tolerant parsing, regex filtering, Kotlin, Swift, script execution.
Tier 1 breaking: expanded node/edge types, intraprocedural CFG, stored AST.
Not adopted: 9 features with FOUNDATION.md reasoning.
Cross-references BACKLOG IDs 14 and 7.

Re-evaluate all architectural recommendations against the actual
codebase as it grew from v1.4.0 (5K lines, 12 modules) to v2.6.0
(17,830 lines, 35 modules).

Architecture audit:
- Reprioritize: dual-function anti-pattern across 15 modules is now optave#1
  (was analysis/formatting split at optave#3)
- Downgrade parser plugin system from optave#1 to optave#20 (parser.js shrank to
  404 lines after native engine took over)
- Add 3 new recommendations: decompose complexity.js (2,163 lines),
  unified graph model for structure/cochange/communities, pagination
  standardization
- Update all metrics and line counts to current state

Roadmap:
- Add Phase 2.5 (Analysis Expansion) documenting 18 modules shipped
  across v2.0.0-v2.6.0 (complexity, communities, structure, flow,
  cochange, manifesto, boundaries, check, audit, batch, triage,
  hybrid search, owners, snapshot, etc.)
- Mark Phase 5.3 (Hybrid Search) as completed early in Phase 2.5
- Update Phase 3 priorities based on revised architecture analysis
- Update version to 2.6.0, language count to 11, phase count to 10
- Add Phase 8 note referencing check command foundation from 2.5

…ptave#265)

* docs: add competitive deep-dive for Joern and reorganize competitive folder

Move COMPETITIVE_ANALYSIS.md into generated/competitive/ and add a
comprehensive feature-by-feature comparison against joernio/joern
(our optave#1-ranked competitor). Covers parsing, graph model, query language,
performance, installation, AI/MCP integration, security analysis,
developer productivity, and ecosystem across 100+ individual features.
Update FOUNDATION.md reference to the new path.

* fix: update broken links to moved COMPETITIVE_ANALYSIS.md

README.md and docs/roadmap/BACKLOG.md still referenced the old path
at generated/COMPETITIVE_ANALYSIS.md after the file was moved to
generated/competitive/COMPETITIVE_ANALYSIS.md in optave#260.

* docs: add Joern-inspired feature candidates with BACKLOG-style grading

Append a new "Joern-Inspired Feature Candidates" section to the Joern
competitive deep-dive. Lists 11 actionable features extracted from
Parsing & Language Support, Graph Model & Analysis Depth, and Query
Language & Interface sections — assessed with the same tier/grading
system used in BACKLOG.md (zero-dep, foundation-aligned, problem-fit,
breaking).

Tier 1 non-breaking: call-chain slicing, type-informed resolution,
error-tolerant parsing, regex filtering, Kotlin, Swift, script execution.
Tier 1 breaking: expanded node/edge types, intraprocedural CFG, stored AST.
Not adopted: 9 features with FOUNDATION.md reasoning.
Cross-references BACKLOG IDs 14 and 7.

* docs: add competitive deep-dive for Narsil-MCP with feature candidates

Comprehensive comparison across 10 dimensions: parsing (32 vs 11
languages), graph model (CFG/DFG/type inference vs complexity/roles/
communities), search (similarity/chunking vs RRF hybrid), security
(147 rules vs none), queries (90 tools vs 21 + compound commands),
performance (cold start vs incremental), install, MCP integration,
developer productivity, and ecosystem.

Feature candidates section covers all comparison sections:
- Tier 1 non-breaking (10): MCP presets, AST chunking, code similarity,
  git blame/symbol history, remote repo indexing, config wizard, Kotlin,
  Swift, Bash, Scala language support
- Tier 1 breaking (1): export map per module
- Tier 2 (2): interactive HTML viz, multiple embedding backends
- Tier 3 (2): OWASP patterns, SBOM generation
- Not adopted (10): taint, type inference, SPARQL/RDF, CCG, in-memory
  arch, 90-tool surface, browser WASM, Forgemax, LSP, license scanning
- Cross-references to BACKLOG IDs 7, 8, 10, 14 and Joern candidates
  J4, J5, J8, J9

* docs: add competitive deep-dive for Joern and reorganize competitive folder

Move COMPETITIVE_ANALYSIS.md into generated/competitive/ and add a
comprehensive feature-by-feature comparison against joernio/joern
(our optave#1-ranked competitor). Covers parsing, graph model, query language,
performance, installation, AI/MCP integration, security analysis,
developer productivity, and ecosystem across 100+ individual features.
Update FOUNDATION.md reference to the new path.

* fix: update broken links to moved COMPETITIVE_ANALYSIS.md

README.md and docs/roadmap/BACKLOG.md still referenced the old path
at generated/COMPETITIVE_ANALYSIS.md after the file was moved to
generated/competitive/COMPETITIVE_ANALYSIS.md in optave#260.

* docs: add Joern-inspired feature candidates with BACKLOG-style grading

Append a new "Joern-Inspired Feature Candidates" section to the Joern
competitive deep-dive. Lists 11 actionable features extracted from
Parsing & Language Support, Graph Model & Analysis Depth, and Query
Language & Interface sections — assessed with the same tier/grading
system used in BACKLOG.md (zero-dep, foundation-aligned, problem-fit,
breaking).

Tier 1 non-breaking: call-chain slicing, type-informed resolution,
error-tolerant parsing, regex filtering, Kotlin, Swift, script execution.
Tier 1 breaking: expanded node/edge types, intraprocedural CFG, stored AST.
Not adopted: 9 features with FOUNDATION.md reasoning.
Cross-references BACKLOG IDs 14 and 7.

* docs: add competitive deep-dive for Narsil-MCP with feature candidates

Comprehensive comparison across 10 dimensions: parsing (32 vs 11
languages), graph model (CFG/DFG/type inference vs complexity/roles/
communities), search (similarity/chunking vs RRF hybrid), security
(147 rules vs none), queries (90 tools vs 21 + compound commands),
performance (cold start vs incremental), install, MCP integration,
developer productivity, and ecosystem.

Feature candidates section covers all comparison sections:
- Tier 1 non-breaking (10): MCP presets, AST chunking, code similarity,
  git blame/symbol history, remote repo indexing, config wizard, Kotlin,
  Swift, Bash, Scala language support
- Tier 1 breaking (1): export map per module
- Tier 2 (2): interactive HTML viz, multiple embedding backends
- Tier 3 (2): OWASP patterns, SBOM generation
- Not adopted (10): taint, type inference, SPARQL/RDF, CCG, in-memory
  arch, 90-tool surface, browser WASM, Forgemax, LSP, license scanning
- Cross-references to BACKLOG IDs 7, 8, 10, 14 and Joern candidates
  J4, J5, J8, J9

* feat: add dedicated `exports <file>` command with per-symbol consumers

Implements feature N11 from the Narsil competitive analysis. The new
command provides a focused export map showing which symbols a file
exports and who calls each one, filling the gap between `explain`
(public/internal split without consumers) and `where --file` (just
export names).

Adds exportsData/fileExports to queries.js, CLI command, MCP tool,
batch support, programmatic API, and integration tests.

Impact: 7 functions changed, 15 affected

* feat: add scoped rebuild for parallel agent rollback

Extract purgeFilesFromGraph() from the inline deletion cascade in
buildGraph() for reuse. Add opts.scope and opts.noReverseDeps to
buildGraph() so agents can surgically rebuild only their changed files
without nuking other agents' graph state.

- `--scope <files...>` on `build` skips collectFiles/getChangedFiles
- `--no-reverse-deps` skips reverse-dep cascade (safe when exports unchanged)
- New `scoped_rebuild` MCP tool for multi-agent orchestration
- purgeFilesFromGraph exported from programmatic API
- Unit tests for purge function, integration tests for scoped rebuild
- Documented agent-level rollback workflow in titan-paradigm.md

Impact: 3 functions changed, 20 affected

* fix: remove leaked scoped_rebuild changes from another session

Reverts purgeFilesFromGraph export, --scope/--no-reverse-deps CLI
options, scoped_rebuild MCP tool+handler, and test list entry that
were accidentally included from a concurrent session's dirty worktree.

Impact: 2 functions changed, 1 affected

* fix: remove stale scoped-rebuild docs from titan-paradigm

The scoped_rebuild feature (--scope, --no-reverse-deps CLI options and
scoped_rebuild MCP tool) was removed in 651ddb2 but the documentation
in titan-paradigm.md still referenced it. Addresses Greptile review
feedback on PR optave#269.

* docs: update incremental benchmarks (2.6.0) (optave#251)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

* docs: update build performance benchmarks (2.6.0) (optave#249)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

* chore: release v2.6.0 (optave#245)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

* docs: update query benchmarks (2.6.0) (optave#252)

* ci: add CLA Assistant workflow and fix CLA.md (optave#244)

* docs: add Contributor License Agreement (CLA)

* ci: add CLA Assistant workflow and fix CLA.md issues

- Add .github/workflows/cla.yml using contributor-assistant/github-action@v2.6.1
  with dedicated cla-signatures branch to avoid polluting main
- Fix CLA.md: section 7→6 reference, capitalization consistency,
  control definition formatting (Roman numerals → lettered list)
- Add Acceptance section documenting the CLA bot signing process
- Add Governing Law clause (Province of Alberta, Canada)
- Update CONTRIBUTING.md with CLA signing instructions

* docs: document CLA recheck command in CONTRIBUTING.md

Address Greptile review feedback on optave#244 — add note that contributors
can comment `recheck` on a PR to re-trigger the CLA signature check.

* feat: add dataflow analysis (flows_to, returns, mutates) (optave#254)

* feat: add dataflow analysis (flows_to, returns, mutates edges)

Track how data moves through functions with three new edge types:
- flows_to: parameter/variable flows into another function as argument
- returns: call return value is captured by the caller
- mutates: parameter-derived value is mutated in-place

Opt-in via `build --dataflow` (JS/TS only for MVP). Adds schema
migration v10 (dataflow table), extractDataflow() AST walker with
scope tracking and confidence scoring, query functions (dataflowData,
dataflowPathData, dataflowImpactData), CLI command with --path and
--impact modes, MCP tool, batch support, and programmatic API exports.

Impact: 29 functions changed, 33 affected

* fix: handle spread args, optional chaining, and reassignment in dataflow

Address review feedback from Greptile:
- Track spread arguments (foo(...args)) by unwrapping spread_element
- Handle optional chaining (foo?.bar()) in callee name resolution
- Track non-declaration assignments (x = foo() without const/let/var)
  as returns edges
- Add 3 tests covering these cases

Impact: 3 functions changed, 3 affected

* docs: add TypeScript migration as Phase 4 in roadmap (optave#255)

Insert Phase 4 (TypeScript Migration) between the architectural
refactoring phase and the intelligent embeddings phase. Renumber
all subsequent phases (old 4-8 → new 5-9) including sub-section
headings, cross-references, dependency graph, and verification table.

The migration is planned after Phase 3 because the architectural
refactoring establishes clean module boundaries that serve as
natural type boundaries for incremental TS adoption.

* feat(queries): expose fileHash in where and query JSON output (optave#257)

* feat(watcher): add structured NDJSON change journal for watch mode

Write symbol-level change events to .codegraph/change-events.ndjson
during watch mode. Each line records added/removed/modified symbols
with node counts and edge data, enabling external tools to detect
rule staleness without polling. File is size-capped at 1 MB with
keep-last-half rotation.

Impact: 8 functions changed, 4 affected

* style: use template literals per biome lint

Impact: 1 functions changed, 1 affected

* feat(queries): expose file content hash in where and query JSON output

Add fileHash field to queryNameData, whereSymbolImpl, and whereFileImpl
return objects by looking up the file_hashes table. This lets consumers
(e.g. code-praxis) detect when a rule's target file has changed since
the rule was created, enabling staleness detection.

Impact: 4 functions changed, 16 affected

* style: use template literal in test fixture

* fix(change-journal): add debug/warn logging for observability

Address review feedback: debug log on successful append and rotation,
warn when a single oversized line prevents rotation.

Impact: 2 functions changed, 2 affected

* style: fix biome formatting in change-journal warn call

Impact: 1 functions changed, 1 affected

* fix(change-journal): use Buffer for byte-accurate rotation midpoint

stat.size returns bytes but String.length counts UTF-16 characters.
Read as Buffer and use buf.indexOf(0x0a) to find the newline at the
byte-level midpoint, ensuring consistent behavior with multi-byte UTF-8.

Impact: 1 functions changed, 1 affected

* feat: add batch-query command and multi-command batch mode (optave#256)

* feat: add batch-query command and multi-command batch mode

Add splitTargets() for comma-separated target expansion, multiBatchData()
for mixed-command orchestration, and a new batch-query CLI command that
defaults to 'where'. The existing batch command also gains comma splitting
and multi-command detection via --from-file/--stdin.

Impact: 5 functions changed, 3 affected

* fix: add try/catch around JSON.parse in batch and batch-query actions

Wrap --from-file and --stdin JSON parsing with error handling so malformed
input produces a clear error message instead of an unhandled exception.

* ci: allow benchmark/ branch name prefix (optave#258)

* docs: competitive deep-dive vs Joern (optave#260)

* docs: add competitive deep-dive for Joern and reorganize competitive folder

Move COMPETITIVE_ANALYSIS.md into generated/competitive/ and add a
comprehensive feature-by-feature comparison against joernio/joern
(our optave#1-ranked competitor). Covers parsing, graph model, query language,
performance, installation, AI/MCP integration, security analysis,
developer productivity, and ecosystem across 100+ individual features.
Update FOUNDATION.md reference to the new path.

* fix: update broken links to moved COMPETITIVE_ANALYSIS.md

README.md and docs/roadmap/BACKLOG.md still referenced the old path
at generated/COMPETITIVE_ANALYSIS.md after the file was moved to
generated/competitive/COMPETITIVE_ANALYSIS.md in optave#260.

* refactor!: consolidate MCP tools and CLI commands (optave#263)

Reduce MCP tool surface from 32 to 29 by merging overlapping tools:

- Rename query_function → query with deps/path modes (absorbs fn_deps + symbol_path)
- Add list mode to execution_flow (absorbs list_entry_points)
- Remove path mode from dataflow tool (now edges + impact only)
- Merge fn and path CLI commands into query (--path flag for path mode)
- Remove --path option from dataflow CLI command
- Update batch commands: remove fn, add dataflow, query uses fnDepsData
- Update MCP_DEFAULTS pagination keys

BREAKING CHANGE: MCP tools fn_deps, symbol_path, list_entry_points removed.
CLI commands fn and path removed. Use query instead.

Impact: 1 functions changed, 1 affected

* docs: competitive deep-dive — codegraph vs narsil-mcp (optave#262)

* docs: add competitive deep-dive for narsil-mcp

Comprehensive feature-by-feature analysis of narsil-mcp (postrv/narsil-mcp),
the closest head-to-head competitor to codegraph. Covers all 8 FOUNDATION.md
principles, 9 feature comparison sections with 130+ features, gap analysis,
and competitive positioning.

* fix: address Greptile review — scoring math and relative path

- Fix principle scoring from 6-0-2 to 7-0-1 (correct count from table)
- Fix relative link to COMPETITIVE_ANALYSIS.md (../ not ./)

* docs: add Joern competitive deep-dive with feature candidates (optave#264)

* docs: add competitive deep-dive for Joern and reorganize competitive folder

Move COMPETITIVE_ANALYSIS.md into generated/competitive/ and add a
comprehensive feature-by-feature comparison against joernio/joern
(our optave#1-ranked competitor). Covers parsing, graph model, query language,
performance, installation, AI/MCP integration, security analysis,
developer productivity, and ecosystem across 100+ individual features.
Update FOUNDATION.md reference to the new path.

* fix: update broken links to moved COMPETITIVE_ANALYSIS.md

README.md and docs/roadmap/BACKLOG.md still referenced the old path
at generated/COMPETITIVE_ANALYSIS.md after the file was moved to
generated/competitive/COMPETITIVE_ANALYSIS.md in optave#260.

* docs: add Joern-inspired feature candidates with BACKLOG-style grading

Append a new "Joern-Inspired Feature Candidates" section to the Joern
competitive deep-dive. Lists 11 actionable features extracted from
Parsing & Language Support, Graph Model & Analysis Depth, and Query
Language & Interface sections — assessed with the same tier/grading
system used in BACKLOG.md (zero-dep, foundation-aligned, problem-fit,
breaking).

Tier 1 non-breaking: call-chain slicing, type-informed resolution,
error-tolerant parsing, regex filtering, Kotlin, Swift, script execution.
Tier 1 breaking: expanded node/edge types, intraprocedural CFG, stored AST.
Not adopted: 9 features with FOUNDATION.md reasoning.
Cross-references BACKLOG IDs 14 and 7.

* feat: add normalizeSymbol utility for stable JSON schema

Add normalizeSymbol(row, db, hashCache) that returns a consistent
7-field symbol shape (name, kind, file, line, endLine, role, fileHash)
across all query and search commands.

Update queryNameData, fnDepsData, fnImpactData, explainFunctionImpl,
listFunctionsData, rolesData, whereSymbolImpl in queries.js and
searchData, multiSearchData, ftsSearchData, hybridSearchData in
embedder.js to use normalizeSymbol. Update SQL in listFunctionsData,
rolesData, iterListFunctions, iterRoles, _prepareSearch, and
ftsSearchData to include end_line and role columns.

Export normalizeSymbol from index.js. Add docs/json-schema.md
documenting the stable schema. Add 8 unit tests and 7 integration
schema conformance tests.

Impact: 13 functions changed, 33 affected

Impact: 14 functions changed, 42 affected

* feat: add normalizeSymbol utility for stable JSON schema (optave#267)

Add normalizeSymbol(row, db, hashCache) that returns a consistent
7-field symbol shape (name, kind, file, line, endLine, role, fileHash)
across all query and search commands.

Update queryNameData, fnDepsData, fnImpactData, explainFunctionImpl,
listFunctionsData, rolesData, whereSymbolImpl in queries.js and
searchData, multiSearchData, ftsSearchData, hybridSearchData in
embedder.js to use normalizeSymbol. Update SQL in listFunctionsData,
rolesData, iterListFunctions, iterRoles, _prepareSearch, and
ftsSearchData to include end_line and role columns.

Export normalizeSymbol from index.js. Add docs/json-schema.md
documenting the stable schema. Add 8 unit tests and 7 integration
schema conformance tests.

Impact: 13 functions changed, 33 affected

Impact: 14 functions changed, 42 affected

Impact: 13 functions changed, 21 affected

* docs: revise architecture audit and roadmap for v2.6.0 (optave#266)

Re-evaluate all architectural recommendations against the actual
codebase as it grew from v1.4.0 (5K lines, 12 modules) to v2.6.0
(17,830 lines, 35 modules).

Architecture audit:
- Reprioritize: dual-function anti-pattern across 15 modules is now optave#1
  (was analysis/formatting split at optave#3)
- Downgrade parser plugin system from optave#1 to optave#20 (parser.js shrank to
  404 lines after native engine took over)
- Add 3 new recommendations: decompose complexity.js (2,163 lines),
  unified graph model for structure/cochange/communities, pagination
  standardization
- Update all metrics and line counts to current state

Roadmap:
- Add Phase 2.5 (Analysis Expansion) documenting 18 modules shipped
  across v2.0.0-v2.6.0 (complexity, communities, structure, flow,
  cochange, manifesto, boundaries, check, audit, batch, triage,
  hybrid search, owners, snapshot, etc.)
- Mark Phase 5.3 (Hybrid Search) as completed early in Phase 2.5
- Update Phase 3 priorities based on revised architecture analysis
- Update version to 2.6.0, language count to 11, phase count to 10
- Add Phase 8 note referencing check command foundation from 2.5

* docs: add Narsil-MCP competitive deep-dive with feature candidates (optave#265)

* docs: add competitive deep-dive for Joern and reorganize competitive folder

Move COMPETITIVE_ANALYSIS.md into generated/competitive/ and add a
comprehensive feature-by-feature comparison against joernio/joern
(our optave#1-ranked competitor). Covers parsing, graph model, query language,
performance, installation, AI/MCP integration, security analysis,
developer productivity, and ecosystem across 100+ individual features.
Update FOUNDATION.md reference to the new path.

* fix: update broken links to moved COMPETITIVE_ANALYSIS.md

README.md and docs/roadmap/BACKLOG.md still referenced the old path
at generated/COMPETITIVE_ANALYSIS.md after the file was moved to
generated/competitive/COMPETITIVE_ANALYSIS.md in optave#260.

* docs: add Joern-inspired feature candidates with BACKLOG-style grading

Append a new "Joern-Inspired Feature Candidates" section to the Joern
competitive deep-dive. Lists 11 actionable features extracted from
Parsing & Language Support, Graph Model & Analysis Depth, and Query
Language & Interface sections — assessed with the same tier/grading
system used in BACKLOG.md (zero-dep, foundation-aligned, problem-fit,
breaking).

Tier 1 non-breaking: call-chain slicing, type-informed resolution,
error-tolerant parsing, regex filtering, Kotlin, Swift, script execution.
Tier 1 breaking: expanded node/edge types, intraprocedural CFG, stored AST.
Not adopted: 9 features with FOUNDATION.md reasoning.
Cross-references BACKLOG IDs 14 and 7.

* docs: add competitive deep-dive for Narsil-MCP with feature candidates

Comprehensive comparison across 10 dimensions: parsing (32 vs 11
languages), graph model (CFG/DFG/type inference vs complexity/roles/
communities), search (similarity/chunking vs RRF hybrid), security
(147 rules vs none), queries (90 tools vs 21 + compound commands),
performance (cold start vs incremental), install, MCP integration,
developer productivity, and ecosystem.

Feature candidates section covers all comparison sections:
- Tier 1 non-breaking (10): MCP presets, AST chunking, code similarity,
  git blame/symbol history, remote repo indexing, config wizard, Kotlin,
  Swift, Bash, Scala language support
- Tier 1 breaking (1): export map per module
- Tier 2 (2): interactive HTML viz, multiple embedding backends
- Tier 3 (2): OWASP patterns, SBOM generation
- Not adopted (10): taint, type inference, SPARQL/RDF, CCG, in-memory
  arch, 90-tool surface, browser WASM, Forgemax, LSP, license scanning
- Cross-references to BACKLOG IDs 7, 8, 10, 14 and Joern candidates
  J4, J5, J8, J9

* feat: add expanded edge types — contains, parameter_of, receiver (Phase 2)

Build file→definition and parent→child contains edges, parameter_of
inverse edges, and receiver edges for method-call dispatch. Add
CORE_EDGE_KINDS, STRUCTURAL_EDGE_KINDS, EVERY_EDGE_KIND constants.
Exclude structural edges from moduleMapData coupling counts. Scope
directory contains-edge cleanup to preserve symbol-level edges.

Impact: 3 functions changed, 22 affected

* chore: add pre-commit diff-impact hook (optave#271)

Add show-diff-impact.sh that automatically runs
`codegraph diff-impact --staged -T` before git commit commands.
The hook injects blast radius info as additionalContext —
informational only, never blocks commits.

* feat(export): add GraphML, GraphSON, Neo4j CSV and interactive viewer (optave#268)

* feat(export): add GraphML, GraphSON, Neo4j CSV formats and interactive HTML viewer

Add three new export formats for graph database interoperability:
- GraphML (XML standard) with file-level and function-level modes
- GraphSON (TinkerPop v3) for Gremlin/JanusGraph compatibility
- Neo4j CSV (bulk import) with separate nodes/relationships files

Add interactive HTML viewer (`codegraph plot`) powered by vis-network:
- Hierarchical, force, and radial layouts with physics toggle
- Node coloring by kind or role, search/filter, legend panel
- Configurable via .plotDotCfg JSON file

Update CLI export command, MCP export_graph tool, and programmatic API
to support all six formats.

Impact: 12 functions changed, 6 affected

* feat(plot): add drill-down, clustering, complexity overlays, and detail panel

Evolve the plot command from a static viewer into an interactive
exploration tool with rich data overlays and navigation.

Data preparation:
- Extract prepareGraphData() with complexity, fan-in/fan-out, Louvain
  community detection, directory derivation, and risk flag computation
- Seed strategies: all (default), top-fanin, entry

Interactive features:
- Detail sidebar: metrics, callers/callees lists, risk badges
- Drill-down: click-to-expand / double-click-to-collapse neighbors
- Clustering: community and directory grouping via vis-network API
- Color by: kind, role, community, complexity (MI-based borders)
- Size by: uniform, fan-in, fan-out, complexity
- Risk overlay: dead-code (dashed), high-blast-radius (shadow), low-MI

CLI options:
- --cluster, --overlay, --seed, --seed-count, --size-by, --color-by

Tests expanded from 7 to 21 covering all new data enrichment, seed
strategies, risk flags, UI elements, and config backward compatibility.

Impact: 5 functions changed, 3 affected

* fix(test): update MCP export_graph enum to include new formats

The previous commit added graphml, graphson, and neo4j export formats
to the MCP tool definition but did not update the test assertion.

* style: format mcp test after enum update

* fix(security): escape config values in HTML template to prevent XSS

Use JSON.stringify() for cfg.layout.direction, effectiveColorBy, and
cfg.clusterBy when interpolated into inline JavaScript. Replace shell
exec() with execFile() for browser-open to avoid path injection.

Impact: 1 functions changed, 1 affected

* docs: add check-readme hook to guides (optave#272)

* feat(export): add GraphML, GraphSON, Neo4j CSV formats and interactive HTML viewer

Add three new export formats for graph database interoperability:
- GraphML (XML standard) with file-level and function-level modes
- GraphSON (TinkerPop v3) for Gremlin/JanusGraph compatibility
- Neo4j CSV (bulk import) with separate nodes/relationships files

Add interactive HTML viewer (`codegraph plot`) powered by vis-network:
- Hierarchical, force, and radial layouts with physics toggle
- Node coloring by kind or role, search/filter, legend panel
- Configurable via .plotDotCfg JSON file

Update CLI export command, MCP export_graph tool, and programmatic API
to support all six formats.

Impact: 12 functions changed, 6 affected

* feat(plot): add drill-down, clustering, complexity overlays, and detail panel

Evolve the plot command from a static viewer into an interactive
exploration tool with rich data overlays and navigation.

Data preparation:
- Extract prepareGraphData() with complexity, fan-in/fan-out, Louvain
  community detection, directory derivation, and risk flag computation
- Seed strategies: all (default), top-fanin, entry

Interactive features:
- Detail sidebar: metrics, callers/callees lists, risk badges
- Drill-down: click-to-expand / double-click-to-collapse neighbors
- Clustering: community and directory grouping via vis-network API
- Color by: kind, role, community, complexity (MI-based borders)
- Size by: uniform, fan-in, fan-out, complexity
- Risk overlay: dead-code (dashed), high-blast-radius (shadow), low-MI

CLI options:
- --cluster, --overlay, --seed, --seed-count, --size-by, --color-by

Tests expanded from 7 to 21 covering all new data enrichment, seed
strategies, risk flags, UI elements, and config backward compatibility.

Impact: 5 functions changed, 3 affected

* fix(test): update MCP export_graph enum to include new formats

The previous commit added graphml, graphson, and neo4j export formats
to the MCP tool definition but did not update the test assertion.

* style: format mcp test after enum update

* fix(security): escape config values in HTML template to prevent XSS

Use JSON.stringify() for cfg.layout.direction, effectiveColorBy, and
cfg.clusterBy when interpolated into inline JavaScript. Replace shell
exec() with execFile() for browser-open to avoid path injection.

Impact: 1 functions changed, 1 affected

* docs: add check-readme hook to recommended practices and guides

Document the new check-readme.sh hook across all three doc locations:
recommended-practices.md, ai-agent-guide.md, and the hooks example
README. Adds settings.json examples, hook behavior descriptions, and
customization entries.

* feat: exports command + scoped rebuild for parallel agents (optave#269)

* docs: add competitive deep-dive for Joern and reorganize competitive folder

Move COMPETITIVE_ANALYSIS.md into generated/competitive/ and add a
comprehensive feature-by-feature comparison against joernio/joern
(our optave#1-ranked competitor). Covers parsing, graph model, query language,
performance, installation, AI/MCP integration, security analysis,
developer productivity, and ecosystem across 100+ individual features.
Update FOUNDATION.md reference to the new path.

* fix: update broken links to moved COMPETITIVE_ANALYSIS.md

README.md and docs/roadmap/BACKLOG.md still referenced the old path
at generated/COMPETITIVE_ANALYSIS.md after the file was moved to
generated/competitive/COMPETITIVE_ANALYSIS.md in optave#260.

* docs: add Joern-inspired feature candidates with BACKLOG-style grading

Append a new "Joern-Inspired Feature Candidates" section to the Joern
competitive deep-dive. Lists 11 actionable features extracted from
Parsing & Language Support, Graph Model & Analysis Depth, and Query
Language & Interface sections — assessed with the same tier/grading
system used in BACKLOG.md (zero-dep, foundation-aligned, problem-fit,
breaking).

Tier 1 non-breaking: call-chain slicing, type-informed resolution,
error-tolerant parsing, regex filtering, Kotlin, Swift, script execution.
Tier 1 breaking: expanded node/edge types, intraprocedural CFG, stored AST.
Not adopted: 9 features with FOUNDATION.md reasoning.
Cross-references BACKLOG IDs 14 and 7.

* docs: add competitive deep-dive for Narsil-MCP with feature candidates

Comprehensive comparison across 10 dimensions: parsing (32 vs 11
languages), graph model (CFG/DFG/type inference vs complexity/roles/
communities), search (similarity/chunking vs RRF hybrid), security
(147 rules vs none), queries (90 tools vs 21 + compound commands),
performance (cold start vs incremental), install, MCP integration,
developer productivity, and ecosystem.

Feature candidates section covers all comparison sections:
- Tier 1 non-breaking (10): MCP presets, AST chunking, code similarity,
  git blame/symbol history, remote repo indexing, config wizard, Kotlin,
  Swift, Bash, Scala language support
- Tier 1 breaking (1): export map per module
- Tier 2 (2): interactive HTML viz, multiple embedding backends
- Tier 3 (2): OWASP patterns, SBOM generation
- Not adopted (10): taint, type inference, SPARQL/RDF, CCG, in-memory
  arch, 90-tool surface, browser WASM, Forgemax, LSP, license scanning
- Cross-references to BACKLOG IDs 7, 8, 10, 14 and Joern candidates
  J4, J5, J8, J9

* feat: add dedicated `exports <file>` command with per-symbol consumers

Implements feature N11 from the Narsil competitive analysis. The new
command provides a focused export map showing which symbols a file
exports and who calls each one, filling the gap between `explain`
(public/internal split without consumers) and `where --file` (just
export names).

Adds exportsData/fileExports to queries.js, CLI command, MCP tool,
batch support, programmatic API, and integration tests.

Impact: 7 functions changed, 15 affected

* feat: add scoped rebuild for parallel agent rollback

Extract purgeFilesFromGraph() from the inline deletion cascade in
buildGraph() for reuse. Add opts.scope and opts.noReverseDeps to
buildGraph() so agents can surgically rebuild only their changed files
without nuking other agents' graph state.

- `--scope <files...>` on `build` skips collectFiles/getChangedFiles
- `--no-reverse-deps` skips reverse-dep cascade (safe when exports unchanged)
- New `scoped_rebuild` MCP tool for multi-agent orchestration
- purgeFilesFromGraph exported from programmatic API
- Unit tests for purge function, integration tests for scoped rebuild
- Documented agent-level rollback workflow in titan-paradigm.md

Impact: 3 functions changed, 20 affected

* fix: remove leaked scoped_rebuild changes from another session

Reverts purgeFilesFromGraph export, --scope/--no-reverse-deps CLI
options, scoped_rebuild MCP tool+handler, and test list entry that
were accidentally included from a concurrent session's dirty worktree.

Impact: 2 functions changed, 1 affected

* fix: remove stale scoped-rebuild docs from titan-paradigm

The scoped_rebuild feature (--scope, --no-reverse-deps CLI options and
scoped_rebuild MCP tool) was removed in 651ddb2 but the documentation
in titan-paradigm.md still referenced it. Addresses Greptile review
feedback on PR optave#269.

* feat: add intraprocedural control flow graph (CFG) construction

Add opt-in CFG analysis that builds basic-block control flow graphs
from tree-sitter AST for individual functions. Enables complexity-aware
impact analysis and opens the path to dataflow (def-use chains).

- DB migration v12: cfg_blocks + cfg_edges tables
- New src/cfg.js module: CFG_RULES, buildFunctionCFG, buildCFGData,
  cfgData, cfgToDOT, cfgToMermaid, cfg CLI printer
- Builder integration: --cfg flag triggers CFG after complexity pass
- CLI: `cfg <name>` command with --format text/dot/mermaid, -j, --ndjson
- MCP: cfg tool with name, format, file, kind, pagination props
- Exports findFunctionNode from complexity.js for reuse
- 24 unit tests + 11 integration tests (35 total)

Phase 1: JS/TS/TSX only. Handles if/else, for/while/do-while, switch,
try/catch/finally, break/continue (with labels), return/throw.

Impact: 27 functions changed, 36 affected

* feat: add stored queryable AST nodes (calls, new, string, regex, throw, await)

Persist selected AST nodes in a dedicated ast_nodes SQLite table during
build, queryable via CLI (codegraph ast), MCP (ast_query), and
programmatic API.

- DB migration v13: ast_nodes table with indexes on kind, name, file,
  parent, and (kind,name)
- New src/ast.js module: buildAstNodes (extraction), astQueryData/
  astQuery (query), AST_NODE_KINDS constant
- Builder integration: full-rebuild deletion, incremental cleanup,
  always-on post-parse extraction (before complexity to preserve _tree)
- CLI: codegraph ast [pattern] with -k, -f, -T, -j, --ndjson,
  --limit, --offset options
- MCP: ast_query tool with pattern, kind, file, no_tests, pagination
- JS/TS/TSX Phase 1: full AST walk for new/throw/await/string/regex;
  all languages get call nodes from symbols.calls
- Pattern matching uses SQL GLOB with auto-wrapping for substring search
- Parent node resolution via narrowest enclosing definition

Impact: 12 functions changed, 26 affected

* fix: correct misleading comment for break without enclosing loop/switch

The comment incorrectly suggested this code path handled break inside
switch cases. It actually handles break with no enclosing loop/switch
context (invalid syntax) as a no-op.

Impact: 2 functions changed, 9 affected

* docs: fix stale MCP tool references in guides

Update tool names and counts to match actual MCP server output:
- query_function → query, fn_deps/symbol_path removed (merged into query)
- list_entry_points removed (merged into execution_flow)
- Add missing tools: ast_query, cfg, dataflow, symbol_children
- Fix count: 31 tools (32 in multi-repo mode)

* feat: expand node types with parameter, property, constant kinds (optave#270)

* feat: expand node types with parameter, property, constant kinds (Phase 1)

Add sub-declaration node extraction to all 9 WASM language extractors,
enabling structural queries like "which functions take a Request param?"
or "which classes have a userId field?" without reading source code.

Schema: migration v11 adds nullable parent_id column with indexes.
Builder: insertNode links children to parent via parent_id FK.
Extractors: JS/TS, Python, Go, Rust, Java, C#, Ruby, PHP, HCL now
emit children arrays for parameters, properties, and constants.
Queries: new childrenData() function, children in contextData output.
CLI: new `children` command, EVERY_SYMBOL_KIND validation on --kind.
MCP: new `symbol_children` tool, extended kind enum on all kind fields.
Constants: CORE_SYMBOL_KINDS (10), EXTENDED_SYMBOL_KINDS (3),
EVERY_SYMBOL_KIND (13). ALL_SYMBOL_KINDS preserved for backward compat.

Native Rust engine: Definition struct gains children field but actual
extraction is deferred to Phase 2 — WASM fallback handles new kinds.

Impact: 63 functions changed, 62 affected

* feat: add expanded edge types — contains, parameter_of, receiver (Phase 2)

Build file→definition and parent→child contains edges, parameter_of
inverse edges, and receiver edges for method-call dispatch. Add
CORE_EDGE_KINDS, STRUCTURAL_EDGE_KINDS, EVERY_EDGE_KIND constants.
Exclude structural edges from moduleMapData coupling counts. Scope
directory contains-edge cleanup to preserve symbol-level edges.

Impact: 3 functions changed, 22 affected

* fix(native): add missing children field to all Rust extractors

The Definition struct gained a children field but no extractor was
updated to include it, causing 50 compilation errors. Add children: None
to every Definition initializer across all 9 language extractors.
Also fix unused variable warnings in parser_registry.rs and parallel.rs.

Impact: 13 functions changed, 10 affected

* ci: trigger workflow re-run

* feat: expand node types with parameter, property, constant kinds (Phase 1)

Add sub-declaration node extraction to all 9 WASM language extractors,
enabling structural queries like "which functions take a Request param?"
or "which classes have a userId field?" without reading source code.

Schema: migration v11 adds nullable parent_id column with indexes.
Builder: insertNode links children to parent via parent_id FK.
Extractors: JS/TS, Python, Go, Rust, Java, C#, Ruby, PHP, HCL now
emit children arrays for parameters, properties, and constants.
Queries: new childrenData() function, children in contextData output.
CLI: new `children` command, EVERY_SYMBOL_KIND validation on --kind.
MCP: new `symbol_children` tool, extended kind enum on all kind fields.
Constants: CORE_SYMBOL_KINDS (10), EXTENDED_SYMBOL_KINDS (3),
EVERY_SYMBOL_KIND (13). ALL_SYMBOL_KINDS preserved for backward compat.

Native Rust engine: Definition struct gains children field but actual
extraction is deferred to Phase 2 — WASM fallback handles new kinds.

Impact: 63 functions changed, 62 affected

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

…ge types (optave#279)

* docs: update incremental benchmarks (2.6.0) (optave#251)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

* docs: update build performance benchmarks (2.6.0) (optave#249)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

* chore: release v2.6.0 (optave#245)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

* docs: update query benchmarks (2.6.0) (optave#252)

* ci: add CLA Assistant workflow and fix CLA.md (optave#244)

* docs: add Contributor License Agreement (CLA)

* ci: add CLA Assistant workflow and fix CLA.md issues

- Add .github/workflows/cla.yml using contributor-assistant/github-action@v2.6.1
  with dedicated cla-signatures branch to avoid polluting main
- Fix CLA.md: section 7→6 reference, capitalization consistency,
  control definition formatting (Roman numerals → lettered list)
- Add Acceptance section documenting the CLA bot signing process
- Add Governing Law clause (Province of Alberta, Canada)
- Update CONTRIBUTING.md with CLA signing instructions

* docs: document CLA recheck command in CONTRIBUTING.md

Address Greptile review feedback on optave#244 — add note that contributors
can comment `recheck` on a PR to re-trigger the CLA signature check.

* feat: add dataflow analysis (flows_to, returns, mutates) (optave#254)

* feat: add dataflow analysis (flows_to, returns, mutates edges)

Track how data moves through functions with three new edge types:
- flows_to: parameter/variable flows into another function as argument
- returns: call return value is captured by the caller
- mutates: parameter-derived value is mutated in-place

Opt-in via `build --dataflow` (JS/TS only for MVP). Adds schema
migration v10 (dataflow table), extractDataflow() AST walker with
scope tracking and confidence scoring, query functions (dataflowData,
dataflowPathData, dataflowImpactData), CLI command with --path and
--impact modes, MCP tool, batch support, and programmatic API exports.

Impact: 29 functions changed, 33 affected

* fix: handle spread args, optional chaining, and reassignment in dataflow

Address review feedback from Greptile:
- Track spread arguments (foo(...args)) by unwrapping spread_element
- Handle optional chaining (foo?.bar()) in callee name resolution
- Track non-declaration assignments (x = foo() without const/let/var)
  as returns edges
- Add 3 tests covering these cases

Impact: 3 functions changed, 3 affected

* docs: add TypeScript migration as Phase 4 in roadmap (optave#255)

Insert Phase 4 (TypeScript Migration) between the architectural
refactoring phase and the intelligent embeddings phase. Renumber
all subsequent phases (old 4-8 → new 5-9) including sub-section
headings, cross-references, dependency graph, and verification table.

The migration is planned after Phase 3 because the architectural
refactoring establishes clean module boundaries that serve as
natural type boundaries for incremental TS adoption.

* feat(queries): expose fileHash in where and query JSON output (optave#257)

* feat(watcher): add structured NDJSON change journal for watch mode

Write symbol-level change events to .codegraph/change-events.ndjson
during watch mode. Each line records added/removed/modified symbols
with node counts and edge data, enabling external tools to detect
rule staleness without polling. File is size-capped at 1 MB with
keep-last-half rotation.

Impact: 8 functions changed, 4 affected

* style: use template literals per biome lint

Impact: 1 functions changed, 1 affected

* feat(queries): expose file content hash in where and query JSON output

Add fileHash field to queryNameData, whereSymbolImpl, and whereFileImpl
return objects by looking up the file_hashes table. This lets consumers
(e.g. code-praxis) detect when a rule's target file has changed since
the rule was created, enabling staleness detection.

Impact: 4 functions changed, 16 affected

* style: use template literal in test fixture

* fix(change-journal): add debug/warn logging for observability

Address review feedback: debug log on successful append and rotation,
warn when a single oversized line prevents rotation.

Impact: 2 functions changed, 2 affected

* style: fix biome formatting in change-journal warn call

Impact: 1 functions changed, 1 affected

* fix(change-journal): use Buffer for byte-accurate rotation midpoint

stat.size returns bytes but String.length counts UTF-16 characters.
Read as Buffer and use buf.indexOf(0x0a) to find the newline at the
byte-level midpoint, ensuring consistent behavior with multi-byte UTF-8.

Impact: 1 functions changed, 1 affected

* feat: add batch-query command and multi-command batch mode (optave#256)

* feat: add batch-query command and multi-command batch mode

Add splitTargets() for comma-separated target expansion, multiBatchData()
for mixed-command orchestration, and a new batch-query CLI command that
defaults to 'where'. The existing batch command also gains comma splitting
and multi-command detection via --from-file/--stdin.

Impact: 5 functions changed, 3 affected

* fix: add try/catch around JSON.parse in batch and batch-query actions

Wrap --from-file and --stdin JSON parsing with error handling so malformed
input produces a clear error message instead of an unhandled exception.

* ci: allow benchmark/ branch name prefix (optave#258)

* docs: competitive deep-dive vs Joern (optave#260)

* docs: add competitive deep-dive for Joern and reorganize competitive folder

Move COMPETITIVE_ANALYSIS.md into generated/competitive/ and add a
comprehensive feature-by-feature comparison against joernio/joern
(our optave#1-ranked competitor). Covers parsing, graph model, query language,
performance, installation, AI/MCP integration, security analysis,
developer productivity, and ecosystem across 100+ individual features.
Update FOUNDATION.md reference to the new path.

* fix: update broken links to moved COMPETITIVE_ANALYSIS.md

README.md and docs/roadmap/BACKLOG.md still referenced the old path
at generated/COMPETITIVE_ANALYSIS.md after the file was moved to
generated/competitive/COMPETITIVE_ANALYSIS.md in optave#260.

* refactor!: consolidate MCP tools and CLI commands (optave#263)

Reduce MCP tool surface from 32 to 29 by merging overlapping tools:

- Rename query_function → query with deps/path modes (absorbs fn_deps + symbol_path)
- Add list mode to execution_flow (absorbs list_entry_points)
- Remove path mode from dataflow tool (now edges + impact only)
- Merge fn and path CLI commands into query (--path flag for path mode)
- Remove --path option from dataflow CLI command
- Update batch commands: remove fn, add dataflow, query uses fnDepsData
- Update MCP_DEFAULTS pagination keys

BREAKING CHANGE: MCP tools fn_deps, symbol_path, list_entry_points removed.
CLI commands fn and path removed. Use query instead.

Impact: 1 functions changed, 1 affected

* docs: competitive deep-dive — codegraph vs narsil-mcp (optave#262)

* docs: add competitive deep-dive for narsil-mcp

Comprehensive feature-by-feature analysis of narsil-mcp (postrv/narsil-mcp),
the closest head-to-head competitor to codegraph. Covers all 8 FOUNDATION.md
principles, 9 feature comparison sections with 130+ features, gap analysis,
and competitive positioning.

* fix: address Greptile review — scoring math and relative path

- Fix principle scoring from 6-0-2 to 7-0-1 (correct count from table)
- Fix relative link to COMPETITIVE_ANALYSIS.md (../ not ./)

* docs: add Joern competitive deep-dive with feature candidates (optave#264)

* docs: add competitive deep-dive for Joern and reorganize competitive folder

Move COMPETITIVE_ANALYSIS.md into generated/competitive/ and add a
comprehensive feature-by-feature comparison against joernio/joern
(our optave#1-ranked competitor). Covers parsing, graph model, query language,
performance, installation, AI/MCP integration, security analysis,
developer productivity, and ecosystem across 100+ individual features.
Update FOUNDATION.md reference to the new path.

* fix: update broken links to moved COMPETITIVE_ANALYSIS.md

README.md and docs/roadmap/BACKLOG.md still referenced the old path
at generated/COMPETITIVE_ANALYSIS.md after the file was moved to
generated/competitive/COMPETITIVE_ANALYSIS.md in optave#260.

* docs: add Joern-inspired feature candidates with BACKLOG-style grading

Append a new "Joern-Inspired Feature Candidates" section to the Joern
competitive deep-dive. Lists 11 actionable features extracted from
Parsing & Language Support, Graph Model & Analysis Depth, and Query
Language & Interface sections — assessed with the same tier/grading
system used in BACKLOG.md (zero-dep, foundation-aligned, problem-fit,
breaking).

Tier 1 non-breaking: call-chain slicing, type-informed resolution,
error-tolerant parsing, regex filtering, Kotlin, Swift, script execution.
Tier 1 breaking: expanded node/edge types, intraprocedural CFG, stored AST.
Not adopted: 9 features with FOUNDATION.md reasoning.
Cross-references BACKLOG IDs 14 and 7.

* feat: add normalizeSymbol utility for stable JSON schema

Add normalizeSymbol(row, db, hashCache) that returns a consistent
7-field symbol shape (name, kind, file, line, endLine, role, fileHash)
across all query and search commands.

Update queryNameData, fnDepsData, fnImpactData, explainFunctionImpl,
listFunctionsData, rolesData, whereSymbolImpl in queries.js and
searchData, multiSearchData, ftsSearchData, hybridSearchData in
embedder.js to use normalizeSymbol. Update SQL in listFunctionsData,
rolesData, iterListFunctions, iterRoles, _prepareSearch, and
ftsSearchData to include end_line and role columns.

Export normalizeSymbol from index.js. Add docs/json-schema.md
documenting the stable schema. Add 8 unit tests and 7 integration
schema conformance tests.

Impact: 13 functions changed, 33 affected

Impact: 14 functions changed, 42 affected

* feat: add normalizeSymbol utility for stable JSON schema (optave#267)

Add normalizeSymbol(row, db, hashCache) that returns a consistent
7-field symbol shape (name, kind, file, line, endLine, role, fileHash)
across all query and search commands.

Update queryNameData, fnDepsData, fnImpactData, explainFunctionImpl,
listFunctionsData, rolesData, whereSymbolImpl in queries.js and
searchData, multiSearchData, ftsSearchData, hybridSearchData in
embedder.js to use normalizeSymbol. Update SQL in listFunctionsData,
rolesData, iterListFunctions, iterRoles, _prepareSearch, and
ftsSearchData to include end_line and role columns.

Export normalizeSymbol from index.js. Add docs/json-schema.md
documenting the stable schema. Add 8 unit tests and 7 integration
schema conformance tests.

Impact: 13 functions changed, 33 affected

Impact: 14 functions changed, 42 affected

Impact: 13 functions changed, 21 affected

* docs: revise architecture audit and roadmap for v2.6.0 (optave#266)

Re-evaluate all architectural recommendations against the actual
codebase as it grew from v1.4.0 (5K lines, 12 modules) to v2.6.0
(17,830 lines, 35 modules).

Architecture audit:
- Reprioritize: dual-function anti-pattern across 15 modules is now optave#1
  (was analysis/formatting split at optave#3)
- Downgrade parser plugin system from optave#1 to optave#20 (parser.js shrank to
  404 lines after native engine took over)
- Add 3 new recommendations: decompose complexity.js (2,163 lines),
  unified graph model for structure/cochange/communities, pagination
  standardization
- Update all metrics and line counts to current state

Roadmap:
- Add Phase 2.5 (Analysis Expansion) documenting 18 modules shipped
  across v2.0.0-v2.6.0 (complexity, communities, structure, flow,
  cochange, manifesto, boundaries, check, audit, batch, triage,
  hybrid search, owners, snapshot, etc.)
- Mark Phase 5.3 (Hybrid Search) as completed early in Phase 2.5
- Update Phase 3 priorities based on revised architecture analysis
- Update version to 2.6.0, language count to 11, phase count to 10
- Add Phase 8 note referencing check command foundation from 2.5

* docs: add Narsil-MCP competitive deep-dive with feature candidates (optave#265)

* docs: add competitive deep-dive for Joern and reorganize competitive folder

Move COMPETITIVE_ANALYSIS.md into generated/competitive/ and add a
comprehensive feature-by-feature comparison against joernio/joern
(our optave#1-ranked competitor). Covers parsing, graph model, query language,
performance, installation, AI/MCP integration, security analysis,
developer productivity, and ecosystem across 100+ individual features.
Update FOUNDATION.md reference to the new path.

* fix: update broken links to moved COMPETITIVE_ANALYSIS.md

README.md and docs/roadmap/BACKLOG.md still referenced the old path
at generated/COMPETITIVE_ANALYSIS.md after the file was moved to
generated/competitive/COMPETITIVE_ANALYSIS.md in optave#260.

* docs: add Joern-inspired feature candidates with BACKLOG-style grading

Append a new "Joern-Inspired Feature Candidates" section to the Joern
competitive deep-dive. Lists 11 actionable features extracted from
Parsing & Language Support, Graph Model & Analysis Depth, and Query
Language & Interface sections — assessed with the same tier/grading
system used in BACKLOG.md (zero-dep, foundation-aligned, problem-fit,
breaking).

Tier 1 non-breaking: call-chain slicing, type-informed resolution,
error-tolerant parsing, regex filtering, Kotlin, Swift, script execution.
Tier 1 breaking: expanded node/edge types, intraprocedural CFG, stored AST.
Not adopted: 9 features with FOUNDATION.md reasoning.
Cross-references BACKLOG IDs 14 and 7.

* docs: add competitive deep-dive for Narsil-MCP with feature candidates

Comprehensive comparison across 10 dimensions: parsing (32 vs 11
languages), graph model (CFG/DFG/type inference vs complexity/roles/
communities), search (similarity/chunking vs RRF hybrid), security
(147 rules vs none), queries (90 tools vs 21 + compound commands),
performance (cold start vs incremental), install, MCP integration,
developer productivity, and ecosystem.

Feature candidates section covers all comparison sections:
- Tier 1 non-breaking (10): MCP presets, AST chunking, code similarity,
  git blame/symbol history, remote repo indexing, config wizard, Kotlin,
  Swift, Bash, Scala language support
- Tier 1 breaking (1): export map per module
- Tier 2 (2): interactive HTML viz, multiple embedding backends
- Tier 3 (2): OWASP patterns, SBOM generation
- Not adopted (10): taint, type inference, SPARQL/RDF, CCG, in-memory
  arch, 90-tool surface, browser WASM, Forgemax, LSP, license scanning
- Cross-references to BACKLOG IDs 7, 8, 10, 14 and Joern candidates
  J4, J5, J8, J9

* feat: add expanded edge types — contains, parameter_of, receiver (Phase 2)

Build file→definition and parent→child contains edges, parameter_of
inverse edges, and receiver edges for method-call dispatch. Add
CORE_EDGE_KINDS, STRUCTURAL_EDGE_KINDS, EVERY_EDGE_KIND constants.
Exclude structural edges from moduleMapData coupling counts. Scope
directory contains-edge cleanup to preserve symbol-level edges.

Impact: 3 functions changed, 22 affected

* chore: add pre-commit diff-impact hook (optave#271)

Add show-diff-impact.sh that automatically runs
`codegraph diff-impact --staged -T` before git commit commands.
The hook injects blast radius info as additionalContext —
informational only, never blocks commits.

* feat(export): add GraphML, GraphSON, Neo4j CSV and interactive viewer (optave#268)

* feat(export): add GraphML, GraphSON, Neo4j CSV formats and interactive HTML viewer

Add three new export formats for graph database interoperability:
- GraphML (XML standard) with file-level and function-level modes
- GraphSON (TinkerPop v3) for Gremlin/JanusGraph compatibility
- Neo4j CSV (bulk import) with separate nodes/relationships files

Add interactive HTML viewer (`codegraph plot`) powered by vis-network:
- Hierarchical, force, and radial layouts with physics toggle
- Node coloring by kind or role, search/filter, legend panel
- Configurable via .plotDotCfg JSON file

Update CLI export command, MCP export_graph tool, and programmatic API
to support all six formats.

Impact: 12 functions changed, 6 affected

* feat(plot): add drill-down, clustering, complexity overlays, and detail panel

Evolve the plot command from a static viewer into an interactive
exploration tool with rich data overlays and navigation.

Data preparation:
- Extract prepareGraphData() with complexity, fan-in/fan-out, Louvain
  community detection, directory derivation, and risk flag computation
- Seed strategies: all (default), top-fanin, entry

Interactive features:
- Detail sidebar: metrics, callers/callees lists, risk badges
- Drill-down: click-to-expand / double-click-to-collapse neighbors
- Clustering: community and directory grouping via vis-network API
- Color by: kind, role, community, complexity (MI-based borders)
- Size by: uniform, fan-in, fan-out, complexity
- Risk overlay: dead-code (dashed), high-blast-radius (shadow), low-MI

CLI options:
- --cluster, --overlay, --seed, --seed-count, --size-by, --color-by

Tests expanded from 7 to 21 covering all new data enrichment, seed
strategies, risk flags, UI elements, and config backward compatibility.

Impact: 5 functions changed, 3 affected

* fix(test): update MCP export_graph enum to include new formats

The previous commit added graphml, graphson, and neo4j export formats
to the MCP tool definition but did not update the test assertion.

* style: format mcp test after enum update

* fix(security): escape config values in HTML template to prevent XSS

Use JSON.stringify() for cfg.layout.direction, effectiveColorBy, and
cfg.clusterBy when interpolated into inline JavaScript. Replace shell
exec() with execFile() for browser-open to avoid path injection.

Impact: 1 functions changed, 1 affected

* docs: add check-readme hook to guides (optave#272)

* feat(export): add GraphML, GraphSON, Neo4j CSV formats and interactive HTML viewer

Add three new export formats for graph database interoperability:
- GraphML (XML standard) with file-level and function-level modes
- GraphSON (TinkerPop v3) for Gremlin/JanusGraph compatibility
- Neo4j CSV (bulk import) with separate nodes/relationships files

Add interactive HTML viewer (`codegraph plot`) powered by vis-network:
- Hierarchical, force, and radial layouts with physics toggle
- Node coloring by kind or role, search/filter, legend panel
- Configurable via .plotDotCfg JSON file

Update CLI export command, MCP export_graph tool, and programmatic API
to support all six formats.

Impact: 12 functions changed, 6 affected

* feat(plot): add drill-down, clustering, complexity overlays, and detail panel

Evolve the plot command from a static viewer into an interactive
exploration tool with rich data overlays and navigation.

Data preparation:
- Extract prepareGraphData() with complexity, fan-in/fan-out, Louvain
  community detection, directory derivation, and risk flag computation
- Seed strategies: all (default), top-fanin, entry

Interactive features:
- Detail sidebar: metrics, callers/callees lists, risk badges
- Drill-down: click-to-expand / double-click-to-collapse neighbors
- Clustering: community and directory grouping via vis-network API
- Color by: kind, role, community, complexity (MI-based borders)
- Size by: uniform, fan-in, fan-out, complexity
- Risk overlay: dead-code (dashed), high-blast-radius (shadow), low-MI

CLI options:
- --cluster, --overlay, --seed, --seed-count, --size-by, --color-by

Tests expanded from 7 to 21 covering all new data enrichment, seed
strategies, risk flags, UI elements, and config backward compatibility.

Impact: 5 functions changed, 3 affected

* fix(test): update MCP export_graph enum to include new formats

The previous commit added graphml, graphson, and neo4j export formats
to the MCP tool definition but did not update the test assertion.

* style: format mcp test after enum update

* fix(security): escape config values in HTML template to prevent XSS

Use JSON.stringify() for cfg.layout.direction, effectiveColorBy, and
cfg.clusterBy when interpolated into inline JavaScript. Replace shell
exec() with execFile() for browser-open to avoid path injection.

Impact: 1 functions changed, 1 affected

* docs: add check-readme hook to recommended practices and guides

Document the new check-readme.sh hook across all three doc locations:
recommended-practices.md, ai-agent-guide.md, and the hooks example
README. Adds settings.json examples, hook behavior descriptions, and
customization entries.

* feat: exports command + scoped rebuild for parallel agents (optave#269)

* docs: add competitive deep-dive for Joern and reorganize competitive folder

Move COMPETITIVE_ANALYSIS.md into generated/competitive/ and add a
comprehensive feature-by-feature comparison against joernio/joern
(our optave#1-ranked competitor). Covers parsing, graph model, query language,
performance, installation, AI/MCP integration, security analysis,
developer productivity, and ecosystem across 100+ individual features.
Update FOUNDATION.md reference to the new path.

* fix: update broken links to moved COMPETITIVE_ANALYSIS.md

README.md and docs/roadmap/BACKLOG.md still referenced the old path
at generated/COMPETITIVE_ANALYSIS.md after the file was moved to
generated/competitive/COMPETITIVE_ANALYSIS.md in optave#260.

* docs: add Joern-inspired feature candidates with BACKLOG-style grading

Append a new "Joern-Inspired Feature Candidates" section to the Joern
competitive deep-dive. Lists 11 actionable features extracted from
Parsing & Language Support, Graph Model & Analysis Depth, and Query
Language & Interface sections — assessed with the same tier/grading
system used in BACKLOG.md (zero-dep, foundation-aligned, problem-fit,
breaking).

Tier 1 non-breaking: call-chain slicing, type-informed resolution,
error-tolerant parsing, regex filtering, Kotlin, Swift, script execution.
Tier 1 breaking: expanded node/edge types, intraprocedural CFG, stored AST.
Not adopted: 9 features with FOUNDATION.md reasoning.
Cross-references BACKLOG IDs 14 and 7.

* docs: add competitive deep-dive for Narsil-MCP with feature candidates

Comprehensive comparison across 10 dimensions: parsing (32 vs 11
languages), graph model (CFG/DFG/type inference vs complexity/roles/
communities), search (similarity/chunking vs RRF hybrid), security
(147 rules vs none), queries (90 tools vs 21 + compound commands),
performance (cold start vs incremental), install, MCP integration,
developer productivity, and ecosystem.

Feature candidates section covers all comparison sections:
- Tier 1 non-breaking (10): MCP presets, AST chunking, code similarity,
  git blame/symbol history, remote repo indexing, config wizard, Kotlin,
  Swift, Bash, Scala language support
- Tier 1 breaking (1): export map per module
- Tier 2 (2): interactive HTML viz, multiple embedding backends
- Tier 3 (2): OWASP patterns, SBOM generation
- Not adopted (10): taint, type inference, SPARQL/RDF, CCG, in-memory
  arch, 90-tool surface, browser WASM, Forgemax, LSP, license scanning
- Cross-references to BACKLOG IDs 7, 8, 10, 14 and Joern candidates
  J4, J5, J8, J9

* feat: add dedicated `exports <file>` command with per-symbol consumers

Implements feature N11 from the Narsil competitive analysis. The new
command provides a focused export map showing which symbols a file
exports and who calls each one, filling the gap between `explain`
(public/internal split without consumers) and `where --file` (just
export names).

Adds exportsData/fileExports to queries.js, CLI command, MCP tool,
batch support, programmatic API, and integration tests.

Impact: 7 functions changed, 15 affected

* feat: add scoped rebuild for parallel agent rollback

Extract purgeFilesFromGraph() from the inline deletion cascade in
buildGraph() for reuse. Add opts.scope and opts.noReverseDeps to
buildGraph() so agents can surgically rebuild only their changed files
without nuking other agents' graph state.

- `--scope <files...>` on `build` skips collectFiles/getChangedFiles
- `--no-reverse-deps` skips reverse-dep cascade (safe when exports unchanged)
- New `scoped_rebuild` MCP tool for multi-agent orchestration
- purgeFilesFromGraph exported from programmatic API
- Unit tests for purge function, integration tests for scoped rebuild
- Documented agent-level rollback workflow in titan-paradigm.md

Impact: 3 functions changed, 20 affected

* fix: remove leaked scoped_rebuild changes from another session

Reverts purgeFilesFromGraph export, --scope/--no-reverse-deps CLI
options, scoped_rebuild MCP tool+handler, and test list entry that
were accidentally included from a concurrent session's dirty worktree.

Impact: 2 functions changed, 1 affected

* fix: remove stale scoped-rebuild docs from titan-paradigm

The scoped_rebuild feature (--scope, --no-reverse-deps CLI options and
scoped_rebuild MCP tool) was removed in 651ddb2 but the documentation
in titan-paradigm.md still referenced it. Addresses Greptile review
feedback on PR optave#269.

* feat: add intraprocedural control flow graph (CFG) construction

Add opt-in CFG analysis that builds basic-block control flow graphs
from tree-sitter AST for individual functions. Enables complexity-aware
impact analysis and opens the path to dataflow (def-use chains).

- DB migration v12: cfg_blocks + cfg_edges tables
- New src/cfg.js module: CFG_RULES, buildFunctionCFG, buildCFGData,
  cfgData, cfgToDOT, cfgToMermaid, cfg CLI printer
- Builder integration: --cfg flag triggers CFG after complexity pass
- CLI: `cfg <name>` command with --format text/dot/mermaid, -j, --ndjson
- MCP: cfg tool with name, format, file, kind, pagination props
- Exports findFunctionNode from complexity.js for reuse
- 24 unit tests + 11 integration tests (35 total)

Phase 1: JS/TS/TSX only. Handles if/else, for/while/do-while, switch,
try/catch/finally, break/continue (with labels), return/throw.

Impact: 27 functions changed, 36 affected

* feat: add stored queryable AST nodes (calls, new, string, regex, throw, await)

Persist selected AST nodes in a dedicated ast_nodes SQLite table during
build, queryable via CLI (codegraph ast), MCP (ast_query), and
programmatic API.

- DB migration v13: ast_nodes table with indexes on kind, name, file,
  parent, and (kind,name)
- New src/ast.js module: buildAstNodes (extraction), astQueryData/
  astQuery (query), AST_NODE_KINDS constant
- Builder integration: full-rebuild deletion, incremental cleanup,
  always-on post-parse extraction (before complexity to preserve _tree)
- CLI: codegraph ast [pattern] with -k, -f, -T, -j, --ndjson,
  --limit, --offset options
- MCP: ast_query tool with pattern, kind, file, no_tests, pagination
- JS/TS/TSX Phase 1: full AST walk for new/throw/await/string/regex;
  all languages get call nodes from symbols.calls
- Pattern matching uses SQL GLOB with auto-wrapping for substring search
- Parent node resolution via narrowest enclosing definition

Impact: 12 functions changed, 26 affected

* fix: correct misleading comment for break without enclosing loop/switch

The comment incorrectly suggested this code path handled break inside
switch cases. It actually handles break with no enclosing loop/switch
context (invalid syntax) as a no-op.

Impact: 2 functions changed, 9 affected

* docs: fix stale MCP tool references in guides

Update tool names and counts to match actual MCP server output:
- query_function → query, fn_deps/symbol_path removed (merged into query)
- list_entry_points removed (merged into execution_flow)
- Add missing tools: ast_query, cfg, dataflow, symbol_children
- Fix count: 31 tools (32 in multi-repo mode)

* feat: expand node types with parameter, property, constant kinds (optave#270)

* feat: expand node types with parameter, property, constant kinds (Phase 1)

Add sub-declaration node extraction to all 9 WASM language extractors,
enabling structural queries like "which functions take a Request param?"
or "which classes have a userId field?" without reading source code.

Schema: migration v11 adds nullable parent_id column with indexes.
Builder: insertNode links children to parent via parent_id FK.
Extractors: JS/TS, Python, Go, Rust, Java, C#, Ruby, PHP, HCL now
emit children arrays for parameters, properties, and constants.
Queries: new childrenData() function, children in contextData output.
CLI: new `children` command, EVERY_SYMBOL_KIND validation on --kind.
MCP: new `symbol_children` tool, extended kind enum on all kind fields.
Constants: CORE_SYMBOL_KINDS (10), EXTENDED_SYMBOL_KINDS (3),
EVERY_SYMBOL_KIND (13). ALL_SYMBOL_KINDS preserved for backward compat.

Native Rust engine: Definition struct gains children field but actual
extraction is deferred to Phase 2 — WASM fallback handles new kinds.

Impact: 63 functions changed, 62 affected

* feat: add expanded edge types — contains, parameter_of, receiver (Phase 2)

Build file→definition and parent→child contains edges, parameter_of
inverse edges, and receiver edges for method-call dispatch. Add
CORE_EDGE_KINDS, STRUCTURAL_EDGE_KINDS, EVERY_EDGE_KIND constants.
Exclude structural edges from moduleMapData coupling counts. Scope
directory contains-edge cleanup to preserve symbol-level edges.

Impact: 3 functions changed, 22 affected

* fix(native): add missing children field to all Rust extractors

The Definition struct gained a children field but no extractor was
updated to include it, causing 50 compilation errors. Add children: None
to every Definition initializer across all 9 language extractors.
Also fix unused variable warnings in parser_registry.rs and parallel.rs.

Impact: 13 functions changed, 10 affected

* ci: trigger workflow re-run

* fix: include cfg_edges and cfg_blocks in full rebuild cleanup

The full rebuild DELETE chain was missing the two CFG tables,
which would leave orphaned CFG data after a fresh build.

Impact: 1 functions changed, 0 affected

* feat: expand node types with parameter, property, constant kinds (Phase 1)

Add sub-declaration node extraction to all 9 WASM language extractors,
enabling structural queries like "which functions take a Request param?"
or "which classes have a userId field?" without reading source code.

Schema: migration v11 adds nullable parent_id column with indexes.
Builder: insertNode links children to parent via parent_id FK.
Extractors: JS/TS, Python, Go, Rust, Java, C#, Ruby, PHP, HCL now
emit children arrays for parameters, properties, and constants.
Queries: new childrenData() function, children in contextData output.
CLI: new `children` command, EVERY_SYMBOL_KIND validation on --kind.
MCP: new `symbol_children` tool, extended kind enum on all kind fields.
Constants: CORE_SYMBOL_KINDS (10), EXTENDED_SYMBOL_KINDS (3),
EVERY_SYMBOL_KIND (13). ALL_SYMBOL_KINDS preserved for backward compat.

Native Rust engine: Definition struct gains children field but actual
extraction is deferred to Phase 2 — WASM fallback handles new kinds.

Impact: 63 functions changed, 62 affected

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

* docs: update architecture audit and roadmap for v2.7.0

Add Phase 2.7 (Deep Analysis & Graph Enrichment) covering all features
shipped since the last review: dataflow analysis, intraprocedural CFG,
AST node storage, expanded node/edge types (13 kinds, 9 edge kinds),
extractors refactoring, CLI consolidation, interactive viewer, exports
command, and normalizeSymbol utility.

Update Phase 3 priorities: add unified AST analysis framework as new optave#1
critical item (5,193 lines of parallel AST walking across complexity/
CFG/dataflow/ast with no shared infrastructure). Update all metrics
across Phase 3 items (50 modules, 26K lines, 13 tables, 34 MCP tools).
Mark qualified names as partially addressed (parent_id + contains edges).
Subsume standalone complexity decomposition into AST framework.

Update Phase 4 type definitions with new kind/edge type hierarchies.
Mark Phase 9.1 visualization as partially complete (plot command).

* fix: correct extractor line counts and duplicate section numbering

- Update extractor line counts from 2,299 to actual 3,023 (verified via wc -l)
- Fix individual per-file counts in both ROADMAP.md and architecture.md
- Remove duplicate section 3.8 numbering for strikethrough/subsumed item

…ve#292)

* docs: update architecture audit and roadmap for v2.7.0

Add Phase 2.7 (Deep Analysis & Graph Enrichment) covering all features
shipped since the last review: dataflow analysis, intraprocedural CFG,
AST node storage, expanded node/edge types (13 kinds, 9 edge kinds),
extractors refactoring, CLI consolidation, interactive viewer, exports
command, and normalizeSymbol utility.

Update Phase 3 priorities: add unified AST analysis framework as new optave#1
critical item (5,193 lines of parallel AST walking across complexity/
CFG/dataflow/ast with no shared infrastructure). Update all metrics
across Phase 3 items (50 modules, 26K lines, 13 tables, 34 MCP tools).
Mark qualified names as partially addressed (parent_id + contains edges).
Subsume standalone complexity decomposition into AST framework.

Update Phase 4 type definitions with new kind/edge type hierarchies.
Mark Phase 9.1 visualization as partially complete (plot command).

* fix: correct extractor line counts and duplicate section numbering

- Update extractor line counts from 2,299 to actual 3,023 (verified via wc -l)
- Fix individual per-file counts in both ROADMAP.md and architecture.md
- Remove duplicate section 3.8 numbering for strikethrough/subsumed item

* refactor: consolidate MCP tools to match CLI changes from PR optave#280

Remove 3 redundant MCP tools and add 1 new tool to mirror the CLI
consolidation done in PR optave#280:

- Remove `explain` tool → fold into `audit` with `quick` param
- Remove `hotspots` tool → fold into `triage` with `level` param
- Remove `manifesto` tool → fold into `check` with manifesto-mode routing
- Add standalone `path` tool (was only accessible via query mode=path)

All backing data functions are unchanged. The `query` tool still supports
mode=path for backward compatibility.

Impact: 1 functions changed, 1 affected

* fix: map triage sort values to valid hotspot metrics

When the triage tool delegates to hotspotsData for file/directory level,
sort values like 'complexity', 'churn', and 'mi' don't exist in
HOTSPOT_QUERIES (which only supports fan-in, fan-out, density, coupling).
Previously these silently fell back to fan-in via the || fallback.

Add explicit TRIAGE_TO_HOTSPOT mapping:
- risk → fan-in (unchanged)
- complexity → density (symbol count as structural proxy)
- churn → coupling (fan-in + fan-out reflects change propagation)
- mi → fan-in (no direct equivalent)
- fan-in → fan-in (pass-through via nullish coalescing)

Impact: 1 functions changed, 1 affected

…ptave#403)

* feat: unified AST analysis framework with pluggable visitor pattern

Implement Phase 3.1 of the architectural refactoring roadmap. Replace 4
independent AST analysis passes (complexity, dataflow, AST-store, CFG)
with a shared visitor framework that runs complexity, dataflow, and
AST-store visitors in a single DFS walk per file.

New framework files:
- visitor.js: shared DFS walker with enterNode/exitNode/enterFunction/
  exitFunction hooks, per-visitor skipChildren, nesting/scope tracking
- engine.js: orchestrates all analyses in one coordinated pass, replaces
  4 sequential buildXxx blocks + WASM pre-parse in builder.js
- metrics.js: extracted Halstead derived math, LOC, MI from complexity.js
- visitor-utils.js: extracted shared helpers from dataflow.js
- visitors/complexity-visitor.js: cognitive/cyclomatic/nesting + Halstead
- visitors/ast-store-visitor.js: new/throw/await/string/regex extraction
- visitors/dataflow-visitor.js: scope stack + define-use chains
- tests/unit/visitor.test.js: 9 tests for walker framework

Modified modules:
- builder.js: 4 sequential buildXxx blocks → single runAnalyses call
- complexity.js: delegates walk to complexity visitor
- dataflow.js: delegates walk to dataflow visitor
- ast.js: delegates walk to ast-store visitor, removed dead code

Bug fixes:
- Fix Ruby dataflow parity: skip nested return keyword tokens inside
  return statements (tree-sitter Ruby grammar nests return/return)

Hook fixes:
- check-dead-exports.sh: exclude public API (index.js) and dynamic
  import() consumers from dead export detection
- check-readme.sh: match ROADMAP.md at any path; allow commit when at
  least one doc is staged (developer reviewed which docs need updating)

Docs:
- ROADMAP.md: update 3.1 with completed items and remaining work
- BACKLOG.md: add Tier 1h with dynamic import/re-export tracking (ID 71)
- CLAUDE.md: add ast-analysis/ to architecture table

Impact: 51 functions changed, 47 affected

* revert: restore original check-dead-exports.sh hook

The hook correctly catches a real limitation — codegraph doesn't track
dynamic import() consumers as graph edges. The proper fix is to add
dynamic import edge tracking (backlog ID 81), not to exclude them
from the hook. Reverting the workaround.

* fix: address Greptile review — indexOf→m.index, precise publicAPI regex, remove unused var

Impact: 2 functions changed, 23 affected

* fix: address Greptile review — halsteadSkip depth counter, debug logging, perf import

- Replace halsteadSkip boolean with halsteadSkipDepth counter to handle
  nested skip-type nodes correctly (e.g. return_type containing
  type_annotation in TypeScript)
- Add debug() logging to all silent catch blocks in engine.js so
  failures are discoverable with --verbose
- Explicitly import performance from node:perf_hooks for clarity

Impact: 5 functions changed, 24 affected

* fix: remove function nodes from nestingNodeTypes and eliminate O(n²) lookup

Address two Greptile review comments on PR optave#388:

1. Function nodes in nestingNodeTypes inflates cognitive complexity by +1
   for every function body — funcDepth already tracks function-level
   nesting, so adding functionNodes to the walker's nestingNodeTypes
   double-counts.

2. Replace O(n²) complexityResults.find() with O(1) resultByLine map
   lookup by storing the full result object (metrics + funcNode) instead
   of just metrics.

Impact: 1 functions changed, 0 affected

* fix: remove function nesting inflation in computeAllMetrics and pass langId to LOC

Address two Greptile review comments:

1. computeAllMetrics added functionNodes to nestingNodeTypes, inflating
   cognitive complexity by +1 for every function body (same bug as the
   engine.js fix in a47eb47, but in the per-function code path).

2. collectResult in complexity-visitor passed null as langId to
   computeLOCMetrics, causing C-style comment detection for all
   languages. Now accepts langId via options and forwards it, so
   Python/Ruby/PHP get correct comment-line counts and MI values.

Impact: 4 functions changed, 5 affected

* fix: guard runAnalyses call, fix nested function nesting, rename _engineOpts

Address three Greptile review comments:

1. Wrap runAnalyses call in builder.js with try/catch + debug() so a
   walk-phase throw doesn't crash the entire build — matches the
   resilience of the previous individual buildXxx try/catch blocks.

2. In function-level mode, enterFunction/exitFunction were no-ops, so
   funcDepth stayed 0 for nested functions (callbacks, closures).
   Now increments/decrements funcDepth in function-level mode too,
   restoring parity with the original computeAllMetrics algorithm.

3. Rename _engineOpts to engineOpts in engine.js since it's actively
   forwarded to all four buildXxx delegate calls — the underscore
   prefix falsely signaled an unused parameter.

Impact: 5 functions changed, 4 affected

* fix: remove redundant processed Set and fix multi-line destructuring in hook

Address two Greptile review comments:

1. Remove the `processed` Set from dataflow-visitor.js — walkWithVisitors
   visits each node exactly once via DFS on a proper tree, so the
   deduplication guard never fires and just wastes memory.

2. Replace single-line destructuring regex in check-dead-exports.sh with
   a multi-line-safe pattern (using the `s` flag) so multi-line
   `const { ... } = await import(...)` patterns are correctly detected
   and their names added to publicAPI.

Impact: 2 functions changed, 0 affected

* refactor: migrate raw SQL into repository pattern (Phase 3.3)

Split src/db/repository.js into src/db/repository/ directory with 10
domain files: nodes, edges, build-stmts, complexity, cfg, dataflow,
cochange, embeddings, graph-read, and barrel index.

Extracted ~120 inline db.prepare() calls from 14 consumer modules
into shared repository functions, eliminating duplication of common
patterns like getNodeId (5 files), bulkNodeIdsByFile (3 files),
callee/caller joins (6+ call sites), and file purge cascades.

Net reduction: -437 lines across the codebase. All 1573 tests pass.

Impact: 73 functions changed, 112 affected

* fix: address Greptile review — deduplicate relatedTests, hoist prepared stmts, fix .raw() no-op

- queries.js: restore DISTINCT-by-file deduplication for relatedTests in
  explainFunctionImpl (lost when switching to findCallers)
- build-stmts.js: prepare SQL statements once in preparePurgeStmts() and
  loop with runPurge() instead of calling db.prepare() per file per table
- cfg.js: replace misleading .raw() with .get() in hasCfgTables

Impact: 7 functions changed, 14 affected

* fix: hoist prepared statement out of BFS loop in getClassHierarchy

db.prepare() was called on every iteration of the while loop in
getClassHierarchy, causing repeated statement compilation for each
ancestor level. Use a WeakMap cache (keyed by db instance) so the
statement is compiled once and reused across iterations.

Impact: 1 functions changed, 0 affected

* fix: re-apply hoisted prepared statement after merge resolution

Impact: 1 functions changed, 0 affected

* fix: cache all hot-path prepared statements in edge repository

- Move getClassHierarchy WeakMap lookup before BFS loop (concern optave#1)
- Cache findCallees/findCallers/findDistinctCallers via shared _cached()
  helper — fixes sequence.js BFS regression (concern optave#2)
- Cache findCalleeNames/findCallerNames — fixes embedder.js per-symbol
  compilation regression (concern optave#2)
- Add _cached() helper to eliminate boilerplate across all cached stmts
- Add getClassHierarchy tests: empty, single-level, multi-level, diamond

* style: fix biome formatting in repository test

…optave#559)

* docs: update competitive analysis for v3.2.0 and March 2026 landscape

Re-rank codegraph from optave#8 (4.0) to optave#5 (4.5) reflecting v3.2.0 features:
41 CLI commands, 32 MCP tools, dataflow across all 11 languages, CFG,
sequence diagrams, architecture boundaries, unified graph model.

Add new competitors: GitNexus (optave#1, 18k stars), DeusData/codebase-memory-mcp
(optave#6, 793 stars in 25 days). Update star counts and feature status across
all 85+ ranked projects. Mark 7 roadmap items as DONE. Flag stagnant
projects. Update joern.md (3,021 stars, 75 contributors, 4 community MCP
wrappers) and narsil-mcp.md (129 stars, SPA frontend, +36 security rules,
development paused since Feb 25).

* docs: fix narsil SPA version attribution in competitive analysis overview

Line 18 incorrectly stated "v1.6.1" as the version when the SPA feature
was introduced. The SPA frontend was added in v1.6.0; v1.6.1 is the
current release. Updated to "added v1.6.0, current v1.6.1" to match the
detailed narsil-mcp.md entry.

* docs: remove hardcoded star count from joern comparison table

The "32 stars, growing" value in the Community & maturity row hardcodes
a stale star count. Other comparison tables use "Growing" consistently
for codegraph's community status. Updated to match.

* fix: correct GitNexus score, Tier 2 rank numbering, and jelly star count

- GitNexus overall score corrected from 4.7 to 4.5 to match the
  arithmetic mean of its six sub-scores (5+5+4+4+4+5)/6 = 4.5
- Tier 2 renumbered starting at optave#38 (was duplicating optave#37 with Tier 1);
  also resolves the pre-existing duplicate optave#43 (Bikach/ChrisRoyse now
  optave#44/optave#45), with all subsequent entries incremented accordingly
- jelly section header updated from 417 to 423 stars to match the
  ranking table

* fix: correct aider rank and codegraph star count per review feedback

* fix: align scoring breakdown sub-scores with overall rankings for stagnant projects

glimpse: Community 4→2 (stagnant since Jan 2026), avg now 3.83≈3.8 matching ranking.
autodev-codebase: Community 3→1 (stagnant since Jan 2026), avg now 3.33, ranking updated 3.4→3.3.

* fix: align ranking scores with sub-score averages for colbymchenry and axon

* fix: correct ranking inversion at positions optave#23/optave#24 (optave#559)

autodev-codebase (3.3) was ranked optave#23 above Claude-code-memory (3.4)
at optave#24. Swapped to maintain descending score order.

* fix: correct score mismatches for code-graph-rag (4.5→4.2) and arbor (3.7→4.2) (optave#559)

* fix: sync breakdown table row order with ranking table for optave#23/optave#24 (optave#559)

* fix: correct ranking inversions and stale rank references (optave#559)

* fix: correct sub-score/overall-score mismatches for codexray, loregrep, MATE

* fix: correct score mismatches and aider header rank

* fix: update narsil-mcp Key Metrics to reflect development stagnation (optave#559)

* fix: add missing "vs arbor" comparison section (optave#559)

* fix: remove duplicate vs-glimpse section and correct role names in vs-arbor (optave#559)

The duplicate vs-glimpse block (stale rank optave#10) was left behind when
vs-arbor was inserted. Removed it — the correct version exists at optave#11.
Also fixed role vocabulary in vs-arbor: bridge → adapter, added entry.

"(phases 1-2)" for the 2 dead-code-removal commits, placed right after
"29 FORGE commits (phase 8 ...)", reads as if those phases were part
of the 29. The PR Split Plan shows PR #2-7 alone sum to exactly 29
(matching the FORGE commit count), so the 2 dead-code commits (PR #1)
are additional. Reword to make the non-overlap explicit.

* docs: add Titan audit report for v3.15.0 run

* docs: add PR #11 self-reference to Titan report split plan

* fix: correct issue-count arithmetic in Titan v3.15.0 report (#1795)

The already-filed list enumerates 18 distinct issue numbers but the
surrounding sentence said 17, making the stated total (23) off by one.

* fix: reconcile GRIND false-positive count in Titan v3.15.0 report (#1795)

The GRIND Results header and pipeline timeline stated 10 false
positives, but the Metrics note derived 15 from the same 24-candidate
pool (24 - 9 adopted/promoted). Update the header/timeline to the
derived 15 and clarify that the 10-row table below consolidates
multiple targets per finding.

* fix: reconcile domain count and stale issue-count mention in Titan report (#1795)

The Domains Analyzed table lists 19 entries, but the Executive Summary,
Pipeline Timeline, and GLOBAL_ARCH.md reference all said 18 domains.
Update all three to 19 to match the enumerated table. Also fixes a
leftover "17 already filed" mention in the Executive Summary that an
earlier commit missed when correcting the same count elsewhere to 18.

* fix: include omitted #1770 and #1772 in Titan report issue enumeration (#1795)

The "18 already filed" list omitted #1770 and #1772, both explicitly
referenced elsewhere in the same report (GRIND False Positives table)
as issues filed during this run. Add them to the enumeration and
update the already-filed count (18 -> 20) and grand total (24 -> 26)
accordingly.

* fix: clarify commit-count breakdown ambiguity in Titan report (#1795)

"(phases 1-2)" for the 2 dead-code-removal commits, placed right after
"29 FORGE commits (phase 8 ...)", reads as if those phases were part
of the 29. The PR Split Plan shows PR #2-7 alone sum to exactly 29
(matching the FORGE commit count), so the 2 dead-code commits (PR #1)
are additional. Reword to make the non-overlap explicit.

* fix: include PARITY-filed #1778 in Titan report issue total (#1795)

The 26-issue grand total omitted #1778, filed during PARITY (noted
in the Pipeline Timeline row) but excluded from the "already filed"
enumeration, which was scoped only to RECON/GAUNTLET/GRIND. Widen the
scope to include PARITY and add #1778, bringing the total to 27.

…atch (#2080) (#2317)

* fix(extractors): seed object-rest-param type annotations for CHA dispatch (#2080)

Investigating this issue revealed two related bugs in
collectObjectRestParams (TS) / collect_object_rest_params (Rust),
both fixed together since the second makes the first meaningful:

1. Neither ever unwrapped TypeScript's required_parameter/
   optional_parameter node — tree-sitter-typescript wraps EVERY
   parameter, typed or not, in that node (confirmed by parsing
   `function f({ ...rest }) {}` with the TS grammar), unlike plain
   tree-sitter-javascript where object_pattern is a direct
   formal_parameters child. Object-rest-param bindings were therefore
   silently never recorded for any .ts/.tsx file at all — the existing
   #1336 test only ever exercised the .js grammar, so this went
   undetected. Fixed by unwrapping via the `pattern` field before
   checking for object_pattern.

2. A type-annotated rest parameter (`{ ...rest }: IWorker`) never got
   a type-annotation-based typeMap entry the way a plain typed
   parameter (`worker: IWorker`) does — handleParamTypeMap's early
   return on `nameNode.type !== 'identifier'` skipped object_pattern
   entirely. Extended it to seed the rest binding's own name directly
   from the annotation when present, so CHA/interface dispatch through
   a typed rest receiver resolves the same way a plain typed parameter
   already does. This direct seed (confidence 0.9) coexists with the
   pre-existing value-chase seed (seedRestParamTypeMap/
   buildObjectRestParamPostPass, confidence 0.65) via
   setTypeMapEntry's higher-confidence-wins merge — an explicit type
   annotation is strictly more reliable than an inferred call-site
   argument name.

Both fixes are necessary together: #2080 asks specifically for
type-annotation-based seeding, a TypeScript-only feature, but the TS
extraction path for rest-param bindings was completely non-functional
without fix #1 regardless of annotations.

Verified end-to-end via native addon rebuild: native and WASM produce
byte-identical edges for both the untyped-parity and typed-CHA-dispatch
scenarios.

docs check acknowledged: internal extractor correctness fix, no CLI/
architecture change to document.

Impact: 2 functions changed, 8 affected

* fix(extractors): don't seed full type onto rest when a sibling is destructured (#2080)

Review finding: { doWork, ...rest }: IWorker excludes doWork from
rest's real type (structurally Omit<IWorker, 'doWork'>), but the
previous seed assigned the full IWorker type to rest regardless,
letting a call like rest.doWork() -- invalid, since doWork was
destructured out -- resolve a false edge via CHA dispatch.

Only seed the annotation type onto the rest binding when the rest
element is the pattern's sole member ({ ...rest }: IWorker, no sibling
properties). object_rest_param_bindings extraction (the #1336
value-chase mechanism) is unaffected -- it already recorded the rest
binding regardless of sibling properties.

docs check acknowledged: internal extractor correctness fix, no CLI/
architecture change to document.

Impact: 1 functions changed, 0 affected

…rs (#2082) (#2320)

* fix(dart): extract bare calls, fix endLine truncation, bodyless members (#2082)

Three pre-existing extractor bugs, found together while adding Dart
constructor-call attribution coverage:

1. Bare (keyword-less) calls (`helper()`, `Foo()`) were never extracted.
   WASM: the callee is a plain identifier sibling immediately preceding
   the call's `selector` node, not a wrapping call_expression --
   resolveDartSelectorMethodName only handled a preceding `.method`
   selector (chained access), not a bare identifier. Native: calls are
   represented as `call_expression` nodes in tree-sitter-dart 0.2, a
   grammar shape match_dart_node had no dispatch case for at all --
   every native Dart call, bare or chained, was silently unextracted.

2. Multi-line function/method endLine was truncated to the signature
   line. tree-sitter-dart splits a function's signature and body into
   SIBLING nodes (function_signature/method_signature + a separate
   function_body), not a parent-child relationship, in both engines.
   Any call inside a multi-line body fell outside [line, endLine], so
   enclosing-function caller-attribution during graph build silently
   misattributed it to file scope instead.

3. Bodyless (semicolon-only) constructors and abstract methods
   (`Foo();`, `double area();`) were never extracted as definitions --
   they wrap their signature in a `declaration` node instead of the
   `method_signature`/`method_declaration` a block-bodied member uses,
   which extractDartClassMembers's field-detection branch silently
   swallowed.

Also fixed, found while implementing #1: a `===` node-reference
comparison in resolveDartSelectorMethodName's sibling-walk. web-tree-sitter
returns a fresh wrapper object from every `.child()` call, so two
accessors for the SAME node are never reference-equal -- only `.id` is
stable. This silently broke the PRE-EXISTING chained-method-call case
too (`obj.method1().method2()` resolved BOTH calls to "method2", the
last selector scanned, not their own names) -- not just the new bare-call
path added here.

Together these took Dart's resolution-benchmark recall from a genuine
0% floor to 100% precision / 61.9% recall (13/21). The remaining FNs
are all receiver-typed calls needing typeMap population for Dart
fields/parameters -- filed as #2319 rather than expanding this PR's
scope. Complexity/CFG metrics still use the signature-only node (a
separate, already-tracked issue, #2182) and are untouched here.

Verified end-to-end via native addon rebuild: native and WASM produce
byte-identical calls/definitions for all three fixes.

docs check acknowledged: internal extractor correctness fix, no CLI/
architecture change to document.

Impact: 5 functions changed, 9 affected

* fix(dart): skip comments between signature and body in endLine (#2082)

A comment between a function/method signature and its body (e.g. a
signature followed by a doc comment then the opening brace on the next
line) is its own intervening SIBLING node in tree-sitter-dart -- the
grammar's comment rule is an `extra` production that can surface
anywhere in the tree, not a token folded into an adjacent node. The
naive "next sibling" lookup in dartFunctionEndLine/
dart_function_end_line mistook that comment for the body itself,
truncating endLine to the comment's own line and reintroducing the
same caller-misattribution bug for any declaration with an intervening
comment.

Skip forward past any number of consecutive comment siblings before
checking for the real body (or a bare `;` for a bodyless signature).
Mirrored in both engines; verified via cargo test (native) and vitest
(WASM).

Impact: 1 functions changed, 0 affected

…e anonymous functions (#2265) (#2446)

Root cause was two compounding bugs, both fixed:

1. handleVarFnAssignment/handleVarFnCapture (extractors/javascript.ts)
   and handle_var_decl (Rust) set a var/const-assigned function's
   Definition.line from the enclosing declaration statement, not the
   function value's own node. `const a = fn1, b = fn2;` gave every
   declarator but the first the wrong line, so `b`'s Definition
   collided with `a`'s real (correctly line-keyed) complexity/CFG
   result once storeComplexityResults/storeCfgResults
   (ast-analysis/apply-results.ts) indexed by each function node's own
   line.

2. matchResultToDef's only disambiguation signal was `name` — always
   null for an arrow function, and never the function expression's own
   internal name for a var-assigned one — so it could never break a
   same-line tie for this whole Definition category, fix #1 or not.
   Added `column`, populated only for this category, and threaded a
   column-first tier into both matchResultToDef (WASM/visitor path,
   apply-results.ts) and matchNativeResult (native-standalone fallback
   path, engine.ts) — a structurally separate but algorithmically
   identical copy of the same matching logic, not consolidated into one
   function since one operates on live tree-sitter nodes and the other
   on native-computed POJOs with no such node.

Rust's own inline full-pipeline complexity/CFG attachment (handle_var_decl)
was never vulnerable to the misattribution itself — it computes and attaches
each Definition's complexity/CFG directly from its own value node, never by
a later line-keyed re-match — but still needed the line fix, since
Definition.line feeds contentHash/incremental-rebuild reconnection and
`codegraph where`, not just this matching path. column is added narrowly to
FunctionComplexityResult/FunctionCfgResult (the two NAPI-crossing structs
the native-standalone fallback path already returns), not to the widely
literal-constructed shared Definition struct in Rust, which has ~200
unrelated construction sites across every language extractor and does not
need it for this JS/TS-only bug.

docs check acknowledged: internal extractor/ast-analysis fix, no language
support, CLI, or architecture-table changes.

Impact: 12 functions changed, 0 affected