@titan-design/code-graph 0.4.0 → 0.5.0

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[];
@@ -1552,4 +1588,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, 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 };
+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 };

package/dist/index.js

@@ -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") {
@@ -5414,6 +5470,7 @@ export {
   embedSnapshot,
   embedTextsCached,
   externalId,
+  externalToFinding,
   fileId,
   findConventions,
   findSimilarCapability,
@@ -5472,6 +5529,7 @@ export {
   summarizeConventions,
   symbolId,
   testCoverageCountMetrics,
+  toFindings,
   tryEmbedSnapshot,
   validateRules,
   violationKey,