@titan-design/code-graph 0.6.0 → 0.8.0

package/README.md

@@ -18,7 +18,7 @@ const { snapshotId, files, nodes, edges, reused } = await indexPaths(store, {
   ref: "head",
 });
 listNodes(store, snapshotId); // file / module / external nodes, symbols on request
-listEdges(store, snapshotId); // imports / re-exports, references on request
+listEdges(store, snapshotId); // imports / re-exports, references and calls on request
 ```
 
 ## What was extracted, and what was not
@@ -28,7 +28,8 @@ In: the parser (tree-sitter WASM for TypeScript, TSX and Python, since moved to
 extractor and its symbol layer, role classification, generated-file detection, id aliasing
 across git renames, the three-tier incremental reuse, and the metrics computed at index time
 (degree, utilization, loc, cyclomatic, cognitive, nesting, class count, lcom4, and per
-symbol `symbol_cognitive`, `symbol_cyclomatic`, `symbol_loc` and `symbol_max_nesting`). `lcom.ts` came along despite being an analysis: `source-metrics.ts` calls it
+symbol `symbol_cognitive`, `symbol_cyclomatic`, `symbol_loc`, `symbol_max_nesting`, and the
+comment and shape metrics below). `lcom.ts` came along despite being an analysis: `source-metrics.ts` calls it
 directly and lcom4 is a pure function of a file's bytes, so it belongs with the metrics that
 carry forward under reuse.
 
@@ -165,7 +166,7 @@ wrong time model for a population re-indexed all at once), `metric`, `id_alias`,
 `file_fingerprint`.
 
 The symbol layer is hidden by default. `listNodes` drops `symbol` nodes and `listEdges` drops
-`references` edges unless you ask for them, so a caller reasoning about module structure sees
+`references` and `calls` edges unless you ask for them (`includeReferences` covers both), so a caller reasoning about module structure sees
 the graph it expects and does not have one import of thirty names read as thirty
 dependencies.
 
@@ -222,9 +223,17 @@ the file is unreadable.
 
 ## Checks and diffs
 
-The rules engine turns a snapshot into pass/fail against a `check.json`. Six rule types:
-`metric-max`, `metric-min`, `metric-product-max`, `forbid-import`, `layered-deps`, and
-`no-internal-only-barrels`. Severity defaults to `error`; only new errors fail a check.
+The rules engine turns a snapshot into pass/fail against a `check.json`. Seven rule types:
+`metric-max`, `metric-min`, `metric-product-max`, `metric-outlier`, `forbid-import`,
+`layered-deps`, and `no-internal-only-barrels`. Severity defaults to `error`; only new errors
+fail a check.
+
+`metric-outlier` takes its threshold from the snapshot instead of the rule:
+`{ "type": "metric-outlier", "id": "long-fn", "metric": "symbol_body_lines", "kind": "symbol", "percentile": 95 }`
+flags every symbol strictly above the 95th percentile of `symbol_body_lines` over all symbols
+that carry it, interpolated linearly between ranks. `percentile` runs from 50 to 100. The rule
+stays silent until `minSample` nodes (default 20) carry the metric. Each violation's
+`threshold` is the computed percentile value.
 
 ```ts
 import { checkSnapshot, loadCheckRules, openCodeGraph } from "@titan-design/code-graph";
@@ -317,6 +326,39 @@ above zero.
   not complexity bounds. Recursion and search match TypeScript call nodes only, so Python
   files get `loop_depth` alone, as in codewatch.
 
+Comment, shape, and exception-handling metrics (TP-322) are also source-local, TypeScript and
+Python, and are written on every function or file, zeros included:
+
+- Per symbol: `symbol_comment_lines` (rows holding a comment inside the function, docstring
+  excluded), `symbol_docstring_lines` (the Python docstring, or a JSDoc block ending on the row
+  above the declaration), `symbol_body_lines` (rows holding code), `symbol_comment_ratio`
+  (comment lines over `max(body lines, 1)`), `symbol_narrating_comments` (comments whose words
+  share at least 2 tokens, or half their tokens, with the identifiers of the statement they sit
+  above or trail), and `symbol_pass_through` (1 when the body is one call that forwards every
+  parameter, in order, as a bare argument, skipping a `self` or `cls` receiver; a function
+  with no parameters is never one).
+- Per file: `except_count` (Python `except` and TypeScript `catch` clauses), `except_density`
+  (per 100 non-blank lines), and `swallowed_except` (handlers whose body is empty, `pass`,
+  `...`, `continue`, a bare or `None`/`null`/`undefined` return, or one call to a logger,
+  `print`, `warn` or `console`).
+
+Call-graph metrics (TP-323) come from `calls` edges, one per caller and callee symbol, each
+carrying the literal arguments of every call site in `attrs.sites`. TypeScript resolves a
+call or `new` through the type checker to one in-repo declaration. Python resolves only a
+bare name declared at module level in the same file, a bare name bound by `from <in-repo
+module> import`, and `self.<name>()` to a method of the enclosing class or a base class
+declared in the same file. Anything else is dropped, never guessed, and an edge whose target
+has no symbol node is pruned. The caller is the enclosing function, method or class, or the
+file for a module-level call. Each function, method and class gets `symbol_caller_count`
+(distinct callers, recursion excluded) and `symbol_single_caller_helper` (1 when a
+non-exported, non-dunder symbol has exactly one caller and it is a symbol). A callable with 2
+or more resolved call sites also gets `symbol_constant_params`: parameters every site passes
+the same literal, or none passes. Callers found only through unresolved calls are missing, so
+a private method that tests call on an instance can read as a single-caller helper. These
+metrics need edges from every file, so they are recomputed on each index. Under reuse, an
+unchanged caller's edge to a callee that moved behind a re-export stays pruned until the
+caller changes, as `references` edges do.
+
 PageRank, relevance, and symbol coupling run at query time over one snapshot:
 
 ```ts

package/dist/index.d.ts

@@ -121,7 +121,7 @@ declare class CodeGraphStore {
     listNodes(snapshotId: number, opts?: {
         includeSymbols?: boolean;
     }): GraphNode[];
-    /** See {@link listNodes}: `references` edges are the symbol layer, excluded by default. */
+    /** See {@link listNodes}: `references` and `calls` edges are the symbol layer, excluded by default. */
     listEdges(snapshotId: number, opts?: {
         includeReferences?: boolean;
     }): GraphEdge[];
@@ -137,7 +137,7 @@ declare class CodeGraphStore {
         limit?: number;
         kind?: string;
     }): TopMetricRow[];
-    /** Edges into or out of one node; `references` edges are excluded unless asked, as in {@link listEdges}. */
+    /** Edges into or out of one node; symbol-layer edges are excluded unless asked, as in {@link listEdges}. */
     listEdgesTouching(snapshotId: number, nodeId: string, opts?: {
         includeReferences?: boolean;
     }): GraphEdge[];
@@ -205,7 +205,7 @@ declare function runPrune(store: CodeGraphStore, options?: PruneOptions & {
  * index version is never reused, so a change to node/edge shape or to a metric's
  * value for the same bytes can never be carried forward from an incompatible graph.
  */
-declare const INDEX_VERSION = "0.16.0";
+declare const INDEX_VERSION = "0.18.0";
 interface IndexOptions {
     /** Roots to walk. Node ids are still rooted at the git toplevel, so importers across roots share an id space. */
     paths: string[];
@@ -448,7 +448,7 @@ declare function readSourceFiles(filePaths: readonly string[]): Promise<ReadFile
  * Everything from a prior snapshot needed to rebuild an unchanged file's
  * contribution to the graph without re-parsing it: its content fingerprint,
  * the node table (to look up external-node names), outbound edges grouped by
- * source, and the source-content metrics (loc, complexity, lcom4, ...).
+ * source file (a symbol's `calls` edges under the file declaring it), and the source-content metrics (loc, complexity, lcom4, ...).
  */
 interface ReuseBasis {
     snapshotId: number;
@@ -494,10 +494,11 @@ declare function edgeWeight(e: GraphEdge): number;
 /**
  * Drop `references` edges (C-53) whose target `symbol` node doesn't exist — an
  * aliased re-export chain, or a barrel that changed under a reused file, can
- * resolve a name to an origin that doesn't declare it. Only `references` can
- * dangle (imports/re-exports resolve to always-emitted file/external nodes);
- * metrics already guard unknown ids, so this just keeps the persisted edge set
- * clean. Mutates `edges` in place.
+ * resolve a name to an origin that doesn't declare it. `calls` edges (TP-323)
+ * are dropped the same way, which is how a callee name that maps to no symbol
+ * node is discarded rather than guessed. Only these two can dangle
+ * (imports/re-exports resolve to always-emitted file/external nodes). Mutates
+ * `edges` in place.
  */
 declare function pruneDanglingReferences(nodes: ReadonlyMap<string, GraphNode>, edges: Map<string, GraphEdge>): void;
 /**
@@ -678,6 +679,16 @@ declare const SOURCE_METRIC_NAMES: ReadonlySet<string>;
  */
 declare function computeSourceMetrics(files: readonly ParsedFile[], fileIdOf: (filePath: string) => string, symbolNamesByFile?: ReadonlyMap<string, ReadonlySet<string>>): GraphMetric[];
 
+declare const SYMBOL_METRIC_NAMES: readonly string[];
+
+/**
+ * Exception-handling metrics (TP-322), pure functions of one file's bytes. A
+ * handler is swallowed when all it does is nothing, skip, bail out empty, or
+ * log: the error stops here and no caller learns of it. Written on every file,
+ * zeros included, so percentiles over a snapshot see the clean files too.
+ */
+declare const EXCEPTION_METRIC_NAMES: readonly string[];
+
 /** How a test↔source pairing was inferred. */
 type LinkMethod = "path" | "coedit";
 interface TestSourceLink {
@@ -1102,7 +1113,7 @@ declare function aggregateMetrics(store: CodeGraphStore, snapshotId: number, opt
 }): MetricAggregate[];
 
 /** The `unit` a metric row is stored with; every row of one metric name carries the same unit. */
-type MetricUnit = "count" | "lines" | "ratio" | "days" | "percent";
+type MetricUnit = "count" | "lines" | "ratio" | "days" | "percent" | "per100loc";
 /** How file values combine into a directory; `none` means no rollup reproduces the group's true value. */
 type MetricRollup = "sum" | "max" | "mean" | "none";
 /** Which way is worse, for ranking and colouring; `neutral` makes no value judgement. */
@@ -1110,7 +1121,7 @@ type MetricDirection = "higher-worse" | "lower-worse" | "neutral";
 /** A missing row reads as zero (a sparse writer's floor) or is left out of means, percentiles, and ranks. */
 type MetricAbsence = "zero" | "exclude";
 /** The code-graph module that writes the metric, for provenance. */
-type MetricSource = "degree" | "source-metrics" | "lcom" | "dead-code" | "growth-risk" | "history" | "test-linker" | "coverage";
+type MetricSource = "degree" | "source-metrics" | "lcom" | "call-graph" | "exception-handling" | "dead-code" | "growth-risk" | "history" | "test-linker" | "coverage";
 interface MetricDescriptor {
     /** The stored name, or a template such as `churn_{w}` when {@link windowed} is set. */
     name: string;
@@ -1170,6 +1181,22 @@ interface MetricProductMaxRule {
     exclude?: string[];
     excludeRoles?: NodeRole[];
 }
+/** Flags nodes whose value sits strictly above the given percentile of the metric over every node of the kind. */
+interface MetricOutlierRule {
+    type: "metric-outlier";
+    id: string;
+    metric: string;
+    kind: NodeKind;
+    /** 50 to 100; the threshold interpolates linearly between the two nearest ranked values. */
+    percentile: number;
+    /** Fewest nodes that must carry the metric before any is judged; defaults to 20. */
+    minSample?: number;
+    /** A node is flagged only if its value also exceeds this absolute floor, guarding sparse metrics whose percentile sits at or near zero. */
+    floor?: number;
+    /** When true, rank and gate on the pool of carriers with a non-zero value only; zero-valued nodes are never flagged. */
+    rankNonZero?: boolean;
+    severity?: Severity;
+}
 interface ForbidImportRule {
     type: "forbid-import";
     id: string;
@@ -1192,7 +1219,7 @@ interface NoInternalOnlyBarrelsRule {
     /** Globs or substrings to skip, such as CLI bin entries the role classifier calls barrels. */
     exclude?: string[];
 }
-type CheckRule = MetricMaxRule | MetricMinRule | MetricProductMaxRule | ForbidImportRule | LayeredDepsRule | NoInternalOnlyBarrelsRule;
+type CheckRule = MetricMaxRule | MetricMinRule | MetricProductMaxRule | MetricOutlierRule | ForbidImportRule | LayeredDepsRule | NoInternalOnlyBarrelsRule;
 interface CheckRulesFile {
     rules: CheckRule[];
 }
@@ -1283,6 +1310,10 @@ interface ValidateRulesOptions {
 }
 declare function validateRules(input: unknown, options?: ValidateRulesOptions): readonly CheckRule[];
 
+declare const DEFAULT_OUTLIER_MIN_SAMPLE = 20;
+/** Linear interpolation between closest ranks, the definition numpy and spreadsheets use by default. */
+declare function percentileOf(values: readonly number[], percentile: number): number;
+
 /** A snapshot id, or a ref name resolved to that ref's newest snapshot. */
 type SnapshotSpec = number | string;
 interface CheckSnapshotOptions {
@@ -1588,4 +1619,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 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 };
+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, 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 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 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, percentileOf, 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 };