@titan-design/code-graph 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { Db, Migration } from '@titan-design/store-sqlite';
 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 { c as CoEditPair, C as ChurnEntry, a as ChurnWindow } from './change-coupling-CyqHgRsm.js';
 import { Embedder } from '@titan-design/embed';
 
 type NodeKind = "package" | "module" | "file" | "symbol" | "external";
@@ -58,6 +58,25 @@ interface FileFingerprint {
     structuralHash?: string;
 }
 
+/** One metric's values over the nodes of one kind in one snapshot; `count` excludes null values. */
+interface MetricAggregate {
+    name: string;
+    nodeKind: NodeKind;
+    count: number;
+    sum: number | null;
+    min: number | null;
+    max: number | null;
+}
+/** One node's value for one metric, joined to the node's own vocabulary columns. */
+interface TopMetricRow {
+    nodeId: string;
+    name: string;
+    kind: string;
+    role: string | null;
+    value: number | null;
+    unit: string | null;
+}
+
 interface SnapshotInsert {
     ref: string;
     commitHash?: string;
@@ -73,11 +92,18 @@ interface SnapshotInsert {
 declare class CodeGraphStore {
     readonly db: Db;
     private readonly statements;
+    private readonly targeted;
     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;
+    /**
+     * Replace every metric of one `name` for a snapshot in a single transaction —
+     * for an overlay such as coverage, which is re-ingested wholesale and must not
+     * accumulate stale rows across runs.
+     */
+    replaceMetricsByName(snapshotId: number, name: string, metrics: readonly GraphMetric[]): void;
     insertAliases(snapshotId: number, aliases: readonly IdAlias[]): void;
     insertFingerprints(snapshotId: number, fingerprints: readonly FileFingerprint[]): void;
     getSnapshot(id: number): SnapshotRow | null;
@@ -100,8 +126,31 @@ declare class CodeGraphStore {
         includeReferences?: boolean;
     }): GraphEdge[];
     listMetrics(snapshotId: number): GraphMetric[];
+    /** Every metric on one node, from the primary key instead of a whole-snapshot read. */
+    listMetricsForNode(snapshotId: number, nodeId: string): GraphMetric[];
+    /** Distinct metric names stored for a snapshot, ascending. */
+    listMetricNames(snapshotId: number): string[];
+    /** The highest-valued nodes for one metric, descending; `limit` defaults to 20. */
+    topByMetric(opts: {
+        snapshotId: number;
+        metric: string;
+        limit?: number;
+        kind?: string;
+    }): TopMetricRow[];
+    /** Edges into or out of one node; `references` edges are excluded unless asked, as in {@link listEdges}. */
+    listEdgesTouching(snapshotId: number, nodeId: string, opts?: {
+        includeReferences?: boolean;
+    }): GraphEdge[];
+    /** Count, sum, min, and max per metric name and node kind; pass `name` for one metric. */
+    aggregateMetrics(snapshotId: number, opts?: {
+        name?: string;
+    }): MetricAggregate[];
     listAliases(snapshotId: number): IdAlias[];
     listFingerprints(snapshotId: number): FileFingerprint[];
+    /** Drop whole snapshots. The domain tables carry no foreign key, so each is cleared by hand. */
+    deleteSnapshots(ids: readonly number[]): void;
+    vacuum(): void;
+    countRowsByTable(tables: readonly string[]): Record<string, number>;
     close(): void;
 }
 /** Open (creating if absent) a code graph database and bring it to the current schema. */
@@ -126,16 +175,37 @@ declare const KIT: {
  * `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";
+/** Every table keyed by `snapshot_id`. No DDL above declares a foreign key, so dropping a snapshot walks this list. */
+declare const SNAPSHOT_SCOPED_TABLES: readonly ["node", "edge", "metric", "id_alias", "file_fingerprint"];
 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;
 
+interface PrunePlan {
+    keep: SnapshotRow[];
+    remove: SnapshotRow[];
+}
+interface PruneOptions {
+    keep?: number;
+    keepRefs?: readonly string[];
+}
+declare function planPrune(store: CodeGraphStore, options?: PruneOptions): PrunePlan;
+interface PruneResult {
+    plan: PrunePlan;
+    rowsBefore: Record<string, number>;
+    rowsAfter: Record<string, number>;
+    vacuumed: boolean;
+}
+declare function runPrune(store: CodeGraphStore, options?: PruneOptions & {
+    vacuum?: boolean;
+}): PruneResult;
+
 /**
  * Bumping this invalidates every reuse basis: a snapshot written by a different
  * 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.14.0";
+declare const INDEX_VERSION = "0.15.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[];
@@ -290,6 +360,51 @@ declare class TsMorphGraphExtractor implements Extractor<GraphFragment> {
  */
 declare function buildFileModuleNodes(repoRoot: string, absPath: string): GraphNode[];
 
+/**
+ * C-81 — **deep AST on-pull**. Structural facts too heavy to persist at index
+ * time (class members, per-parameter types, return type) are recomputed lazily
+ * here from the working-tree source when a consumer actually pulls a target.
+ * Persisting them would bloat every symbol node and break the incremental reuse
+ * basis (inferred types embed absolute `import("…")` paths); computing on demand
+ * keeps the index lean while still answering "what are the members / params of
+ * this" for the one target being read.
+ *
+ * A single-file in-memory ts-morph project (no tsconfig, no dependency walk) —
+ * so the extraction is cheap and reads only explicit syntactic annotations.
+ */
+interface ParamInfo {
+    name: string;
+    type: string | null;
+}
+interface MemberInfo {
+    name: string;
+    memberKind: string;
+    signature: string | null;
+    isStatic: boolean;
+}
+interface DeepAst {
+    target: string;
+    kind: "file" | "symbol";
+    declarationKind: string | null;
+    signature: string | null;
+    purpose: string | null;
+    params: ParamInfo[];
+    returnType: string | null;
+    /** Class/interface members for a symbol; exported declarations for a file. */
+    members: MemberInfo[];
+    note?: string;
+}
+interface DeepAstInput {
+    /** Repo-relative file id, e.g. `src/a.ts`. */
+    filePath: string;
+    /** Absolute path to the file on disk. */
+    absPath: string;
+    /** Symbol name for a symbol target; omit for a file target. */
+    symbolName?: string;
+}
+/** Deep structural facts for one target, or null when the source is unreadable. */
+declare function computeDeepAst(input: DeepAstInput): DeepAst | null;
+
 declare function fileId(repoRoot: string, absPath: string): string;
 declare function moduleId(repoRoot: string, absPath: string): string;
 declare function parentModuleId(id: string): string | null;
@@ -466,9 +581,84 @@ interface DetectRenamesOptions {
 declare function detectGitHead(repoRoot: string): string | null;
 declare function isInsideGitRepo(repoRoot: string): boolean;
 
+/** Resolve a ref (branch, tag, sha) to its current commit sha, or null. */
+declare function resolveGitRef(repoRoot: string, ref: string): string | null;
 declare function detectRenames(options: DetectRenamesOptions): RenamePair[];
 declare function buildAliases(repoRoot: string, pairs: readonly RenamePair[]): IdAlias[];
 
+/** Snapshot attrs key naming the snapshot its id aliases were computed against; written from index version 0.15.0. */
+declare const ALIAS_BASE_ATTR = "aliasBase";
+type LineageSnapshot = Pick<SnapshotRow, "id" | "commitHash" | "attrs">;
+/** Each snapshot's alias base, or null for a root: the tree the id_alias rows form across snapshots. */
+type Lineage = ReadonlyMap<number, number | null>;
+interface LineageStep {
+    snapshotId: number;
+    /** `forward` applies the snapshot's aliases (base to snapshot); `backward` undoes them. */
+    direction: "forward" | "backward";
+}
+/**
+ * The recorded base per snapshot. A snapshot written before 0.15.0 records none,
+ * so it gets the newest earlier snapshot with a commit: the one the indexer diffed against then.
+ */
+declare function buildLineage(snapshots: readonly LineageSnapshot[]): Lineage;
+/** Steps from one snapshot to another through their nearest common base, or null when they share none. */
+declare function lineagePath(lineage: Lineage, fromId: number, toId: number, maxHops?: number): LineageStep[] | null;
+
+type AliasLoader = (snapshotId: number) => readonly IdAlias[];
+interface AliasResolution {
+    requestedId: string;
+    /** The id in the target snapshot's id space; equal to `requestedId` when nothing moved. */
+    id: string;
+    /** Each alias applied in walk order; a backward step lists the alias it undid. */
+    hops: IdAlias[];
+    /** `move` when any hop changed directory, otherwise the last hop's reason; absent without hops. */
+    reason?: IdAliasReason;
+}
+interface AliasChain {
+    fromSnapshotId: number | null;
+    toSnapshotId: number;
+    /** False when the snapshots share no alias base; only the target's own aliases apply then, as before 0.15.0. */
+    connected: boolean;
+    steps: readonly LineageStep[];
+    resolve(id: string): string;
+    trace(id: string): AliasResolution;
+}
+interface AliasChainInput {
+    lineage: Lineage;
+    loadAliases: AliasLoader;
+    /** Null resolves an id from any ancestor of `to`. */
+    from: number | null;
+    to: number;
+    maxHops?: number;
+}
+/** Carry node ids from one snapshot into another across every rename between them. */
+declare function createAliasChain(input: AliasChainInput): AliasChain;
+
+interface AliasChainOptions {
+    maxHops?: number;
+}
+interface ResolveAliasOptions extends AliasChainOptions {
+    /** The snapshot the id was read in; omitted, the id may come from any ancestor of the target. */
+    fromSnapshotId?: number;
+}
+interface PriorSnapshotOptions {
+    /** Only snapshots older than this id count; omitted, every snapshot does. */
+    before?: number;
+    /** A git checkout to resolve `ref` in; without it only the snapshot's `ref` label matches. */
+    repoRoot?: string;
+}
+/** The alias-base tree over every snapshot in the store. */
+declare function loadLineage(store: CodeGraphStore): Lineage;
+/** Carry node ids from `fromSnapshotId` into `toSnapshotId` through every alias between them, in either direction. */
+declare function aliasChain(store: CodeGraphStore, fromSnapshotId: number | null, toSnapshotId: number, options?: AliasChainOptions): AliasChain;
+/** Resolve an id to its form in `toSnapshotId`: `a.ts` renamed to `b.ts` then `c.ts` resolves to `c.ts`. */
+declare function resolveAlias(store: CodeGraphStore, id: string, toSnapshotId: number, options?: ResolveAliasOptions): AliasResolution;
+/**
+ * The newest snapshot a ref denotes: first the snapshot of the commit git resolves
+ * `ref` to (with `repoRoot`), else the newest snapshot whose `ref` label is `ref`.
+ */
+declare function priorSnapshotForRef(store: CodeGraphStore, ref: string, options?: PriorSnapshotOptions): SnapshotRow | null;
+
 declare function computeMetrics(nodes: readonly GraphNode[], edges: readonly GraphEdge[]): GraphMetric[];
 
 /**
@@ -528,6 +718,17 @@ interface HistoryMetricsOptions {
     /** Epoch seconds that windows end at; defaults to the current time. */
     nowEpoch?: number;
 }
+/** Windows the dashboard switcher offers; churn is stored for each by default. */
+declare const DEFAULT_CHURN_WINDOWS: number[];
+/** De-duped, ascending windows including the primary, with `lifetime` last (widest) when requested. */
+declare function resolveChurnWindows(requested: number[] | undefined, primaryWindow: number, includeLifetime: boolean): ChurnWindow[];
+interface LoadedHistory {
+    metrics: GraphMetric[];
+    /** Churn entries inside the primary window, which also scopes test-coverage linking and ownership. */
+    primaryEntries: readonly ChurnEntry[];
+}
+/** {@link buildHistoryMetrics} plus the primary-window entries it read; null when git or history is unavailable. */
+declare function loadHistoryMetrics(nodes: Iterable<GraphNode>, idRoot: string, options?: HistoryMetricsOptions): LoadedHistory | null;
 interface TestCoverageOwnershipOptions {
     /** Window named in the metric suffix. Default 30. */
     windowDays?: ChurnWindow;
@@ -648,6 +849,17 @@ interface SymbolSpan {
  */
 declare function attributeCoverage(coverage: IstanbulCoverage, fileIdOf: (absPath: string) => string | null, symbolsByFile: ReadonlyMap<string, readonly SymbolSpan[]>): GraphMetric[];
 
+/** Metric-name suffix for a window: `30d`, `180d`, or `lifetime`. */
+declare function windowSuffix(window: ChurnWindow): string;
+/**
+ * Age-discount metrics: `recency_{w}` = min(1, age/w) for each file that churned
+ * in window `w`, plus one window-independent `file_age_days` per file. Multiplying
+ * a hotspot score by recency stops a young file's burst of churn from reading as
+ * decay. Recency is emitted (as 1) even when the age is unknown, so a rule that
+ * needs every hotspot factor is never silently disabled; `file_age_days` only when known.
+ */
+declare function computeRecencyWindows(firstSeen: ReadonlyMap<string, number>, churnedIdsByWindow: ReadonlyMap<ChurnWindow, ReadonlySet<string>>, nowEpoch: number): GraphMetric[];
+
 interface PageRankOptions {
     /** Per-node teleport weight. Unset or empty → uniform teleport across all nodes. */
     personalization?: ReadonlyMap<string, number>;
@@ -774,6 +986,86 @@ declare function computeSymbolConsumers(edges: readonly ReferenceEdgeLite[]): Sy
  */
 declare function computeSymbolCoupling(edges: readonly ReferenceEdgeLite[], options?: SymbolCouplingOptions): SymbolCouplingPair[];
 
+/**
+ * Per-package and per-pair structural quality metrics, plus an overall
+ * Newman-Girvan modularity Q for the package partition.
+ *
+ * Operates on a barrel-resolved edge set by default: edges that land on a
+ * file with role="barrel" are rewritten to land on the underlying files
+ * the barrel re-exports from (transitively). The intent is to measure the
+ * real dependency surface, not the re-export plumbing.
+ *
+ * See C-8 task notes for the design rationale and empirical calibration
+ * data from the 2026-05-21 codewatch dogfood.
+ */
+interface PartitionQualityInput {
+    /** Logical packages — at minimum needs an id. */
+    packages: ReadonlyArray<{
+        id: string;
+    }>;
+    /** Package id → list of file ids assigned to that package. */
+    fileByPackage: ReadonlyMap<string, ReadonlyArray<string>>;
+    /** All file/module/external nodes for the snapshot. Used to identify role="barrel". */
+    nodes: readonly GraphNode[];
+    /** All edges for the snapshot. */
+    edges: readonly GraphEdge[];
+    /**
+     * When true, edges landing on a barrel file are resolved through its
+     * re-export chain to the underlying source files. The cheap implementation
+     * fans each barrel import into N synthetic edges (one per re-export
+     * target), which over-attributes — a single `import { x } from "./pkg"`
+     * becomes N edges as if every re-export were used. Default false until
+     * a weighted or symbol-tracking version is available.
+     */
+    resolveBarrels?: boolean;
+}
+type PackageFlag = "weak-boundary";
+type PairFlag = "tight" | "moderate" | "none";
+type PackageLayer = "top" | "middle" | "foundation";
+interface PackageStats {
+    pkgId: string;
+    fileCount: number;
+    internalEdges: number;
+    outgoingEdges: number;
+    incomingEdges: number;
+    /** internal / (internal + outgoing) — higher = more self-contained. */
+    cohesion: number;
+    /** outgoing / (outgoing + incoming) — Martin's I metric at the package level. */
+    instability: number;
+    /**
+     * Abstractness proxy A ∈ [0,1]: share of the package's files with role
+     * "types" (dedicated type/interface definitions). codewatch has no
+     * symbol-level abstract/concrete counts, so this file-role ratio stands in
+     * for Martin's A. Enables the instability×abstractness main-sequence plot.
+     */
+    abstractness: number;
+    layer: PackageLayer;
+    flags: PackageFlag[];
+}
+interface PairCoupling {
+    from: string;
+    to: string;
+    edges: number;
+    /** edges / files(from) — fraction of from-side files contributing dependencies into `to`. */
+    intensity: number;
+    flag: PairFlag;
+}
+interface PartitionQualityResult {
+    modularityQ: number;
+    totalEdges: number;
+    perPackage: PackageStats[];
+    pairCoupling: PairCoupling[];
+    /** Total raised flags across packages + pairs (excluding "moderate"). */
+    flagsCount: number;
+}
+declare function computePartitionQuality(input: PartitionQualityInput): PartitionQualityResult;
+/**
+ * Invert a package→files bucket map into a file→package lookup, skipping the
+ * empty-string "unassigned" bucket. Shared by partition-quality and the CLI's
+ * arch/wiki package rollups, which all need the same file→package direction.
+ */
+declare function invertBuckets(fileByPackage: ReadonlyMap<string, ReadonlyArray<string>>): Map<string, string>;
+
 /**
  * PageRank over one snapshot's file-level graph (symbol nodes and `references`
  * edges excluded, as codewatch's `graph relevant` reads it). Pass
@@ -801,6 +1093,51 @@ declare function listEdges(store: CodeGraphStore, snapshotId: number, opts?: {
     includeReferences?: boolean;
 }): GraphEdge[];
 declare function listMetrics(store: CodeGraphStore, snapshotId: number): GraphMetric[];
+declare function listMetricsForNode(store: CodeGraphStore, snapshotId: number, nodeId: string): GraphMetric[];
+declare function listEdgesTouching(store: CodeGraphStore, snapshotId: number, nodeId: string, opts?: {
+    includeReferences?: boolean;
+}): GraphEdge[];
+declare function aggregateMetrics(store: CodeGraphStore, snapshotId: number, opts?: {
+    name?: string;
+}): MetricAggregate[];
+
+/** The `unit` a metric row is stored with; every row of one metric name carries the same unit. */
+type MetricUnit = "count" | "lines" | "ratio" | "days" | "percent";
+/** How file values combine into a directory; `none` means no rollup reproduces the group's true value. */
+type MetricRollup = "sum" | "max" | "mean" | "none";
+/** Which way is worse, for ranking and colouring; `neutral` makes no value judgement. */
+type MetricDirection = "higher-worse" | "lower-worse" | "neutral";
+/** A missing row reads as zero (a sparse writer's floor) or is left out of means, percentiles, and ranks. */
+type MetricAbsence = "zero" | "exclude";
+/** The code-graph module that writes the metric, for provenance. */
+type MetricSource = "degree" | "source-metrics" | "lcom" | "dead-code" | "growth-risk" | "history" | "test-linker" | "coverage";
+interface MetricDescriptor {
+    /** The stored name, or a template such as `churn_{w}` when {@link windowed} is set. */
+    name: string;
+    unit: MetricUnit;
+    /** Node kinds the writer attaches this metric to. */
+    appliesTo: readonly NodeKind[];
+    rollup: MetricRollup;
+    direction: MetricDirection;
+    absent: MetricAbsence;
+    source: MetricSource;
+    description: string;
+    /** Set on templates: `{w}` in `name` and `description` stands for a window such as `30d` or `lifetime`. */
+    windowed?: true;
+    /** Set on a resolved windowed descriptor: the window its name carries. */
+    window?: string;
+}
+
+/** Every metric name code-graph writes, with windowed names as `{w}` templates. */
+declare const METRIC_CATALOGUE: readonly MetricDescriptor[];
+
+/** The descriptor for a stored metric name, resolving windowed names such as `churn_90d`; null when uncatalogued. */
+declare function describeMetric(name: string): MetricDescriptor | null;
+/** Descriptors for a set of stored names, in the order given; uncatalogued names are returned separately. */
+declare function describeMetrics(names: Iterable<string>): {
+    described: MetricDescriptor[];
+    unknown: string[];
+};
 
 type Severity = "error" | "warning";
 interface MetricMaxRule {
@@ -883,12 +1220,26 @@ interface CheckResult {
     passed: boolean;
 }
 
+/** The three whole-snapshot reads rule evaluation needs; any store with them can be checked. */
+type RuleStore = Pick<CodeGraphStore, "listNodes" | "listEdges" | "listMetrics">;
+
 interface RunChecksOptions {
     snapshotId: number;
     rules: readonly CheckRule[];
     baselineSnapshotId?: number;
 }
 declare function runChecks(store: CodeGraphStore, options: RunChecksOptions): CheckResult;
+/** Every rule's violations in one snapshot with no baseline; needs only the three whole-snapshot reads. */
+declare function snapshotViolations(store: RuleStore, snapshotId: number, rules: readonly CheckRule[]): CheckViolation[];
+/** Identity of a violation across snapshots: severity, value and message may change, the key does not. */
+declare function violationKey(v: CheckViolation): string;
+/** {@link violationKey} with both node ids carried into another snapshot's id space; unmoved ids key as before. */
+declare function rebasedViolationKey(v: CheckViolation, resolve: (id: string) => string): string;
+
+/** Glob when the pattern has a `*` (`**` crosses directories, `*` stays in a segment); otherwise a case-sensitive substring. */
+declare function patternToRegex(pattern: string): RegExp;
+declare function compilePatterns(patterns: readonly string[] | undefined): RegExp[];
+declare function matchesAny(value: string, patterns: readonly RegExp[]): boolean;
 
 interface ValidateRulesOptions {
     /** Called with a human-readable message when a deprecated alias is healed. */
@@ -952,7 +1303,10 @@ 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. */
+/**
+ * Structural diff of two snapshots. Ids follow the alias chain between them, across
+ * every rename in between, so a move is not a delete plus an add.
+ */
 declare function diffSnapshots(store: CodeGraphStore, options: DiffSnapshotsOptions): GraphDiff;
 
 interface UnchangedViolation {
@@ -975,7 +1329,11 @@ interface DiffCheckResultsOptions {
     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). */
+/**
+ * Run the rules on both snapshots and bucket each violation as new, resolved, or
+ * unchanged (worsened or improved by value). From-side ids follow the alias chain
+ * into the to-snapshot, so a moved file's violations stay unchanged.
+ */
 declare function diffCheckResults(store: CodeGraphStore, options: DiffCheckResultsOptions): CheckDiff;
 
 interface EmbeddableSymbol {
@@ -1074,4 +1432,124 @@ declare function tryEmbedSnapshot(store: CodeGraphStore, snapshotId: number, emb
  */
 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 };
+/** A text-summarization backend the product injects; `model` keys the stored summaries. */
+interface Summarizer {
+    readonly model: string;
+    summarize(prompt: string): Promise<string>;
+}
+interface ConventionSymbol {
+    name: string;
+    signature: string;
+    purpose?: string;
+}
+interface ConventionArea {
+    /** Stable over membership: `area-` plus a hash of the member file list. */
+    id: string;
+    /** Dominant directory of the members. */
+    label: string;
+    /** Member files, most-connected first. */
+    files: string[];
+    size: number;
+    topSymbols: ConventionSymbol[];
+    /** Hash of the summarizer prompt, which is the summary-cache key. */
+    contentHash: string;
+    summary?: string;
+}
+interface ConventionCoverage {
+    /** Non-generated indexed files in the snapshot. */
+    files: number;
+    /** Files inside a kept area; the rest are too small or isolated to summarize. */
+    grouped: number;
+    areas: number;
+    summarized: number;
+}
+interface ConventionMap {
+    model: string;
+    coverage: ConventionCoverage;
+    areas: ConventionArea[];
+}
+interface SummarizeConventionsResult extends ConventionMap {
+    /** Cache misses sent to the summarizer on this call. */
+    newlySummarized: number;
+    /** Areas whose summary was already stored. */
+    reused: number;
+}
+interface ConventionMatch {
+    id: string;
+    label: string;
+    summary: string;
+    files: string[];
+    size: number;
+    /** Cosine similarity of the query to the area summary, in [-1, 1]. */
+    score: number;
+}
+interface ConventionQueryResult {
+    query: string;
+    model: string;
+    embeddingModel: string;
+    coverage: ConventionCoverage;
+    matches: ConventionMatch[];
+}
+/** The cut level: how coarse the partition is and which areas are kept. */
+interface ConventionOptions {
+    /** Coarse community count to merge down to; default scales with repo size. */
+    targetCount?: number;
+    /** Areas smaller than this stay ungrouped (not summarized). Default 3. */
+    minSize?: number;
+}
+interface FindConventionsOptions extends ConventionOptions {
+    /** Matches returned. Default 3. */
+    limit?: number;
+}
+interface ConventionCorpus {
+    areas: ConventionArea[];
+    /** Summarizer prompt per area, keyed by the area's `contentHash`. */
+    prompts: Map<string, string>;
+    coverage: ConventionCoverage;
+}
+
+/**
+ * Greedy-modularity (Clauset-Newman-Moore) community detection over the
+ * undirected file dependency graph. Deterministic: ties and labels resolve
+ * by sorted node id, so the same graph always yields the same partition.
+ *
+ * Two optional controls shape the C-88 capability-altitude cut, in opposite
+ * directions: `maxSize` skips any merge that would grow a community past it
+ * (greedy CNM otherwise snowballs a dense graph into one giant blob — the
+ * cap shapes formation instead of trying to split after the fact), and
+ * `targetCount` keeps merging past the natural modularity stop (taking the
+ * least-bad allowed merge) while more communities than that remain, so a
+ * sparse fragmented graph still coarsens. Disconnected components can never
+ * merge, so the floor is the component count.
+ */
+declare function detectCommunities(fileIds: readonly string[], edges: readonly GraphEdge[], opts?: {
+    targetCount?: number;
+    maxSize?: number;
+}): Map<string, string[]>;
+
+/** Coarse capability-altitude cut: about one area per 25 files, clamped to 6..40. */
+declare function defaultTargetCount(fileCount: number): number;
+/**
+ * The deterministic half of the convention layer: partition the barrel-resolved
+ * file graph into coarse areas and build each area's summarizer prompt and cache key.
+ */
+declare function buildConventionAreas(store: CodeGraphStore, snapshotId: number, opts?: ConventionOptions): ConventionCorpus;
+
+/** The blob_cache namespace for area summaries; the model column holds `summarizer.model`. */
+declare const COMMUNITY_SUMMARY_NAMESPACE = "code-graph/community-summary";
+/**
+ * Generate or reuse the summary of every area. Only cache misses reach the
+ * summarizer, so cost scales with what structurally changed, not with repo size.
+ */
+declare function summarizeConventions(store: CodeGraphStore, snapshotId: number, summarizer: Summarizer, opts?: ConventionOptions): Promise<SummarizeConventionsResult>;
+/** Read-only view: the partition plus whatever summaries are already stored. Never calls a summarizer. */
+declare function getConventionMap(store: CodeGraphStore, snapshotId: number, model: string, opts?: ConventionOptions): ConventionMap;
+
+/**
+ * "How does this repo do X?": rank summarized areas by similarity of their
+ * summary to the question. Returns candidates, not verdicts. Summary vectors
+ * share the content-addressed embedding cache with the symbol layer.
+ */
+declare function findConventions(store: CodeGraphStore, snapshotId: number, query: string, embedder: Embedder, model: string, opts?: FindConventionsOptions): Promise<ConventionQueryResult>;
+
+export { ALIAS_BASE_ATTR, ALL_ROLES, type AliasChain, type AliasChainInput, type AliasChainOptions, type AliasLoader, type AliasResolution, COMMUNITY_SUMMARY_NAMESPACE, COVERAGE_METRIC_NAME, type CachedEmbedResult, type CheckDiff, type CheckResult, type CheckRule, type CheckRulesFile, type CheckSnapshotOptions, type CheckSnapshotResult, type CheckViolation, CodeGraphStore, type ConventionArea, type ConventionCorpus, type ConventionCoverage, type ConventionMap, type ConventionMatch, type ConventionOptions, type ConventionQueryResult, type ConventionSymbol, DEAD_CODE_METRIC_NAMES, DEFAULT_CHURN_WINDOWS, DOMAIN_DDL, type DeepAst, type DeepAstInput, type DiffCheckResultsOptions, type DiffSnapshotsOptions, type EdgeKind, type EmbedAttempt, type EmbedCoverage, type EmbedSnapshotResult, type EmbeddableSymbol, type FileFingerprint, type FindConventionsOptions, type FindSimilarOptions, type ForbidImportRule, GROWTH_RISK_METRIC_NAMES, type GraphDiff, type GraphDiffSummary, type GraphEdge, type GraphFragment, type GraphMetric, type GraphNode, type HistoryMetricsOptions, INDEX_VERSION, type IdAlias, type IdAliasReason, type IndexOptions, type IndexResult, type IstanbulCoverage, KIT, LanguageExtractor, type LanguageExtractorOptions, type LayeredDepsRule, type LineSpan, type Lineage, type LineageSnapshot, type LineageStep, type LinkMethod, type LinkTestsOptions, type LoadedHistory, METRIC_CATALOGUE, MIGRATIONS, type MemberInfo, type MetricAbsence, type MetricAggregate, type MetricDelta, type MetricDescriptor, type MetricDirection, type MetricMaxRule, type MetricMinRule, type MetricProductMaxRule, type MetricRollup, type MetricSource, type MetricUnit, type NoInternalOnlyBarrelsRule, type NodeKind, type NodeRename, type NodeRole, type PackageFlag, type PackageLayer, type PackageStats, type PageRankOptions, type PageRankResult, type PageRankRow, type PairCoupling, type PairFlag, type ParamInfo, type PartitionQualityInput, type PartitionQualityResult, type PriorSnapshotOptions, type PruneOptions, type PrunePlan, type PruneResult, PythonGraphExtractor, type ReadFile, type ReferenceEdgeLite, type RelevanceOptions, type ResolveAliasOptions, type ReuseBasis, type RuleStore, type RunChecksOptions, SCHEMA_VERSION, SNAPSHOT_SCOPED_TABLES, SOURCE_METRIC_NAMES, SYMBOL_EMBEDDING_NAMESPACE, SYMBOL_ID_SEP, type Severity, type SimilarCandidate, type SimilarResult, type SnapshotInsert, type SnapshotRow, type SnapshotSpec, type SourceLanguage, type SummarizeConventionsResult, type Summarizer, type SymbolConsumers, type SymbolCouplingOptions, type SymbolCouplingPair, type SymbolSpan, type TestCoverageOwnershipOptions, type TestSourceLink, type TopMetricRow, TsMorphGraphExtractor, type TsMorphGraphExtractorOptions, type UnchangedViolation, type ValidateRulesOptions, aggregateMetrics, aliasChain, annotateRoles, attributeCoverage, buildAliases, buildConventionAreas, buildEmbedText, buildFileModuleNodes, buildIndexerMetrics, buildLineage, canonicalEdgeKind, canonicalMetricName, canonicalRole, checkSnapshot, classifyRole, collectDeclaredNames, collectDeclaredSpans, compilePatterns, computeDeadCodeMetrics, computeDeepAst, computeGrowthRiskMetrics, computeMetrics, computePageRank, computePartitionQuality, computeRecencyWindows, computeRelevance, computeRoleHints, computeSourceMetrics, computeSymbolConsumers, computeSymbolCoupling, computeTestCoverageOwnership, createAliasChain, defaultTargetCount, describeMetric, describeMetrics, detectCommunities, detectGitHead, detectGitToplevel, detectRenames, diffCheckResults, diffSnapshots, edgeWeight, embedSnapshot, embedTextsCached, externalId, fileId, findConventions, findSimilarCapability, getConventionMap, getEdgeWeight, groupTestsBySource, hashContent, hashEmbedText, indexPaths, invertBuckets, isGeneratedByHeuristic, isGeneratedFile, isInsideGitRepo, lineagePath, linkTestsToSources, listEdges, listEdgesTouching, listEmbeddableSymbols, listMetrics, listMetricsForNode, listNodes, loadCheckRules, loadGeneratedPatterns, loadHistoryMetrics, loadLineage, matchesAny, moduleId, openCodeGraph, packageId, parentModuleId, parseSymbolId, patternToRegex, planPrune, priorSnapshotForRef, pruneDanglingReferences, readSourceFiles, rebasedViolationKey, resolveAlias, resolveBarrelEdges, resolveChurnWindows, resolveGitRef, resolveSnapshot, runChecks, runPrune, snapshotPageRank, snapshotReferenceEdges, snapshotRelevance, snapshotSymbolConsumers, snapshotSymbolCoupling, snapshotViolations, structuralSignature, summarizeConventions, symbolId, testCoverageCountMetrics, tryEmbedSnapshot, validateRules, violationKey, walkSourceFiles, windowSuffix };