feat: codemap-richer-index — substrate extraction (Tiers 1-12)

[SutuSebastian]

Summary

Adds 9 new tables + ~12 new columns to the codemap structural index, taking it from "files / symbols / imports / exports / dependencies / calls" to a substrate that supports bindings-precise refactoring, cycle detection, metrics, runtime auditing, and test-suite introspection.

Tracks the strategic plan in docs/plans/substrate-extraction.md (existing). All work is fully additive — no existing recipe / query / table shape changed semantics.

What landed

Tier	New tables/columns	Flagship recipes
Tier 1	symbol name_column_*, scope_local_id; imports/exports/calls/markers position cols; import_specifiers	foundations
Tier 2 (.0-.5)	scopes, references (with kind='member' later), bindings, refined globals/TYPE_GLOBALS	find-references, find-write-sites, find-symbol-references
Tier 4	function_params	find-by-param-type
Tier 6	re_export_chains	barrel-chains
Tier 11	symbol body_line_count / param_count / nesting_depth; file_metrics	large-functions, deeply-nested-functions
Tier 12	module_cycles (via Tarjan SCC)	circular-imports
Tier 5	runtime_markers	find-leftover-console, env-var-audit
Tier 9	test_suites	find-skipped-tests, tests-by-file
Cleanup	audit-cache excluded from default glob; JSX intrinsics + TSQualifiedName handled	—

Empirical results

codemap-self (~350 files):

• Full reindex: ~600 ms
• Targeted (1 file): 9 ms
• Bindings precision: 98.75% resolved

merchant-dashboard-v2 (2120 files, real React app):

• Full reindex: 3.77 s
• Targeted: 9 ms
• Bindings precision: 98.25% resolved (1.75% unresolved is callback-edge floor)
• 1855 it/test blocks + 459 describes auto-detected across vitest + bun-test mixed framework
• 223 console calls + 17 env vars + 24 import cycles + 38 XL functions flagged

Why this is a separate PR

This is the groundwork that enables future write capabilities (the feat/codemap-apply PR) — but it's orthogonal:

• This PR: extracts richer index data from AST
• feat/codemap-apply: writes files from diff-shaped rows

Different layers, different review concerns. Splitting keeps each PR reviewable.

Test plan

• All 930 existing tests pass at every commit
• All golden scenarios pass at every commit
• Schema version bumped at every additive table (SCHEMA_VERSION 10 → 25)
• Empirical perf measured on codemap-self + merchant-dashboard-v2
• (Reviewer) verify substrate is sensible on another repo of your choice via `bun src/index.ts --root --full`

Commit history

16 granular commits preserved (one per slice). The fine-grained history surfaces the empirical-test loop — e.g. the JSX intrinsics fix is its own commit, triggered by running the substrate on a real React codebase and finding 17% unresolved.

Squash-on-merge is fine if the team prefers a single landing commit.

Deferred to follow-up (NOT in this PR)

• Callback arrow scope precision (the ~1% unresolved floor)
• Token-count metric (oxc tokeniser integration)
• Lint-tool suppressions enrichment (eslint-disable, ts-expect-error)
• Tier 7 CSS expansion (selectors, @media)
• Tier 13 ORM/SQL templates (Prisma/Drizzle parsing)

Summary by CodeRabbit

• New Features

  • New codemap apply command and transport tool for recipe-driven edits with dry-run, confirmation gating, conflict detection, and atomic per-file writes.
  • Expanded indexing and analysis: import specifiers, lexical scopes, references, bindings, function params, runtime markers, test suites, re-export chains, and module-cycle detection.
  • New query/recipe templates for discovery (call-sites, export/import sites, references, barrel chains, circular imports, large/deep functions, env-vars, tests rollups, etc.).

• Database Schema

  • Schema version bumped with many new tables and finer positional metadata.

• Tests

  • Extensive unit and end-to-end tests for apply behavior, engines, and indexing.

• Documentation

  • Updated docs and templates describing apply flow, new schema, recipes, and usage.

[changeset-bot]

🦋 Changeset detected

Latest commit: d00cabe

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@stainless-code/codemap	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Warning

Rate limit exceeded

@SutuSebastian has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 42 minutes and 18 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d746fa7b-bf61-4ec3-a905-c4149f5bd2e1

📥 Commits

Reviewing files that changed from the base of the PR and between d757272 and d00cabe.

📒 Files selected for processing (1)

• .changeset/codemap-richer-index.md

📝 Walkthrough

Walkthrough

Adds a two-phase diff apply engine wired into CLI/MCP/HTTP with tests and docs. Simultaneously overhauls indexing with new schema, parser extractors, bindings/cycles resolution, updates index-engine, and introduces numerous recipes, fixtures, and research documentation.

Changes

Codemap apply engine and integrations

Layer / File(s)	Summary
Apply engine implementation and validations src/application/apply-engine.ts	Two-phase validate/apply with path containment, duplicate detection, conflict reporting, and atomic file writes.
Apply engine unit tests src/application/apply-engine.test.ts	Covers envelopes, conflicts, ordering, CRLF, deletions, $ escaping, duplicates, path escapes, and failures.
CLI command, parsing, and e2e tests src/cli/*	Adds apply command, args/help, interactive preview/prompt, JSON/TTY output; end-to-end tests.
MCP/HTTP tool handlers and server wiring src/application/tool-handlers.ts, src/application/http-server.ts, src/application/mcp-server.ts, tests	Registers apply tool, validates payloads, dispatches engine, returns structured results; tests added.
Apply docs, glossary, changeset, and roadmap update .agents/*, docs/*, templates/agents/*, .changeset/*	Documents apply behavior/envelope and wiring; glossary entry; changeset; roadmap/backlog adjusted.

Richer indexing substrate, bindings/cycles, recipes, and fixtures

Layer / File(s)	Summary
DB schema/version and TS row APIs src/db.ts	Schema version bump with new tables/columns and indexes; updated insert/drop and TypeScript row interfaces.
Parser refactor, parsed types, and adapter outputs src/parser.ts, src/parsed-types.ts, src/adapters/*	Modular extractor pipeline; returns new datasets; adapters emit extended payloads.
New extraction tiers (offsets/jsdoc/types/scopes/symbols/components/complexity/calls/references/runtime-markers/tests) src/extractors/*, src/markers.ts	Implements tiered extractors to populate new schema tables and marker columns.
Index engine pass-2, bindings resolver, and import cycles src/application/index-engine.ts, src/application/bindings-engine.ts, src/application/cycles-engine.ts, tests	Persists new datasets; computes/persists bindings, re-export chains, and module cycles; updates tests.
Recipe templates and golden fixtures templates/recipes/*, fixtures/golden/**/*	Adds SQL/Markdown recipes for new capabilities and corresponding golden fixtures and scenarios.
Research note, architecture tables, config, and params merge tweak docs/*, src/config.ts, src/application/recipe-params.ts	Adds research note; adjusts architecture docs; excludes audit-cache; tweaks params merge.

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant MCP
  participant HTTP
  participant ToolHandlers
  participant ApplyEngine
  CLI->>ToolHandlers: parse/run apply
  MCP->>ToolHandlers: apply(args)
  HTTP->>ToolHandlers: apply(JSON)
  ToolHandlers->>ApplyEngine: validate/apply(rows, root, dryRun)
  ApplyEngine-->>ToolHandlers: envelope {mode, applied, files, conflicts, summary}

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related PRs

• stainless-code/codemap#19 — Related call-graph/calls extractor work; overlaps schema and extractor areas.

Suggested labels

enhancement, documentation

Poem

A rabbit taps the keys with glee,
Diffs align in harmony.
Validate, then write—so spry,
Conflicts pause, then safely try.
New maps bind names through every lane,
Cycles traced, the loops we tame—🐇✨

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/codemap-richer-index

[coderabbitai]

Actionable comments posted: 12

🧹 Nitpick comments (6)

docs/research/codemap-richer-index-synthesis-2026-05.md (1)

100-113: 💤 Low value

Aspirational code example in research note — consider validation status.

This Path B sketch shows a future integration pattern with ts-morph, not a current API. The import path @stainless-code/codemap-mcp and method query_recipe may not match the actual package structure when this is implemented.

The coding guideline states "Code examples in documentation must be tested and kept current." However, this is a research note containing design explorations rather than user-facing documentation. The example is explicitly labeled as a "sketch" of a potential future direction (Path B), and section 9 notes these research notes will be slimmed or retired as decisions lift to plan PRs.

Consider whether aspirational design examples in research notes should be syntax-validated even if not functionally tested, or if the guideline only applies to user-facing documentation of current features.

As per coding guidelines: "Code examples in documentation must be tested and kept current" — but this applies to research note design sketches which describe future possibilities rather than current implementation.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/research/codemap-richer-index-synthesis-2026-05.md` around lines 100 -
113, The example code block uses non‑existent/unstable symbols (codemap,
query_recipe from "@stainless-code/codemap-mcp", and ts-morph's Project) and is
an aspirational sketch, so update the note to mark the snippet as
unvalidated/experimental: add an explicit one‑line disclaimer before the code
that this is a Path B sketch, not a tested API, and mention the specific symbols
(codemap, query_recipe, Project, ts-morph) that may change; alternatively,
replace the snippet with a syntactically valid but clearly stubbed example
(e.g., pseudocode or comment placeholders) so the document obeys the “examples
must be kept current” guideline while preserving the research intent.

src/application/index-engine.ts (1)

293-312: ⚡ Quick win

fetchTableStats not updated for the eight new tables.

The richer-index PR adds scopes, references, bindings, import_specifiers, function_params, runtime_markers, test_suites, re_export_chains, module_cycles, file_metrics, but the post-index stats summary still only lists the original 12. Users running codemap --full won't see the new tiers' row counts in the indexer output, which makes "did extraction work?" hard to verify without ad-hoc SQL. Consider extending IndexTableStats and this query to surface the new tables.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/application/index-engine.ts` around lines 293 - 312, The fetchTableStats
function and the IndexTableStats type need to be updated to include the eight+
new tables added by the richer-index PR; update the SQL in fetchTableStats to
SELECT COUNT(*) for each new table (scopes, references, bindings,
import_specifiers, function_params, runtime_markers, test_suites,
re_export_chains, module_cycles, file_metrics, etc.) and expand the
IndexTableStats shape to include corresponding fields so the returned row maps
to the new properties; ensure the returned object keys match IndexTableStats
property names and that fetchTableStats still returns the row cast as
IndexTableStats.

src/application/bindings-engine.ts (3)

541-557: ⚡ Quick win

Duplicated re_export_source parser — extract a shared helper.

The 16-line block that parses re_export_source into (source, imported_name) is replicated verbatim in resolveBindings (541‑557) and resolveReExportChains (752‑764). Any future tweak (e.g., new .default encoding) must be mirrored in both places. Extract a small helper to keep them in sync.

♻️ Suggested helper

+function parseReExportSource(
+  raw: string,
+  fallbackName: string,
+): { source: string; imported_name: string } {
+  const dotIdx = raw.lastIndexOf(".");
+  const sourceTail = raw.split("/").pop() ?? "";
+  const hasNameSuffix =
+    !sourceTail.startsWith(".") &&
+    dotIdx > raw.lastIndexOf("/") &&
+    dotIdx > 0;
+  return {
+    source: hasNameSuffix ? raw.slice(0, dotIdx) : raw,
+    imported_name: hasNameSuffix ? raw.slice(dotIdx + 1) : fallbackName,
+  };
+}

…then call it from both loops.

Also applies to: 752-764

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/application/bindings-engine.ts` around lines 541 - 557, Extract the
duplicated parsing logic for r.re_export_source into a single helper (e.g.,
parseReExportSource or parseReExportSourceString) that accepts the
re_export_source string and returns an object with { source, imported_name };
then replace the 16-line parsing block in resolveBindings and the identical
block in resolveReExportChains with calls to that helper, passing
r.re_export_source and using the returned source/imported_name to call
re.set(r.name, ...) (or the equivalent in the other loop). Ensure the helper
implements the same rules (detecting the last dot after the last slash, handling
`.default` and names without suffixes) so behavior remains identical.

---

437-597: 💤 Low value

Add JSDoc to exported binding-engine functions.

resolveBindings, resolveReExportChains, persistReExportChains, and persistBindings are exported public APIs. Only resolveReExportChains has a doc comment. The repo's coding guideline requires accompanying documentation on public APIs; a one-liner stating the responsibility, side effects (persistReExportChains deletes & rewrites the whole table), and the orphan-clearing behavior of persistBindings would help callers understand the contract without reading the body.

As per coding guidelines: "All public APIs must have accompanying documentation".

Also applies to: 735-811

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/application/bindings-engine.ts` around lines 437 - 597, Add JSDoc
comments to the exported public functions resolveBindings,
resolveReExportChains, persistReExportChains, and persistBindings: for each
provide a one-line summary of responsibility and any side effects (e.g.,
persistReExportChains deletes and rewrites the entire re-export table) and for
persistBindings mention its orphan-clearing behavior when writing bindings;
place the comments immediately above each function declaration (matching the
style used for resolveReExportChains) so callers can understand the contract
without reading the implementation.

---

13-371: 💤 Low value

Duplicate entries in TYPE_GLOBALS and GLOBALS — dedupe.

Set<string> literals contain several duplicates that bloat the source and obscure intent:

• TYPE_GLOBALS: Window, Document, HTMLElement, FileReader, FormData, Headers, Request, Response, URL, URLSearchParams, Event all appear twice in different "section comments".
• GLOBALS: Number, FileReader, Image, FormData, AbortController, Headers, Request, Response, URL, URLSearchParams, Blob, File are repeated.

Also, GLOBALS contains reserved keywords / non-identifiers (undefined, null, true, false, this, arguments, super, new, void, typeof, instanceof, in, of) which can never be references.name values, so they're dead entries. None of these affect correctness (Set dedupes at insert) but they make the allowlists harder to audit.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/application/bindings-engine.ts` around lines 13 - 371, Remove duplicate
and invalid entries from the two allowlists: dedupe TYPE_GLOBALS and GLOBALS by
ensuring each symbol appears only once (e.g., remove repeated "Window",
"Document", "HTMLElement", "FileReader", "FormData", "Headers", "Request",
"Response", "URL", "URLSearchParams", "Event", etc. from TYPE_GLOBALS and
repeated "Number", "FileReader", "Image", "FormData", "AbortController",
"Headers", "Request", "Response", "URL", "URLSearchParams", "Blob", "File" from
GLOBALS). Also remove reserved keywords/non-identifiers from GLOBALS (e.g.,
"undefined", "null", "true", "false", "this", "arguments", "super", "new",
"void", "typeof", "instanceof", "in", "of") since they cannot be reference
names; keep the sets concise and optionally reorder or comment-group remaining
entries for readability while preserving the Set literal names TYPE_GLOBALS and
GLOBALS.

src/extractors/runtime-markers.ts (1)

30-47: 💤 Low value

end parameter is unused — drop it or wire it through.

emit() accepts end but only does void end;. Either remove the param (cleaner signature) or emit line_end/column_end alongside line_start/column_start for symmetry with markers (which now records both). Recipes that highlight runtime markers in editors would benefit from the end span.

♻️ Suggested simplification

-    function emit(
-      kind: "console" | "debugger" | "throw" | "process-env",
-      start: number,
-      end: number,
-      detail: string | null,
-    ) {
+    function emit(
+      kind: "console" | "debugger" | "throw" | "process-env",
+      start: number,
+      detail: string | null,
+    ) {
       const lineStart = offsetToLine(lineMap, start);
       const lineStartOffset = lineMap[lineStart - 1] ?? 0;
       out.push({
         file_path: relPath,
         kind,
         line_start: lineStart,
         column_start: start - lineStartOffset,
         detail,
         scope_local_id: scopes.currentLocalId(),
       });
-      void end;
     }

…and drop end at each call site.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/extractors/runtime-markers.ts` around lines 30 - 47, The emit function
currently accepts an unused end parameter; either remove end from the emit
signature and all its call sites (simpler), or wire it through to emit span end
fields: compute lineEnd = offsetToLine(lineMap, end) and lineEndOffset =
lineMap[lineEnd - 1] ?? 0 and add line_end: lineEnd and column_end: end -
lineEndOffset to the object pushed into out (alongside existing file_path, kind,
line_start, column_start, detail, scope_local_id), updating all callers of emit
and keeping references to emit, offsetToLine, lineMap, out, relPath, and
scopes.currentLocalId() in mind; ensure symmetry with the markers
representation.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/application/apply-engine.ts`:
- Around line 122-124: The lexical resolve of projectRoot (resolvedRoot) doesn't
follow symlinks and allows symlink-escape when later using filesystem-aware ops
(readFileSync, writeFileSync, renameSync); fix by resolving symlinks with
fs.realpathSync on the resolvedRoot (or realpathSync the file's parent before
any write/read/rename) and use that real path in isWithinRoot checks so all
isWithinRoot comparisons use real paths rather than path.resolve results; update
uses of resolvedRoot/isWithinRoot to compare against the realpath (or validate
realpath of targets) to prevent symlink escape.

In `@src/application/index-engine.ts`:
- Around line 443-452: The incremental path unconditionally calls
insertFileMetrics(db, [data.fileMetrics]) which can throw if data.fileMetrics is
undefined/null; match the full-rebuild behavior in insertParsedResults by adding
a presence guard (e.g., if (data.fileMetrics)) before calling insertFileMetrics
so insertFileMetrics is only invoked when fileMetrics exists; locate the call in
the incremental flow where insertFileMetrics is invoked and apply the same
conditional check used in insertParsedResults (and consider extractFileData's
possible undefined return).

In `@src/extractors/calls.ts`:
- Around line 37-44: The callee extraction currently only handles a single
MemberExpression level (Identifier.property or ThisExpression.property) and
drops nested chains like foo.bar.baz(); update the logic around callee?.type ===
"MemberExpression" to recursively flatten MemberExpression chains: walk the
callee object up while its type is MemberExpression, prepending each property
(use ".prop" for non-computed properties and "[<expression>]" for computed
properties) until you reach an Identifier or ThisExpression, then prefix the
root name (identifier name or "this") to produce calleeName; preserve existing
handling for Identifier and ThisExpression and ensure you respect computed vs
non-computed properties when building the string.

In `@src/extractors/components.ts`:
- Around line 20-32: The code currently uses a single variable currentScope in
the scope-tracking object (enter, current, exit) which loses outer scope when
nested components are traversed; replace currentScope with a stack (e.g.,
scopeStack: string[]), modify enter(name) to push name and ensure
hookCalls.set(name, []) when first seen, modify current() to return the top of
the stack (last element) or null when empty, and modify exit() to pop the stack;
apply the same stack-based change to the other similar scope-tracking blocks
(the ones mirroring enter/current/exit logic) so nested scope attribution is
preserved across all occurrences (refer to the functions/methods named enter,
current, exit and the variable hookCalls to locate each instance).

In `@src/extractors/references.ts`:
- Around line 74-80: The VariableDeclarator visitor currently only marks
declarations as writes when node.init exists, so bare declarations like let x;
or var y; are missed; update the VariableDeclarator handler (function name:
VariableDeclarator) to mark declaration binding positions unconditionally for
Identifier ids by adding the id.start to writePositions and suppressedReads
regardless of node.init (keep the existing id type check), i.e., remove or
bypass the node.init gating so declarations without initializers emit write
refs.
- Around line 54-60: The AssignmentExpression visitor only handles Identifier
LHS nodes; update it to treat ObjectPattern and ArrayPattern LHSs by walking the
pattern and adding each Identifier's start to writePositions (and to
suppressedReads when node.operator === "=") so destructured targets like ({a} =
obj) or [x] = arr are marked as writes rather than reads; keep the existing
behavior for simple Identifier handling and for non-"=" operators (compound
assignments) where suppressedReads should not be added.

In `@src/extractors/scopes.ts`:
- Line 33: The current scope string assembly (variable scopeStr built from name)
uses empty names for anonymous scopes which produces identical text (e.g.,
"foo.") and causes call-edge collisions; update the logic in the scope-building
code (the scopeStr assignment and the other occurrences that append name) to
substitute a stable anonymous token when name === "" — for example use a
deterministic local identifier (node.localId or a generated stable id tied to
the block/function) instead of an empty string, so replace `${name}` with
`${name || <stableAnonIdForNode>}` wherever scopeStr is constructed (ensure the
same token source is used at all occurrences to keep tokens stable across runs).

In `@src/extractors/symbols.ts`:
- Around line 151-152: The code currently uses node.start/node.end when
computing line spans via offsetToLine for each declarator (affecting
lineStart/lineEnd and body_line_count), which overestimates spans in
multi-declaration statements; update the logic in the symbols extraction so each
declarator uses its own positions: use decl.start/decl.end for declarators and,
for declarators whose init is a function, use init.start/init.end to compute the
function body span (so offsetToLine(lineMap, decl.start/decl.end) or
offsetToLine(lineMap, init.start/init.end) as appropriate), and ensure the same
change is applied where node.start/node.end are used later (the other occurrence
analogous to lines 180-181).

In `@src/extractors/type-stringify.ts`:
- Around line 16-18: The current TSQualifiedName handling uses tn.left?.name
which fails when tn.left is another TSQualifiedName; replace that inline string
interpolation with a recursive resolver that walks TSQualifiedName nodes to
build the full dotted identifier (e.g., implement a helper like
getQualifiedName(node) or update the current stringify function to, when
encountering tn.type === "TSQualifiedName", recursively compute the left part
(if left.type === "TSQualifiedName" call the resolver, otherwise use left.name)
and then append "." + right.name so nested names like A.B.C are returned intact
before any generic/composed logic.

In `@templates/recipes/find-export-sites.md`:
- Line 9: The action description uses call-site wording "callee-token-precise"
which is inconsistent for an export-site recipe; update the description string
so it uses export-specific terminology (e.g., replace "callee-token-precise"
with "export-name-token-precise" or "export-token-precise") so the phrase reads:
"Each row carries `file_path:line_start:column_start` (export-name-token-precise
per R.6) plus `is_re_export`..." and keep the rest of the sentence intact.

In `@templates/recipes/find-skipped-tests.sql`:
- Around line 6-10: The CASE that computes status currently checks is_skipped
before is_only, causing rows with multiple flags to be labeled 'skipped' instead
of the higher-priority 'only'; update the CASE expression (the WHEN branches
that set status) so that WHEN is_only = 1 THEN 'only' comes before WHEN
is_skipped = 1 THEN 'skipped' (keep is_todo logic and the AS status alias
unchanged) so `.only` is prioritized when multiple flags are set.

In `@templates/recipes/large-functions.md`:
- Line 10: Update the description in templates/recipes/large-functions.md to
explicitly state that the query returns only the top 50 largest functions (the
SQL uses LIMIT 50), so users know the output is truncated; mention the ranking
is by body_line_count and includes complexity, and note that if they need the
full set they should remove or change the LIMIT in the corresponding SQL query.

---

Nitpick comments:
In `@docs/research/codemap-richer-index-synthesis-2026-05.md`:
- Around line 100-113: The example code block uses non‑existent/unstable symbols
(codemap, query_recipe from "@stainless-code/codemap-mcp", and ts-morph's
Project) and is an aspirational sketch, so update the note to mark the snippet
as unvalidated/experimental: add an explicit one‑line disclaimer before the code
that this is a Path B sketch, not a tested API, and mention the specific symbols
(codemap, query_recipe, Project, ts-morph) that may change; alternatively,
replace the snippet with a syntactically valid but clearly stubbed example
(e.g., pseudocode or comment placeholders) so the document obeys the “examples
must be kept current” guideline while preserving the research intent.

In `@src/application/bindings-engine.ts`:
- Around line 541-557: Extract the duplicated parsing logic for
r.re_export_source into a single helper (e.g., parseReExportSource or
parseReExportSourceString) that accepts the re_export_source string and returns
an object with { source, imported_name }; then replace the 16-line parsing block
in resolveBindings and the identical block in resolveReExportChains with calls
to that helper, passing r.re_export_source and using the returned
source/imported_name to call re.set(r.name, ...) (or the equivalent in the other
loop). Ensure the helper implements the same rules (detecting the last dot after
the last slash, handling `.default` and names without suffixes) so behavior
remains identical.
- Around line 437-597: Add JSDoc comments to the exported public functions
resolveBindings, resolveReExportChains, persistReExportChains, and
persistBindings: for each provide a one-line summary of responsibility and any
side effects (e.g., persistReExportChains deletes and rewrites the entire
re-export table) and for persistBindings mention its orphan-clearing behavior
when writing bindings; place the comments immediately above each function
declaration (matching the style used for resolveReExportChains) so callers can
understand the contract without reading the implementation.
- Around line 13-371: Remove duplicate and invalid entries from the two
allowlists: dedupe TYPE_GLOBALS and GLOBALS by ensuring each symbol appears only
once (e.g., remove repeated "Window", "Document", "HTMLElement", "FileReader",
"FormData", "Headers", "Request", "Response", "URL", "URLSearchParams", "Event",
etc. from TYPE_GLOBALS and repeated "Number", "FileReader", "Image", "FormData",
"AbortController", "Headers", "Request", "Response", "URL", "URLSearchParams",
"Blob", "File" from GLOBALS). Also remove reserved keywords/non-identifiers from
GLOBALS (e.g., "undefined", "null", "true", "false", "this", "arguments",
"super", "new", "void", "typeof", "instanceof", "in", "of") since they cannot be
reference names; keep the sets concise and optionally reorder or comment-group
remaining entries for readability while preserving the Set literal names
TYPE_GLOBALS and GLOBALS.

In `@src/application/index-engine.ts`:
- Around line 293-312: The fetchTableStats function and the IndexTableStats type
need to be updated to include the eight+ new tables added by the richer-index
PR; update the SQL in fetchTableStats to SELECT COUNT(*) for each new table
(scopes, references, bindings, import_specifiers, function_params,
runtime_markers, test_suites, re_export_chains, module_cycles, file_metrics,
etc.) and expand the IndexTableStats shape to include corresponding fields so
the returned row maps to the new properties; ensure the returned object keys
match IndexTableStats property names and that fetchTableStats still returns the
row cast as IndexTableStats.

In `@src/extractors/runtime-markers.ts`:
- Around line 30-47: The emit function currently accepts an unused end
parameter; either remove end from the emit signature and all its call sites
(simpler), or wire it through to emit span end fields: compute lineEnd =
offsetToLine(lineMap, end) and lineEndOffset = lineMap[lineEnd - 1] ?? 0 and add
line_end: lineEnd and column_end: end - lineEndOffset to the object pushed into
out (alongside existing file_path, kind, line_start, column_start, detail,
scope_local_id), updating all callers of emit and keeping references to emit,
offsetToLine, lineMap, out, relPath, and scopes.currentLocalId() in mind; ensure
symmetry with the markers representation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1f375594-3e45-41a9-a686-5c2acd6c859f

📥 Commits

Reviewing files that changed from the base of the PR and between bfc0b8a and b5191f1.

📒 Files selected for processing (99)

• .agents/rules/codemap.md
• .agents/skills/codemap/SKILL.md
• .changeset/codemap-apply.md
• docs/architecture.md
• docs/glossary.md
• docs/plans/codemap-apply.md
• docs/plans/substrate-extraction.md
• docs/research/codemap-richer-index-synthesis-2026-05.md
• docs/roadmap.md
• fixtures/golden/minimal/barrel-chains.json
• fixtures/golden/minimal/circular-imports.json
• fixtures/golden/minimal/deeply-nested-functions.json
• fixtures/golden/minimal/env-var-audit.json
• fixtures/golden/minimal/find-by-param-type.json
• fixtures/golden/minimal/find-call-sites.json
• fixtures/golden/minimal/find-export-sites.json
• fixtures/golden/minimal/find-import-sites.json
• fixtures/golden/minimal/find-leftover-console.json
• fixtures/golden/minimal/find-references.json
• fixtures/golden/minimal/find-skipped-tests.json
• fixtures/golden/minimal/find-symbol-definitions.json
• fixtures/golden/minimal/find-symbol-references.json
• fixtures/golden/minimal/find-write-sites.json
• fixtures/golden/minimal/index-summary.json
• fixtures/golden/minimal/large-functions.json
• fixtures/golden/minimal/tests-by-file.json
• fixtures/golden/scenarios.json
• src/adapters/builtin.ts
• src/adapters/types.ts
• src/application/apply-engine.test.ts
• src/application/apply-engine.ts
• src/application/bindings-engine.ts
• src/application/cycles-engine.ts
• src/application/http-server.ts
• src/application/impact-engine.test.ts
• src/application/index-engine.ts
• src/application/mcp-server.test.ts
• src/application/mcp-server.ts
• src/application/recipe-params.ts
• src/application/resource-handlers.test.ts
• src/application/tool-handlers.test.ts
• src/application/tool-handlers.ts
• src/cli/bootstrap.ts
• src/cli/cmd-apply.test.ts
• src/cli/cmd-apply.ts
• src/cli/main.ts
• src/config.ts
• src/db.ts
• src/extractors/calls.ts
• src/extractors/complexity.ts
• src/extractors/components.ts
• src/extractors/jsdoc.ts
• src/extractors/markers.ts
• src/extractors/offsets.ts
• src/extractors/params.ts
• src/extractors/references.ts
• src/extractors/runtime-markers.ts
• src/extractors/scopes.ts
• src/extractors/symbols.ts
• src/extractors/tests.ts
• src/extractors/type-stringify.ts
• src/extractors/types.ts
• src/markers.ts
• src/parsed-types.ts
• src/parser.ts
• templates/agents/rules/codemap.md
• templates/agents/skills/codemap/SKILL.md
• templates/recipes/barrel-chains.md
• templates/recipes/barrel-chains.sql
• templates/recipes/circular-imports.md
• templates/recipes/circular-imports.sql
• templates/recipes/deeply-nested-functions.md
• templates/recipes/deeply-nested-functions.sql
• templates/recipes/env-var-audit.md
• templates/recipes/env-var-audit.sql
• templates/recipes/find-by-param-type.md
• templates/recipes/find-by-param-type.sql
• templates/recipes/find-call-sites.md
• templates/recipes/find-call-sites.sql
• templates/recipes/find-export-sites.md
• templates/recipes/find-export-sites.sql
• templates/recipes/find-import-sites.md
• templates/recipes/find-import-sites.sql
• templates/recipes/find-leftover-console.md
• templates/recipes/find-leftover-console.sql
• templates/recipes/find-references.md
• templates/recipes/find-references.sql
• templates/recipes/find-skipped-tests.md
• templates/recipes/find-skipped-tests.sql
• templates/recipes/find-symbol-definitions.md
• templates/recipes/find-symbol-definitions.sql
• templates/recipes/find-symbol-references.md
• templates/recipes/find-symbol-references.sql
• templates/recipes/find-write-sites.md
• templates/recipes/find-write-sites.sql
• templates/recipes/large-functions.md
• templates/recipes/large-functions.sql
• templates/recipes/tests-by-file.md
• templates/recipes/tests-by-file.sql

💤 Files with no reviewable changes (2)

• docs/roadmap.md
• docs/plans/codemap-apply.md

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/db.ts (1)

1265-1294: ⚡ Quick win

insertTestSuites uses firstId + parent_index mapping with minimal but practical constraints.

The code assumes:

1. Parent rows are emitted before children — the test extractor's DFS traversal guarantees this: a parent is added at index idx, pushed onto parentStack, and all children are added while the parent is on the stack, so all children indices are > idx. This is not an implicit contract; it's enforced by the extractor.

2. No inter-batch concurrent writes to test_suites — batchInsert calls db.run() once per BATCH_SIZE batch without transaction wrapping. In the single-process per-file extraction context, this is safe; a concurrent writer between batches would desynchronize the firstId + parent_index mapping and violate the immediate FK on parent_suite_id.

3. No gaps in sqlite_sequence — single-process per-file context makes this unlikely.

For robustness, consider wrapping the function body in a SAVEPOINT (precedent: reconcileBoundaryRules on lines 627–641) to pin the sqlite_sequence snapshot to the inserts and handle failure atomicity:

♻️ Suggested hardening

 export function insertTestSuites(db: CodemapDatabase, rows: TestSuiteRow[]) {
   if (!rows.length) return;
-  // Insert in a single transaction; rowids are sequential so the
-  // parent_index → real id mapping is `firstId + parent_index`.
+  db.run("SAVEPOINT insert_test_suites");
+  try {
     const firstIdRow = db
       .query<{ seq: number | null }>(
         "SELECT seq FROM sqlite_sequence WHERE name = 'test_suites'",
       )
       .get();
     const firstId = (firstIdRow?.seq ?? 0) + 1;
     batchInsert(
       db,
       rows,
       "INSERT INTO test_suites (file_path, name, kind, line_start, line_end, parent_suite_id, is_skipped, is_only, is_todo, framework)",
       "(?,?,?,?,?,?,?,?,?,?)",
       (r, v) =>
         v.push(
           r.file_path,
           r.name,
           r.kind,
           r.line_start,
           r.line_end,
           r.parent_index === null ? null : firstId + r.parent_index,
           r.is_skipped,
           r.is_only,
           r.is_todo,
           r.framework,
         ),
     );
+    db.run("RELEASE SAVEPOINT insert_test_suites");
+  } catch (error) {
+    db.run("ROLLBACK TO SAVEPOINT insert_test_suites");
+    db.run("RELEASE SAVEPOINT insert_test_suites");
+    throw error;
+  }
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/db.ts` around lines 1265 - 1294, insertTestSuites currently reads
sqlite_sequence then calls batchInsert across multiple db.run batches which can
be desynchronized by intervening writes; wrap the body of insertTestSuites in a
SAVEPOINT (like reconcileBoundaryRules does) so you pin the sqlite_sequence
snapshot, SELECT the seq after creating the SAVEPOINT to compute firstId, run
batchInsert while inside that SAVEPOINT, and RELEASE the SAVEPOINT on success or
ROLLBACK TO SAVEPOINT on error to preserve atomicity and keep the parent_index →
real id mapping correct.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/extractors/runtime-markers.ts`:
- Around line 54-60: The current runtime-marker emission uses only identifier
text (callee.object.name === "console"/"process") which misclassifies locally
shadowed bindings; before calling emit("console", ...) or emit("process", ...)
add a scope-resolved guard that verifies the Identifier is not bound in the
active scope chain (i.e. skip if there is a local binding for the Identifier
name). Locate the MemberExpression handler that references callee and emit, and
use your parser/scope API (currentScope/ancestors or
scopeManager.getScope/getBinding/hasBinding) to check for a local binding for
callee.object.name; only call emit when no local binding exists. Apply the same
change to both console and process emission sites so locally shadowed variables
are ignored (preserving global-only detection used by find-leftover-console and
env-var-audit).

---

Nitpick comments:
In `@src/db.ts`:
- Around line 1265-1294: insertTestSuites currently reads sqlite_sequence then
calls batchInsert across multiple db.run batches which can be desynchronized by
intervening writes; wrap the body of insertTestSuites in a SAVEPOINT (like
reconcileBoundaryRules does) so you pin the sqlite_sequence snapshot, SELECT the
seq after creating the SAVEPOINT to compute firstId, run batchInsert while
inside that SAVEPOINT, and RELEASE the SAVEPOINT on success or ROLLBACK TO
SAVEPOINT on error to preserve atomicity and keep the parent_index → real id
mapping correct.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4e92d930-8cad-495b-b54d-5b23d17e6e81

📥 Commits

Reviewing files that changed from the base of the PR and between b5191f1 and d757272.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (24)

• docs/architecture.md
• docs/glossary.md
• docs/golden-queries.md
• docs/research/codemap-richer-index-synthesis-2026-05.md
• docs/roadmap.md
• fixtures/golden/scenarios.json
• package.json
• src/application/bindings-engine.ts
• src/application/index-engine.ts
• src/application/run-index.ts
• src/application/types.ts
• src/db.ts
• src/extractors/calls.ts
• src/extractors/components.ts
• src/extractors/references.ts
• src/extractors/runtime-markers.ts
• src/extractors/scopes.ts
• src/extractors/symbols.ts
• src/extractors/type-stringify.ts
• templates/agents/rules/codemap.md
• templates/agents/skills/codemap/SKILL.md
• templates/recipes/find-export-sites.md
• templates/recipes/find-skipped-tests.sql
• templates/recipes/large-functions.md

✅ Files skipped from review due to trivial changes (5)

• docs/golden-queries.md
• templates/recipes/find-export-sites.md
• templates/agents/rules/codemap.md
• docs/architecture.md
• docs/research/codemap-richer-index-synthesis-2026-05.md

🚧 Files skipped from review as they are similar to previous changes (10)

• templates/recipes/find-skipped-tests.sql
• src/application/index-engine.ts
• src/extractors/type-stringify.ts
• src/extractors/calls.ts
• src/extractors/scopes.ts
• docs/roadmap.md
• src/extractors/symbols.ts
• src/extractors/references.ts
• src/application/bindings-engine.ts
• src/extractors/components.ts