@titan-design/code-graph 0.7.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
@@ -166,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.
 
@@ -342,6 +342,23 @@ Python, and are written on every function or file, zeros included:
   `...`, `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.17.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;
 /**
@@ -1120,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" | "exception-handling" | "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;
@@ -1190,6 +1191,10 @@ interface MetricOutlierRule {
     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 {