@titan-design/code-graph 0.1.1 → 0.3.0

package/README.md

@@ -5,8 +5,8 @@ symbols, external packages, and the import / re-export / reference edges between
 index-time source metrics, in one SQLite file built from `@titan-design/store-sqlite` kit
 tables and refreshed incrementally.
 
-Tier 2 of the titan-platform DAG. Depends on `store-sqlite`, `ts-morph`, and the tree-sitter
-WASM grammars. Extracted from codewatch's `@codewatch/graph` (TP-9), split along the seam the
+Tier 2 of the titan-platform DAG. Depends on `store-sqlite`, `code-parser` (tree-sitter WASM
+parsing and the file filter), `ts-morph`, `web-tree-sitter` for node types, and `embed` plus `retrieval` for similar-symbol search. Extracted from codewatch's `@codewatch/graph` (TP-9), split along the seam the
 audit identified: that package did the job of both a store and a code graph.
 
 ```ts
@@ -23,7 +23,8 @@ listEdges(store, snapshotId); // imports / re-exports, references on request
 
 ## What was extracted, and what was not
 
-In: the parser (tree-sitter WASM for TypeScript, TSX and Python), the walk, the ts-morph
+In: the parser (tree-sitter WASM for TypeScript, TSX and Python, since moved to
+`@titan-design/code-parser` and still re-exported here), the walk, the ts-morph
 extractor and its symbol layer, role classification, generated-file detection, id aliasing
 across git renames, the three-tier incremental reuse, and the metrics computed at index time
 (degree, utilization, loc, cyclomatic, cognitive, nesting, class count, lcom4, per-symbol
@@ -31,16 +32,22 @@ complexity). `lcom.ts` came along despite being an analysis: `source-metrics.ts`
 directly and lcom4 is a pure function of a file's bytes, so it belongs with the metrics that
 carry forward under reuse.
 
+Ported later (TP-123, TP-124), strictly as codewatch had them: the rules engine
+(`check*.ts`, now `src/check/`) and the snapshot diff plus check diff (`diff.ts`,
+`check-diff.ts`, now `src/diff/`). See [Checks and diffs](#checks-and-diffs).
+Ported with TP-127 and TP-128: dead code, growth risk, PageRank, relevance, and symbol
+coupling, now `src/analysis/`. See [Graph analyses](#graph-analyses).
+Ported with TP-133: the test linker and the Istanbul coverage overlay, also in `src/analysis/`,
+and test-coverage ownership. See [Test linking and coverage](#test-linking-and-coverage).
+
+Ported with TP-250: package partition quality (`src/analysis/partition-quality.ts`) and
+snapshot pruning (`src/prune.ts`). See [Partition quality](#partition-quality) and
+[Pruning snapshots](#pruning-snapshots).
+
 Deferred, all of it still in codewatch, all of it a follow-up on this package rather than a
 change to it:
 
-- The rules engine (`check*.ts`) that turns a snapshot into pass/fail against a config.
-- Git-history mining: churn, ownership, change coupling, symbol coupling, test coverage
-  linking. `buildIndexerMetrics` used to fold these into the same pass; here it computes only
-  what a file's own bytes and the assembled graph determine.
-- Graph analyses over a finished snapshot: communities, pagerank, partition quality,
-  relevance, conventions, coverage overlay, dead code, growth risk, patterns, prune,
-  test-linker, diff, reuse-delta reporting, embeddings.
+- Graph analyses over a finished snapshot: communities, conventions, reuse-delta reporting.
 
 Python support is new here rather than ported. codewatch walked TypeScript only; the parser
 already had the grammar. The Python extractor is deliberately narrower than the ts-morph one:
@@ -49,16 +56,24 @@ same tree-sitter declaration walk that feeds complexity.
 
 ## The id scheme
 
-Preserved exactly from codewatch, because this repo's own `dag:check` consumes it through
-codewatch's CLI:
+File, module and external ids are preserved exactly from codewatch, because this repo's own
+`dag:check` consumes them through codewatch's CLI. Symbol ids diverge from codewatch since
+index version 0.14.0:
 
 - A **file** id is its path relative to the git toplevel, in posix form:
   `packages/registry/src/index.ts`. Ids root at the git toplevel even when you walk a
   subtree, so importers across subtrees share one id space.
 - A **module** id is the file id minus its extension: `packages/registry/src/index`. Its
   parent is the directory above it.
-- A **symbol** id hangs under its declaring file as `<fileId>#<name>`. `#` is legal in
-  neither a posix path nor a JS identifier, so the first one is the split.
+- A **symbol** id hangs under its declaring file as `<fileId>#<qualifiedName>`, split on the
+  first `#`. A top-level declaration's qualified name is its own name
+  (`src/a.ts#createThing`). A member or nested declaration is prefixed by its enclosing named
+  scopes, joined with `.`: `src/a.ts#Job.run`, `src/a.ts#outer.helper`, and
+  `src/a.ts#handlers.onClick` for a method of `const handlers = {…}`. Anonymous scopes, such
+  as a callback argument or an unbound class expression, add no segment, so ids do not depend
+  on declaration order. One scope binds a name once: a getter/setter pair, a Python property's
+  accessors, and overloads each share one node. Index versions before 0.14.0 keyed members by
+  bare name, so same-named methods in one file collapsed into one node (TP-182).
 - An **external** id is `npm:<package>` (scope-aware) or the `node:` builtin verbatim.
 
 `NodeKind`, `EdgeKind`, and the `role` vocabulary are unchanged. So is the property the DAG
@@ -67,11 +82,54 @@ package's source file, not to an `npm:` external, by remapping the `dist/*.d.ts`
 ts-morph resolves back onto `src/`. That remap needs the target package built, which is why
 `pnpm build` precedes both `pnpm test` and `dag:check`.
 
+## Identity across renames
+
+Added in index version 0.15.0 (TP-187). Git rename detection writes `id_alias` rows mapping a
+file's and its module's old id to the new one. A file rename also writes an alias for every
+symbol present on both sides, so `a.ts#Job.run` follows `a.ts` to `b.ts#Job.run`. A symbol
+renamed inside a file is not followed.
+
+Each snapshot records its alias base in `attrs.aliasBase`: the snapshot whose commit its
+aliases were computed against. A new index of a ref diffs against that ref's newest committed
+snapshot, falling back to the newest committed snapshot of any ref. The bases form a tree, so
+ids can be carried between any two snapshots that share an ancestor, forward or backward.
+
+```ts
+import { aliasChain, priorSnapshotForRef, resolveAlias } from "@titan-design/code-graph";
+
+resolveAlias(store, "src/job.ts", 4, { fromSnapshotId: 1 });
+// { id: 'core/worker.ts', reason: 'move',
+//   hops: [ src/job.ts -> src/task.ts, src/task.ts -> src/worker.ts, src/worker.ts -> core/worker.ts ] }
+resolveAlias(store, "src/job.ts#Job.run", 4, { fromSnapshotId: 1 }).id; // 'core/worker.ts#Job.run'
+aliasChain(store, 1, 4).resolve; // one resolver for many ids
+priorSnapshotForRef(store, "main", { before: 7, repoRoot: "." }); // the snapshot main denotes
+```
+
+Without `fromSnapshotId`, `resolveAlias` walks from the root of the target's lineage, so an id
+from any ancestor resolves. Each snapshot's aliases are applied once, in order: they come from
+one git diff, so `a.ts` to `b.ts` plus `b.ts` to `a.ts` in one snapshot is a swap, not a
+cycle. Walks stop after 10,000 snapshots. Two snapshots with no common base fall back to the
+to-snapshot's own aliases, which is what `diffSnapshots` did before 0.15.0.
+
+`priorSnapshotForRef` prefers the snapshot of the commit git resolves the ref to, and
+otherwise the newest snapshot labelled with that ref. A snapshot written before 0.15.0 records
+no base; its base is inferred as the newest earlier snapshot with a commit, which is the one
+the 0.14.0 indexer diffed against. Nothing is written on read, so a 0.14.0 store opened
+read-only diffs and checks across renames too.
+
 ## The three reuse tiers
 
 Every run writes a fingerprint per file: a content hash and a comment/whitespace-insensitive
 hash of its parse structure. The next run diffs against the most recent snapshot carrying the
-same `INDEX_VERSION` and sorts each file into one tier.
+same `INDEX_VERSION` and sorts each file into one tier. `INDEX_VERSION` is bumped whenever a
+metric can change for the same bytes, not only when the node or edge shape changes: 0.12.0
+marks `.tsx` files moving to the tsx grammar, which changed their complexity metrics and
+symbol spans; 0.13.0 marks the dead-code and growth-risk metrics joining the carry-forward set;
+0.14.0 marks symbol ids qualified by their enclosing scopes (TP-182); 0.15.0 marks symbol
+aliases on a file rename and the recorded alias base (TP-187). A snapshot from an older version
+is never reused, so the first run after an upgrade is a full index. The first 0.14.0 run after
+an older snapshot writes `requalify` id aliases from each bare-name id to its qualified
+successor, only where exactly one declaration in the file carries that name.
 
 | Tier | Trigger | Work skipped |
 |---|---|---|
@@ -88,6 +146,10 @@ always recomputed over the whole assembled graph, so a heavily-reused run and a
 
 `openCodeGraph` opens the database with the kit's pragmas and runs three migrations.
 
+It refuses a database stamped past `SCHEMA_VERSION` with `SchemaTooNewError`: a code graph
+database belongs to one build, so a higher version means a newer build already moved the
+schema and this one would query columns that are gone.
+
 Kit tables: `snapshot` (the snapshot registry), `node` (`entity_snap`, keyed
 `(snapshot_id, id)`), `blob_cache` (content-addressed, for the embedding and summary caches
 an analysis layer will want). Migration 2 adds four columns the kit shapes do not carry but
@@ -103,3 +165,276 @@ The symbol layer is hidden by default. `listNodes` drops `symbol` nodes and `lis
 `references` edges unless you ask for them, so a caller reasoning about module structure sees
 the graph it expects and does not have one import of thirty names read as thirty
 dependencies.
+
+## Targeted reads and the metric catalogue
+
+Added for the read API (TP-183). Three store reads answer one node or one metric without
+loading a snapshot, and a catalogue describes every metric name the package writes.
+
+```ts
+import { aggregateMetrics, describeMetric, listEdgesTouching, listMetricsForNode } from "@titan-design/code-graph";
+
+listMetricsForNode(store, snapshotId, "packages/registry/src/invoke.ts"); // every metric on one node
+listEdgesTouching(store, snapshotId, "packages/registry/src/invoke.ts"); // edges in and out; references on request
+aggregateMetrics(store, snapshotId, { name: "loc" }); // [{ name: "loc", nodeKind: "file", count, sum, min, max }]
+describeMetric("churn_90d"); // { unit: "lines", rollup: "sum", direction: "neutral", absent: "zero", window: "90d", … }
+```
+
+Three more store reads answer a report's questions without loading a snapshot:
+`listMetricNames(snapshotId)` for the distinct names stored, `topByMetric({ snapshotId,
+metric, limit, kind })` for the highest-valued nodes joined to their kind and role, and
+`replaceMetricsByName(snapshotId, name, metrics)`, which swaps one metric's whole row set in
+a single transaction so a re-ingested overlay such as coverage never accumulates stale rows.
+
+`computeDeepAst({ filePath, absPath, symbolName })` reads structure too heavy to persist
+(params, return type, class members) from the working tree on demand, and returns null when
+the file is unreadable.
+
+- **Reads.** `listMetricsForNode` searches the metric primary key, `listEdgesTouching` the edge
+  primary key plus `idx_edge_dst`, and `aggregateMetrics` `idx_metric_name`. None scans a
+  table, and no index or migration was added, so any existing store serves them. A self-loop
+  comes back once. `aggregateMetrics` groups by metric name and node kind, because
+  `utilization` and the degree metrics sit on several kinds; `count` skips null values.
+- **Catalogue.** `METRIC_CATALOGUE` holds one `MetricDescriptor` per name: `unit`,
+  `appliesTo` (node kinds), `rollup` (`sum`, `max`, `mean`, or `none`), `direction`
+  (`higher-worse`, `lower-worse`, or `neutral`), `absent`, `source`, and `description`.
+  Windowed names are templates such as `churn_{w}`; `describeMetric` resolves a stored name
+  such as `churn_90d` or `test_bus_factor_lifetime` to a concrete descriptor, and returns
+  null for a name nothing writes.
+- **`rollup: "none"`** means no rollup reproduces the group's own value. Summing fan-in counts
+  a directory's internal edges, and summing per-file commit counts counts a shared commit
+  more than once. A reader must not synthesize those.
+- **`absent`** says what a missing row means. `zero`: the writer is sparse, so count the node
+  as zero (dead code, growth risk, churn, `linked_test_count`). `exclude`: the metric does not
+  apply or was not measured (a max over no functions, `coverage_pct` before ingest), so leave
+  the node out of means, percentiles, and ranks.
+- **Completeness is tested.** `catalogue-completeness.test.ts` indexes a fixture repo with
+  history and a coverage overlay, and fails, naming the metric, when a stored name has no
+  descriptor, when a descriptor's unit or node kinds disagree with the rows, or when a
+  descriptor matches nothing.
+- **Browser-safe.** The catalogue imports only `types.ts`. The `code-graph-catalogue-pure`
+  and `code-graph-catalogue-no-node` rules in `.codewatch/check.json` hold it there, so a
+  later browser subpath can re-export it. It ships from the root export today, which does
+  pull in Node.
+
+## Checks and diffs
+
+The rules engine turns a snapshot into pass/fail against a `check.json`. Six rule types:
+`metric-max`, `metric-min`, `metric-product-max`, `forbid-import`, `layered-deps`, and
+`no-internal-only-barrels`. Severity defaults to `error`; only new errors fail a check.
+
+```ts
+import { checkSnapshot, loadCheckRules, openCodeGraph } from "@titan-design/code-graph";
+
+const store = openCodeGraph(".codewatch/graph.db");
+const rules = await loadCheckRules(".codewatch/check.json", { onWarn: console.warn });
+const { result } = checkSnapshot(store, { snapshot: "head", baseline: "main", rules });
+result.passed; // false only when a violation is an error and absent from the baseline
+```
+
+`snapshot` and `baseline` take a numeric snapshot id or a ref name; a ref resolves to its
+newest snapshot. `runChecks(store, { snapshotId, rules, baselineSnapshotId })` is the same
+engine on ids, and `validateRules(json)` validates an already-parsed rules object.
+
+The baseline is a ratchet. A violation whose key (rule id, node id, and destination id for
+edge rules) also fires on the baseline snapshot is marked `isCarryover` and counts as
+carryover, so existing debt does not block a change but new debt does. The baseline's node ids
+are first carried through the alias chain into the checked snapshot (`rebasedViolationKey`),
+so a moved file's violations carry over instead of reading as one resolved plus one new.
+Unmoved ids key exactly as `violationKey` always did. Deprecated metric and
+role spellings in a rules file (`lines`, `tests`) heal to their canonical names with a
+warning through `onWarn` instead of failing validation.
+
+`diffSnapshots(store, { fromSnapshotId, toSnapshotId })` reports added, removed and renamed
+nodes, added and removed edges, and metric deltas on nodes present in both. Ids follow the
+alias chain between the two snapshots, across every rename in between, so a move reads as a
+rename rather than a delete plus an add, and its edges do not churn. Metric and edge-kind spellings are
+canonicalised before comparing.
+
+`diffCheckResults(store, { fromSnapshotId, toSnapshotId, rules })` runs the rules on both
+snapshots and buckets each violation as new, resolved, or unchanged; unchanged metric
+violations are further split into worsened and improved by value. From-side ids follow the
+alias chain, as in the ratchet.
+
+`scripts/dag-check-self.mjs` in the repo root runs this repo's DAG check on this engine
+instead of codewatch's CLI.
+
+The glob matching the rules use is exported too, because a CLI filters its own `--include`
+and `--exclude` flags with the same semantics: `patternToRegex` (a `*` glob when the pattern
+holds one, a case-sensitive substring otherwise), `compilePatterns`, and `matchesAny`.
+
+## Similar symbols
+
+Ported from codewatch's `embeddings.ts` (TP-129). It answers "does something like this
+already exist?" before you write it. The embedder is injected; this package never builds
+one and never talks to a network on its own.
+
+```ts
+import { OllamaEmbedder } from "@titan-design/embed";
+import { findSimilarCapability, tryEmbedSnapshot } from "@titan-design/code-graph";
+
+const embedder = new OllamaEmbedder();
+const attempt = await tryEmbedSnapshot(store, snapshotId, embedder);
+// { ok: true, result: { symbols, embedded, withPurpose, newlyEmbedded, reused, model } }
+// or { ok: false, model, error } when the backend is down; the snapshot is unaffected
+const { candidates, coverage } = await findSimilarCapability(store, snapshotId, "parse a duration", embedder);
+```
+
+- **Corpus.** Exported symbols with a signature, minus test, fixture and generated files.
+  The embedded text is `signature -- purpose` (the docstring), never the body.
+- **Storage.** Vectors go in `blob_cache` under namespace `code-graph/symbol-embedding`,
+  keyed by `embedder.model` and the SHA-256 of the text. They are not snapshot-scoped, so
+  re-embedding unchanged text costs zero embed calls. `embedSnapshot` throws on a backend
+  failure; `tryEmbedSnapshot` reports it.
+- **Query.** `vectorRetriever` over a `BruteForceVectorIndex` from `retrieval`. The query is
+  embedded with role `query` and the symbol texts with role `document`; the embedder applies
+  the matching prefix (`search_query: ` / `search_document: ` for nomic models).
+- **Results are candidates, not verdicts.** Each has a cosine score, and `coverage` says how
+  many symbols were searchable and how many carry purpose text. There is deliberately no
+  co-location filter.
+- **Python symbols are not in the corpus yet.** The Python extractor records no signature or
+  docstring, so no Python symbol passes the corpus filter.
+- **Prefixes are part of the cache key.** `embedder.model` includes a hash of the embedder's
+  prefix table, so two prefix configurations never share a vector. codewatch used no prefix;
+  `new OllamaEmbedder({ prefixes: { document: "", query: "" } })` reproduces its rankings.
+
+## Graph analyses
+
+Dead-code and growth-risk metrics are computed at index time, like the source metrics, and
+carry forward for unchanged files. Both are sparse: a file gets a row only when a count is
+above zero.
+
+- Dead code, TypeScript only: `unreachable_statements` (after a `return`, `throw`, `break`
+  or `continue` in the same block), `unused_locals`, and `unused_params` (trailing run only).
+- Growth risk, TypeScript and Python: `loop_depth` (at 2 or more), `recursive_functions`,
+  and `search_in_loop` (`.includes`, `.find` and similar inside a loop). These are smells,
+  not complexity bounds. Recursion and search match TypeScript call nodes only, so Python
+  files get `loop_depth` alone, as in codewatch.
+
+PageRank, relevance, and symbol coupling run at query time over one snapshot:
+
+```ts
+import {
+  snapshotPageRank,
+  snapshotRelevance,
+  snapshotSymbolCoupling,
+} from "@titan-design/code-graph";
+
+snapshotPageRank(store, snapshotId); // global centrality over the file-level graph
+snapshotPageRank(store, snapshotId, { personalization: new Map([[fileId, 1]]) }); // seeded
+snapshotRelevance(store, snapshotId, [fileId]); // seeded over symmetrized edges
+snapshotSymbolCoupling(store, snapshotId); // symbol pairs co-imported by 2+ files
+```
+
+The pure `computePageRank`, `computeRelevance`, `computeSymbolConsumers`, and
+`computeSymbolCoupling` take node and edge arrays instead of a store.
+
+### Partition quality
+
+`computePartitionQuality` scores a package partition of the file graph: per-package cohesion,
+Martin instability, an abstractness proxy (the share of `role: "types"` files), a layer label
+(`top`, `middle`, `foundation`), pair coupling by intensity (`edges / files(from)`), and a
+Newman-Girvan modularity Q over the whole partition.
+
+```ts
+import { computePartitionQuality, invertBuckets } from "@titan-design/code-graph";
+
+const result = computePartitionQuality({ packages, fileByPackage, nodes, edges });
+result.modularityQ; // 0.77 on titan-platform's packages/*
+invertBuckets(fileByPackage); // file id -> package id, skipping the "" unassigned bucket
+```
+
+`resolveBarrels: true` rewrites an edge landing on a `role: "barrel"` file to the files it
+re-exports, transitively. It over-attributes: one import of one name through a barrel becomes
+one edge per re-export target, which is why it is off by default.
+
+### Pruning snapshots
+
+`planPrune` keeps the most recent `keep` snapshots (default 10) plus every snapshot whose ref
+is in `keepRefs`; `runPrune` deletes the rest and reports row counts before and after.
+
+```ts
+import { planPrune, runPrune } from "@titan-design/code-graph";
+
+planPrune(store, { keep: 10, keepRefs: ["main"] }); // { keep, remove }
+runPrune(store, { keep: 10, vacuum: true }); // { plan, rowsBefore, rowsAfter, vacuumed }
+```
+
+The domain tables declare no foreign key, so `CodeGraphStore.deleteSnapshots` clears each of
+`SNAPSHOT_SCOPED_TABLES` itself rather than relying on a cascade. `blob_cache` is
+content-addressed and not snapshot-scoped, so a prune never drops a cached embedding.
+
+## Git history
+
+Ported in TP-126, strictly as codewatch had it: churn over rolling windows, first-seen dates,
+ownership and bus factor, and change coupling. The engine lives in `src/history/` and is
+published on its own subpath. Its API is path-based: repo-relative posix paths in, plain
+records out, no node ids or snapshots.
+
+```ts
+import { computeChangeCoupling, couplingFor, loadChurnEntries } from "@titan-design/code-graph/history";
+
+const entries = loadChurnEntries({ repoRoot: ".", windowDays: 90 }) ?? []; // null outside git
+const { pairs, skippedLargeCommits } = computeChangeCoupling(entries);
+couplingFor(pairs, "packages/code-graph/src/indexer.ts"); // partners by co-edit count
+```
+
+`indexPaths` writes history metrics on file nodes by default, through the
+`history-metrics.ts` adapter, with codewatch's names: `churn_{w}`, `churn_{w}_commits`,
+`churn_{w}_authors` and `recency_{w}` for each window, `file_age_days`, and `bus_factor_{w}`
+plus `top_author_share_{w}` for the primary window. Windows default to 30, 90 and 180 days
+plus `churnWindowDays` (the primary, default 30); `churnWindows` replaces the defaults and
+`lifetime: true` adds an all-history window with its own ownership. `computeChurn: false`
+turns all of it off. Outside git, or without a git binary, the index simply has no history
+metrics.
+
+The adapter is exported from the package root, not from `./history`, because it speaks
+`GraphMetric` and the seam below does not. A product that indexes on its own terms calls
+`loadHistoryMetrics(nodes, idRoot, options)` for both the metric rows and the primary-window
+churn entries they were built from (`LoadedHistory`), with `HistoryMetricsOptions`,
+`DEFAULT_CHURN_WINDOWS` (`[30, 90, 180]`), `resolveChurnWindows`, `windowSuffix` (`30d`,
+`lifetime`) and `computeRecencyWindows` alongside it. Node ids are the history engine's
+repo-relative paths, so both must be rooted at the same `idRoot`.
+
+Change coupling is not stored. It is computed on demand from `loadChurnEntries`, as
+codewatch's `graph coupled` command did.
+
+**The seam.** Nothing under `src/history/` imports the rest of code-graph; the rest may import
+it. The `code-graph-history-seam` rule in `.codewatch/check.json` fails `pnpm dag:check` on
+any such import. That keeps a later extraction into `@titan-design/git-history` a directory
+move plus an import-path change.
+
+**Behaviour kept from codewatch, gaps included.** A rename is followed only inside the commit
+that made it, so a file's churn before the rename stays on its old path and is dropped.
+First-seen dates come from a separate `--no-renames` pass, which makes a renamed file look
+younger. `--since` resolves against git's clock while window slicing uses `nowEpoch`. History
+metrics are recomputed on every index and never carried forward under reuse.
+
+## Test linking and coverage
+
+Ported in TP-133, strictly as codewatch had it. `linkTestsToSources` pairs each test file
+with non-test files in two passes. Pass 1 uses path conventions: it strips a `.test` or `.spec`
+infix and collapses a `__tests__/`, `test/` or `tests/` segment. Pass 2 gives a test that
+pass 1 left unpaired its strongest co-edited non-test partner, with at least 2 shared commits.
+
+`indexPaths` writes `linked_test_count` on each linked source, with or without git. With git
+history on it also writes `test_bus_factor_{w}` and `test_top_author_share_{w}` for the
+primary window. These summarize churn authorship across all tests linked to a source, so a
+file can be well spread in production code and a single-author silo in its tests. All three
+are recomputed on every index and never carried forward.
+
+`computeTestCoverageOwnership` lives in the `history-metrics.ts` adapter, not in
+`src/history/`. It needs test links, and the seam forbids history from importing them.
+
+```ts
+import { attributeCoverage } from "@titan-design/code-graph";
+
+// fileIdOf maps an absolute path to a file id, or null to skip; spans come from symbol nodes' attrs.
+const metrics = attributeCoverage(istanbulReport, fileIdOf, symbolSpansByFile);
+```
+
+`attributeCoverage` turns an Istanbul `coverage-final.json` into `coverage_pct` metrics: one
+per file (covered functions over total functions) and one per symbol, matched by line-range
+containment to the innermost symbol. Coverage depends on which tests ran, not on file bytes,
+so the index never writes or carries it. The caller stores it on the snapshot it measured,
+as codewatch's `graph coverage` command does.

package/dist/change-coupling-CyqHgRsm.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A churn window is either a rolling N-day window or `"lifetime"` = all of git
+ * history (no `--since` bound). Lifetime mode lets an unfamiliar repo be audited
+ * cold, where any recent rolling slice is thin relative to the repo's whole
+ * life, so a windowed view reads an established repo as nearly churn-free.
+ */
+type ChurnWindow = number | "lifetime";
+
+interface ChurnEntry {
+    commit: string;
+    /** Author identity: git author email (%ae), stable across name spelling drift. */
+    author: string;
+    /** Committer time (%ct), epoch seconds; lets one wide log be sliced per window. */
+    epoch: number;
+    /** Repo-relative posix path, rebased onto the caller's root. */
+    filePath: string;
+    added: number;
+    deleted: number;
+}
+interface LoadChurnOptions {
+    /** Directory paths are made relative to; entries outside it are dropped. */
+    repoRoot: string;
+    windowDays?: ChurnWindow;
+}
+/**
+ * Parse the last `windowDays` of git history into ChurnEntry[] rebased onto
+ * `repoRoot`. Returns null if git isn't available; [] if no commits matched.
+ * Used both for churn metrics and for change-coupling.
+ */
+declare function loadChurnEntries(options: LoadChurnOptions): ChurnEntry[] | null;
+declare function parseChurnLog(text: string): ChurnEntry[];
+declare function resolveRenamedPath(rawPath: string): string;
+/** Entries whose commit landed within the last `windowDays` of `nowEpoch`. */
+declare function entriesWithin(entries: readonly ChurnEntry[], windowDays: number, nowEpoch: number): ChurnEntry[];
+
+interface CoEditPair {
+    fileA: string;
+    fileB: string;
+    /** Commits in which both files changed. */
+    count: number;
+    /** Most recent commits (up to maxCommitsPerPair). */
+    commits: string[];
+}
+interface ComputeChangeCouplingOptions {
+    /** Skip pairs that co-occur in fewer than this many commits. Default 2. */
+    minCount?: number;
+    /** Truncate the commits sample per pair. Default 10. */
+    maxCommitsPerPair?: number;
+    /**
+     * Skip commits touching more than this many files (sweeping refactors, mass
+     * renames). Default 50: beyond that the O(n²) pair explosion is signal-poor.
+     */
+    largeCommitThreshold?: number;
+    /** Filter file paths to this set before pairing. */
+    knownPaths?: ReadonlySet<string>;
+}
+interface ChangeCouplingResult {
+    pairs: CoEditPair[];
+    /** Commits dropped by largeCommitThreshold, so callers can say when sweeps suppressed the signal. */
+    skippedLargeCommits: number;
+    /** Threshold that was applied (echoed for diagnostic messages). */
+    largeCommitThreshold: number;
+}
+interface CouplingPartner {
+    partner: string;
+    count: number;
+    commits: string[];
+}
+declare function computeChangeCoupling(entries: readonly ChurnEntry[], options?: ComputeChangeCouplingOptions): ChangeCouplingResult;
+/** Files most coupled to `seed`, by co-edit count desc then path; the seed itself is excluded. */
+declare function couplingFor(pairs: readonly CoEditPair[], seed: string): CouplingPartner[];
+
+export { type ChurnEntry as C, type LoadChurnOptions as L, type ChurnWindow as a, type ChangeCouplingResult as b, type CoEditPair as c, type ComputeChangeCouplingOptions as d, type CouplingPartner as e, computeChangeCoupling as f, couplingFor as g, entriesWithin as h, loadChurnEntries as l, parseChurnLog as p, resolveRenamedPath as r };