@titan-design/code-graph 0.3.0 → 0.5.0

package/dist/index.js

@@ -1396,8 +1396,8 @@ function walk(requestedId, maps) {
 }
 function chainSteps(input) {
   if (input.from === null) return { steps: rootPath(input.lineage, input.to, input.maxHops), connected: true };
-  const path11 = lineagePath(input.lineage, input.from, input.to, input.maxHops);
-  if (path11) return { steps: path11, 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) {
@@ -4177,11 +4177,13 @@ function describeMetrics(names) {
 
 // src/check/context.ts
 function buildRuleContext(store, snapshotId) {
-  const nodes = store.listNodes(snapshotId);
+  const all = store.listNodes(snapshotId, { includeSymbols: true });
+  const nodes = all.filter((n) => n.kind !== "symbol");
+  const symbolNodes2 = all.filter((n) => n.kind === "symbol");
   const edges = store.listEdges(snapshotId);
   const nodesById = /* @__PURE__ */ new Map();
   for (const n of nodes) nodesById.set(n.id, n);
-  return { nodes, nodesById, metricsByNode: indexMetrics(store.listMetrics(snapshotId)), edges };
+  return { nodes, symbolNodes: symbolNodes2, nodesById, metricsByNode: indexMetrics(store.listMetrics(snapshotId)), edges };
 }
 function indexMetrics(metrics) {
   const metricsByNode = /* @__PURE__ */ new Map();
@@ -4339,6 +4341,18 @@ function barrelMessage(barrelPkg, importerCount) {
   return importerCount === 0 ? `barrel in package "${barrelPkg}" has no importers` : `barrel in package "${barrelPkg}" has ${importerCount} internal importer(s) but zero external`;
 }
 
+// src/check/violation-location.ts
+var CODE_GRAPH_TOOL = "code-graph";
+function locateNode(node) {
+  if (node.kind !== "symbol") return { path: node.id };
+  const location = { path: node.parentId ?? node.id, symbol: node.name };
+  const startLine = node.attrs?.startLine;
+  const endLine = node.attrs?.endLine;
+  if (typeof startLine === "number") location.lineStart = startLine;
+  if (typeof endLine === "number") location.lineEnd = endLine;
+  return location;
+}
+
 // src/check/metric-rules.ts
 function nodeFilter(rule) {
   return {
@@ -4353,71 +4367,76 @@ function passesFilter(node, filter) {
   if (node.role && filter.excludedRoles.has(node.role)) return false;
   return true;
 }
-function runMetricMaxRule(rule, ctx) {
+function candidateNodes(rule, ctx) {
   const filter = nodeFilter(rule);
+  const pool = rule.kind === "symbol" ? ctx.symbolNodes : ctx.nodes;
+  return pool.filter((node) => passesFilter(node, filter));
+}
+function toViolation(rule, breach) {
+  return {
+    ruleId: rule.id,
+    severity: severityOf(rule),
+    nodeId: breach.node.id,
+    metric: breach.metric,
+    value: breach.value,
+    threshold: breach.threshold,
+    message: breach.message,
+    ...locateNode(breach.node),
+    evidence: breach.evidence,
+    tool: CODE_GRAPH_TOOL
+  };
+}
+function thresholdBreach(node, metric, value, bound, threshold) {
+  const op = bound === "max" ? ">" : "<";
+  return {
+    node,
+    metric,
+    value,
+    threshold,
+    message: `${metric}=${formatNumber(value)} ${op} ${formatNumber(threshold)}`,
+    evidence: `${metric}=${formatNumber(value)} (${bound} ${formatNumber(threshold)})`
+  };
+}
+function runMetricMaxRule(rule, ctx) {
   const out = [];
-  for (const node of ctx.nodes) {
-    if (!passesFilter(node, filter)) continue;
+  for (const node of candidateNodes(rule, ctx)) {
     const value = ctx.metricsByNode.get(node.id)?.get(rule.metric);
-    if (value === void 0) continue;
-    if (value <= rule.max) continue;
-    out.push({
-      ruleId: rule.id,
-      severity: severityOf(rule),
-      nodeId: node.id,
-      metric: rule.metric,
-      value,
-      threshold: rule.max,
-      message: `${rule.metric}=${formatNumber(value)} > ${formatNumber(rule.max)}`
-    });
+    if (value === void 0 || value <= rule.max) continue;
+    out.push(toViolation(rule, thresholdBreach(node, rule.metric, value, "max", rule.max)));
   }
   return out;
 }
 function runMetricMinRule(rule, ctx) {
-  const filter = nodeFilter(rule);
   const out = [];
-  for (const node of ctx.nodes) {
-    if (!passesFilter(node, filter)) continue;
+  for (const node of candidateNodes(rule, ctx)) {
     const value = ctx.metricsByNode.get(node.id)?.get(rule.metric);
-    if (value === void 0) continue;
-    if (value >= rule.min) continue;
-    out.push({
-      ruleId: rule.id,
-      severity: severityOf(rule),
-      nodeId: node.id,
-      metric: rule.metric,
-      value,
-      threshold: rule.min,
-      message: `${rule.metric}=${formatNumber(value)} < ${formatNumber(rule.min)}`
-    });
+    if (value === void 0 || value >= rule.min) continue;
+    out.push(toViolation(rule, thresholdBreach(node, rule.metric, value, "min", rule.min)));
   }
   return out;
 }
 function runMetricProductMaxRule(rule, ctx) {
-  const filter = nodeFilter(rule);
   const out = [];
-  for (const node of ctx.nodes) {
-    if (!passesFilter(node, filter)) continue;
+  for (const node of candidateNodes(rule, ctx)) {
     const inner = ctx.metricsByNode.get(node.id);
     if (!inner) continue;
     const components = collectComponents(rule.metrics, inner);
     if (!components) continue;
     const product = components.reduce((a, b) => a * b, 1);
     if (product <= rule.max) continue;
-    out.push(productViolation(rule, node.id, components, product));
+    out.push(toViolation(rule, productBreach(rule, node, components, product)));
   }
   return out;
 }
-function productViolation(rule, nodeId, components, product) {
+function productBreach(rule, node, components, product) {
   const detail = rule.metrics.map((m, i) => `${m}=${formatNumber(components[i])}`).join(" * ");
   return {
-    ruleId: rule.id,
-    severity: severityOf(rule),
-    nodeId,
+    node,
     metric: rule.metrics.join(" * "),
     value: product,
     threshold: rule.max,
-    message: `${detail} = ${formatNumber(product)} > ${formatNumber(rule.max)}`
+    message: `${detail} = ${formatNumber(product)} > ${formatNumber(rule.max)}`,
+    evidence: `${detail} = ${formatNumber(product)} (max ${formatNumber(rule.max)})`
   };
 }
 function collectComponents(metrics, values) {
@@ -4507,6 +4526,43 @@ function countByOriginAndSeverity(violations) {
   return counts;
 }
 
+// src/check/findings.ts
+function toFindings(result) {
+  return result.violations.map(violationToFinding);
+}
+function violationToFinding(v) {
+  const tool = v.tool ?? CODE_GRAPH_TOOL;
+  const target = v.destinationId ? `${v.nodeId}->${v.destinationId}` : v.nodeId;
+  return withoutUndefined({
+    id: `${tool}:${v.ruleId}:${target}`,
+    path: v.path ?? v.nodeId,
+    lineStart: v.lineStart,
+    lineEnd: v.lineEnd,
+    symbol: v.symbol,
+    signal: v.ruleId,
+    value: v.value,
+    threshold: v.threshold,
+    severity: v.severity,
+    evidence: v.evidence ?? v.message,
+    tool
+  });
+}
+function externalToFinding(input) {
+  return withoutUndefined({
+    id: `${input.tool}:${input.rule}:${input.file}:${input.line}`,
+    path: input.file,
+    lineStart: input.line,
+    lineEnd: input.endLine,
+    signal: input.rule,
+    severity: input.severity,
+    evidence: input.message,
+    tool: input.tool
+  });
+}
+function withoutUndefined(finding) {
+  return Object.fromEntries(Object.entries(finding).filter(([, v]) => v !== void 0));
+}
+
 // src/check/validate.ts
 function validateRules(input, options = {}) {
   if (!input || typeof input !== "object") {
@@ -4723,18 +4779,18 @@ function checkSnapshot(store, options) {
   });
   return { snapshot, baselineSnapshot, result };
 }
-async function loadCheckRules(path11, options = {}) {
+async function loadCheckRules(path12, options = {}) {
   let raw;
   try {
-    raw = await readFile2(path11, "utf8");
+    raw = await readFile2(path12, "utf8");
   } catch (err) {
-    throw new Error(`Cannot read rules file at ${path11}: ${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 ${path11}: ${errorMessage(err)}`);
+    throw new Error(`Invalid JSON in ${path12}: ${errorMessage(err)}`);
   }
   return validateRules(parsed, options);
 }
@@ -5037,9 +5093,320 @@ 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,
@@ -5063,6 +5430,7 @@ export {
   annotateRoles,
   attributeCoverage,
   buildAliases,
+  buildConventionAreas,
   buildEmbedText,
   buildFileModuleNodes,
   buildIndexerMetrics,
@@ -5089,8 +5457,10 @@ export {
   computeSymbolCoupling,
   computeTestCoverageOwnership,
   createAliasChain,
+  defaultTargetCount,
   describeMetric,
   describeMetrics,
+  detectCommunities,
   detectGitHead,
   detectGitToplevel,
   detectRenames,
@@ -5100,8 +5470,11 @@ export {
   embedSnapshot,
   embedTextsCached,
   externalId,
+  externalToFinding,
   fileId,
+  findConventions,
   findSimilarCapability,
+  getConventionMap,
   getEdgeWeight,
   getLanguageFromPath3 as getLanguageFromPath,
   getSupportedLanguages,
@@ -5153,8 +5526,10 @@ export {
   snapshotSymbolCoupling,
   snapshotViolations,
   structuralSignature,
+  summarizeConventions,
   symbolId,
   testCoverageCountMetrics,
+  toFindings,
   tryEmbedSnapshot,
   validateRules,
   violationKey,