@titan-design/code-graph 0.2.0 → 0.4.0

package/dist/index.js

@@ -13,7 +13,7 @@ import {
 } from "./chunk-PFI5XMUG.js";
 
 // src/store.ts
-import { openDatabase, runMigrations } from "@titan-design/store-sqlite";
+import { openDatabase, quoteIdent, runMigrations } from "@titan-design/store-sqlite";
 
 // src/schema.ts
 import { kitMigration } from "@titan-design/store-sqlite";
@@ -62,6 +62,7 @@ var DOMAIN_DDL = `
     PRIMARY KEY (snapshot_id, file_id)
   );
 `;
+var SNAPSHOT_SCOPED_TABLES = ["node", "edge", "metric", "id_alias", "file_fingerprint"];
 var MIGRATIONS = [
   kitMigration(1, { snapshot: KIT.snapshot, entitySnap: KIT.entitySnap, cacheBlob: KIT.cacheBlob }),
   { version: 2, name: "code graph columns", up: (db) => db.exec(KIT_EXTENSIONS) },
@@ -122,15 +123,81 @@ function rowToFingerprint(row) {
   };
 }
 
+// src/store-reads.ts
+var EDGE_COLS = "src_id, dst_id, kind, attrs";
+var AGGREGATE_SELECT = `SELECT m.name AS name, n.kind AS node_kind, COUNT(m.value) AS count,
+  SUM(m.value) AS sum, MIN(m.value) AS min, MAX(m.value) AS max
+  FROM metric m CROSS JOIN node n ON n.snapshot_id = m.snapshot_id AND n.id = m.node_id`;
+var TOP_SELECT = `SELECT m.node_id, m.value, m.unit, n.kind, n.name, n.role
+  FROM metric m JOIN node n ON n.snapshot_id = m.snapshot_id AND n.id = m.node_id
+  WHERE m.snapshot_id = ? AND m.name = ?`;
+var TOP_ORDER = "ORDER BY m.value DESC LIMIT ?";
+function prepareTargetedStatements(db) {
+  return {
+    listMetricsForNode: db.prepare(
+      "SELECT node_id, name, value, unit FROM metric WHERE snapshot_id = ? AND node_id = ?"
+    ),
+    // The second arm skips self-loops so an edge from a node to itself comes back once.
+    listEdgesTouching: db.prepare(
+      `SELECT ${EDGE_COLS} FROM edge WHERE snapshot_id = @snapshotId AND src_id = @nodeId
+       UNION ALL
+       SELECT ${EDGE_COLS} FROM edge WHERE snapshot_id = @snapshotId AND dst_id = @nodeId AND src_id <> @nodeId`
+    ),
+    aggregateMetric: db.prepare(
+      `${AGGREGATE_SELECT} WHERE m.snapshot_id = ? AND m.name = ? GROUP BY n.kind ORDER BY n.kind`
+    ),
+    aggregateMetrics: db.prepare(
+      `${AGGREGATE_SELECT} WHERE m.snapshot_id = ? GROUP BY m.name, n.kind ORDER BY m.name, n.kind`
+    ),
+    listMetricNames: db.prepare("SELECT DISTINCT name FROM metric WHERE snapshot_id = ? ORDER BY name"),
+    topByMetric: db.prepare(`${TOP_SELECT} ${TOP_ORDER}`),
+    topByMetricOfKind: db.prepare(`${TOP_SELECT} AND n.kind = ? ${TOP_ORDER}`)
+  };
+}
+function readMetricsForNode(stmts, snapshotId, nodeId) {
+  return stmts.listMetricsForNode.all(snapshotId, nodeId).map(rowToMetric);
+}
+function readEdgesTouching(stmts, snapshotId, nodeId) {
+  return stmts.listEdgesTouching.all({ snapshotId, nodeId }).map(rowToEdge);
+}
+function readMetricNames(stmts, snapshotId) {
+  return stmts.listMetricNames.all(snapshotId).map((r) => r.name);
+}
+function readTopByMetric(stmts, opts) {
+  const limit = opts.limit ?? 20;
+  const rows = opts.kind === void 0 ? stmts.topByMetric.all(opts.snapshotId, opts.metric, limit) : stmts.topByMetricOfKind.all(opts.snapshotId, opts.metric, opts.kind, limit);
+  return rows.map((r) => ({
+    nodeId: r.node_id,
+    name: r.name,
+    kind: r.kind,
+    role: r.role,
+    value: r.value,
+    unit: r.unit
+  }));
+}
+function readMetricAggregates(stmts, snapshotId, name) {
+  const rows = name === void 0 ? stmts.aggregateMetrics.all(snapshotId) : stmts.aggregateMetric.all(snapshotId, name);
+  return rows.map((r) => ({
+    name: r.name,
+    nodeKind: r.node_kind,
+    count: r.count,
+    sum: r.sum,
+    min: r.min,
+    max: r.max
+  }));
+}
+
 // src/store.ts
 var NODE_COLS = "id, kind, name, parent_id, language, role, attrs";
 var CodeGraphStore = class {
   constructor(db) {
     this.db = db;
     this.statements = prepareStatements(db);
+    this.targeted = prepareTargetedStatements(db);
   }
   db;
   statements;
+  targeted;
   createSnapshot(input) {
     const result = this.statements.insertSnapshot.run({
       ref: input.ref,
@@ -179,6 +246,21 @@ var CodeGraphStore = class {
       }
     })();
   }
+  /**
+   * 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, name, metrics) {
+    const del = this.statements.deleteMetricsByName;
+    const insert = this.statements.insertMetric;
+    this.db.transaction(() => {
+      del.run(snapshotId, name);
+      for (const m of metrics) {
+        insert.run({ snapshotId, nodeId: m.nodeId, name: m.name, value: m.value, unit: m.unit ?? null });
+      }
+    })();
+  }
   insertAliases(snapshotId, aliases) {
     const stmt = this.statements.insertAlias;
     this.db.transaction(() => {
@@ -233,12 +315,53 @@ var CodeGraphStore = class {
   listMetrics(snapshotId) {
     return this.statements.listMetrics.all(snapshotId).map(rowToMetric);
   }
+  /** Every metric on one node, from the primary key instead of a whole-snapshot read. */
+  listMetricsForNode(snapshotId, nodeId) {
+    return readMetricsForNode(this.targeted, snapshotId, nodeId);
+  }
+  /** Distinct metric names stored for a snapshot, ascending. */
+  listMetricNames(snapshotId) {
+    return readMetricNames(this.targeted, snapshotId);
+  }
+  /** The highest-valued nodes for one metric, descending; `limit` defaults to 20. */
+  topByMetric(opts) {
+    return readTopByMetric(this.targeted, opts);
+  }
+  /** Edges into or out of one node; `references` edges are excluded unless asked, as in {@link listEdges}. */
+  listEdgesTouching(snapshotId, nodeId, opts) {
+    const edges = readEdgesTouching(this.targeted, snapshotId, nodeId);
+    return opts?.includeReferences ? edges : edges.filter((e) => e.kind !== "references");
+  }
+  /** Count, sum, min, and max per metric name and node kind; pass `name` for one metric. */
+  aggregateMetrics(snapshotId, opts) {
+    return readMetricAggregates(this.targeted, snapshotId, opts?.name);
+  }
   listAliases(snapshotId) {
     return this.statements.listAliases.all(snapshotId).map(rowToAlias);
   }
   listFingerprints(snapshotId) {
     return this.statements.listFingerprints.all(snapshotId).map(rowToFingerprint);
   }
+  /** Drop whole snapshots. The domain tables carry no foreign key, so each is cleared by hand. */
+  deleteSnapshots(ids) {
+    if (ids.length === 0) return;
+    this.db.transaction(() => {
+      for (const id of ids) {
+        for (const stmt of this.statements.deleteBySnapshot) stmt.run(id);
+      }
+    })();
+  }
+  vacuum() {
+    this.db.exec("VACUUM");
+  }
+  countRowsByTable(tables) {
+    const out = {};
+    for (const table of tables) {
+      const row = this.db.prepare(`SELECT COUNT(*) AS n FROM ${quoteIdent(table)}`).get();
+      out[table] = row.n;
+    }
+    return out;
+  }
   close() {
     this.db.close();
   }
@@ -281,6 +404,10 @@ function prepareStatements(db) {
     listAliases: db.prepare("SELECT old_id, new_id, reason FROM id_alias WHERE snapshot_id = ?"),
     listFingerprints: db.prepare(
       "SELECT file_id, content_hash, structural_hash FROM file_fingerprint WHERE snapshot_id = ?"
+    ),
+    deleteMetricsByName: db.prepare("DELETE FROM metric WHERE snapshot_id = ? AND name = ?"),
+    deleteBySnapshot: [...SNAPSHOT_SCOPED_TABLES, "snapshot"].map(
+      (table) => db.prepare(`DELETE FROM ${quoteIdent(table)} WHERE ${table === "snapshot" ? "id" : "snapshot_id"} = ?`)
     )
   };
 }
@@ -290,6 +417,34 @@ function openCodeGraph(dbPath) {
   return new CodeGraphStore(db);
 }
 
+// src/prune.ts
+var CASCADE_TABLES = SNAPSHOT_SCOPED_TABLES;
+function planPrune(store, options = {}) {
+  const keepCount = options.keep ?? 10;
+  const keepRefs = new Set(options.keepRefs ?? []);
+  const all = store.listSnapshots({ limit: 1e6 });
+  const keep = [];
+  const remove = [];
+  for (let i = 0; i < all.length; i++) {
+    const snap = all[i];
+    if (i < keepCount || keepRefs.has(snap.ref)) {
+      keep.push(snap);
+    } else {
+      remove.push(snap);
+    }
+  }
+  return { keep, remove };
+}
+function runPrune(store, options = {}) {
+  const plan = planPrune(store, options);
+  const tables = ["snapshot", ...CASCADE_TABLES];
+  const rowsBefore = store.countRowsByTable(tables);
+  store.deleteSnapshots(plan.remove.map((s) => s.id));
+  if (options.vacuum) store.vacuum();
+  const rowsAfter = store.countRowsByTable(tables);
+  return { plan, rowsBefore, rowsAfter, vacuumed: !!options.vacuum };
+}
+
 // src/indexer.ts
 import { realpathSync } from "fs";
 import * as path9 from "path";
@@ -491,14 +646,14 @@ function enter(scope, segment) {
   return qualify(scope, segment);
 }
 function walkScopes(root, python, visit) {
-  const step = (node, scope) => {
+  const step2 = (node, scope) => {
     visit(node, scope);
     const inner = enter(scope, scopeSegment(node, python));
     for (const child of node.children) {
-      if (child) step(child, inner);
+      if (child) step2(child, inner);
     }
   };
-  step(root, "");
+  step2(root, "");
 }
 
 // src/declared-names.ts
@@ -1109,6 +1264,9 @@ function detectGitHead(repoRoot) {
 function isInsideGitRepo(repoRoot) {
   return runGit(repoRoot, ["rev-parse", "--is-inside-work-tree"]) === "true";
 }
+function resolveGitRef(repoRoot, ref) {
+  return runGit(repoRoot, ["rev-parse", ref]);
+}
 function detectRenames(options) {
   const threshold = options.similarityThreshold ?? 80;
   const args = [
@@ -1164,6 +1322,160 @@ function buildAliases(repoRoot, pairs) {
   return out;
 }
 
+// src/identity/lineage.ts
+var ALIAS_BASE_ATTR = "aliasBase";
+var DEFAULT_MAX_HOPS = 1e4;
+function recordedBase(snap) {
+  if (!(ALIAS_BASE_ATTR in snap.attrs)) return void 0;
+  const base = snap.attrs[ALIAS_BASE_ATTR];
+  return typeof base === "number" && base < snap.id ? base : null;
+}
+function buildLineage(snapshots) {
+  const out = /* @__PURE__ */ new Map();
+  let lastWithCommit = null;
+  for (const snap of [...snapshots].sort((a, b) => a.id - b.id)) {
+    const recorded = recordedBase(snap);
+    out.set(snap.id, recorded === void 0 ? lastWithCommit : recorded);
+    if (snap.commitHash) lastWithCommit = snap.id;
+  }
+  return out;
+}
+function ancestry(lineage, snapshotId, maxHops = DEFAULT_MAX_HOPS) {
+  const out = [];
+  let current = snapshotId;
+  while (current !== null && current !== void 0 && out.length <= maxHops) {
+    out.push(current);
+    current = lineage.get(current);
+  }
+  return out;
+}
+function lineagePath(lineage, fromId, toId, maxHops = DEFAULT_MAX_HOPS) {
+  const up = ancestry(lineage, fromId, maxHops);
+  const down = ancestry(lineage, toId, maxHops);
+  const upIndex = new Map(up.map((id, i) => [id, i]));
+  const meet = down.findIndex((id) => upIndex.has(id));
+  if (meet < 0) return null;
+  const backward = up.slice(0, upIndex.get(down[meet])).map((id) => step(id, "backward"));
+  const forward = down.slice(0, meet).reverse().map((id) => step(id, "forward"));
+  return [...backward, ...forward];
+}
+function rootPath(lineage, toId, maxHops = DEFAULT_MAX_HOPS) {
+  return ancestry(lineage, toId, maxHops).reverse().map((id) => step(id, "forward"));
+}
+function step(snapshotId, direction) {
+  return { snapshotId, direction };
+}
+
+// src/identity/alias-chain.ts
+function stepMap(aliases, direction) {
+  const byId = /* @__PURE__ */ new Map();
+  const sorted = [...aliases].sort((a, b) => compare(a.oldId, b.oldId) || compare(a.newId, b.newId));
+  for (const alias of sorted) {
+    const key = direction === "forward" ? alias.oldId : alias.newId;
+    if (!byId.has(key)) byId.set(key, alias);
+  }
+  return { direction, byId };
+}
+function compare(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function overallReason(hops) {
+  if (hops.length === 0) return void 0;
+  return hops.some((h) => h.reason === "move") ? "move" : hops[hops.length - 1].reason;
+}
+function walk(requestedId, maps) {
+  let id = requestedId;
+  const hops = [];
+  for (const { direction, byId } of maps) {
+    const alias = byId.get(id);
+    if (!alias) continue;
+    hops.push(alias);
+    id = direction === "forward" ? alias.newId : alias.oldId;
+  }
+  return { requestedId, id, hops, reason: overallReason(hops) };
+}
+function chainSteps(input) {
+  if (input.from === null) return { steps: rootPath(input.lineage, input.to, input.maxHops), connected: true };
+  const path12 = lineagePath(input.lineage, input.from, input.to, input.maxHops);
+  if (path12) return { steps: path12, connected: true };
+  return { steps: [{ snapshotId: input.to, direction: "forward" }], connected: false };
+}
+function createAliasChain(input) {
+  const { steps, connected } = chainSteps(input);
+  const maps = steps.map((s) => stepMap(input.loadAliases(s.snapshotId), s.direction));
+  const cache = /* @__PURE__ */ new Map();
+  const trace = (id) => {
+    let hit = cache.get(id);
+    if (!hit) cache.set(id, hit = walk(id, maps));
+    return hit;
+  };
+  return { fromSnapshotId: input.from, toSnapshotId: input.to, connected, steps, resolve: (id) => trace(id).id, trace };
+}
+
+// src/identity/store-identity.ts
+function allSnapshots(store) {
+  return store.db.prepare("SELECT * FROM snapshot ORDER BY id").all().map(rowToSnapshot);
+}
+function loadLineage(store) {
+  return buildLineage(allSnapshots(store));
+}
+function aliasChain(store, fromSnapshotId, toSnapshotId, options = {}) {
+  return createAliasChain({
+    lineage: loadLineage(store),
+    loadAliases: (id) => store.listAliases(id),
+    from: fromSnapshotId,
+    to: toSnapshotId,
+    maxHops: options.maxHops
+  });
+}
+function resolveAlias(store, id, toSnapshotId, options = {}) {
+  return aliasChain(store, options.fromSnapshotId ?? null, toSnapshotId, options).trace(id);
+}
+function priorSnapshotForRef(store, ref, options = {}) {
+  const before = options.before ?? Number.POSITIVE_INFINITY;
+  const candidates2 = allSnapshots(store).filter((s) => s.id < before).reverse();
+  const commit = options.repoRoot ? resolveGitRef(options.repoRoot, `${ref}^{commit}`) : null;
+  const byCommit = commit ? candidates2.find((s) => s.commitHash === commit) : void 0;
+  return byCommit ?? candidates2.find((s) => s.ref === ref) ?? null;
+}
+function aliasBaseFor(store, ref) {
+  const committed = allSnapshots(store).filter((s) => s.commitHash).reverse();
+  return committed.find((s) => s.ref === ref) ?? committed[0] ?? null;
+}
+
+// src/identity/index-aliases.ts
+var SYMBOLS_OF_FILE = `SELECT id FROM node
+  WHERE snapshot_id = ? AND id >= ? AND id < ? AND kind = 'symbol'`;
+function symbolIdsOf(store, snapshotId, fileId2) {
+  const rows = store.db.prepare(SYMBOLS_OF_FILE).all(snapshotId, `${fileId2}#`, `${fileId2}$`);
+  return rows.map((r) => r.id);
+}
+function movedSymbolAliases(store, baseSnapshotId, fileAliases, nodes) {
+  const out = [];
+  for (const alias of fileAliases) {
+    if (nodes.get(alias.newId)?.kind !== "file") continue;
+    for (const oldId of symbolIdsOf(store, baseSnapshotId, alias.oldId)) {
+      const newId = alias.newId + SYMBOL_ID_SEP + oldId.slice(alias.oldId.length + 1);
+      if (nodes.get(newId)?.kind === "symbol") out.push({ oldId, newId, reason: alias.reason });
+    }
+  }
+  return out;
+}
+function renameAliases(input, baseCommit) {
+  if (input.detectRenames === false || !isInsideGitRepo(input.rootDir)) return [];
+  const target = input.commitHash ?? detectGitHead(input.rootDir) ?? void 0;
+  if (target === baseCommit) return [];
+  const pairs = detectRenames({ repoRoot: input.rootDir, fromCommit: baseCommit, toCommit: target });
+  return buildAliases(input.idRoot, pairs);
+}
+function computeAliasBridge(store, input) {
+  const base = aliasBaseFor(store, input.ref);
+  if (!base?.commitHash) return { baseSnapshotId: null, aliases: [] };
+  const fileAliases = renameAliases(input, base.commitHash);
+  const symbols = movedSymbolAliases(store, base.id, fileAliases, input.nodes);
+  return { baseSnapshotId: base.id, aliases: [...fileAliases, ...symbols] };
+}
+
 // src/generated.ts
 import { readFileSync } from "fs";
 import * as path7 from "path";
@@ -1932,17 +2244,17 @@ function ownLocalNames(fn) {
   const body = fn.childForFieldName("body");
   if (!body) return [];
   const out = [];
-  const walk = (node) => {
+  const walk2 = (node) => {
     if (FUNCTION_TYPES.has(node.type)) return;
     if (node.type === "variable_declarator") {
       const name = node.childForFieldName("name");
       if (name?.type === "identifier") out.push(name.text);
     }
     for (const child of node.namedChildren) {
-      if (child) walk(child);
+      if (child) walk2(child);
     }
   };
-  walk(body);
+  walk2(body);
   return out;
 }
 function collectBindingDecls(fn, ids, nameCount) {
@@ -1951,25 +2263,25 @@ function collectBindingDecls(fn, ids, nameCount) {
     ids.add(n.id);
     nameCount.set(n.text, (nameCount.get(n.text) ?? 0) + 1);
   };
-  const walk = (node) => {
+  const walk2 = (node) => {
     if (PARAM_TYPES.has(node.type)) mark(node.namedChild(0));
     else if (node.type === "variable_declarator") mark(node.childForFieldName("name"));
     for (const child of node.namedChildren) {
-      if (child) walk(child);
+      if (child) walk2(child);
     }
   };
-  walk(fn);
+  walk2(fn);
 }
 function countReferences(fn, declIds, out) {
-  const walk = (node) => {
+  const walk2 = (node) => {
     if ((node.type === "identifier" || node.type === "shorthand_property_identifier") && !declIds.has(node.id)) {
       out.set(node.text, (out.get(node.text) ?? 0) + 1);
     }
     for (const child of node.namedChildren) {
-      if (child) walk(child);
+      if (child) walk2(child);
     }
   };
-  walk(fn);
+  walk2(fn);
 }
 
 // src/analysis/growth-risk.ts
@@ -2650,7 +2962,7 @@ function qualifiedByName(file) {
 }
 
 // src/indexer.ts
-var INDEX_VERSION = "0.14.0";
+var INDEX_VERSION = "0.15.0";
 var LANGUAGES = ["typescript", "python"];
 function canonicalizePath(p) {
   try {
@@ -2668,26 +2980,16 @@ function countByKind(items) {
   for (const item of items) out[item.kind] = (out[item.kind] ?? 0) + 1;
   return out;
 }
-function persist(store, ref, commitHash, accumulator, aliases, metrics) {
-  const snapshotId = store.createSnapshot({ ref, commitHash, indexVersion: INDEX_VERSION });
+function persist(store, snapshot, accumulator, aliases, metrics) {
+  const { ref, commitHash, aliasBase } = snapshot;
+  const attrs = { [ALIAS_BASE_ATTR]: aliasBase };
+  const snapshotId = store.createSnapshot({ ref, commitHash, indexVersion: INDEX_VERSION, attrs });
   store.insertNodes(snapshotId, [...accumulator.nodes.values()]);
   store.insertEdges(snapshotId, [...accumulator.edges.values()]);
   if (aliases.length > 0) store.insertAliases(snapshotId, aliases);
   if (metrics.length > 0) store.insertMetrics(snapshotId, metrics);
   return snapshotId;
 }
-function findPriorCommit(store) {
-  return store.listSnapshots({ limit: 50 }).find((s) => s.commitHash)?.commitHash ?? null;
-}
-function resolveAliases(rootDir, idRoot, options, store) {
-  if (options.detectRenames === false) return [];
-  if (!isInsideGitRepo(rootDir)) return [];
-  const priorCommit = findPriorCommit(store);
-  if (!priorCommit) return [];
-  const target = options.commitHash ?? detectGitHead(rootDir) ?? void 0;
-  if (target === priorCommit) return [];
-  return buildAliases(idRoot, detectRenames({ repoRoot: rootDir, fromCommit: priorCommit, toCommit: target }));
-}
 function resolveSymbolAliases(store, idRoot, parsedByPath, nodeIds) {
   const prior = store.listSnapshots({ limit: 1 })[0];
   if (!prior || !predatesQualifiedSymbols(prior.indexVersion)) return [];
@@ -2745,12 +3047,15 @@ async function indexPaths(store, options) {
     history: options.computeChurn === false ? void 0 : historyOptions(options)
   });
   const rootDir = rootDirs[0];
+  const ref = options.ref ?? "wd";
+  const bridge = computeAliasBridge(store, { ...options, rootDir, idRoot, ref, nodes: accumulator.nodes });
   const aliases = [
-    ...resolveAliases(rootDir, idRoot, options, store),
+    ...bridge.aliases,
     ...resolveSymbolAliases(store, idRoot, parsedByPath, new Set(accumulator.nodes.keys()))
   ];
   const commitHash = options.commitHash ?? detectGitHead(rootDir) ?? void 0;
-  const snapshotId = persist(store, options.ref ?? "wd", commitHash, accumulator, aliases, metrics);
+  const snapshot = { ref, commitHash, aliasBase: bridge.baseSnapshotId };
+  const snapshotId = persist(store, snapshot, accumulator, aliases, metrics);
   store.insertFingerprints(snapshotId, buildFingerprints(readFiles, idRoot, classified.structuralByFileId));
   return {
     snapshotId,
@@ -2770,6 +3075,143 @@ async function indexPaths(store, options) {
 // src/index.ts
 import { getLanguageFromPath as getLanguageFromPath3, getSupportedLanguages, parseFile as parseFile2, shouldIncludeFile as shouldIncludeFile2 } from "@titan-design/code-parser";
 
+// src/extractors/deep-ast.ts
+import { readFileSync as readFileSync2 } from "fs";
+import * as path10 from "path";
+import {
+  Node as Node4,
+  Project as Project2,
+  ScriptTarget as ScriptTarget2
+} from "ts-morph";
+function computeDeepAst(input) {
+  const sf = loadSourceFile(input.absPath);
+  if (!sf) return null;
+  const target = input.symbolName ? `${input.filePath}#${input.symbolName}` : input.filePath;
+  return input.symbolName ? symbolDeepAst(sf, input.symbolName, target) : fileDeepAst(sf, target);
+}
+function loadSourceFile(absPath) {
+  try {
+    const text = readFileSync2(absPath, "utf8");
+    const project = new Project2({
+      useInMemoryFileSystem: true,
+      compilerOptions: { target: ScriptTarget2.Latest, allowJs: true }
+    });
+    return project.createSourceFile(`f${path10.extname(absPath) || ".ts"}`, text);
+  } catch {
+    return null;
+  }
+}
+function symbolDeepAst(sf, name, target) {
+  const decl = lookupDeclaration(sf, name);
+  if (!decl) {
+    return { ...empty(target, "symbol"), note: "declaration not found in source" };
+  }
+  const text = declarationText(decl);
+  return {
+    target,
+    kind: "symbol",
+    declarationKind: decl.getKindName(),
+    signature: text.signature ?? null,
+    purpose: text.purpose ?? null,
+    params: paramsOf(decl),
+    returnType: returnTypeOf(decl),
+    members: membersOf(decl)
+  };
+}
+function fileDeepAst(sf, target) {
+  return {
+    ...empty(target, "file"),
+    declarationKind: "SourceFile",
+    members: exportedDeclarations(sf)
+  };
+}
+function empty(target, kind) {
+  return {
+    target,
+    kind,
+    declarationKind: null,
+    signature: null,
+    purpose: null,
+    params: [],
+    returnType: null,
+    members: []
+  };
+}
+function callableOf(decl) {
+  if (Node4.isFunctionDeclaration(decl) || Node4.isMethodDeclaration(decl)) return decl;
+  if (Node4.isVariableDeclaration(decl)) {
+    const init = decl.getInitializer();
+    if (init && (Node4.isArrowFunction(init) || Node4.isFunctionExpression(init))) return init;
+  }
+  return null;
+}
+function paramsOf(decl) {
+  const callable = callableOf(decl);
+  if (!callable) return [];
+  return callable.getParameters().map((p) => ({
+    name: p.getName(),
+    type: p.getTypeNode()?.getText() ?? null
+  }));
+}
+function returnTypeOf(decl) {
+  return callableOf(decl)?.getReturnTypeNode()?.getText() ?? null;
+}
+function membersOf(decl) {
+  if (Node4.isClassDeclaration(decl)) return classMembers(decl);
+  if (Node4.isInterfaceDeclaration(decl)) return interfaceMembers(decl);
+  return [];
+}
+function classMembers(cls) {
+  return cls.getMembers().map((m) => ({
+    name: memberName(m),
+    memberKind: m.getKindName(),
+    signature: memberSignature(m),
+    isStatic: Node4.isStaticable(m) ? m.isStatic() : false
+  }));
+}
+function interfaceMembers(iface) {
+  return iface.getMembers().map((m) => ({
+    name: memberName(m),
+    memberKind: m.getKindName(),
+    signature: memberSignature(m),
+    isStatic: false
+  }));
+}
+function exportedDeclarations(sf) {
+  const out = [];
+  for (const [name, decls] of sf.getExportedDeclarations()) {
+    const decl = decls[0];
+    if (!decl) continue;
+    out.push({
+      name,
+      memberKind: decl.getKindName(),
+      signature: declarationText(decl).signature ?? memberSignature(decl),
+      isStatic: false
+    });
+  }
+  return out;
+}
+function memberName(m) {
+  if (Node4.isConstructorDeclaration(m)) return "constructor";
+  return Node4.hasName(m) ? m.getName() : "";
+}
+function memberSignature(m) {
+  if (Node4.isMethodDeclaration(m) || Node4.isMethodSignature(m) || Node4.isConstructorDeclaration(m)) {
+    const params = m.getParameters().map((p) => oneLine2(p.getText())).join(", ");
+    const ret = m.getReturnTypeNode()?.getText();
+    const name = Node4.isConstructorDeclaration(m) ? "constructor" : memberName(m);
+    return oneLine2(`${name}(${params})${ret ? `: ${ret}` : ""}`);
+  }
+  if (Node4.isPropertyDeclaration(m) || Node4.isPropertySignature(m)) {
+    const type = m.getTypeNode()?.getText();
+    return oneLine2(`${memberName(m)}${type ? `: ${type}` : ""}`);
+  }
+  return null;
+}
+function oneLine2(s) {
+  return s.replace(/\s+/g, " ").trim();
+}
+
 // src/aliases.ts
 var METRIC_ALIASES = /* @__PURE__ */ new Map([
   ["lines", "loc"],
@@ -3121,6 +3563,199 @@ function comparePairs(a, b) {
   return a.bId < b.bId ? -1 : a.bId > b.bId ? 1 : 0;
 }
 
+// src/analysis/partition-quality.ts
+var FOUNDATION_INSTABILITY_MAX = 0.3;
+var TOP_INSTABILITY_MIN = 0.9;
+var WEAK_COHESION_MAX = 0.5;
+var TIGHT_INTENSITY_MIN = 0.6;
+var MODERATE_INTENSITY_MIN = 0.3;
+function computePartitionQuality(input) {
+  const resolveBarrels = input.resolveBarrels ?? false;
+  const pkgByFile = invertBuckets(input.fileByPackage);
+  const barrelTargets = resolveBarrels ? buildBarrelTargetMap(input.nodes, input.edges) : /* @__PURE__ */ new Map();
+  const resolvedPairs = buildResolvedPairs(
+    input.edges,
+    pkgByFile,
+    barrelTargets,
+    resolveBarrels
+  );
+  const counts = countByPackage(resolvedPairs);
+  const totalEdges = resolvedPairs.length;
+  const filesByPkg = filesPerPackage(input.fileByPackage);
+  const abstractByPkg = countAbstractFiles(input.nodes, pkgByFile);
+  const perPackage = input.packages.map(
+    (p) => buildPackageStats(p.id, counts, filesByPkg, abstractByPkg)
+  );
+  const pairCoupling = buildPairCoupling(resolvedPairs, filesByPkg);
+  const modularityQ = computeModularity(perPackage, totalEdges);
+  const flagsCount = perPackage.reduce((acc, p) => acc + p.flags.length, 0) + pairCoupling.filter((c) => c.flag === "tight").length;
+  return { modularityQ, totalEdges, perPackage, pairCoupling, flagsCount };
+}
+function invertBuckets(fileByPackage) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [pkgId, files] of fileByPackage) {
+    if (pkgId === "") continue;
+    for (const f of files) out.set(f, pkgId);
+  }
+  return out;
+}
+function filesPerPackage(fileByPackage) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [pkgId, files] of fileByPackage) {
+    out.set(pkgId, files.length);
+  }
+  return out;
+}
+function buildBarrelTargetMap(nodes, edges) {
+  const barrelIds = new Set(
+    nodes.filter((n) => n.role === "barrel").map((n) => n.id)
+  );
+  if (barrelIds.size === 0) return /* @__PURE__ */ new Map();
+  const directReExports = /* @__PURE__ */ new Map();
+  for (const e of edges) {
+    if (!barrelIds.has(e.srcId)) continue;
+    if (e.kind !== "re-exports") continue;
+    let list = directReExports.get(e.srcId);
+    if (!list) {
+      list = [];
+      directReExports.set(e.srcId, list);
+    }
+    list.push(e.dstId);
+  }
+  const resolved = /* @__PURE__ */ new Map();
+  const resolve4 = (barrel, visiting) => {
+    if (resolved.has(barrel)) return resolved.get(barrel);
+    if (visiting.has(barrel)) return [];
+    visiting.add(barrel);
+    const out = [];
+    for (const target of directReExports.get(barrel) ?? []) {
+      if (barrelIds.has(target)) {
+        for (const inner of resolve4(target, visiting)) out.push(inner);
+      } else {
+        out.push(target);
+      }
+    }
+    visiting.delete(barrel);
+    resolved.set(barrel, out);
+    return out;
+  };
+  for (const id of barrelIds) resolve4(id, /* @__PURE__ */ new Set());
+  return resolved;
+}
+function buildResolvedPairs(edges, pkgByFile, barrelTargets, resolveBarrels) {
+  const out = [];
+  for (const e of edges) {
+    if (resolveBarrels && e.kind === "re-exports") continue;
+    const fromPkg = pkgByFile.get(e.srcId);
+    if (!fromPkg) continue;
+    const targets = barrelTargets.get(e.dstId) ?? [e.dstId];
+    for (const dst of targets) {
+      const toPkg = pkgByFile.get(dst);
+      if (toPkg) out.push({ from: fromPkg, to: toPkg });
+    }
+  }
+  return out;
+}
+function countByPackage(pairs) {
+  const out = /* @__PURE__ */ new Map();
+  const get = (id) => {
+    let c = out.get(id);
+    if (!c) {
+      c = { internal: 0, outgoing: 0, incoming: 0 };
+      out.set(id, c);
+    }
+    return c;
+  };
+  for (const p of pairs) {
+    if (p.from === p.to) {
+      get(p.from).internal += 1;
+    } else {
+      get(p.from).outgoing += 1;
+      get(p.to).incoming += 1;
+    }
+  }
+  return out;
+}
+function buildPackageStats(pkgId, counts, filesByPkg, abstractByPkg) {
+  const c = counts.get(pkgId) ?? { internal: 0, outgoing: 0, incoming: 0 };
+  const cohesion = ratioOrZero(c.internal, c.internal + c.outgoing);
+  const instability = ratioOrZero(c.outgoing, c.outgoing + c.incoming);
+  const fileCount = filesByPkg.get(pkgId) ?? 0;
+  const abstractness = ratioOrZero(abstractByPkg.get(pkgId) ?? 0, fileCount);
+  const layer = classifyLayer(instability);
+  const flags = [];
+  if (layer !== "top" && cohesion < WEAK_COHESION_MAX && c.internal + c.outgoing > 0) {
+    flags.push("weak-boundary");
+  }
+  return {
+    pkgId,
+    fileCount,
+    internalEdges: c.internal,
+    outgoingEdges: c.outgoing,
+    incomingEdges: c.incoming,
+    cohesion,
+    instability,
+    abstractness,
+    layer,
+    flags
+  };
+}
+function countAbstractFiles(nodes, pkgByFile) {
+  const out = /* @__PURE__ */ new Map();
+  for (const n of nodes) {
+    if (n.kind !== "file" || n.role !== "types") continue;
+    const pkg = pkgByFile.get(n.id);
+    if (pkg) out.set(pkg, (out.get(pkg) ?? 0) + 1);
+  }
+  return out;
+}
+function ratioOrZero(num, denom) {
+  return denom === 0 ? 0 : num / denom;
+}
+function classifyLayer(instability) {
+  if (instability <= FOUNDATION_INSTABILITY_MAX) return "foundation";
+  if (instability >= TOP_INSTABILITY_MIN) return "top";
+  return "middle";
+}
+function buildPairCoupling(pairs, filesByPkg) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const p of pairs) {
+    if (p.from === p.to) continue;
+    const key = JSON.stringify([p.from, p.to]);
+    const entry = counts.get(key);
+    if (entry) entry.edges += 1;
+    else counts.set(key, { from: p.from, to: p.to, edges: 1 });
+  }
+  const out = [];
+  for (const { from, to, edges } of counts.values()) {
+    const filesFrom = filesByPkg.get(from) ?? 0;
+    const intensity = filesFrom === 0 ? 0 : edges / filesFrom;
+    const flag = classifyPairIntensity(intensity);
+    out.push({ from, to, edges, intensity, flag });
+  }
+  return out.sort(comparePairs2);
+}
+function classifyPairIntensity(intensity) {
+  if (intensity >= TIGHT_INTENSITY_MIN) return "tight";
+  if (intensity >= MODERATE_INTENSITY_MIN) return "moderate";
+  return "none";
+}
+function comparePairs2(a, b) {
+  if (a.from !== b.from) return a.from < b.from ? -1 : 1;
+  return a.to < b.to ? -1 : 1;
+}
+function computeModularity(perPackage, totalEdges) {
+  if (totalEdges === 0) return 0;
+  let Q = 0;
+  for (const p of perPackage) {
+    const e_cc = p.internalEdges / totalEdges;
+    const touching = p.internalEdges * 2 + p.outgoingEdges + p.incomingEdges;
+    const a_c = touching / (2 * totalEdges);
+    Q += e_cc - a_c * a_c;
+  }
+  return Q;
+}
+
 // src/analysis/snapshot.ts
 function snapshotPageRank(store, snapshotId, options = {}) {
   return computePageRank(store.listNodes(snapshotId), store.listEdges(snapshotId), options);
@@ -3148,6 +3783,397 @@ function listEdges(store, snapshotId, opts) {
 function listMetrics(store, snapshotId) {
   return store.listMetrics(snapshotId);
 }
+function listMetricsForNode(store, snapshotId, nodeId) {
+  return store.listMetricsForNode(snapshotId, nodeId);
+}
+function listEdgesTouching(store, snapshotId, nodeId, opts) {
+  return store.listEdgesTouching(snapshotId, nodeId, opts);
+}
+function aggregateMetrics(store, snapshotId, opts) {
+  return store.aggregateMetrics(snapshotId, opts);
+}
+
+// src/catalogue/entries.ts
+var FILE = ["file"];
+var SYMBOL = ["symbol"];
+var STRUCTURAL = ["file", "module", "external"];
+var DEGREE = [
+  {
+    name: "fan_in",
+    unit: "count",
+    appliesTo: STRUCTURAL,
+    rollup: "none",
+    direction: "neutral",
+    absent: "zero",
+    source: "degree",
+    description: "Import and re-export edges into the node. Summing over a group would count its internal edges."
+  },
+  {
+    name: "fan_out",
+    unit: "count",
+    appliesTo: STRUCTURAL,
+    rollup: "none",
+    direction: "higher-worse",
+    absent: "zero",
+    source: "degree",
+    description: "Import and re-export edges out of the node. Summing over a group would count its internal edges."
+  },
+  {
+    name: "instability",
+    unit: "ratio",
+    appliesTo: STRUCTURAL,
+    rollup: "none",
+    direction: "neutral",
+    absent: "exclude",
+    source: "degree",
+    description: "fan_out / (fan_in + fan_out); written only when the node has an import edge."
+  },
+  {
+    name: "utilization",
+    unit: "count",
+    appliesTo: [...STRUCTURAL, "symbol"],
+    rollup: "none",
+    direction: "neutral",
+    absent: "zero",
+    source: "degree",
+    description: "Inbound edges weighted by reference count over the barrel-resolved graph: how heavily a node is used."
+  }
+];
+var SOURCE = [
+  {
+    name: "loc",
+    unit: "lines",
+    appliesTo: FILE,
+    rollup: "sum",
+    direction: "higher-worse",
+    absent: "zero",
+    source: "source-metrics",
+    description: "Non-blank lines in the file."
+  },
+  {
+    name: "function_count",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "sum",
+    direction: "neutral",
+    absent: "zero",
+    source: "source-metrics",
+    description: "Functions, methods, and arrow functions declared in the file."
+  },
+  {
+    name: "cyclomatic_max",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "max",
+    direction: "higher-worse",
+    absent: "exclude",
+    source: "source-metrics",
+    description: "Highest cyclomatic complexity of any function in the file."
+  },
+  {
+    name: "cyclomatic_sum",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "sum",
+    direction: "higher-worse",
+    absent: "zero",
+    source: "source-metrics",
+    description: "Cyclomatic complexity summed over the file's functions."
+  },
+  {
+    name: "cognitive_max",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "max",
+    direction: "higher-worse",
+    absent: "exclude",
+    source: "source-metrics",
+    description: "Highest cognitive complexity of any function in the file."
+  },
+  {
+    name: "cognitive_sum",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "sum",
+    direction: "higher-worse",
+    absent: "zero",
+    source: "source-metrics",
+    description: "Cognitive complexity summed over the file's functions."
+  },
+  {
+    name: "max_nesting_depth",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "max",
+    direction: "higher-worse",
+    absent: "exclude",
+    source: "source-metrics",
+    description: "Deepest block nesting inside any function in the file."
+  },
+  {
+    name: "symbol_cognitive",
+    unit: "count",
+    appliesTo: SYMBOL,
+    rollup: "max",
+    direction: "higher-worse",
+    absent: "exclude",
+    source: "source-metrics",
+    description: "Cognitive complexity of the function a symbol names; the max when several functions share the name."
+  },
+  {
+    name: "symbol_cyclomatic",
+    unit: "count",
+    appliesTo: SYMBOL,
+    rollup: "max",
+    direction: "higher-worse",
+    absent: "exclude",
+    source: "source-metrics",
+    description: "Cyclomatic complexity of the function a symbol names; the max when several functions share the name."
+  },
+  {
+    name: "class_count",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "sum",
+    direction: "neutral",
+    absent: "zero",
+    source: "lcom",
+    description: "Classes declared in the file; written only when there is one."
+  },
+  {
+    name: "lcom4_max",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "max",
+    direction: "higher-worse",
+    absent: "exclude",
+    source: "lcom",
+    description: "Highest LCOM4 of any class in the file; above 1 means the class could split."
+  }
+];
+var SMELLS = [
+  {
+    name: "unreachable_statements",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "sum",
+    direction: "higher-worse",
+    absent: "zero",
+    source: "dead-code",
+    description: "Statements after an unconditional return, throw, break, or continue. TypeScript only."
+  },
+  {
+    name: "unused_locals",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "sum",
+    direction: "higher-worse",
+    absent: "zero",
+    source: "dead-code",
+    description: "Local bindings never read. TypeScript only."
+  },
+  {
+    name: "unused_params",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "sum",
+    direction: "higher-worse",
+    absent: "zero",
+    source: "dead-code",
+    description: "Trailing parameters never read. TypeScript only."
+  },
+  {
+    name: "loop_depth",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "max",
+    direction: "higher-worse",
+    absent: "zero",
+    source: "growth-risk",
+    description: "Deepest lexical loop nesting; written at 2 or more."
+  },
+  {
+    name: "recursive_functions",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "sum",
+    direction: "higher-worse",
+    absent: "zero",
+    source: "growth-risk",
+    description: "Functions that call themselves by name. TypeScript only."
+  },
+  {
+    name: "search_in_loop",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "sum",
+    direction: "higher-worse",
+    absent: "zero",
+    source: "growth-risk",
+    description: "Linear searches such as .includes or .find inside a loop. TypeScript only."
+  }
+];
+var HISTORY = [
+  {
+    name: "churn_{w}",
+    unit: "lines",
+    appliesTo: FILE,
+    rollup: "sum",
+    direction: "neutral",
+    absent: "zero",
+    source: "history",
+    windowed: true,
+    description: "Lines added plus deleted in the {w} window."
+  },
+  {
+    name: "churn_{w}_commits",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "none",
+    direction: "neutral",
+    absent: "zero",
+    source: "history",
+    windowed: true,
+    description: "Commits touching the file in the {w} window. A group's distinct commits are not the sum."
+  },
+  {
+    name: "churn_{w}_authors",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "none",
+    direction: "neutral",
+    absent: "zero",
+    source: "history",
+    windowed: true,
+    description: "Distinct authors of the file's commits in the {w} window. Not additive."
+  },
+  {
+    name: "recency_{w}",
+    unit: "ratio",
+    appliesTo: FILE,
+    rollup: "none",
+    direction: "neutral",
+    absent: "exclude",
+    source: "history",
+    windowed: true,
+    description: "min(1, file age / window) for a file that churned in the {w} window; 1 for lifetime. A hotspot discount."
+  },
+  {
+    name: "file_age_days",
+    unit: "days",
+    appliesTo: FILE,
+    rollup: "max",
+    direction: "neutral",
+    absent: "exclude",
+    source: "history",
+    description: "Days since the file first appeared in git history."
+  },
+  {
+    name: "bus_factor_{w}",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "none",
+    direction: "lower-worse",
+    absent: "exclude",
+    source: "history",
+    windowed: true,
+    description: "Fewest authors covering half the file's churn in the {w} window."
+  },
+  {
+    name: "top_author_share_{w}",
+    unit: "ratio",
+    appliesTo: FILE,
+    rollup: "none",
+    direction: "higher-worse",
+    absent: "exclude",
+    source: "history",
+    windowed: true,
+    description: "Share of the file's churn in the {w} window written by its top author."
+  }
+];
+var TESTS = [
+  {
+    name: "linked_test_count",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "none",
+    direction: "lower-worse",
+    absent: "zero",
+    source: "test-linker",
+    description: "Test files linked to this source. One test can link to several sources, so it does not sum."
+  },
+  {
+    name: "test_bus_factor_{w}",
+    unit: "count",
+    appliesTo: FILE,
+    rollup: "none",
+    direction: "lower-worse",
+    absent: "exclude",
+    source: "test-linker",
+    windowed: true,
+    description: "Bus factor of the churn on this source's linked tests in the {w} window."
+  },
+  {
+    name: "test_top_author_share_{w}",
+    unit: "ratio",
+    appliesTo: FILE,
+    rollup: "none",
+    direction: "higher-worse",
+    absent: "exclude",
+    source: "test-linker",
+    windowed: true,
+    description: "Top author's share of the churn on this source's linked tests in the {w} window."
+  },
+  {
+    name: "coverage_pct",
+    unit: "percent",
+    appliesTo: ["file", "symbol"],
+    rollup: "none",
+    direction: "lower-worse",
+    absent: "exclude",
+    source: "coverage",
+    description: "Functions covered over functions total, from an ingested Istanbul report. Never written by the indexer."
+  }
+];
+var METRIC_CATALOGUE = [...DEGREE, ...SOURCE, ...SMELLS, ...HISTORY, ...TESTS];
+
+// src/catalogue/describe.ts
+var WINDOW_TOKEN = "{w}";
+var WINDOW_PATTERN = "(\\d+d|lifetime)";
+var BY_NAME = new Map(METRIC_CATALOGUE.filter((d) => !d.windowed).map((d) => [d.name, d]));
+var WINDOWED = METRIC_CATALOGUE.filter((d) => d.windowed).map((template) => ({
+  pattern: new RegExp(`^${template.name.replace(WINDOW_TOKEN, WINDOW_PATTERN)}$`),
+  template
+}));
+function resolveWindow(template, window) {
+  const resolved = {
+    ...template,
+    name: template.name.replace(WINDOW_TOKEN, window),
+    description: template.description.replace(WINDOW_TOKEN, window),
+    window
+  };
+  delete resolved.windowed;
+  return resolved;
+}
+function describeMetric(name) {
+  const exact = BY_NAME.get(name);
+  if (exact) return exact;
+  for (const { pattern, template } of WINDOWED) {
+    const match = pattern.exec(name);
+    if (match) return resolveWindow(template, match[1]);
+  }
+  return null;
+}
+function describeMetrics(names) {
+  const described = [];
+  const unknown = [];
+  for (const name of new Set(names)) {
+    const descriptor = describeMetric(name);
+    if (descriptor) described.push(descriptor);
+    else unknown.push(name);
+  }
+  return { described, unknown };
+}
 
 // src/check/context.ts
 function buildRuleContext(store, snapshotId) {
@@ -3430,7 +4456,7 @@ function runChecks(store, options) {
     violations.push(...runRule(rule, ctx));
   }
   if (options.baselineSnapshotId) {
-    const baselineKeys = collectBaselineKeys(store, options.baselineSnapshotId, options.rules);
+    const baselineKeys = collectBaselineKeys(store, options.baselineSnapshotId, options.snapshotId, options.rules);
     for (const v of violations) {
       if (baselineKeys.has(violationKey(v))) v.isCarryover = true;
     }
@@ -3446,17 +4472,26 @@ function runChecks(store, options) {
     passed: counts.newErrors === 0
   };
 }
-function collectBaselineKeys(store, baselineSnapshotId, rules) {
+function snapshotViolations(store, snapshotId, rules) {
+  const ctx = buildRuleContext(store, snapshotId);
+  return rules.flatMap((rule) => runRule(rule, ctx));
+}
+function collectBaselineKeys(store, baselineSnapshotId, snapshotId, rules) {
   const ctx = buildRuleContext(store, baselineSnapshotId);
+  const chain = aliasChain(store, baselineSnapshotId, snapshotId);
   const keys = /* @__PURE__ */ new Set();
   for (const rule of rules) {
-    for (const v of runRule(rule, ctx)) keys.add(violationKey(v));
+    for (const v of runRule(rule, ctx)) keys.add(rebasedViolationKey(v, chain.resolve));
   }
   return keys;
 }
 function violationKey(v) {
   return v.destinationId ? `${v.ruleId}|${v.nodeId}|${v.destinationId}` : `${v.ruleId}|${v.nodeId}`;
 }
+function rebasedViolationKey(v, resolve4) {
+  const destinationId = v.destinationId ? resolve4(v.destinationId) : v.destinationId;
+  return violationKey({ ...v, nodeId: resolve4(v.nodeId), destinationId });
+}
 function countByOriginAndSeverity(violations) {
   const counts = { newErrors: 0, newWarnings: 0, carryoverErrors: 0, carryoverWarnings: 0 };
   for (const v of violations) {
@@ -3688,18 +4723,18 @@ function checkSnapshot(store, options) {
   });
   return { snapshot, baselineSnapshot, result };
 }
-async function loadCheckRules(path10, options = {}) {
+async function loadCheckRules(path12, options = {}) {
   let raw;
   try {
-    raw = await readFile2(path10, "utf8");
+    raw = await readFile2(path12, "utf8");
   } catch (err) {
-    throw new Error(`Cannot read rules file at ${path10}: ${errorMessage(err)}`);
+    throw new Error(`Cannot read rules file at ${path12}: ${errorMessage(err)}`);
   }
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch (err) {
-    throw new Error(`Invalid JSON in ${path10}: ${errorMessage(err)}`);
+    throw new Error(`Invalid JSON in ${path12}: ${errorMessage(err)}`);
   }
   return validateRules(parsed, options);
 }
@@ -3708,13 +4743,8 @@ function errorMessage(err) {
 }
 
 // src/diff/diff.ts
-function aliasMap(aliases) {
-  const m = /* @__PURE__ */ new Map();
-  for (const a of aliases) m.set(a.oldId, a);
-  return m;
-}
 function resolveId(id, aliases) {
-  return aliases.get(id)?.newId ?? id;
+  return aliases.resolve(id);
 }
 function edgeKey2(srcId, dstId, kind) {
   return JSON.stringify([srcId, dstId, canonicalEdgeKind(kind)]);
@@ -3741,7 +4771,7 @@ function diffNodes(fromNodes, toNodes, aliases) {
     }
     matchedToIds.add(newId);
     if (newId !== fromNode.id) {
-      renamed.push({ oldId: fromNode.id, newId, reason: aliases.get(fromNode.id).reason, node: toNode });
+      renamed.push({ oldId: fromNode.id, newId, reason: aliases.trace(fromNode.id).reason, node: toNode });
     }
   }
   const added = toNodes.filter((toNode) => !matchedToIds.has(toNode.id));
@@ -3792,7 +4822,7 @@ function diffMetrics(fromMetrics, toMetrics, aliases, commonNewIds) {
 }
 function diffSnapshots(store, options) {
   const { fromSnapshotId, toSnapshotId } = options;
-  const aliases = aliasMap(store.listAliases(toSnapshotId));
+  const aliases = aliasChain(store, fromSnapshotId, toSnapshotId);
   const nodeDiff = diffNodes(store.listNodes(fromSnapshotId), store.listNodes(toSnapshotId), aliases);
   const edgeDiff = diffEdges(store.listEdges(fromSnapshotId), store.listEdges(toSnapshotId), aliases);
   const metricDeltas = diffMetrics(
@@ -3829,11 +4859,12 @@ function summarize({ fromSnapshotId, toSnapshotId }, nodeDiff, edgeDiff, metricD
 function diffCheckResults(store, options) {
   const from = runChecks(store, { snapshotId: options.fromSnapshotId, rules: options.rules });
   const to = runChecks(store, { snapshotId: options.toSnapshotId, rules: options.rules });
+  const chain = aliasChain(store, options.fromSnapshotId, options.toSnapshotId);
   return {
     fromSnapshotId: options.fromSnapshotId,
     toSnapshotId: options.toSnapshotId,
     rulesEvaluated: options.rules.length,
-    ...bucketViolations(indexByKey(from.violations), indexByKey(to.violations))
+    ...bucketViolations(indexByKey(from.violations, chain.resolve), indexByKey(to.violations))
   };
 }
 function bucketViolations(fromByKey, toByKey) {
@@ -3855,9 +4886,9 @@ function bucketViolations(fromByKey, toByKey) {
   }
   return buckets;
 }
-function indexByKey(violations) {
+function indexByKey(violations, resolve4) {
   const out = /* @__PURE__ */ new Map();
-  for (const v of violations) out.set(violationKey(v), v);
+  for (const v of violations) out.set(resolve4 ? rebasedViolationKey(v, resolve4) : violationKey(v), v);
   return out;
 }
 function computeDelta(from, to) {
@@ -4006,29 +5037,348 @@ function buildSymbolIndex(store, model, symbols) {
 function toCandidate(s, score) {
   return { id: s.id, name: s.name, file: s.file, signature: s.signature, purpose: s.purpose, score };
 }
+
+// src/conventions/communities.ts
+function detectCommunities(fileIds, edges, opts) {
+  const nodeSet = new Set(fileIds);
+  const adj = buildUndirectedAdjacency(edges, nodeSet);
+  const communityOf = greedyModularity(fileIds, adj, opts);
+  const out = /* @__PURE__ */ new Map();
+  for (const f of fileIds) pushMulti(out, communityOf.get(f) ?? f, f);
+  return out;
+}
+function buildUndirectedAdjacency(edges, nodeSet) {
+  const adj = /* @__PURE__ */ new Map();
+  const link = (a, b) => {
+    let row = adj.get(a);
+    if (!row) {
+      row = /* @__PURE__ */ new Map();
+      adj.set(a, row);
+    }
+    row.set(b, (row.get(b) ?? 0) + 1);
+  };
+  for (const e of edges) {
+    if (e.srcId === e.dstId) continue;
+    if (!nodeSet.has(e.srcId) || !nodeSet.has(e.dstId)) continue;
+    link(e.srcId, e.dstId);
+    link(e.dstId, e.srcId);
+  }
+  return adj;
+}
+function greedyModularity(nodes, adj, opts) {
+  const state = initCommunities(nodes, adj);
+  if (state.twoM === 0) return new Map(nodes.map((n) => [n, n]));
+  for (; ; ) {
+    const coarsen = opts?.targetCount !== void 0 && state.members.size > opts.targetCount;
+    const best = bestMerge(state, coarsen, opts?.maxSize);
+    if (!best) break;
+    applyMerge(state, best.i, best.j);
+  }
+  return communityLabels(state);
+}
+function initCommunities(nodes, adj) {
+  const members = /* @__PURE__ */ new Map();
+  const deg = /* @__PURE__ */ new Map();
+  const between = /* @__PURE__ */ new Map();
+  let twoM = 0;
+  for (const n of nodes) {
+    const row = /* @__PURE__ */ new Map();
+    let d = 0;
+    for (const [k, w] of adj.get(n) ?? []) {
+      row.set(k, w);
+      d += w;
+    }
+    members.set(n, [n]);
+    deg.set(n, d);
+    between.set(n, row);
+    twoM += d;
+  }
+  return { members, deg, between, twoM };
+}
+function bestMerge(state, allowNegative, maxSize) {
+  const { members, between, deg, twoM } = state;
+  let best = null;
+  for (const [i, row] of between) {
+    for (const [j, eij] of row) {
+      if (i >= j) continue;
+      if (maxSize !== void 0 && members.get(i).length + members.get(j).length > maxSize) {
+        continue;
+      }
+      const dQ = 2 * eij / twoM - 2 * deg.get(i) * deg.get(j) / (twoM * twoM);
+      if (!allowNegative && dQ <= 1e-12) continue;
+      if (best === null || dQ > best.dQ) best = { i, j, dQ };
+    }
+  }
+  return best;
+}
+function applyMerge(state, i, j) {
+  const { members, deg, between } = state;
+  members.get(i).push(...members.get(j));
+  members.delete(j);
+  deg.set(i, deg.get(i) + deg.get(j));
+  deg.delete(j);
+  const rowI = between.get(i);
+  for (const [k, w] of between.get(j)) {
+    if (k === i) continue;
+    rowI.set(k, (rowI.get(k) ?? 0) + w);
+    const rowK = between.get(k);
+    rowK.set(i, (rowK.get(i) ?? 0) + w);
+    rowK.delete(j);
+  }
+  rowI.delete(j);
+  between.delete(j);
+}
+function communityLabels(state) {
+  const out = /* @__PURE__ */ new Map();
+  const reps = [...state.members.keys()].sort();
+  reps.forEach((rep, idx) => {
+    for (const n of state.members.get(rep)) out.set(n, `c${idx}`);
+  });
+  return out;
+}
+function pushMulti(map, key, value) {
+  let list = map.get(key);
+  if (!list) {
+    list = [];
+    map.set(key, list);
+  }
+  list.push(value);
+}
+
+// src/conventions/areas.ts
+import * as path11 from "path";
+import { contentHashOf as contentHashOf2 } from "@titan-design/store-sqlite";
+var DEFAULT_MIN_SIZE = 3;
+var PROMPT_FILE_CAP = 30;
+var PROMPT_SYMBOL_CAP = 15;
+function defaultTargetCount(fileCount) {
+  return Math.min(40, Math.max(6, Math.ceil(fileCount / 25)));
+}
+function buildConventionAreas(store, snapshotId, opts) {
+  const nodes = store.listNodes(snapshotId, { includeSymbols: true });
+  const { files, edges } = resolvedFileGraph(store, snapshotId, nodes);
+  const symbolsByFile = collectExportedSymbols(nodes);
+  const areas = [];
+  const prompts = /* @__PURE__ */ new Map();
+  for (const members of partitionFiles(files, edges, opts)) {
+    const { area, prompt } = buildArea(members, edges, symbolsByFile);
+    areas.push(area);
+    prompts.set(area.contentHash, prompt);
+  }
+  const grouped = areas.reduce((s, a) => s + a.size, 0);
+  return { areas, prompts, coverage: { files: files.length, grouped, areas: areas.length, summarized: 0 } };
+}
+function resolvedFileGraph(store, snapshotId, nodes) {
+  const files = nodes.filter((n) => n.kind === "file" && n.role !== "generated").map((n) => n.id).sort();
+  const fileSet = new Set(files);
+  const edges = resolveBarrelEdges(nodes, store.listEdges(snapshotId)).filter(
+    (e) => e.srcId !== e.dstId && fileSet.has(e.srcId) && fileSet.has(e.dstId)
+  );
+  return { files, edges };
+}
+function partitionFiles(files, edges, opts) {
+  const target = opts?.targetCount ?? defaultTargetCount(files.length);
+  const minSize = opts?.minSize ?? DEFAULT_MIN_SIZE;
+  const maxSize = Math.max(minSize * 2, Math.ceil(files.length / target * 2));
+  return [...detectCommunities(files, edges, { targetCount: target, maxSize }).values()].filter((members) => members.length >= minSize).sort(bySizeThenFirstFile);
+}
+function bySizeThenFirstFile(a, b) {
+  if (a.length !== b.length) return b.length - a.length;
+  return (a[0] ?? "") < (b[0] ?? "") ? -1 : 1;
+}
+function collectExportedSymbols(nodes) {
+  const byFile = /* @__PURE__ */ new Map();
+  for (const n of nodes) {
+    if (n.kind !== "symbol") continue;
+    const attrs = n.attrs ?? {};
+    if (attrs.exported !== true || !attrs.signature) continue;
+    const file = n.parentId ?? n.id.split("#")[0] ?? n.id;
+    const list = byFile.get(file) ?? [];
+    list.push({ name: n.name, signature: attrs.signature, purpose: attrs.purpose });
+    byFile.set(file, list);
+  }
+  return byFile;
+}
+function buildArea(members, edges, symbolsByFile) {
+  const files = rankByDegree(members, edges);
+  const label = dominantDirectory(files);
+  const topSymbols = pickTopSymbols(files, symbolsByFile);
+  const prompt = buildPrompt(label, files, topSymbols);
+  const area = {
+    id: `area-${contentHashOf2(files.join("\n")).slice(0, 8)}`,
+    label,
+    files,
+    size: files.length,
+    topSymbols,
+    contentHash: contentHashOf2(prompt)
+  };
+  return { area, prompt };
+}
+function rankByDegree(members, edges) {
+  const memberSet = new Set(members);
+  const degree = /* @__PURE__ */ new Map();
+  for (const e of edges) {
+    if (!memberSet.has(e.srcId) || !memberSet.has(e.dstId)) continue;
+    degree.set(e.srcId, (degree.get(e.srcId) ?? 0) + 1);
+    degree.set(e.dstId, (degree.get(e.dstId) ?? 0) + 1);
+  }
+  return [...members].sort((a, b) => {
+    const d = (degree.get(b) ?? 0) - (degree.get(a) ?? 0);
+    return d !== 0 ? d : a < b ? -1 : 1;
+  });
+}
+function dominantDirectory(files) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const f of files) {
+    const dir = path11.posix.dirname(f);
+    counts.set(dir, (counts.get(dir) ?? 0) + 1);
+  }
+  const dirs = [...counts.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1));
+  const topDir = dirs[0]?.[0] ?? ".";
+  return dirs.length > 1 ? `${topDir} (+${dirs.length - 1} dirs)` : topDir;
+}
+function pickTopSymbols(rankedFiles, symbolsByFile) {
+  const out = [];
+  for (const file of rankedFiles) {
+    for (const sym of symbolsByFile.get(file) ?? []) {
+      out.push(sym);
+      if (out.length >= PROMPT_SYMBOL_CAP) return out;
+    }
+  }
+  return out;
+}
+function buildPrompt(label, files, symbols) {
+  const shown = files.slice(0, PROMPT_FILE_CAP);
+  const lines = [
+    'You are writing one entry of a repository "convention map" \u2014 a',
+    "capability-altitude summary coding agents read at PLAN time to learn how",
+    "this repo does things and where new code belongs.",
+    "",
+    `Capability area: ${label}`,
+    `Files (${files.length}):`,
+    ...shown.map((f) => `- ${f}`)
+  ];
+  if (files.length > shown.length) lines.push(`- \u2026and ${files.length - shown.length} more`);
+  if (symbols.length > 0) {
+    lines.push("Key exported symbols:");
+    for (const s of symbols) lines.push(`- ${s.signature}${s.purpose ? ` \u2014 ${s.purpose}` : ""}`);
+  }
+  lines.push(
+    "",
+    "Write 2-3 sentences: (1) what this area does, and (2) HOW \u2014 the key entry",
+    "points, patterns and conventions to follow when adding related code.",
+    "Plain text only, no preamble or headings."
+  );
+  return lines.join("\n");
+}
+
+// src/conventions/summaries.ts
+import { CacheBlobTable as CacheBlobTable2 } from "@titan-design/store-sqlite";
+var COMMUNITY_SUMMARY_NAMESPACE = "code-graph/community-summary";
+function summaryCache(store) {
+  return new CacheBlobTable2(store.db, { name: KIT.cacheBlob });
+}
+function loadSummaries(store, model, hashes) {
+  const cache = summaryCache(store);
+  const found = /* @__PURE__ */ new Map();
+  for (const contentHash of new Set(hashes)) {
+    const hit = cache.get({ namespace: COMMUNITY_SUMMARY_NAMESPACE, model, contentHash });
+    if (hit) found.set(contentHash, hit.value.toString("utf8"));
+  }
+  return found;
+}
+function storeSummary(store, model, contentHash, summary) {
+  summaryCache(store).put({ namespace: COMMUNITY_SUMMARY_NAMESPACE, model, contentHash }, summary);
+}
+function attachSummaries(areas, summaries) {
+  for (const area of areas) area.summary = summaries.get(area.contentHash);
+}
+async function summarizeConventions(store, snapshotId, summarizer, opts) {
+  const { areas, prompts, coverage } = buildConventionAreas(store, snapshotId, opts);
+  attachSummaries(areas, loadSummaries(store, summarizer.model, areas.map((a) => a.contentHash)));
+  let newlySummarized = 0;
+  for (const area of areas) {
+    if (area.summary !== void 0) continue;
+    const summary = (await summarizer.summarize(prompts.get(area.contentHash))).trim();
+    storeSummary(store, summarizer.model, area.contentHash, summary);
+    area.summary = summary;
+    newlySummarized++;
+  }
+  coverage.summarized = areas.filter((a) => a.summary).length;
+  return { model: summarizer.model, coverage, areas, newlySummarized, reused: areas.length - newlySummarized };
+}
+function getConventionMap(store, snapshotId, model, opts) {
+  const { areas, coverage } = buildConventionAreas(store, snapshotId, opts);
+  attachSummaries(areas, loadSummaries(store, model, areas.map((a) => a.contentHash)));
+  coverage.summarized = areas.filter((a) => a.summary).length;
+  return { model, coverage, areas };
+}
+
+// src/conventions/query.ts
+import { BruteForceVectorIndex as BruteForceVectorIndex2, vectorRetriever as vectorRetriever2 } from "@titan-design/retrieval";
+var MATCH_FILE_CAP = 5;
+var DEFAULT_LIMIT = 3;
+async function findConventions(store, snapshotId, query, embedder, model, opts = {}) {
+  const map = getConventionMap(store, snapshotId, model, opts);
+  const summarized = map.areas.filter((a) => Boolean(a.summary));
+  if (summarized.length === 0) {
+    throw new Error(`No convention summaries stored for model ${model}; run summarizeConventions first.`);
+  }
+  const { byHash } = await embedTextsCached(store, embedder, summarized.map((a) => a.summary));
+  const index = new BruteForceVectorIndex2();
+  for (const area of summarized) index.add(area.id, byHash.get(hashEmbedText(area.summary)));
+  const hits = await vectorRetriever2(embedder, index).retrieve(query, { limit: opts.limit ?? DEFAULT_LIMIT });
+  const byId = new Map(summarized.map((a) => [a.id, a]));
+  return {
+    query,
+    model,
+    embeddingModel: embedder.model,
+    coverage: map.coverage,
+    matches: hits.map((h) => toMatch(byId.get(h.id), h.score ?? 0))
+  };
+}
+function toMatch(area, score) {
+  return {
+    id: area.id,
+    label: area.label,
+    summary: area.summary,
+    files: area.files.slice(0, MATCH_FILE_CAP),
+    size: area.size,
+    score
+  };
+}
 export {
+  ALIAS_BASE_ATTR,
   ALL_ROLES,
+  COMMUNITY_SUMMARY_NAMESPACE,
   COVERAGE_METRIC_NAME,
   CodeGraphStore,
   DEAD_CODE_METRIC_NAMES,
+  DEFAULT_CHURN_WINDOWS,
   DOMAIN_DDL,
   GROWTH_RISK_METRIC_NAMES,
   INDEX_VERSION,
   KIT,
   LanguageExtractor,
+  METRIC_CATALOGUE,
   MIGRATIONS,
   PythonGraphExtractor,
   SCHEMA_VERSION,
+  SNAPSHOT_SCOPED_TABLES,
   SOURCE_METRIC_NAMES,
   SYMBOL_EMBEDDING_NAMESPACE,
   SYMBOL_ID_SEP,
   TsMorphGraphExtractor,
+  aggregateMetrics,
+  aliasChain,
   annotateRoles,
   attributeCoverage,
   buildAliases,
+  buildConventionAreas,
   buildEmbedText,
   buildFileModuleNodes,
   buildIndexerMetrics,
+  buildLineage,
   canonicalEdgeKind,
   canonicalMetricName,
   canonicalRole,
@@ -4036,16 +5386,25 @@ export {
   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,
@@ -4056,7 +5415,9 @@ export {
   embedTextsCached,
   externalId,
   fileId,
+  findConventions,
   findSimilarCapability,
+  getConventionMap,
   getEdgeWeight,
   getLanguageFromPath3 as getLanguageFromPath,
   getSupportedLanguages,
@@ -4064,38 +5425,57 @@ export {
   hashContent,
   hashEmbedText,
   indexPaths,
+  invertBuckets,
   isGeneratedByHeuristic,
   isGeneratedFile,
   isInsideGitRepo,
+  lineagePath,
   linkTestsToSources,
   listEdges,
+  listEdgesTouching,
   listEmbeddableSymbols,
   listMetrics,
+  listMetricsForNode,
   listNodes,
   loadCheckRules,
   loadGeneratedPatterns,
+  loadHistoryMetrics,
+  loadLineage,
+  matchesAny,
   moduleId,
   openCodeGraph,
   packageId,
   parentModuleId,
   parseFile2 as parseFile,
   parseSymbolId,
+  patternToRegex,
+  planPrune,
+  priorSnapshotForRef,
   pruneDanglingReferences,
   readSourceFiles,
+  rebasedViolationKey,
+  resolveAlias,
   resolveBarrelEdges,
+  resolveChurnWindows,
+  resolveGitRef,
   resolveSnapshot,
   runChecks,
+  runPrune,
   shouldIncludeFile2 as shouldIncludeFile,
   snapshotPageRank,
   snapshotReferenceEdges,
   snapshotRelevance,
   snapshotSymbolConsumers,
   snapshotSymbolCoupling,
+  snapshotViolations,
   structuralSignature,
+  summarizeConventions,
   symbolId,
   testCoverageCountMetrics,
   tryEmbedSnapshot,
   validateRules,
-  walkSourceFiles
+  violationKey,
+  walkSourceFiles,
+  windowSuffix
 };
 //# sourceMappingURL=index.js.map