@titan-design/code-graph 0.9.1 → 0.10.0

package/README.md

@@ -271,6 +271,16 @@ snapshots and buckets each violation as new, resolved, or unchanged; unchanged m
 violations are further split into worsened and improved by value. From-side ids follow the
 alias chain, as in the ratchet.
 
+`computeFootprints({ nodes, edges }, options)` gives each symbol node a footprint built from
+structural inputs only, so a moved declaration or a churn window never reads as a change. It
+has three parts, each a `hashText` over canonical JSON: `signature` (name, exported, signature,
+purpose; no span), `consumers` (sorted distinct files with a `references` edge into the symbol),
+and `coupling` (sorted co-import partners at or above `minCoImports`, default 2). `hash` combines
+the three. Consumers include test files unless `ignoreConsumer(fileId)` rejects them; a rejected
+file is dropped from coupling too. `symbolSetHash({ unitId, symbolIds }, footprints)` hashes a
+doc unit's sorted `[symbolId, footprint.hash]` pairs, so it ignores member order and changes when
+a member is added, removed or changed.
+
 `scripts/dag-check-self.mjs` in the repo root runs this repo's DAG check on this engine
 instead of codewatch's CLI.
 

package/dist/index.d.ts

@@ -1470,6 +1470,47 @@ interface DiffCheckResultsOptions {
  */
 declare function diffCheckResults(store: CodeGraphStore, options: DiffCheckResultsOptions): CheckDiff;
 
+/**
+ * A symbol's documentable footprint (C-75): structural inputs only, so a moved declaration,
+ * a churn window or a centrality shift never reads as a change.
+ */
+interface FootprintParts {
+    /** Hash of `{name, exported, signature, purpose}`; no span. */
+    signature: string;
+    /** Hash of the sorted distinct file ids that reference the symbol. */
+    consumers: string;
+    /** Hash of the sorted co-import partner symbol ids at or above `minCoImports`. */
+    coupling: string;
+}
+interface SymbolFootprint {
+    symbolId: string;
+    parts: FootprintParts;
+    /** Hash of the three part hashes. */
+    hash: string;
+}
+interface FootprintGraph {
+    nodes: readonly GraphNode[];
+    edges: readonly GraphEdge[];
+}
+interface FootprintOptions {
+    /** Drop a referencing file from consumers and co-import coupling, e.g. test files. Default keeps all. */
+    ignoreConsumer?: (fileId: string) => boolean;
+    /** Co-import threshold for a coupling partner. Default 2. */
+    minCoImports?: number;
+}
+/** A doc target: the default unit is one file holding its symbols. */
+interface FootprintUnit {
+    unitId: string;
+    symbolIds: readonly string[];
+}
+/** Footprint of every symbol node in the graph, keyed by symbol id. */
+declare function computeFootprints(graph: FootprintGraph, options?: FootprintOptions): Map<string, SymbolFootprint>;
+/**
+ * Order-independent hash of a unit's `[symbolId, footprint.hash]` pairs. A member with no
+ * footprint hashes as null, so a symbol that disappears still changes the set.
+ */
+declare function symbolSetHash(unit: FootprintUnit, footprints: ReadonlyMap<string, SymbolFootprint>): string;
+
 interface EmbeddableSymbol {
     id: string;
     name: string;
@@ -1686,4 +1727,4 @@ declare function getConventionMap(store: CodeGraphStore, snapshotId: number, mod
  */
 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, DEFAULT_OUTLIER_MIN_SAMPLE, DOMAIN_DDL, type DeepAst, type DeepAstInput, type DiffCheckResultsOptions, type DiffSnapshotsOptions, EXCEPTION_METRIC_NAMES, type EdgeKind, type EmbedAttempt, type EmbedCoverage, type EmbedSnapshotResult, type EmbeddableSymbol, type ExternalDiagnostic, FINDING_DDL, type FileFingerprint, type FindConventionsOptions, type FindSimilarOptions, type Finding, type FindingKeyInput, 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 MetricOutlierRule, 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, SYMBOL_METRIC_NAMES, type Severity, type SimilarCandidate, type SimilarResult, type SnapshotInsert, type SnapshotRow, type SnapshotSpec, type SourceLanguage, type StoredFinding, type StoredVerdict, 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, type VerdictCitation, type VerdictLabel, aggregateMetrics, aliasChain, annotateRoles, attributeCoverage, buildAliases, buildConventionAreas, buildEmbedText, buildFileModuleNodes, buildIndexerMetrics, buildLineage, canonicalEdgeKind, canonicalMetricName, canonicalRole, carryForwardVerdicts, 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, findingKey, getConventionMap, getEdgeWeight, groupTestsBySource, hashContent, hashEmbedText, hashText, indexPaths, invertBuckets, isGeneratedByHeuristic, isGeneratedFile, isInsideGitRepo, keyFindings, lineagePath, linkTestsToSources, listEdges, listEdgesTouching, listEmbeddableSymbols, listFindings, listMetrics, listMetricsForNode, listNodes, listVerdicts, loadCheckRules, loadGeneratedPatterns, loadHistoryMetrics, loadLineage, matchesAny, moduleId, normalizeFlaggedText, openCodeGraph, packageId, parentModuleId, parseSymbolId, patternToRegex, percentileOf, planPrune, priorSnapshotForRef, pruneDanglingReferences, readSourceFiles, rebasedViolationKey, resolveAlias, resolveBarrelEdges, resolveChurnWindows, resolveGitRef, resolveSnapshot, runChecks, runPrune, saveFindings, saveVerdicts, snapshotPageRank, snapshotReferenceEdges, snapshotRelevance, snapshotSymbolConsumers, snapshotSymbolCoupling, snapshotViolations, structuralSignature, summarizeConventions, symbolId, testCoverageCountMetrics, toFindings, tryEmbedSnapshot, validateRules, violationKey, walkSourceFiles, windowSuffix };
+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, DEFAULT_OUTLIER_MIN_SAMPLE, DOMAIN_DDL, type DeepAst, type DeepAstInput, type DiffCheckResultsOptions, type DiffSnapshotsOptions, EXCEPTION_METRIC_NAMES, type EdgeKind, type EmbedAttempt, type EmbedCoverage, type EmbedSnapshotResult, type EmbeddableSymbol, type ExternalDiagnostic, FINDING_DDL, type FileFingerprint, type FindConventionsOptions, type FindSimilarOptions, type Finding, type FindingKeyInput, type FootprintGraph, type FootprintOptions, type FootprintParts, type FootprintUnit, 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 MetricOutlierRule, 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, SYMBOL_METRIC_NAMES, type Severity, type SimilarCandidate, type SimilarResult, type SnapshotInsert, type SnapshotRow, type SnapshotSpec, type SourceLanguage, type StoredFinding, type StoredVerdict, type SummarizeConventionsResult, type Summarizer, type SymbolConsumers, type SymbolCouplingOptions, type SymbolCouplingPair, type SymbolFootprint, type SymbolSpan, type TestCoverageOwnershipOptions, type TestSourceLink, type TopMetricRow, TsMorphGraphExtractor, type TsMorphGraphExtractorOptions, type UnchangedViolation, type ValidateRulesOptions, type VerdictCitation, type VerdictLabel, aggregateMetrics, aliasChain, annotateRoles, attributeCoverage, buildAliases, buildConventionAreas, buildEmbedText, buildFileModuleNodes, buildIndexerMetrics, buildLineage, canonicalEdgeKind, canonicalMetricName, canonicalRole, carryForwardVerdicts, checkSnapshot, classifyRole, collectDeclaredNames, collectDeclaredSpans, compilePatterns, computeDeadCodeMetrics, computeDeepAst, computeFootprints, 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, findingKey, getConventionMap, getEdgeWeight, groupTestsBySource, hashContent, hashEmbedText, hashText, indexPaths, invertBuckets, isGeneratedByHeuristic, isGeneratedFile, isInsideGitRepo, keyFindings, lineagePath, linkTestsToSources, listEdges, listEdgesTouching, listEmbeddableSymbols, listFindings, listMetrics, listMetricsForNode, listNodes, listVerdicts, loadCheckRules, loadGeneratedPatterns, loadHistoryMetrics, loadLineage, matchesAny, moduleId, normalizeFlaggedText, openCodeGraph, packageId, parentModuleId, parseSymbolId, patternToRegex, percentileOf, planPrune, priorSnapshotForRef, pruneDanglingReferences, readSourceFiles, rebasedViolationKey, resolveAlias, resolveBarrelEdges, resolveChurnWindows, resolveGitRef, resolveSnapshot, runChecks, runPrune, saveFindings, saveVerdicts, snapshotPageRank, snapshotReferenceEdges, snapshotRelevance, snapshotSymbolConsumers, snapshotSymbolCoupling, snapshotViolations, structuralSignature, summarizeConventions, symbolId, symbolSetHash, testCoverageCountMetrics, toFindings, tryEmbedSnapshot, validateRules, violationKey, walkSourceFiles, windowSuffix };

package/dist/index.js

@@ -1050,6 +1050,13 @@ function remapDistToSrc(abs) {
   }
   return abs;
 }
+function repoTypeRoots(repoRoot) {
+  const roots = [];
+  for (let dir = path3.resolve(repoRoot); ; dir = path3.dirname(dir)) {
+    roots.push(path3.join(dir, "node_modules", "@types"));
+    if (path3.dirname(dir) === dir) return roots;
+  }
+}
 
 // src/extractors/reexport-resolve.ts
 function resolveReExportOrigin(ctx, importerAbs, specifier, name) {
@@ -1247,7 +1254,8 @@ var TsMorphGraphExtractor = class {
         allowJs: true,
         target: ScriptTarget.ESNext,
         module: ModuleKind.ESNext,
-        moduleResolution: ModuleResolutionKind.NodeNext
+        moduleResolution: ModuleResolutionKind.NodeNext,
+        typeRoots: repoTypeRoots(this.repoRoot)
       }
     });
     return this.project;
@@ -6199,6 +6207,63 @@ function computeDelta(from, to) {
   return to.value - from.value;
 }
 
+// src/diff/footprint.ts
+var DEFAULT_MIN_CO_IMPORTS2 = 2;
+function computeFootprints(graph, options = {}) {
+  const edges = referenceEdges(graph.edges, options.ignoreConsumer);
+  const consumers = consumersBySymbol(edges);
+  const partners = partnersBySymbol(edges, options.minCoImports ?? DEFAULT_MIN_CO_IMPORTS2);
+  const out = /* @__PURE__ */ new Map();
+  for (const node of graph.nodes) {
+    if (node.kind !== "symbol") continue;
+    const parts = {
+      signature: hashJson(signatureOf2(node)),
+      consumers: hashJson(consumers.get(node.id) ?? []),
+      coupling: hashJson(partners.get(node.id) ?? [])
+    };
+    const hash = hashJson([parts.signature, parts.consumers, parts.coupling]);
+    out.set(node.id, { symbolId: node.id, parts, hash });
+  }
+  return out;
+}
+function symbolSetHash(unit, footprints) {
+  const pairs = [...new Set(unit.symbolIds)].sort().map((id) => [id, footprints.get(id)?.hash ?? null]);
+  return hashJson(pairs);
+}
+function hashJson(value) {
+  return hashText(JSON.stringify(value));
+}
+function signatureOf2(node) {
+  const attrs = node.attrs ?? {};
+  return {
+    name: node.name,
+    exported: attrs.exported === true,
+    signature: typeof attrs.signature === "string" ? attrs.signature : null,
+    purpose: typeof attrs.purpose === "string" ? attrs.purpose : null
+  };
+}
+function referenceEdges(edges, ignoreConsumer) {
+  return edges.filter(
+    (e) => canonicalEdgeKind(e.kind) === "references" && !ignoreConsumer?.(e.srcId)
+  );
+}
+function consumersBySymbol(edges) {
+  return new Map(computeSymbolConsumers(edges).map((c) => [c.symbolId, c.consumers]));
+}
+function partnersBySymbol(edges, minCoImports) {
+  const partners = /* @__PURE__ */ new Map();
+  const add = (from, to) => {
+    const set = partners.get(from) ?? /* @__PURE__ */ new Set();
+    set.add(to);
+    partners.set(from, set);
+  };
+  for (const pair of computeSymbolCoupling(edges, { minCoImports })) {
+    add(pair.aId, pair.bId);
+    add(pair.bId, pair.aId);
+  }
+  return new Map([...partners].map(([id, set]) => [id, [...set].sort()]));
+}
+
 // src/embeddings/corpus.ts
 import { contentHashOf } from "@titan-design/store-sqlite";
 function buildEmbedText(signature, purpose) {
@@ -6697,6 +6762,7 @@ export {
   compilePatterns,
   computeDeadCodeMetrics,
   computeDeepAst,
+  computeFootprints,
   computeGrowthRiskMetrics,
   computeMetrics,
   computePageRank,
@@ -6789,6 +6855,7 @@ export {
   structuralSignature,
   summarizeConventions,
   symbolId,
+  symbolSetHash,
   testCoverageCountMetrics,
   toFindings,
   tryEmbedSnapshot,