@titan-design/code-graph 0.6.0 → 0.7.0

package/README.md

@@ -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.
 
@@ -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,22 @@ 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`).
+
 PageRank, relevance, and symbol coupling run at query time over one snapshot:
 
 ```ts

package/dist/index.d.ts

@@ -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.17.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[];
@@ -678,6 +678,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 +1112,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 +1120,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" | "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 +1180,18 @@ 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;
+    severity?: Severity;
+}
 interface ForbidImportRule {
     type: "forbid-import";
     id: string;
@@ -1192,7 +1214,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 +1305,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 +1614,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 };