@titan-design/code-graph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Jewkes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# @titan-design/code-graph
+
+The dependency graph of a TypeScript or Python tree: files, modules, exported and internal
+symbols, external packages, and the import / re-export / reference edges between them, with
+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
+audit identified: that package did the job of both a store and a code graph.
+
+```ts
+import { indexPaths, listEdges, listNodes, openCodeGraph } from "@titan-design/code-graph";
+
+const store = openCodeGraph(".codewatch/graph.db");
+const { snapshotId, files, nodes, edges, reused } = await indexPaths(store, {
+  paths: ["packages", "products"],
+  ref: "head",
+});
+listNodes(store, snapshotId); // file / module / external nodes, symbols on request
+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
+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
+complexity). `lcom.ts` came along despite being an analysis: `source-metrics.ts` calls it
+directly and lcom4 is a pure function of a file's bytes, so it belongs with the metrics that
+carry forward under reuse.
+
+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.
+
+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:
+no type checker, so imports resolve by dotted path against the tree and symbols come from the
+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:
+
+- 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.
+- 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
+check rests on: an import of a workspace package by its published name resolves to that
+package's source file, not to an `npm:` external, by remapping the `dist/*.d.ts` entry
+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`.
+
+## 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.
+
+| Tier | Trigger | Work skipped |
+|---|---|---|
+| reuse | content hash matches | parse and extract both; nodes, edges and source metrics carried forward verbatim |
+| cosmetic | content changed, structural hash matches | the ts-morph extract; edges come from the basis, symbol line spans are refreshed from the fresh parse |
+| full | structural hash changed, or the file is new | nothing |
+
+A file-membership delta (a file added or removed) forces the files whose imports it
+re-resolves back to full extraction even when they are byte-identical. Degree metrics are
+always recomputed over the whole assembled graph, so a heavily-reused run and a
+`incremental: false` run produce the same snapshot; `indexer.test.ts` asserts that.
+
+## Store layout
+
+`openCodeGraph` opens the database with the kit's pragmas and runs three migrations.
+
+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
+every consumer reads directly: `node.language`, `node.role`, `snapshot.commit_hash`,
+`snapshot.index_version`.
+
+Domain tables in `schema.ts`: `edge` (snapshot-scoped, keyed
+`(snapshot_id, src_id, dst_id, kind)` — the kit's own edge table is bi-temporal, which is the
+wrong time model for a population re-indexed all at once), `metric`, `id_alias`, and
+`file_fingerprint`.
+
+The symbol layer is hidden by default. `listNodes` drops `symbol` nodes and `listEdges` drops
+`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.

package/dist/index.d.ts

@@ -0,0 +1,532 @@
+import { Db, Migration } from '@titan-design/store-sqlite';
+import { Tree } from 'web-tree-sitter';
+import { Project } from 'ts-morph';
+
+type NodeKind = "package" | "module" | "file" | "symbol" | "external";
+type EdgeKind = "imports" | "re-exports" | "calls" | "extends" | "implements" | "references" | "depends-on";
+type IdAliasReason = "rename" | "move" | "merge";
+type NodeRole = "test" | "fixture" | "barrel" | "types" | "config" | "script" | "entry" | "generated" | "source";
+interface GraphNode {
+    id: string;
+    kind: NodeKind;
+    name: string;
+    parentId?: string;
+    language?: string;
+    role?: NodeRole;
+    attrs?: Record<string, unknown>;
+}
+interface GraphEdge {
+    srcId: string;
+    dstId: string;
+    kind: EdgeKind;
+    attrs?: Record<string, unknown>;
+}
+interface GraphMetric {
+    nodeId: string;
+    name: string;
+    value: number | null;
+    unit?: string;
+}
+interface GraphFragment {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+interface SnapshotRow {
+    id: number;
+    ref: string;
+    commitHash: string | null;
+    takenAt: string;
+    indexVersion: string;
+    attrs: Record<string, unknown>;
+}
+interface IdAlias {
+    oldId: string;
+    newId: string;
+    reason: IdAliasReason;
+}
+interface FileFingerprint {
+    fileId: string;
+    contentHash: string;
+    /**
+     * Comment/whitespace-insensitive parse-structure hash (C-18). Absent on
+     * snapshots written before C-18 (they can only reuse whole unchanged files).
+     */
+    structuralHash?: string;
+}
+
+interface SnapshotInsert {
+    ref: string;
+    commitHash?: string;
+    indexVersion: string;
+    attrs?: Record<string, unknown>;
+}
+/**
+ * The code graph's query surface over store-sqlite's snapshot-scoped kit tables
+ * plus this package's domain tables. Replaces codewatch's `GraphDatabase`: the
+ * connection, pragmas, and migration runner are the kit's; what is left here is
+ * the code-specific statements the indexer and its readers need.
+ */
+declare class CodeGraphStore {
+    readonly db: Db;
+    private readonly statements;
+    constructor(db: Db);
+    createSnapshot(input: SnapshotInsert): number;
+    insertNodes(snapshotId: number, nodes: readonly GraphNode[]): void;
+    insertEdges(snapshotId: number, edges: readonly GraphEdge[]): void;
+    insertMetrics(snapshotId: number, metrics: readonly GraphMetric[]): void;
+    insertAliases(snapshotId: number, aliases: readonly IdAlias[]): void;
+    insertFingerprints(snapshotId: number, fingerprints: readonly FileFingerprint[]): void;
+    getSnapshot(id: number): SnapshotRow | null;
+    listSnapshots(opts?: {
+        ref?: string;
+        limit?: number;
+    }): SnapshotRow[];
+    getLatestSnapshotByRef(ref: string): SnapshotRow | null;
+    getNode(snapshotId: number, id: string): GraphNode | null;
+    /**
+     * File-level structural graph by default: the per-symbol layer is excluded so
+     * consumers that reason about module structure see the graph they expect. Pass
+     * `includeSymbols` for the symbol layer (the reuse basis needs it).
+     */
+    listNodes(snapshotId: number, opts?: {
+        includeSymbols?: boolean;
+    }): GraphNode[];
+    /** See {@link listNodes}: `references` edges are the symbol layer, excluded by default. */
+    listEdges(snapshotId: number, opts?: {
+        includeReferences?: boolean;
+    }): GraphEdge[];
+    listMetrics(snapshotId: number): GraphMetric[];
+    listAliases(snapshotId: number): IdAlias[];
+    listFingerprints(snapshotId: number): FileFingerprint[];
+    close(): void;
+}
+/** Open (creating if absent) a code graph database and bring it to the current schema. */
+declare function openCodeGraph(dbPath: string): CodeGraphStore;
+
+/**
+ * Kit table names. The code graph is snapshot-scoped end to end: a whole repo is
+ * re-indexed together, so `snapshotTableDdl` + `entitySnapTableDdl` are the right
+ * time model and the interval `edgeTableDdl` is not — one unchanged import would
+ * otherwise write a row per file per snapshot. The edge table below is therefore
+ * the snapshot-scoped counterpart, owned here.
+ */
+declare const KIT: {
+    readonly snapshot: "snapshot";
+    readonly entitySnap: "node";
+    readonly cacheBlob: "blob_cache";
+};
+/**
+ * Domain tables. `edge` is the snapshot-scoped edge shape (the kit's own edge
+ * table is bi-temporal); `metric` holds index-time measurements keyed by node;
+ * `id_alias` carries a node id across a rename so two snapshots line up; and
+ * `file_fingerprint` is the reuse basis the incremental indexer diffs against.
+ */
+declare const DOMAIN_DDL = "\n  CREATE TABLE IF NOT EXISTS edge (\n    snapshot_id INTEGER NOT NULL,\n    src_id      TEXT NOT NULL,\n    dst_id      TEXT NOT NULL,\n    kind        TEXT NOT NULL,\n    attrs       TEXT,\n    PRIMARY KEY (snapshot_id, src_id, dst_id, kind)\n  );\n  CREATE INDEX IF NOT EXISTS idx_edge_dst ON edge(snapshot_id, dst_id);\n  CREATE INDEX IF NOT EXISTS idx_edge_kind ON edge(snapshot_id, kind);\n\n  CREATE TABLE IF NOT EXISTS metric (\n    snapshot_id INTEGER NOT NULL,\n    node_id     TEXT NOT NULL,\n    name        TEXT NOT NULL,\n    value       REAL,\n    unit        TEXT,\n    PRIMARY KEY (snapshot_id, node_id, name)\n  );\n  CREATE INDEX IF NOT EXISTS idx_metric_name ON metric(snapshot_id, name);\n\n  CREATE TABLE IF NOT EXISTS id_alias (\n    snapshot_id INTEGER NOT NULL,\n    old_id      TEXT NOT NULL,\n    new_id      TEXT NOT NULL,\n    reason      TEXT NOT NULL,\n    PRIMARY KEY (snapshot_id, old_id, new_id)\n  );\n\n  CREATE TABLE IF NOT EXISTS file_fingerprint (\n    snapshot_id     INTEGER NOT NULL,\n    file_id         TEXT NOT NULL,\n    content_hash    TEXT NOT NULL,\n    structural_hash TEXT,\n    PRIMARY KEY (snapshot_id, file_id)\n  );\n";
+declare const MIGRATIONS: Migration[];
+
+/**
+ * Bumping this invalidates every reuse basis: a snapshot written by a different
+ * index version is never reused, so a change to node/edge shape can never be
+ * carried forward from an incompatible graph.
+ */
+declare const INDEX_VERSION = "0.11.0";
+interface IndexOptions {
+    /** Roots to walk. Node ids are still rooted at the git toplevel, so importers across roots share an id space. */
+    paths: string[];
+    ref?: string;
+    commitHash?: string;
+    tsConfig?: string;
+    detectRenames?: boolean;
+    computeMetrics?: boolean;
+    /**
+     * Reuse the prior snapshot for byte-identical files: skip their tree-sitter
+     * parse + ts-morph extract and carry their nodes/edges/source metrics forward.
+     * Defaults to `true`; the reuse path is equivalent to a full index, so the only
+     * reason to disable it is to rebuild from scratch.
+     */
+    incremental?: boolean;
+}
+interface IndexResult {
+    snapshotId: number;
+    files: number;
+    nodes: number;
+    edges: number;
+    aliases: number;
+    metrics: number;
+    /** Files whose parse + extract were skipped by reusing the prior snapshot. */
+    reused: number;
+    /** Files parsed + extracted this run (new, changed, or full index). */
+    reparsed: number;
+    /** Parsed files whose extract was skipped as cosmetic; a subset of `reparsed`. */
+    cosmetic: number;
+    nodesByKind: Record<string, number>;
+    edgesByKind: Record<string, number>;
+}
+/**
+ * Index one or more roots into a new snapshot: walk, read, parse what changed,
+ * extract, annotate roles, compute metrics, and persist. Files unchanged since
+ * the prior snapshot are carried forward rather than re-parsed, so the result
+ * matches a full index regardless of how much was reused.
+ */
+declare function indexPaths(store: CodeGraphStore, options: IndexOptions): Promise<IndexResult>;
+
+interface ParsedFile {
+    tree: Tree;
+    content: string;
+    filePath: string;
+    language: string;
+}
+interface Extractor<T> {
+    name: string;
+    extract(file: ParsedFile): T[];
+}
+
+declare function parseFile(content: string, filePath: string, language: string): Promise<ParsedFile>;
+declare function getSupportedLanguages(): string[];
+
+declare function shouldIncludeFile(filePath: string, languages: string[]): boolean;
+declare function getLanguageFromPath(filePath: string): string | null;
+
+interface LanguageExtractorOptions {
+    repoRoot: string;
+    tsConfigPath?: string;
+}
+/**
+ * One extractor over every supported language: each delegate already returns an
+ * empty fragment list for files it does not own, so dispatch is a fold. Keeps
+ * `assembleFragments` language-agnostic.
+ */
+declare class LanguageExtractor implements Extractor<GraphFragment> {
+    readonly name = "language-graph";
+    private readonly delegates;
+    constructor(options: LanguageExtractorOptions);
+    extract(file: ParsedFile): GraphFragment[];
+}
+
+/**
+ * Tree-sitter Python extraction. Deliberately narrower than the ts-morph side:
+ * no type checker, so imports resolve by dotted path against the tree rather
+ * than by symbol resolution, and symbols are the declarations the same
+ * tree-sitter walk already finds for complexity. Enough to place Python files in
+ * the graph with their dependencies; a semantic Python layer is a follow-up.
+ */
+declare class PythonGraphExtractor implements Extractor<GraphFragment> {
+    private readonly repoRoot;
+    readonly name = "python-graph";
+    constructor(repoRoot: string);
+    extract(file: ParsedFile): GraphFragment[];
+    private collectImports;
+    /**
+     * Resolve `a.b.c` (or a leading-dot relative import) to an in-repo file id by
+     * walking the dotted path from the importing file's package and then from the
+     * repo root, which covers both intra-package and root-relative layouts.
+     */
+    private resolveDotted;
+}
+
+interface TsMorphGraphExtractorOptions {
+    repoRoot: string;
+    tsConfigPath?: string;
+    project?: Project;
+}
+declare class TsMorphGraphExtractor implements Extractor<GraphFragment> {
+    readonly name = "ts-morph-graph";
+    private readonly repoRoot;
+    private readonly tsConfigPath?;
+    private project?;
+    constructor(options: TsMorphGraphExtractorOptions);
+    extract(file: ParsedFile): GraphFragment[];
+    private ensureProject;
+    private loadSourceFile;
+    private buildFileAndModuleNodes;
+    private collectEdges;
+    private recordImportEdge;
+    /**
+     * Split an import into per-export `references` edges targeting `symbol` nodes,
+     * so per-symbol utilization (which exports are hot) falls out of the same
+     * inbound-weight sum that powers file utilization (C-53). Extracted *forward*
+     * from the importing file — source-local, exactly like the file-level import
+     * weight — which sidesteps the reuse-breaking reverse `findReferences` query:
+     * an unchanged file's outbound reference edges are carried forward verbatim.
+     */
+    private recordSymbolReferences;
+    /**
+     * Resolve an imported name to the id of the `symbol` node for the export that
+     * actually *declares* it — following re-exports through barrels via ts-morph's
+     * own `getExportedDeclarations`, so `import { x } from "./barrel"` credits the
+     * origin file's `x`, not the barrel. When ts-morph can't resolve the specifier
+     * (e.g. an extensionless relative import), falls back to a filesystem-based
+     * re-export walk that still sees through barrel hops (C-70). Returns null for
+     * external / unresolved targets.
+     * A name that resolves to no local declaration (an aliased re-export the
+     * origin doesn't export under this name) yields a dangling edge, pruned after
+     * assembly (`pruneDanglingReferences`).
+     */
+    private resolveSymbolTarget;
+    private recordReExportEdge;
+    /**
+     * Resolve an import/export specifier to a graph node id (an in-repo file id or
+     * an `external` node, creating the external node on first sight), or `null`
+     * when it should not produce an edge.
+     */
+    private resolveTarget;
+    private resolveInternal;
+    /**
+     * Resolve a relative specifier ts-morph failed to link by walking the
+     * filesystem from the importing file. ts-morph's NodeNext resolution only
+     * links relative imports that carry an explicit `.js` extension, so
+     * extensionless bundler-style imports (`../types`, common in code outside the
+     * tsconfig project such as `dashboard/`) resolve to nothing and would
+     * otherwise fall through to the `npm:` external bucket (C-44). Resolves
+     * through the ts-morph filesystem host so it honours in-memory test fixtures.
+     */
+    private resolveRelativeInternal;
+    private inRepoFileId;
+}
+
+/**
+ * Build the `file` + `module` nodes for a source file from its path alone.
+ * Path-derived and deterministic, so the incremental indexer can reconstruct an
+ * unchanged file's nodes without re-parsing it — they are byte-for-byte the same
+ * nodes the extractor would emit. Keep this the single source of truth for
+ * file/module node shape.
+ */
+declare function buildFileModuleNodes(repoRoot: string, absPath: string): GraphNode[];
+
+declare function fileId(repoRoot: string, absPath: string): string;
+declare function moduleId(repoRoot: string, absPath: string): string;
+declare function parentModuleId(id: string): string | null;
+declare function packageId(name: string): string;
+declare const SYMBOL_ID_SEP = "#";
+declare function symbolId(fileId: string, exportName: string): string;
+/**
+ * Inverse of {@link symbolId}: split a `<fileId>#<name>` symbol id back into its
+ * declaring file and export name. Returns null for an id with no separator (a
+ * plain file id), so callers can filter the symbol layer cleanly. `#` is illegal
+ * in both posix paths and JS identifiers, so the first occurrence is the split.
+ */
+declare function parseSymbolId(id: string): {
+    fileId: string;
+    name: string;
+} | null;
+declare function externalId(specifier: string): string;
+
+/** SHA-256 of file content. The fingerprint that gates per-file reuse. */
+declare function hashContent(content: string): string;
+/**
+ * Comment/whitespace-insensitive hash of a file's parse structure (C-18). Walks
+ * the tree-sitter tree emitting each node's type plus leaf text, skipping comment
+ * nodes; whitespace and positions are absent from the tree, so a pure reformat or
+ * comment edit yields the SAME signature while any token change yields a new one.
+ * Two files with an equal signature therefore produce identical edges and AST
+ * metrics and differ only in line spans (and loc) — the COSMETIC reuse class.
+ */
+declare function structuralSignature(file: ParsedFile): string;
+/** The languages that have an extractor; anything else is skipped by the walk. */
+type SourceLanguage = "typescript" | "python";
+interface ReadFile {
+    filePath: string;
+    language: SourceLanguage;
+    content: string;
+    hash: string;
+}
+/** Read + hash every source file. Cheap I/O; the parse/extract it gates is not. */
+declare function readSourceFiles(filePaths: readonly string[]): Promise<ReadFile[]>;
+/**
+ * Everything from a prior snapshot needed to rebuild an unchanged file's
+ * contribution to the graph without re-parsing it: its content fingerprint,
+ * the node table (to look up external-node names), outbound edges grouped by
+ * source, and the source-content metrics (loc, complexity, lcom4, ...).
+ */
+interface ReuseBasis {
+    snapshotId: number;
+    fingerprints: Map<string, string>;
+    /** Per-file structural signature (C-18); empty for a pre-C-18 basis. */
+    structuralHashes: Map<string, string>;
+    nodesById: Map<string, GraphNode>;
+    edgesBySrc: Map<string, GraphEdge[]>;
+    sourceMetricsByFile: Map<string, GraphMetric[]>;
+    /** Symbol nodes grouped by their declaring file id, to carry forward for reused files (C-53). */
+    symbolsByFile: Map<string, GraphNode[]>;
+}
+
+/**
+ * Recursively collect the source files under `rootDirs` that pass the ingest
+ * filter for `languages`, deduped by absolute path across roots (walk order
+ * preserved). Extracted from the indexer (C-61): as a function nested inside the
+ * per-root loop, the recursive walker carried a cognitive-complexity nesting
+ * bonus that made it the indexer's single most complex function (cx 19, above
+ * the exported entry point). Hoisting it here — one recursion helper, one
+ * directory branch — drops it well under budget and makes the walker unit-
+ * testable in isolation.
+ */
+declare function walkSourceFiles(rootDirs: readonly string[], languages: readonly string[]): Promise<string[]>;
+
+/** 1-based inclusive line span of a declaration, for coverage range-attribution (C-63). */
+interface LineSpan {
+    startLine: number;
+    endLine: number;
+}
+/**
+ * Every function/method/class a file DECLARES, mapped to its 1-based line span
+ * (the model-B symbol surface, C-64, now carrying spans for C-63 coverage
+ * range-containment). A superset of the file's exports: internal helpers like
+ * `mergeFragments` are included so they get a `symbol` node (and, by name match,
+ * their complexity + coverage) even though nothing imports them. Names come from
+ * the same tree-sitter walk that computes complexity, so they never drift.
+ * Anonymous declarations (a default-exported arrow, inline callbacks) contribute
+ * no name and are skipped. A name declared more than once keeps its last span
+ * (overloads / same-named methods are rare; range lookup still resolves most).
+ */
+declare function collectDeclaredSpans(file: ParsedFile): Map<string, LineSpan>;
+/** Declared names only — the Set view over {@link collectDeclaredSpans}. */
+declare function collectDeclaredNames(file: ParsedFile): Set<string>;
+
+/** Edge weight (C-51 reference count), floored at 1 for unweighted edges. */
+declare function edgeWeight(e: GraphEdge): number;
+/**
+ * Drop `references` edges (C-53) whose target `symbol` node doesn't exist — an
+ * aliased re-export chain, or a barrel that changed under a reused file, can
+ * resolve a name to an origin that doesn't declare it. Only `references` can
+ * dangle (imports/re-exports resolve to always-emitted file/external nodes);
+ * metrics already guard unknown ids, so this just keeps the persisted edge set
+ * clean. Mutates `edges` in place.
+ */
+declare function pruneDanglingReferences(nodes: ReadonlyMap<string, GraphNode>, edges: Map<string, GraphEdge>): void;
+/**
+ * Resolve edges that land on a barrel (`role="barrel"` — a bare `index.*`
+ * re-export file) onto the files the barrel actually re-exports from, so
+ * downstream signals measure the real dependency surface instead of the
+ * re-export plumbing. A cross-package `import … from "@codewatch/graph"`
+ * resolves to the barrel; without this every such import piles onto the barrel
+ * as an artificial hub while the module that truly does the work is
+ * under-credited.
+ *
+ * An inbound edge `F → B` (weight w) is split across B's outbound re-export
+ * targets `t_i` in proportion to each target's re-export weight `r_i` (C-51:
+ * the count of names B forwards from `t_i`). This CONSERVES w — no magnitude
+ * inflation, unlike a uniform fan-out that turns one import into N edges — and
+ * attributes it by how much of the barrel each target supplies. Resolution
+ * recurses through barrel chains (a barrel re-exporting a barrel) with a
+ * visited guard against re-export cycles; a barrel with no resolvable
+ * re-exports is left as its own target so the dependency is never dropped.
+ *
+ * Pure over the assembled node/edge set, so it is deterministic regardless of
+ * how much of an incremental index was reused.
+ */
+declare function resolveBarrelEdges(nodes: readonly GraphNode[], edges: readonly GraphEdge[]): GraphEdge[];
+
+declare const ALL_ROLES: readonly NodeRole[];
+interface RoleHints {
+    /** File begins with a `#!` shebang, i.e. it is an executable entry point. */
+    hasShebang?: boolean;
+    /** File is codegen output (`.gitattributes linguist-generated` or heuristic). */
+    isGenerated?: boolean;
+}
+declare function classifyRole(id: string, hints?: RoleHints): NodeRole;
+interface AnnotateRolesOptions {
+    /** Node ids whose source begins with a `#!` shebang. */
+    shebangIds?: ReadonlySet<string>;
+    /** Node ids detected as generated (codegen output). */
+    generatedIds?: ReadonlySet<string>;
+}
+interface ReadFileLike {
+    filePath: string;
+    content: string;
+}
+/**
+ * Derive per-file role hints for a batch of read files in one pass: the shebang
+ * set (executable entries) and the generated set (codegen output, detected via
+ * `.gitattributes linguist-generated` under `idRoot` plus filename/path
+ * heuristics). Lives here so the indexer stays at its file-size ceiling.
+ */
+declare function computeRoleHints(readFiles: readonly ReadFileLike[], idRoot: string, toId: (root: string, filePath: string) => string): AnnotateRolesOptions;
+declare function annotateRoles(nodes: readonly GraphNode[], options?: AnnotateRolesOptions): GraphNode[];
+
+/** True when a path looks generated by filename/dir convention alone. */
+declare function isGeneratedByHeuristic(id: string): boolean;
+/**
+ * A file is generated when it matches a repo-declared `linguist-generated`
+ * pattern or the filename/path heuristic. `patterns` come from
+ * {@link parseGeneratedPatterns}; pass `[]` when no `.gitattributes` exists.
+ */
+declare function isGeneratedFile(id: string, patterns: readonly RegExp[]): boolean;
+/** Read `<rootDir>/.gitattributes` and compile its linguist-generated patterns. */
+declare function loadGeneratedPatterns(rootDir: string): RegExp[];
+
+declare function canonicalMetricName(name: string): string;
+declare function canonicalRole(name: string): NodeRole;
+declare function canonicalEdgeKind(name: string): EdgeKind;
+
+interface RenamePair {
+    oldPath: string;
+    newPath: string;
+    similarity: number;
+}
+interface DetectRenamesOptions {
+    repoRoot: string;
+    fromCommit: string;
+    toCommit?: string;
+    similarityThreshold?: number;
+}
+declare function detectGitHead(repoRoot: string): string | null;
+declare function isInsideGitRepo(repoRoot: string): boolean;
+declare function detectGitToplevel(cwd: string): string | null;
+declare function detectRenames(options: DetectRenamesOptions): RenamePair[];
+declare function buildAliases(repoRoot: string, pairs: readonly RenamePair[]): IdAlias[];
+
+declare function computeMetrics(nodes: readonly GraphNode[], edges: readonly GraphEdge[]): GraphMetric[];
+
+/**
+ * Names of every metric `computeSourceMetrics` can emit. These are pure
+ * functions of a file's content, so the incremental indexer can carry them
+ * forward unchanged for a byte-identical file instead of re-parsing it. If a
+ * new source metric is added above, add its name here — the incremental
+ * round-trip test will fail loudly if this set drifts out of sync.
+ */
+declare const SOURCE_METRIC_NAMES: ReadonlySet<string>;
+/**
+ * Per-file source metrics. `symbolNamesByFile` maps a file id to the names of
+ * the `symbol` nodes it declares; when supplied, per-function complexity is
+ * emitted on those symbol nodes (C-58; all declared functions since C-64). It
+ * defaults to empty, so existing callers/tests that don't thread the symbol
+ * layer keep emitting only file-level metrics.
+ */
+declare function computeSourceMetrics(files: readonly ParsedFile[], fileIdOf: (filePath: string) => string, symbolNamesByFile?: ReadonlyMap<string, ReadonlySet<string>>): GraphMetric[];
+
+interface IndexerMetricsInput {
+    nodes: Map<string, GraphNode>;
+    edges: Map<string, GraphEdge>;
+    /** Files (re)parsed this run — source metrics are computed fresh for these. */
+    parsedFiles: ParsedFile[];
+    /** Source metrics carried forward verbatim for reused (unchanged) files. */
+    reusedSourceMetrics: GraphMetric[];
+    idRoot: string;
+}
+/**
+ * Assemble the metric set for a snapshot: graph-wide degree metrics over the
+ * full node/edge set, freshly-computed source metrics for (re)parsed files, and
+ * reused source metrics carried forward for unchanged files. Everything but the
+ * reused source metrics is recomputed over the full set, so the result matches a
+ * full index regardless of how much was reused.
+ *
+ * Git-history metrics (churn, ownership, change coupling, test coverage) are
+ * deliberately absent here; they are a separate analysis layer, deferred with
+ * the rest of codewatch's analyses.
+ */
+declare function buildIndexerMetrics(input: IndexerMetricsInput): GraphMetric[];
+
+/**
+ * The free-function reading surface named in the package API. Each delegates to
+ * the store's method of the same name, so a caller that only reads a snapshot
+ * never has to hold on to the store's shape.
+ */
+declare function listNodes(store: CodeGraphStore, snapshotId: number, opts?: {
+    includeSymbols?: boolean;
+}): GraphNode[];
+declare function listEdges(store: CodeGraphStore, snapshotId: number, opts?: {
+    includeReferences?: boolean;
+}): GraphEdge[];
+declare function listMetrics(store: CodeGraphStore, snapshotId: number): GraphMetric[];
+
+export { ALL_ROLES, CodeGraphStore, DOMAIN_DDL, type EdgeKind, type Extractor, type FileFingerprint, type GraphEdge, type GraphFragment, type GraphMetric, type GraphNode, INDEX_VERSION, type IdAlias, type IdAliasReason, type IndexOptions, type IndexResult, KIT, LanguageExtractor, type LanguageExtractorOptions, type LineSpan, MIGRATIONS, type NodeKind, type NodeRole, type ParsedFile, PythonGraphExtractor, type ReadFile, type ReuseBasis, SOURCE_METRIC_NAMES, SYMBOL_ID_SEP, type SnapshotInsert, type SnapshotRow, type SourceLanguage, TsMorphGraphExtractor, type TsMorphGraphExtractorOptions, annotateRoles, buildAliases, buildFileModuleNodes, buildIndexerMetrics, canonicalEdgeKind, canonicalMetricName, canonicalRole, classifyRole, collectDeclaredNames, collectDeclaredSpans, computeMetrics, computeRoleHints, computeSourceMetrics, detectGitHead, detectGitToplevel, detectRenames, edgeWeight, externalId, fileId, getLanguageFromPath, getSupportedLanguages, hashContent, indexPaths, isGeneratedByHeuristic, isGeneratedFile, isInsideGitRepo, listEdges, listMetrics, listNodes, loadGeneratedPatterns, moduleId, openCodeGraph, packageId, parentModuleId, parseFile, parseSymbolId, pruneDanglingReferences, readSourceFiles, resolveBarrelEdges, shouldIncludeFile, structuralSignature, symbolId, walkSourceFiles };