@titan-design/code-graph 0.3.0 → 0.4.0

package/README.md

@@ -44,10 +44,13 @@ Ported with TP-250: package partition quality (`src/analysis/partition-quality.t
 snapshot pruning (`src/prune.ts`). See [Partition quality](#partition-quality) and
 [Pruning snapshots](#pruning-snapshots).
 
-Deferred, all of it still in codewatch, all of it a follow-up on this package rather than a
-change to it:
+Ported with TP-130: community detection and the convention layer (`src/conventions/`). See
+[Conventions](#conventions). codewatch keeps the CLI command, the `claude -p` summarizer, and
+the MCP and read-API wiring.
 
-- Graph analyses over a finished snapshot: communities, conventions, reuse-delta reporting.
+Deferred, still in codewatch, a follow-up on this package rather than a change to it:
+
+- Reuse-delta reporting over a finished snapshot.
 
 Python support is new here rather than ported. codewatch walked TypeScript only; the parser
 already had the grammar. The Python extractor is deliberately narrower than the ts-morph one:
@@ -364,6 +367,43 @@ The domain tables declare no foreign key, so `CodeGraphStore.deleteSnapshots` cl
 `SNAPSHOT_SCOPED_TABLES` itself rather than relying on a cascade. `blob_cache` is
 content-addressed and not snapshot-scoped, so a prune never drops a cached embedding.
 
+## Conventions
+
+"How does this repo do X, and where does code like this belong?" Ported from codewatch's
+unmerged C-88 branch (TP-130). The layer cuts the barrel-resolved file graph into a few coarse
+areas, has an injected summarizer describe each one, and ranks areas against a question by
+embedding similarity. Verified against this release on this repo's `packages/`, with a fake
+summarizer:
+
+```ts
+import { findConventions, getConventionMap, summarizeConventions } from "@titan-design/code-graph";
+
+const summarizer = { model: "claude:sonnet", summarize: (prompt: string) => callYourLlm(prompt) };
+await summarizeConventions(store, snapshotId, summarizer);
+// { coverage: { files: 713, grouped: 513, areas: 24, summarized: 24 }, newlySummarized: 24, reused: 0, … }
+// a second run: { newlySummarized: 0, reused: 24 }
+
+getConventionMap(store, snapshotId, "claude:sonnet"); // the same areas, stored summaries only
+await findConventions(store, snapshotId, "how are CLI commands registered?", embedder, "claude:sonnet");
+// { matches: [ { label, summary, files: [ …up to 5 ], size, score }, … up to 3 ] }
+```
+
+- **The cut.** `detectCommunities` is greedy modularity (Clauset-Newman-Moore), not Leiden. It
+  is deterministic without a seed: ties resolve by sorted id. `targetCount` keeps merging past
+  the natural modularity stop until that many communities remain, and a size cap of twice the
+  ideal share keeps a dense repo from collapsing into one area. The default target is one area
+  per 25 files, clamped to 6..40. Areas under `minSize` (default 3) files are left unsummarized.
+  Disconnected components never merge, so the component count is the floor.
+- **Only the coarse level is summarized.** LLM cost is one call per area, and each summary is
+  stored in `blob_cache` under `code-graph/community-summary`, keyed by `summarizer.model` and a
+  hash of the prompt. The prompt carries the member files and their key exported signatures, so
+  an area whose membership and signatures did not change is a cache hit in any snapshot. On
+  this repo a finer cut (`targetCount: 60`) still reused 8 of its 35 areas.
+- **The package ships no LLM client.** `Summarizer` is `{ model, summarize(prompt) }`; the
+  product supplies it. `getConventionMap` and `findConventions` never call it. `findConventions`
+  throws when no summary is stored for the model, and returns candidates with scores, not
+  verdicts. Summary vectors go through the same embedding cache as similar symbols.
+
 ## Git history
 
 Ported in TP-126, strictly as codewatch had it: churn over rolling windows, first-seen dates,

package/dist/index.d.ts

@@ -1432,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 { ALIAS_BASE_ATTR, ALL_ROLES, type AliasChain, type AliasChainInput, type AliasChainOptions, type AliasLoader, type AliasResolution, COVERAGE_METRIC_NAME, type CachedEmbedResult, type CheckDiff, type CheckResult, type CheckRule, type CheckRulesFile, type CheckSnapshotOptions, type CheckSnapshotResult, type CheckViolation, CodeGraphStore, 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 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 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, 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, describeMetric, describeMetrics, detectGitHead, detectGitToplevel, detectRenames, diffCheckResults, diffSnapshots, edgeWeight, embedSnapshot, embedTextsCached, externalId, fileId, findSimilarCapability, 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, symbolId, testCoverageCountMetrics, tryEmbedSnapshot, validateRules, violationKey, walkSourceFiles, windowSuffix };
+/** 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 };

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) {
@@ -4723,18 +4723,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 +5037,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 +5374,7 @@ export {
   annotateRoles,
   attributeCoverage,
   buildAliases,
+  buildConventionAreas,
   buildEmbedText,
   buildFileModuleNodes,
   buildIndexerMetrics,
@@ -5089,8 +5401,10 @@ export {
   computeSymbolCoupling,
   computeTestCoverageOwnership,
   createAliasChain,
+  defaultTargetCount,
   describeMetric,
   describeMetrics,
+  detectCommunities,
   detectGitHead,
   detectGitToplevel,
   detectRenames,
@@ -5101,7 +5415,9 @@ export {
   embedTextsCached,
   externalId,
   fileId,
+  findConventions,
   findSimilarCapability,
+  getConventionMap,
   getEdgeWeight,
   getLanguageFromPath3 as getLanguageFromPath,
   getSupportedLanguages,
@@ -5153,6 +5469,7 @@ export {
   snapshotSymbolCoupling,
   snapshotViolations,
   structuralSignature,
+  summarizeConventions,
   symbolId,
   testCoverageCountMetrics,
   tryEmbedSnapshot,