fix(heritage): PR #142 review fixes (6 cycles) (#143)

* fix(heritage): address PR #142 review findings (cycle 1)

Class superClass generics, type-alias resolve, incremental scope expansion,
module-level symbol preference, complex extends fallback, recipe dedupe;
heritage-resolver tests + new recipe goldens; doc/glossary updates.

* fix(heritage): address review cycle 2 (expression bases, SQL dedupe)

Skip resolve for (expression) heritage markers; align type-descendants
homonym dedupe with ancestors via scope_local_id ordering; add scoped
re-resolve test.

* docs: close type-heritage-substrate plan (review cycle 3)

Delete shipped plan per docs-governance; prune roadmap and agent-surface
cross-refs; document (expression) heritage rows in recipe help.

* fix(heritage): review cycle 4 (default import, re-export, SQL)

Resolve default-import bases; expand incremental scope for re-export
barrel importers; homonym dedupe on ancestor start symbols; align
type kind filters; doc/changeset parity updates.

* test(heritage): review cycle 5 (persist + incremental e2e)

Add persistTypeHeritageResolution unit test and run-index incremental
test proving scoped heritage re-resolve updates DB rows.

* docs(recipes): note type kind filter on type-descendants (cycle 6)

Author: SutuSebastian

.changeset/type-heritage-review-fixes.md

@@ -0,0 +1,5 @@
+---
+"@stainless-code/codemap": patch
+---
+
+Fix type heritage resolve edge cases: default-import bases, re-export barrel incremental scope, homonym dedupe in ancestor walks, and `(expression)` complex extends handling.

.changeset/type-hierarchy-recipes.md

@@ -2,4 +2,4 @@
 "@stainless-code/codemap": patch
 ---
 
-Add `type-ancestors` and `type-descendants` query recipes for extends/implements hierarchy walks parsed from indexed symbol signatures.
+Add `type-ancestors` and `type-descendants` query recipes for extends/implements hierarchy walks (backed by the `type_heritage` substrate after #142).

docs/architecture.md

@@ -151,7 +151,7 @@ A local SQLite database (`.codemap/index.db`) indexes the project tree and store
 
 **Watch wiring:** **`src/cli/cmd-watch.ts`** (argv — `--debounce <ms>` / `--quiet`; bootstrap absorbs `--root`/`--config`) + **`src/application/watcher.ts`** (engine — pure debouncer + glob filter + injectable backend; production wires [chokidar v5](https://github.com/paulmillr/chokidar) selected via the 6-watcher audit in PR #46 — pure JS, runs identically on Bun + Node, ~30M repos use it). On every change/add/unlink event chokidar emits, the engine filters via `shouldIndexPath` (same indexed extensions as the indexer + project-local recipes; skips `node_modules` / `.git` / `dist`), debounces with a sliding window (default 250 ms), then calls `createReindexOnChange` which opens a DB, runs `runCodemapIndex({mode: 'files', files: [...changed]})`, closes the DB, and logs `reindex N file(s) in Mms` to stderr unless `--quiet`. SIGINT / SIGTERM drains pending edits via `flushNow()` before the watcher closes. **Default-ON for `mcp` / `serve` since 2026-05:** both transports boot the watcher in-process so every tool reads a live index — eliminates the per-request reindex prelude. Opt out with `--no-watch`, `CODEMAP_WATCH=0`, or `CODEMAP_NO_WATCH=1`. **`src/application/watch-policy.ts`** disables the watcher on WSL2 Windows drive mounts (`/mnt/*`) unless `CODEMAP_FORCE_WATCH=1`; stderr points at `codemap agents init --git-hooks` for git-triggered freshness. Standalone `codemap watch` runs the watcher decoupled from a transport for users wiring it next to a separate MCP / HTTP process. **Audit prelude optimization:** module-level `watchActive` flag; `handleAudit` skips its incremental-index prelude when active (and marks the close as readonly to avoid a wasted checkpoint). Explicit `no_index: false` still forces the prelude.
 
-**Performance wiring:** **`--performance`** plumbs through **`RunIndexOptions.performance`** → **`indexFiles({ performance, collectMs })`**. `parse-worker-core.ts` records per-file **`parseMs`** on each `ParsedFile`; main thread times the seven phases (`collect`, `parse`, `insert`, `index_create`, `bindings`, `module_cycles`, `re_export_chains`) and assembles **`IndexPerformanceReport`** under `IndexRunStats.performance`. Note: `total_ms` is `indexFiles` wall-clock (parse + insert + DDL + bindings + cycles + re_exports), **not** end-to-end run wall — `collect_ms` happens before `indexFiles` and is reported separately. Env var **`CODEMAP_PERFORMANCE_JSON=<path>`** dumps the report as JSON post-run (consumed by [`bun run check:perf-baseline`](./benchmark.md#perf-baseline-regression-guardrail) for CI regression-gating).
+**Performance wiring:** **`--performance`** plumbs through **`RunIndexOptions.performance`** → **`indexFiles({ performance, collectMs })`**. `parse-worker-core.ts` records per-file **`parseMs`** on each `ParsedFile`; main thread times the eight phases (`collect`, `parse`, `insert`, `index_create`, `bindings`, `module_cycles`, `re_export_chains`, `heritage`) and assembles **`IndexPerformanceReport`** under `IndexRunStats.performance`. Note: `total_ms` is `indexFiles` wall-clock (parse + insert + DDL + bindings + cycles + re_exports + heritage), **not** end-to-end run wall — `collect_ms` happens before `indexFiles` and is reported separately. Env var **`CODEMAP_PERFORMANCE_JSON=<path>`** dumps the report as JSON post-run (consumed by [`bun run check:perf-baseline`](./benchmark.md#perf-baseline-regression-guardrail) for CI regression-gating).
 
 **Agent templates:** `codemap agents init` writes thin pointer files (~16-line SKILL + ~22-line rule) to consumer disk; full content is served live by `codemap skill` / `codemap rule` (CLI) and `codemap://skill` / `codemap://rule` (MCP / HTTP) from `templates/agent-content/<kind>/*.md`. Section files concatenate in lexical order; `*.gen.md` sections dispatch to renderers in `application/agent-content.ts` so recipe catalog + schema DDL auto-register. Pointer-version stamp (`<!-- codemap-pointer-version: N -->`) + once-per-process stderr nag (`maybeWarnStalePointers`) flag stale consumer templates; cure is `codemap agents init --force`. Full matrix: [agents.md](./agents.md).
 
@@ -271,22 +271,22 @@ Edges are deduped per (caller_scope, callee, call vs constructor) per file: if `
 
 ### `type_heritage` — Class/interface extends and implements edges (`STRICT`)
 
-| Column              | Type       | Description                                                                            |
-| ------------------- | ---------- | -------------------------------------------------------------------------------------- |
-| id                  | INTEGER PK | Auto-increment row id                                                                  |
-| child_file_path     | TEXT FK    | File defining the child type                                                           |
-| child_name          | TEXT       | Child class or interface name                                                          |
-| child_kind          | TEXT       | `class` or `interface`                                                                 |
-| child_line_start    | INTEGER    | Child definition line                                                                  |
-| relation            | TEXT       | `extends` or `implements`                                                              |
-| base_simple_name    | TEXT       | Unqualified base name used for graph walks                                             |
-| base_qualified_name | TEXT       | Qualified base when present (e.g. `pkg.Type`); nullable                                |
-| base_file_path      | TEXT       | Resolved definition file (null until resolve pass)                                     |
-| base_symbol_id      | INTEGER FK | Resolved `symbols.id` (null when unresolved)                                           |
-| resolution_kind     | TEXT       | `same-file`, `imported`, `qualified-unresolved`, or `unresolved`                       |
-| type_args           | TEXT       | Comma-separated generic args when present (display only; walks use `base_simple_name`) |
-
-Populated at parse time from oxc AST; `heritage-resolver` fills `base_file_path` / `base_symbol_id` after bindings on full rebuild (scoped on incremental). Powers `type-ancestors` and `type-descendants` recipes.
+| Column              | Type       | Description                                                                                                                         |
+| ------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| id                  | INTEGER PK | Auto-increment row id                                                                                                               |
+| child_file_path     | TEXT FK    | File defining the child type                                                                                                        |
+| child_name          | TEXT       | Child class or interface name                                                                                                       |
+| child_kind          | TEXT       | `class` or `interface`                                                                                                              |
+| child_line_start    | INTEGER    | Child definition line                                                                                                               |
+| relation            | TEXT       | `extends` or `implements`                                                                                                           |
+| base_simple_name    | TEXT       | Unqualified base name used for graph walks                                                                                          |
+| base_qualified_name | TEXT       | Qualified base when present (e.g. `pkg.Type`); `(expression)` marks non-simple extends/implements expressions excluded from resolve |
+| base_file_path      | TEXT       | Resolved definition file (null until resolve pass)                                                                                  |
+| base_symbol_id      | INTEGER FK | Resolved `symbols.id` (null when unresolved)                                                                                        |
+| resolution_kind     | TEXT       | `same-file`, `imported`, `qualified-unresolved`, or `unresolved`                                                                    |
+| type_args           | TEXT       | Comma-separated generic args when present (display only; walks use `base_simple_name`)                                              |
+
+Populated at parse time from oxc AST; `heritage-resolver` fills `base_file_path` / `base_symbol_id` after bindings on full rebuild. Incremental `--files` re-resolves rows in changed files plus importers and consumers pointing at changed base files. Powers `type-ancestors` and `type-descendants` recipes.
 
 ### `imports` — Import statements (`STRICT`)
 

docs/benchmark.md

@@ -207,7 +207,7 @@ Independent of the consumer-facing scenarios above, the repo carries a **per-pha
 
 ### Mechanism
 
-1. `bun src/index.ts --full --performance` populates [`IndexPerformanceReport`](../src/application/types.ts) with `collect_ms` / `parse_ms` / `insert_ms` / `index_create_ms` / `bindings_ms` / `module_cycles_ms` / `re_export_chains_ms` / `total_ms`.
+1. `bun src/index.ts --full --performance` populates [`IndexPerformanceReport`](../src/application/types.ts) with `collect_ms` / `parse_ms` / `insert_ms` / `index_create_ms` / `bindings_ms` / `module_cycles_ms` / `re_export_chains_ms` / `heritage_ms` / `total_ms`.
 2. Setting `CODEMAP_PERFORMANCE_JSON=<path>` dumps that report as JSON to `<path>` after the run (no CLI flag added; env-var only).
 3. [`scripts/check-perf-baseline.ts`](../scripts/check-perf-baseline.ts) (alias `bun run check:perf-baseline`) runs the indexer 3× on this repo, takes per-phase **medians**, and compares to `fixtures/benchmark/perf-baseline.json`.
 4. **Local / scheduled only** — run before perf-sensitive PRs; [`.github/workflows/perf-baseline.yml`](../.github/workflows/perf-baseline.yml) fires weekly + `workflow_dispatch` for drift visibility. **Not** on the PR CI path (6 min × 3 runs + bimodal GHA runners → flaky merge gate).

docs/glossary.md

@@ -309,7 +309,7 @@ TS shape for one row of the `imports` table.
 
 ### `IndexPerformanceReport`
 
-TS shape emitted under `IndexRunStats.performance` when `--performance` is set. Seven per-phase timings (`collect_ms`, `parse_ms`, `insert_ms`, `index_create_ms`, `bindings_ms`, `module_cycles_ms`, `re_export_chains_ms`) + `total_ms` + top-10 slowest files. Note: `total_ms` is `indexFiles` wall-clock (parse + insert + DDL + bindings + cycles + re_exports) and excludes `collect_ms`; end-to-end run wall is `collect_ms + total_ms`. Setting `CODEMAP_PERFORMANCE_JSON=<path>` dumps the report as JSON post-run.
+TS shape emitted under `IndexRunStats.performance` when `--performance` is set. Eight per-phase timings (`collect_ms`, `parse_ms`, `insert_ms`, `index_create_ms`, `bindings_ms`, `module_cycles_ms`, `re_export_chains_ms`, `heritage_ms`) + `total_ms` + top-10 slowest files. Note: `total_ms` is `indexFiles` wall-clock (parse + insert + DDL + bindings + cycles + re_exports + heritage) and excludes `collect_ms`; end-to-end run wall is `collect_ms + total_ms`. Setting `CODEMAP_PERFORMANCE_JSON=<path>` dumps the report as JSON post-run.
 
 ### `IndexResult`
 
@@ -582,6 +582,10 @@ The glob implementation used on both Bun and Node (since the `collectFiles` refa
 
 A small end-to-end vertical slice (see [`.cursor/rules/tracer-bullets.mdc`](../.cursor/rules/tracer-bullets.mdc)). Used in PRs to validate the critical path before expanding.
 
+### `type_heritage` (table)
+
+One row per `extends` / `implements` edge on a class or interface. Populated at parse from oxc AST; `heritage-resolver` (pass 2, after bindings) fills `base_file_path` / `base_symbol_id` and sets `resolution_kind` (`same-file`, `imported`, `qualified-unresolved`, `unresolved`). Non-simple expression bases use `base_qualified_name = '(expression)'` and stay out of recipe walks. Incremental `--files` re-resolves rows in changed files plus importers and consumers pointing at changed base files (including one-hop type re-export barrels). Powers `type-ancestors` and `type-descendants` recipes. **`file_path` param:** on `type-ancestors` it disambiguates the start symbol only; on `type-descendants` it also filters output to descendants in that file.
+
 ### `type_members` (table)
 
 Properties and method signatures on interfaces and object-literal types. `symbol_name` references the parent `symbols.name`. `type` is null when the parser can't reconstruct the annotation. See `TypeMemberRow`.

docs/plans/agent-surface-and-ops.md

@@ -40,12 +40,11 @@ Details: [agents.md](../agents.md). Merge history: [agent-surface-delivery.md](.
 
 ## Related existing plans
 
-| Plan                                                          | Relationship                                                                                                 |
-| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| [c9-plugin-layer](./c9-plugin-layer.md)                       | Prerequisite for [framework-route-extraction](./framework-route-extraction.md)                               |
-| [github-marketplace-action](./github-marketplace-action.md)   | May add `affected` mode (shipped CLI/MCP `affected` + `affected-tests` recipe)                               |
-| [perf-triangulation-rollout](./perf-triangulation-rollout.md) | Parse-worker hardening shipped #130; Phase 3 deferrals remain in rollout plan                                |
-| [type-heritage-substrate](./type-heritage-substrate.md)       | Lifts [#141](https://github.com/stainless-code/codemap/pull/141) recipe limits via `type_heritage` substrate |
+| Plan                                                          | Relationship                                                                   |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| [c9-plugin-layer](./c9-plugin-layer.md)                       | Prerequisite for [framework-route-extraction](./framework-route-extraction.md) |
+| [github-marketplace-action](./github-marketplace-action.md)   | May add `affected` mode (shipped CLI/MCP `affected` + `affected-tests` recipe) |
+| [perf-triangulation-rollout](./perf-triangulation-rollout.md) | Parse-worker hardening shipped #130; Phase 3 deferrals remain in rollout plan  |
 
 ---