@titan-design/code-graph 0.3.0 → 0.5.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

@@ -1206,6 +1206,14 @@ interface CheckViolation {
     threshold?: number;
     destinationId?: string;
     isCarryover?: boolean;
+    /** Repo-relative file the violation sits in; a symbol's parent file. */
+    path?: string;
+    lineStart?: number;
+    lineEnd?: number;
+    symbol?: string;
+    /** One line a reader can check without re-running the rule, such as `loc=412 (max 350)`. */
+    evidence?: string;
+    tool?: string;
 }
 interface CheckResult {
     snapshotId: number;
@@ -1236,6 +1244,34 @@ declare function violationKey(v: CheckViolation): string;
 /** {@link violationKey} with both node ids carried into another snapshot's id space; unmoved ids key as before. */
 declare function rebasedViolationKey(v: CheckViolation, resolve: (id: string) => string): string;
 
+/** One tool-neutral audit finding; every finding cites a path so a citation checker can verify it. */
+interface Finding {
+    id: string;
+    path: string;
+    lineStart?: number;
+    lineEnd?: number;
+    symbol?: string;
+    signal: string;
+    value?: number;
+    baseline?: number;
+    threshold?: number;
+    severity: Severity;
+    evidence?: string;
+    tool: string;
+}
+/** A diagnostic from an outside linter, shaped structurally so no linter package is imported. */
+interface ExternalDiagnostic {
+    tool: string;
+    rule: string;
+    file: string;
+    line: number;
+    endLine?: number;
+    message: string;
+    severity: "error" | "warning";
+}
+declare function toFindings(result: CheckResult): Finding[];
+declare function externalToFinding(input: ExternalDiagnostic): Finding;
+
 /** Glob when the pattern has a `*` (`**` crosses directories, `*` stays in a segment); otherwise a case-sensitive substring. */
 declare function patternToRegex(pattern: string): RegExp;
 declare function compilePatterns(patterns: readonly string[] | undefined): RegExp[];
@@ -1432,4 +1468,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 ExternalDiagnostic, type FileFingerprint, type FindConventionsOptions, type FindSimilarOptions, type Finding, 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, externalToFinding, 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, toFindings, tryEmbedSnapshot, validateRules, violationKey, walkSourceFiles, windowSuffix };