@titan-design/code-graph 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,10 +1,14 @@
 import { Db, Migration } from '@titan-design/store-sqlite';
-import { Tree } from 'web-tree-sitter';
+import { Extractor, ParsedFile } from '@titan-design/code-parser';
+export { Extractor, ParsedFile, getLanguageFromPath, getSupportedLanguages, parseFile, shouldIncludeFile } from '@titan-design/code-parser';
 import { Project } from 'ts-morph';
+import { c as CoEditPair, a as ChurnWindow, C as ChurnEntry } from './change-coupling-CyqHgRsm.js';
+import { Embedder } from '@titan-design/embed';
 
 type NodeKind = "package" | "module" | "file" | "symbol" | "external";
 type EdgeKind = "imports" | "re-exports" | "calls" | "extends" | "implements" | "references" | "depends-on";
-type IdAliasReason = "rename" | "move" | "merge";
+/** `requalify` maps a bare-name symbol id from before index version 0.14.0 to its scope-qualified successor. */
+type IdAliasReason = "rename" | "move" | "merge" | "requalify";
 type NodeRole = "test" | "fixture" | "barrel" | "types" | "config" | "script" | "entry" | "generated" | "source";
 interface GraphNode {
     id: string;
@@ -123,13 +127,15 @@ declare const KIT: {
  */
 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[];
+/** The top of this package's schema. A code graph database is never shared, so this is the top of one. */
+declare const SCHEMA_VERSION: number;
 
 /**
  * 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.
+ * index version is never reused, so a change to node/edge shape or to a metric's
+ * value for the same bytes can never be carried forward from an incompatible graph.
  */
-declare const INDEX_VERSION = "0.11.0";
+declare const INDEX_VERSION = "0.14.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[];
@@ -145,6 +151,14 @@ interface IndexOptions {
      * reason to disable it is to rebuild from scratch.
      */
     incremental?: boolean;
+    /** Git churn, recency, and ownership metrics. Defaults to `true`; history is skipped silently outside git. */
+    computeChurn?: boolean;
+    /** Primary churn window in days (default 30); scopes ownership. */
+    churnWindowDays?: number;
+    /** Windows to store churn for (default 30, 90, 180); the primary window is always included. */
+    churnWindows?: number[];
+    /** Also store an all-time `lifetime` churn and ownership window over full git history. */
+    lifetime?: boolean;
 }
 interface IndexResult {
     snapshotId: number;
@@ -170,23 +184,6 @@ interface IndexResult {
  */
 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;
@@ -298,10 +295,10 @@ 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;
+declare function symbolId(fileId: string, qualifiedName: 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
+ * declaring file and qualified 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.
  */
@@ -368,15 +365,10 @@ interface LineSpan {
     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).
+ * Qualified declared names mapped to their 1-based line span (C-63 coverage
+ * range-containment). One scope binds a name once, as TypeScript and Python do,
+ * so a getter/setter pair, a Python property's accessors, and `@overload` stubs
+ * share one entry; when a qualified name repeats, the last span wins.
  */
 declare function collectDeclaredSpans(file: ParsedFile): Map<string, LineSpan>;
 /** Declared names only — the Set view over {@link collectDeclaredSpans}. */
@@ -458,6 +450,8 @@ declare function canonicalMetricName(name: string): string;
 declare function canonicalRole(name: string): NodeRole;
 declare function canonicalEdgeKind(name: string): EdgeKind;
 
+declare function detectGitToplevel(cwd: string): string | null;
+
 interface RenamePair {
     oldPath: string;
     newPath: string;
@@ -471,7 +465,7 @@ interface DetectRenamesOptions {
 }
 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[];
 
@@ -494,6 +488,62 @@ declare const SOURCE_METRIC_NAMES: ReadonlySet<string>;
  */
 declare function computeSourceMetrics(files: readonly ParsedFile[], fileIdOf: (filePath: string) => string, symbolNamesByFile?: ReadonlyMap<string, ReadonlySet<string>>): GraphMetric[];
 
+/** How a test↔source pairing was inferred. */
+type LinkMethod = "path" | "coedit";
+interface TestSourceLink {
+    /** Node id of the test file. */
+    testId: string;
+    /** Node id of the (non-test) file it covers. */
+    sourceId: string;
+    method: LinkMethod;
+}
+interface LinkTestsOptions {
+    /** Minimum co-edit count for a pass-2 (coedit) link. Default 2. */
+    minCoEditCount?: number;
+}
+/**
+ * Two-pass test↔source linker. Pass 1 pairs each test file with non-test files
+ * matching its path conventions (high confidence). Pass 2 supplements tests
+ * left unpaired by pass 1 with their strongest co-edited non-test partner from
+ * change-coupling. Handles orphan tests (no pairing), orphan/untested sources
+ * (no incoming link), and one-to-many pairings (a test matching several
+ * sources, or a source covered by several tests).
+ */
+declare function linkTestsToSources(nodes: readonly GraphNode[], coEditPairs: readonly CoEditPair[], options?: LinkTestsOptions): TestSourceLink[];
+/**
+ * Per-source coverage breadth: how many distinct test files link to each
+ * covered source. Emitted only for sources with at least one linked test.
+ */
+declare function testCoverageCountMetrics(links: readonly TestSourceLink[]): GraphMetric[];
+/** Map each covered source to the set of test files that link to it. */
+declare function groupTestsBySource(links: readonly TestSourceLink[]): Map<string, Set<string>>;
+
+interface HistoryMetricsOptions {
+    /** Primary window: scopes ownership. Default 30. */
+    churnWindowDays?: number;
+    /** Windows to store churn and recency for; default {@link DEFAULT_CHURN_WINDOWS}, primary always included. */
+    churnWindows?: number[];
+    /** Also store an all-time `lifetime` window over full git history. */
+    includeLifetime?: boolean;
+    /** Epoch seconds that windows end at; defaults to the current time. */
+    nowEpoch?: number;
+}
+interface TestCoverageOwnershipOptions {
+    /** Window named in the metric suffix. Default 30. */
+    windowDays?: ChurnWindow;
+    /** Coverage threshold for bus factor (default 0.5 = 50% of churn). */
+    busFactorThreshold?: number;
+}
+/**
+ * Bus-factor / top-author-share of the *test coverage* for each source, keyed
+ * on the source node. Aggregates churn authorship across all test files linked
+ * to a source (via the two-pass linker) and summarises it the same way as
+ * production ownership — so a file can read as well-spread on production code
+ * yet a single-author silo on its tests (or vice versa). Emitted only for
+ * sources with at least one linked test that has churn in the window.
+ */
+declare function computeTestCoverageOwnership(entries: readonly ChurnEntry[], links: readonly TestSourceLink[], options?: TestCoverageOwnershipOptions): GraphMetric[];
+
 interface IndexerMetricsInput {
     nodes: Map<string, GraphNode>;
     edges: Map<string, GraphEdge>;
@@ -502,6 +552,8 @@ interface IndexerMetricsInput {
     /** Source metrics carried forward verbatim for reused (unchanged) files. */
     reusedSourceMetrics: GraphMetric[];
     idRoot: string;
+    /** Git-history metrics (churn, recency, ownership); omitted means none. */
+    history?: HistoryMetricsOptions;
 }
 /**
  * Assemble the metric set for a snapshot: graph-wide degree metrics over the
@@ -510,12 +562,233 @@ interface IndexerMetricsInput {
  * 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.
+ * Git-history metrics come from the path-based engine in `./history/` through
+ * the `history-metrics.ts` adapter. Test-coverage metrics run with or without it.
  */
 declare function buildIndexerMetrics(input: IndexerMetricsInput): GraphMetric[];
 
+/**
+ * Function-local dead-code metrics (C-65 Phase 1). Pure functions of one file's
+ * bytes — the same class as the source metrics in source-metrics.ts — so they
+ * ride the content-hash incremental reuse gate. Kept in their own module (not
+ * appended to source-metrics.ts) so the already-churn-hot source-metrics.ts is
+ * not touched; the reuse machinery folds these names in alongside
+ * SOURCE_METRIC_NAMES (see incremental.ts) and index-metrics.ts computes them
+ * fresh for (re)parsed files.
+ */
+declare const DEAD_CODE_METRIC_NAMES: ReadonlySet<string>;
+/**
+ * Per-file dead-code metrics for TypeScript files. Emitted sparsely — only when
+ * a count is > 0 — so a clean file adds no rows (a full index and an incremental
+ * re-index therefore produce the identical metric set). Non-TypeScript files are
+ * skipped for now.
+ */
+declare function computeDeadCodeMetrics(files: readonly ParsedFile[], fileIdOf: (filePath: string) => string): GraphMetric[];
+
+/**
+ * Growth-risk / scaling-smell metrics (C-66 Phase 2). Cheap, function-local
+ * *heuristics* — NOT Big-O or a proven complexity class (real asymptotic
+ * inference is undecidable; see the roadmap's hard NO). Pure functions of one
+ * file's bytes, so they ride the content-hash incremental reuse gate, folded
+ * into the carry-forward set in incremental.ts alongside the source/dead-code
+ * metric names. Emitted sparsely (only when a smell is present).
+ */
+declare const GROWTH_RISK_METRIC_NAMES: ReadonlySet<string>;
+/**
+ * Per-file growth-risk metrics for TS/Python files, all SMELLS not bounds:
+ * - `loop_depth` — max *lexical* loop nesting (triple-nested → 3), emitted at
+ *   depth ≥ 2 (depth-2 loops over two *different* collections are actually linear).
+ * - `recursive_functions` — named functions that call themselves directly.
+ * - `search_in_loop` — linear-scan method calls (`.includes`/`.find`/…) inside a
+ *   loop (an O(n) scan per iteration; `.includes` on a `Set` is O(1)).
+ * All emitted sparsely (only when present). Non-TS/Python files are skipped.
+ */
+declare function computeGrowthRiskMetrics(files: readonly ParsedFile[], fileIdOf: (filePath: string) => string): GraphMetric[];
+
+/**
+ * Coverage is a whole-suite DYNAMIC artifact — a function of *which tests ran*,
+ * not of any file's bytes — so it must NOT ride the content-hash reuse gate. It
+ * is emitted as a `coverage_pct` metric that is deliberately absent from every
+ * *_METRIC_NAMES reuse set, so an incremental index never carries it forward: a
+ * later index produces a snapshot with NO coverage until re-ingested. That is the
+ * overlay semantics — coverage is attached to the snapshot it was measured
+ * against and never inferred for another.
+ */
+declare const COVERAGE_METRIC_NAME = "coverage_pct";
+/** Minimal Istanbul `coverage-final.json` shape we read (function-level). */
+interface IstanbulFn {
+    loc: {
+        start: {
+            line: number;
+        };
+        end: {
+            line: number;
+        };
+    };
+}
+interface IstanbulFileCoverage {
+    fnMap: Record<string, IstanbulFn>;
+    /** Per-function hit counts, keyed to fnMap ids. */
+    f: Record<string, number>;
+}
+type IstanbulCoverage = Record<string, IstanbulFileCoverage>;
+/** A symbol node's 1-based line span, for range-containment attribution. */
+interface SymbolSpan {
+    id: string;
+    startLine: number;
+    endLine: number;
+}
+/**
+ * Attribute an Istanbul coverage report to graph nodes as `coverage_pct` metrics:
+ * one per covered FILE (covered functions / total functions), and one per SYMBOL
+ * a covered function maps into by RANGE containment (symbol spans) — matching
+ * by range, not name, so anonymous/mangled Istanbul function names are handled.
+ * A symbol spanning several functions (a class) reports its methods' coverage
+ * ratio. Files Istanbul reports but the graph doesn't know are skipped.
+ */
+declare function attributeCoverage(coverage: IstanbulCoverage, fileIdOf: (absPath: string) => string | null, symbolsByFile: ReadonlyMap<string, readonly SymbolSpan[]>): GraphMetric[];
+
+interface PageRankOptions {
+    /** Per-node teleport weight. Unset or empty → uniform teleport across all nodes. */
+    personalization?: ReadonlyMap<string, number>;
+    /** Probability of following an edge vs teleporting (default 0.85). */
+    damping?: number;
+    /** L1 convergence threshold (default 1e-6). */
+    tolerance?: number;
+    /** Cap on power-iteration steps (default 100). */
+    maxIterations?: number;
+    /** Per-kind edge weight; missing kinds default to 1.0. */
+    edgeWeights?: Partial<Record<EdgeKind, number>>;
+}
+interface PageRankRow {
+    nodeId: string;
+    score: number;
+}
+interface PageRankResult {
+    /** Sorted descending by score; ties broken by node id ascending. */
+    rows: PageRankRow[];
+    iterations: number;
+    converged: boolean;
+}
+/** Edge weight used by PageRank for a given edge kind, honoring user overrides. */
+declare function getEdgeWeight(kind: EdgeKind, overrides?: Partial<Record<EdgeKind, number>>): number;
+declare function computePageRank(nodes: readonly GraphNode[], edges: readonly GraphEdge[], options?: PageRankOptions): PageRankResult;
+
+interface RelevanceOptions {
+    /** Probability of following an edge vs teleporting back to the seeds (default 0.85). */
+    damping?: number;
+    /** Per-kind edge weight override, forwarded to PageRank. */
+    edgeWeights?: PageRankOptions["edgeWeights"];
+}
+/**
+ * C-89 — **seeded (personalized) PageRank as a relevance-to-target proximity
+ * measure** (Aider RepoMap-style). The teleport vector is concentrated on
+ * `seedIds`, so the stationary distribution scores every node by how tightly it
+ * couples to the seeds through the resolved dependency graph: near neighbours
+ * score high, decaying with graph distance. This is "relevance to what I'm
+ * looking at," distinct from global PageRank centrality ("globally famous"),
+ * which stays the no-seed cold path.
+ *
+ * The edge set is **symmetrized** (each edge added in both directions) so
+ * relevance flows to a target's callers AND its dependencies — a purely forward
+ * walk from the seed would only reach what the seed depends on, never who
+ * depends on it. Edge kind (and therefore weight) is preserved on the reversed
+ * copy, so a heavier `calls` edge stays heavier in both directions.
+ *
+ * Returns a Map from node id to relevance score (seeds included). An empty seed
+ * set returns an empty map — callers then fall back to global centrality.
+ */
+declare function computeRelevance(nodes: readonly GraphNode[], edges: readonly GraphEdge[], seedIds: readonly string[], options?: RelevanceOptions): Map<string, number>;
+
+/**
+ * Symbol-level change coupling (C-60). Decomposes a god-file the file-level
+ * coupling view rolls up as one blob (e.g. `types.ts`) into *which symbol* is
+ * used where. Built on the C-53 `references` edge substrate: `src` is the
+ * importing file, `dst` is the imported symbol node id (`<fileId>#<name>`).
+ *
+ * Two slices, both pure functions of the assembled reference edge set (a
+ * whole-graph rollup like utilization/PageRank, sound under incremental reuse
+ * since it reads the reassembled edges, not a per-file cache):
+ *
+ * - **Slice C — per-symbol consumers**: invert the edges by `dst`, giving the
+ *   set of files that import each symbol. Directly answers "what IN this file is
+ *   used where"; covers span-less types/consts that a git-hunk approach cannot.
+ * - **Slice B — co-import coupling**: group edges by `src`, and every pair of
+ *   symbols co-imported by the same file is a coupling pair. Two symbols that
+ *   are always imported together travel together — structural (used-together),
+ *   drift-free coupling, as opposed to the temporal (changed-together) git
+ *   co-edit signal.
+ */
+/** The minimal shape of a `references` edge this module consumes. */
+interface ReferenceEdgeLite {
+    /** Importing file id. */
+    srcId: string;
+    /** Imported symbol node id (`<fileId>#<name>`). */
+    dstId: string;
+}
+/** One symbol's consumer set (Slice C). */
+interface SymbolConsumers {
+    symbolId: string;
+    /** Declaring file, parsed from the symbol id. */
+    fileId: string;
+    /** Export name. */
+    name: string;
+    /** Distinct importing file ids, sorted. */
+    consumers: string[];
+}
+/** A pair of symbols co-imported by the same file (Slice B). */
+interface SymbolCouplingPair {
+    aId: string;
+    aFile: string;
+    aName: string;
+    bId: string;
+    bFile: string;
+    bName: string;
+    /** Distinct files that import both symbols. */
+    coImports: number;
+    /** True when the two symbols are declared in different files. */
+    crossFile: boolean;
+}
+interface SymbolCouplingOptions {
+    /** Skip pairs co-imported by fewer than this many files. Default 2. */
+    minCoImports?: number;
+    /**
+     * Skip importing files that reference more than this many distinct symbols —
+     * a wide barrel-style importer would otherwise explode into O(n²) noise
+     * pairs, mirroring change-coupling's large-commit guard. Default 40.
+     */
+    largeImporterThreshold?: number;
+}
+/**
+ * Group reference edges by imported symbol, yielding each symbol's distinct
+ * consuming files (Slice C). Sorted by consumer count desc, then symbol id, so
+ * the most broadly-depended-on exports lead.
+ */
+declare function computeSymbolConsumers(edges: readonly ReferenceEdgeLite[]): SymbolConsumers[];
+/**
+ * Every pair of symbols co-imported by the same file becomes a coupling pair,
+ * counted by how many distinct files co-import them (Slice B). Wide importers
+ * are dropped to keep the pairing near-linear. Sorted by co-import count desc,
+ * cross-file pairs preferred at a tie (they are the actionable ones — a
+ * same-file pair is just cohesion within one module).
+ */
+declare function computeSymbolCoupling(edges: readonly ReferenceEdgeLite[], options?: SymbolCouplingOptions): SymbolCouplingPair[];
+
+/**
+ * PageRank over one snapshot's file-level graph (symbol nodes and `references`
+ * edges excluded, as codewatch's `graph relevant` reads it). Pass
+ * `personalization` to seed the walk toward target node ids.
+ */
+declare function snapshotPageRank(store: CodeGraphStore, snapshotId: number, options?: PageRankOptions): PageRankResult;
+/** Relevance of every file-level node to `seedIds`, as codewatch's `graph context` computes it. */
+declare function snapshotRelevance(store: CodeGraphStore, snapshotId: number, seedIds: readonly string[], options?: RelevanceOptions): Map<string, number>;
+/** The snapshot's `references` edges: importing file to imported symbol. */
+declare function snapshotReferenceEdges(store: CodeGraphStore, snapshotId: number): ReferenceEdgeLite[];
+/** Per-symbol consumer files for one snapshot. */
+declare function snapshotSymbolConsumers(store: CodeGraphStore, snapshotId: number): SymbolConsumers[];
+/** Co-import symbol coupling pairs for one snapshot. */
+declare function snapshotSymbolCoupling(store: CodeGraphStore, snapshotId: number, options?: SymbolCouplingOptions): SymbolCouplingPair[];
+
 /**
  * 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
@@ -529,4 +802,276 @@ declare function listEdges(store: CodeGraphStore, snapshotId: number, opts?: {
 }): 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 };
+type Severity = "error" | "warning";
+interface MetricMaxRule {
+    type: "metric-max";
+    id: string;
+    metric: string;
+    max: number;
+    kind?: NodeKind;
+    severity?: Severity;
+    exclude?: string[];
+    excludeRoles?: NodeRole[];
+}
+interface MetricMinRule {
+    type: "metric-min";
+    id: string;
+    metric: string;
+    min: number;
+    kind?: NodeKind;
+    severity?: Severity;
+    exclude?: string[];
+    excludeRoles?: NodeRole[];
+}
+interface MetricProductMaxRule {
+    type: "metric-product-max";
+    id: string;
+    metrics: string[];
+    max: number;
+    kind?: NodeKind;
+    severity?: Severity;
+    exclude?: string[];
+    excludeRoles?: NodeRole[];
+}
+interface ForbidImportRule {
+    type: "forbid-import";
+    id: string;
+    from: string;
+    to: string;
+    severity?: Severity;
+}
+interface LayeredDepsRule {
+    type: "layered-deps";
+    id: string;
+    layers: string[][];
+    severity?: Severity;
+}
+interface NoInternalOnlyBarrelsRule {
+    type: "no-internal-only-barrels";
+    id: string;
+    /** Path prefixes marking package roots; node ids carry no intrinsic package membership. */
+    packageRoots: string[];
+    severity?: Severity;
+    /** Globs or substrings to skip, such as CLI bin entries the role classifier calls barrels. */
+    exclude?: string[];
+}
+type CheckRule = MetricMaxRule | MetricMinRule | MetricProductMaxRule | ForbidImportRule | LayeredDepsRule | NoInternalOnlyBarrelsRule;
+interface CheckRulesFile {
+    rules: CheckRule[];
+}
+interface CheckViolation {
+    ruleId: string;
+    severity: Severity;
+    nodeId: string;
+    message: string;
+    metric?: string;
+    value?: number;
+    threshold?: number;
+    destinationId?: string;
+    isCarryover?: boolean;
+}
+interface CheckResult {
+    snapshotId: number;
+    baselineSnapshotId?: number;
+    rulesEvaluated: number;
+    nodesEvaluated: number;
+    violations: CheckViolation[];
+    newErrors: number;
+    newWarnings: number;
+    carryoverErrors: number;
+    carryoverWarnings: number;
+    passed: boolean;
+}
+
+interface RunChecksOptions {
+    snapshotId: number;
+    rules: readonly CheckRule[];
+    baselineSnapshotId?: number;
+}
+declare function runChecks(store: CodeGraphStore, options: RunChecksOptions): CheckResult;
+
+interface ValidateRulesOptions {
+    /** Called with a human-readable message when a deprecated alias is healed. */
+    onWarn?: (message: string) => void;
+}
+declare function validateRules(input: unknown, options?: ValidateRulesOptions): readonly CheckRule[];
+
+/** A snapshot id, or a ref name resolved to that ref's newest snapshot. */
+type SnapshotSpec = number | string;
+interface CheckSnapshotOptions {
+    snapshot: SnapshotSpec;
+    rules: readonly CheckRule[];
+    baseline?: SnapshotSpec;
+}
+interface CheckSnapshotResult {
+    snapshot: SnapshotRow;
+    baselineSnapshot?: SnapshotRow;
+    result: CheckResult;
+}
+declare function resolveSnapshot(store: CodeGraphStore, spec: SnapshotSpec): SnapshotRow;
+/** Check one snapshot against a rule set, marking violations already present in the baseline as carryover. */
+declare function checkSnapshot(store: CodeGraphStore, options: CheckSnapshotOptions): CheckSnapshotResult;
+/** Read and validate a `check.json` rules file; deprecated aliases heal through `onWarn`. */
+declare function loadCheckRules(path: string, options?: ValidateRulesOptions): Promise<readonly CheckRule[]>;
+
+interface MetricDelta {
+    nodeId: string;
+    name: string;
+    before: number | null;
+    after: number | null;
+    delta: number | null;
+}
+interface NodeRename {
+    oldId: string;
+    newId: string;
+    reason: IdAliasReason;
+    node: GraphNode;
+}
+interface GraphDiffSummary {
+    fromSnapshotId: number;
+    toSnapshotId: number;
+    addedNodes: number;
+    removedNodes: number;
+    renamedNodes: number;
+    unchangedNodes: number;
+    addedEdges: number;
+    removedEdges: number;
+    metricChanges: number;
+}
+interface GraphDiff {
+    summary: GraphDiffSummary;
+    addedNodes: GraphNode[];
+    removedNodes: GraphNode[];
+    renamedNodes: NodeRename[];
+    addedEdges: GraphEdge[];
+    removedEdges: GraphEdge[];
+    metricDeltas: MetricDelta[];
+}
+
+interface DiffSnapshotsOptions {
+    fromSnapshotId: number;
+    toSnapshotId: number;
+}
+/** Structural diff of two snapshots; the to-snapshot's id aliases carry renamed nodes across so a move is not a delete plus an add. */
+declare function diffSnapshots(store: CodeGraphStore, options: DiffSnapshotsOptions): GraphDiff;
+
+interface UnchangedViolation {
+    from: CheckViolation;
+    to: CheckViolation;
+    delta: number | null;
+}
+interface CheckDiff {
+    fromSnapshotId: number;
+    toSnapshotId: number;
+    rulesEvaluated: number;
+    newViolations: CheckViolation[];
+    resolvedViolations: CheckViolation[];
+    unchanged: UnchangedViolation[];
+    worsened: UnchangedViolation[];
+    improved: UnchangedViolation[];
+}
+interface DiffCheckResultsOptions {
+    fromSnapshotId: number;
+    toSnapshotId: number;
+    rules: readonly CheckRule[];
+}
+/** Run the rules on both snapshots and bucket each violation as new, resolved, or unchanged (worsened or improved by value). */
+declare function diffCheckResults(store: CodeGraphStore, options: DiffCheckResultsOptions): CheckDiff;
+
+interface EmbeddableSymbol {
+    id: string;
+    name: string;
+    file: string;
+    signature: string;
+    purpose?: string;
+    text: string;
+    textHash: string;
+}
+interface EmbedCoverage {
+    /** Embeddable exported symbols in the snapshot. */
+    symbols: number;
+    /** How many symbols have a stored vector for this model. */
+    embedded: number;
+    /** How many carry docstring purpose text (where recall is strongest). */
+    withPurpose: number;
+}
+interface EmbedSnapshotResult extends EmbedCoverage {
+    model: string;
+    /** Unique new texts sent to the embedder (symbols can share a text). */
+    newlyEmbedded: number;
+    /** Symbols whose vector was already stored (content-addressed cache hits). */
+    reused: number;
+}
+/** Outcome of the non-fatal indexing pass: a down backend is reported, never thrown. */
+type EmbedAttempt = {
+    ok: true;
+    result: EmbedSnapshotResult;
+} | {
+    ok: false;
+    model: string;
+    error: string;
+};
+interface SimilarCandidate {
+    id: string;
+    name: string;
+    file: string;
+    signature: string;
+    purpose?: string;
+    /** Cosine similarity to the query, in [-1, 1]. */
+    score: number;
+}
+interface SimilarResult {
+    query: string;
+    model: string;
+    coverage: EmbedCoverage;
+    candidates: SimilarCandidate[];
+}
+/** Query prefixes are the embedder's to apply; configure them with its `prefixes` option. */
+interface FindSimilarOptions {
+    limit?: number;
+}
+
+/** Mirrors the gate harness: purpose text is appended to the signature when present. */
+declare function buildEmbedText(signature: string, purpose?: string | null): string;
+declare function hashEmbedText(text: string): string;
+/**
+ * The embeddable corpus of a snapshot: exported symbols that carry a signature,
+ * excluding test/fixture/generated code (matching the validated gate corpus).
+ */
+declare function listEmbeddableSymbols(store: CodeGraphStore, snapshotId: number): EmbeddableSymbol[];
+
+/** The blob_cache namespace for symbol vectors; the model column holds `embedder.model`, which names the vector space including its prefixes. */
+declare const SYMBOL_EMBEDDING_NAMESPACE = "code-graph/symbol-embedding";
+interface CachedEmbedResult {
+    /** L2-normalized vectors for every input text, keyed by its text hash. */
+    byHash: Map<string, number[]>;
+    /** Hashes that had no stored vector and were embedded on this call. */
+    newHashes: Set<string>;
+}
+/**
+ * Embed texts through the content-addressed store: only texts whose hash has
+ * no vector for this model reach the embedder; new vectors are normalized and
+ * persisted batch by batch so the next call (or a retry after a failure) is a cache hit.
+ */
+declare function embedTextsCached(store: CodeGraphStore, embedder: Embedder, texts: readonly string[]): Promise<CachedEmbedResult>;
+
+/**
+ * Precompute capability embeddings for a snapshot. Only texts whose hash has no
+ * stored vector are sent to the embedder, so re-runs and unchanged symbols cost
+ * nothing: the content-addressed store is the incremental-reuse mechanism.
+ */
+declare function embedSnapshot(store: CodeGraphStore, snapshotId: number, embedder: Embedder): Promise<EmbedSnapshotResult>;
+/**
+ * The post-index pass. A backend failure (ollama down, model missing) must not
+ * fail the index: the snapshot is already persisted and valid without vectors.
+ */
+declare function tryEmbedSnapshot(store: CodeGraphStore, snapshotId: number, embedder: Embedder): Promise<EmbedAttempt>;
+/**
+ * The query-time "about to write X: does it exist?" surface. Embeds the query
+ * (an intent sentence, a pseudo-signature, or both as `sig -- intent`), ranks
+ * the snapshot's embedded symbols by cosine similarity, and returns the top-K
+ * with coverage so the caller can weigh how much of the repo was searchable.
+ */
+declare function findSimilarCapability(store: CodeGraphStore, snapshotId: number, query: string, embedder: Embedder, opts?: FindSimilarOptions): Promise<SimilarResult>;
+
+export { ALL_ROLES, COVERAGE_METRIC_NAME, type CachedEmbedResult, type CheckDiff, type CheckResult, type CheckRule, type CheckRulesFile, type CheckSnapshotOptions, type CheckSnapshotResult, type CheckViolation, CodeGraphStore, DEAD_CODE_METRIC_NAMES, DOMAIN_DDL, type DiffCheckResultsOptions, type DiffSnapshotsOptions, type EdgeKind, type EmbedAttempt, type EmbedCoverage, type EmbedSnapshotResult, type EmbeddableSymbol, type FileFingerprint, type FindSimilarOptions, type ForbidImportRule, GROWTH_RISK_METRIC_NAMES, type GraphDiff, type GraphDiffSummary, type GraphEdge, type GraphFragment, type GraphMetric, type GraphNode, INDEX_VERSION, type IdAlias, type IdAliasReason, type IndexOptions, type IndexResult, type IstanbulCoverage, KIT, LanguageExtractor, type LanguageExtractorOptions, type LayeredDepsRule, type LineSpan, type LinkMethod, type LinkTestsOptions, MIGRATIONS, type MetricDelta, type MetricMaxRule, type MetricMinRule, type MetricProductMaxRule, type NoInternalOnlyBarrelsRule, type NodeKind, type NodeRename, type NodeRole, type PageRankOptions, type PageRankResult, type PageRankRow, PythonGraphExtractor, type ReadFile, type ReferenceEdgeLite, type RelevanceOptions, type ReuseBasis, type RunChecksOptions, SCHEMA_VERSION, SOURCE_METRIC_NAMES, SYMBOL_EMBEDDING_NAMESPACE, SYMBOL_ID_SEP, type Severity, type SimilarCandidate, type SimilarResult, type SnapshotInsert, type SnapshotRow, type SnapshotSpec, type SourceLanguage, type SymbolConsumers, type SymbolCouplingOptions, type SymbolCouplingPair, type SymbolSpan, type TestCoverageOwnershipOptions, type TestSourceLink, TsMorphGraphExtractor, type TsMorphGraphExtractorOptions, type UnchangedViolation, type ValidateRulesOptions, annotateRoles, attributeCoverage, buildAliases, buildEmbedText, buildFileModuleNodes, buildIndexerMetrics, canonicalEdgeKind, canonicalMetricName, canonicalRole, checkSnapshot, classifyRole, collectDeclaredNames, collectDeclaredSpans, computeDeadCodeMetrics, computeGrowthRiskMetrics, computeMetrics, computePageRank, computeRelevance, computeRoleHints, computeSourceMetrics, computeSymbolConsumers, computeSymbolCoupling, computeTestCoverageOwnership, detectGitHead, detectGitToplevel, detectRenames, diffCheckResults, diffSnapshots, edgeWeight, embedSnapshot, embedTextsCached, externalId, fileId, findSimilarCapability, getEdgeWeight, groupTestsBySource, hashContent, hashEmbedText, indexPaths, isGeneratedByHeuristic, isGeneratedFile, isInsideGitRepo, linkTestsToSources, listEdges, listEmbeddableSymbols, listMetrics, listNodes, loadCheckRules, loadGeneratedPatterns, moduleId, openCodeGraph, packageId, parentModuleId, parseSymbolId, pruneDanglingReferences, readSourceFiles, resolveBarrelEdges, resolveSnapshot, runChecks, snapshotPageRank, snapshotReferenceEdges, snapshotRelevance, snapshotSymbolConsumers, snapshotSymbolCoupling, structuralSignature, symbolId, testCoverageCountMetrics, tryEmbedSnapshot, validateRules, walkSourceFiles };