@ttsc/graph 0.18.4 → 0.19.1

package/src/server/runTrace.ts

@@ -3,20 +3,41 @@ import { ITtscGraphEdge } from "../structures/ITtscGraphEdge";
 import { ITtscGraphEvidence } from "../structures/ITtscGraphEvidence";
 import { ITtscGraphNode } from "../structures/ITtscGraphNode";
 import { ITtscGraphTrace } from "../structures/ITtscGraphTrace";
-import { accessAliasesFor } from "./accessAliases";
 import { isExternalNode, isTestPath } from "./pathPolicy";
 import { resolveGraphHandle } from "./resolveHandle";
-import { resultGuide, resultNext } from "./resultGuide";
-import { edgeEvidenceOf, edgeEvidenceTextOf, signatureOf } from "./runDetails";
+import { IRunnerOutput, resultNext } from "./resultNext";
+import { edgeEvidenceOf, signatureOf } from "./runDetails";
 
-const DEFAULT_DEPTH = 2;
-const DEFAULT_MAX_NODES = 6;
-const MAX_OPEN_DEPTH = 2;
-const MAX_OPEN_NODES = 8;
+const DEFAULT_DEPTH = 3;
+const DEFAULT_MAX_NODES = 12;
+// An open trace used to stop at two hops and eight nodes, whatever depth the
+// caller asked for. A question that spans a runtime chain — a state change
+// through tracking, scheduling, rendering, then patching — is that chain hop by
+// hop, so the model re-issued a trace per hop and paid a round trip for each: a
+// single vue question spent twenty-six calls walking a flow the graph could have
+// walked once. The cap now follows the chain instead of cutting it.
+const MAX_OPEN_DEPTH = 8;
+const MAX_OPEN_NODES = 32;
 const MAX_IMPACT_DEPTH = 4;
 const MAX_IMPACT_NODES = 16;
 const MAX_HOPS_PER_NODE = 2;
-const MAX_STEPS = 6;
+const MAX_STEPS = 12;
+const EXECUTION_KINDS = new Set<string>([
+  "calls",
+  "instantiates",
+  "accesses",
+  "renders",
+]);
+const DISPATCH_KINDS = new Set<string>(["overrides", "implements"]);
+// An interface the codebase implements everywhere — a disposable, a listener, a
+// lifecycle hook — is not a step in one flow, and naming its implementors is a
+// dump of the codebase rather than an answer. Past this many, the declaration
+// stays a leaf and `details` answers `implementedBy` for a caller that wants the
+// list. The cut is the graph's existing definition of a hub (see
+// `isSharedUtility`): across the benchmark corpus it follows 84–100% of dispatch
+// sites per project and refuses only the genuinely polymorphic ones (zod's
+// 36-way schema interface, VS Code's 533-way disposable).
+const DISPATCH_HUB = 12;
 
 /**
  * Breadth-first trace along the dependency graph. Structural
@@ -28,7 +49,7 @@ const MAX_STEPS = 6;
 export function runTrace(
   graph: TtscGraphMemory,
   props: ITtscGraphTrace.IRequest,
-): ITtscGraphTrace {
+): IRunnerOutput<ITtscGraphTrace> {
   const direction = props.direction ?? "forward";
   const focus = props.focus ?? "all";
   const impact = direction === "impact";
@@ -54,34 +75,32 @@ export function runTrace(
   const start = resolveGraphHandle(graph, props.from);
   if (start.candidates) {
     return {
-      type: "trace",
-      direction,
-      hops: [],
-      reached: [],
-      truncated: false,
+      result: {
+        type: "trace",
+        direction,
+        hops: [],
+        reached: [],
+        truncated: false,
+        candidates: start.candidates.map((n) => summary(graph, n)),
+      },
       next: resultNext(
         "clarify",
-        "The start handle is ambiguous; choose one returned candidate.",
+        "The start handle is ambiguous: it matched several candidates, one of which names the trace.",
       ),
-      guide: resultGuide(
-        "Disambiguate with the returned candidates, or ask the user for the intended symbol.",
-      ),
-      candidates: start.candidates.map((n) => summary(graph, n)),
     };
   }
   if (start.node === undefined) {
     return {
-      type: "trace",
-      direction,
-      hops: [],
-      reached: [],
-      truncated: false,
+      result: {
+        type: "trace",
+        direction,
+        hops: [],
+        reached: [],
+        truncated: false,
+      },
       next: resultNext(
-        "clarify",
-        "The start handle did not resolve in the compiler graph.",
-      ),
-      guide: resultGuide(
-        "The start symbol was not resolved; answer that the graph has no trace from this handle.",
+        "outside",
+        "The start handle did not resolve in the graph, so it holds no trace from this handle.",
       ),
     };
   }
@@ -95,24 +114,34 @@ export function runTrace(
       hops: [],
       reached: [],
       truncated: false,
-      next: resultNext(
-        "answer",
-        "The path result is the structural flow answer; cite path nodes and evidence ranges.",
-      ),
-      guide: resultGuide(
-        "Use the returned path, hops, and evidence ranges as the flow answer.",
-      ),
     };
+    const pathNext = resultNext(
+      "answer",
+      "The path result is the structural flow: its path nodes and evidence ranges are what the graph holds between the two ends.",
+    );
     const target = resolveGraphHandle(graph, props.to);
     if (target.candidates) {
       return {
-        ...base,
-        start: summary(graph, start.node),
-        candidates: target.candidates.map((n) => summary(graph, n)),
+        result: {
+          ...base,
+          start: summary(graph, start.node),
+          candidates: target.candidates.map((n) => summary(graph, n)),
+        },
+        next: resultNext(
+          "inspect",
+          "The target names several nodes; re-trace with the id of the one the question means.",
+          "trace",
+        ),
       };
     }
     if (target.node === undefined) {
-      return { ...base, start: summary(graph, start.node) };
+      return {
+        result: { ...base, start: summary(graph, start.node) },
+        next: resultNext(
+          "outside",
+          "The target resolved to no node, so the graph holds no path to it.",
+        ),
+      };
     }
     const found = findPath(
       graph,
@@ -124,13 +153,42 @@ export function runTrace(
     );
     const path = found?.path ?? [];
     const hops = found?.hops ?? [];
+    const junctions =
+      hops.length > 0
+        ? []
+        : junctionsBetween(graph, start.node.id, target.node.id, focus);
     return {
-      ...base,
-      start: summary(graph, start.node),
-      target: summary(graph, target.node),
-      hops,
-      path: path.map((node, i) => summary(graph, node, i, false, true)),
-      steps: traceSteps(graph, hops),
+      result: {
+        ...base,
+        start: summary(graph, start.node),
+        target: summary(graph, target.node),
+        hops,
+        path: path.map((node, i) => summary(graph, node, i, false, true)),
+        steps: traceSteps(graph, hops),
+        ...(junctions.length > 0 ? { junctions } : {}),
+      },
+      // An empty path is a fact, not an answer, and the old message called it
+      // one: "its path nodes and evidence ranges are what the graph holds
+      // between the two ends" — of a result that held nothing. The two ends do
+      // not call each other, which in an event-driven codebase is the common
+      // case: a pointer handler emits, an emitter's `emit()` runs listeners a
+      // registration put in an array, and no call edge crosses that array. The
+      // callers of the target are the way across, and the graph has them, so
+      // say which call to make instead of handing back an empty result dressed
+      // as the answer. Excalidraw's tour spent eleven calls finding this out.
+      next:
+        hops.length > 0
+          ? pathNext
+          : junctions.length > 0
+            ? resultNext(
+                "inspect",
+                "No call path runs between the two ends — a callback stands between them (an event emitter, a subscription, a lifecycle hook), and no call edge crosses one. `junctions` names the symbols both ends touch, which is the seam: trace the junction to see who registers on it and who fires it.",
+                "trace",
+              )
+            : resultNext(
+                "outside",
+                "No call path runs from the start to the target and they touch nothing in common, so the graph holds no connection between them.",
+              ),
     };
   }
 
@@ -151,7 +209,9 @@ export function runTrace(
       }
       const edges = orderedEdges(
         graph,
-        reverse ? graph.incoming(id) : graph.outgoing(id),
+        reverse
+          ? graph.incoming(id)
+          : [...graph.outgoing(id), ...dispatchEdges(graph, id, focus)],
         direction,
         reverse,
       );
@@ -169,11 +229,6 @@ export function runTrace(
         };
         const evidence = edgeEvidenceOf(edge);
         if (evidence !== undefined) hop.evidence = evidence;
-        const aliases = accessAliasesFor(
-          graph.node(edge.to),
-          edgeEvidenceTextOf(edge),
-        );
-        if (aliases !== undefined) hop.aliases = aliases;
         // A back-edge to the start or an already-reached node: record the hop;
         // its endpoints are already represented.
         if (visited.has(otherId)) {
@@ -201,20 +256,19 @@ export function runTrace(
   }
 
   return {
-    type: "trace",
-    start: summary(graph, start.node),
-    direction,
-    hops,
-    reached: [...reached.values()],
-    steps: traceSteps(graph, hops),
+    result: {
+      type: "trace",
+      start: summary(graph, start.node),
+      direction,
+      hops,
+      reached: [...reached.values()],
+      steps: traceSteps(graph, hops),
+      truncated,
+    },
     next: resultNext(
       "answer",
-      "Steps, hops, reached nodes, and evidence ranges are the flow answer surface.",
+      "Steps, hops, reached nodes, and evidence ranges are the flow the graph holds from this start.",
     ),
-    guide: resultGuide(
-      "Use steps, hops, reached nodes, and evidence ranges as the flow answer or reading-list anchor.",
-    ),
-    truncated,
   };
 }
 
@@ -231,9 +285,7 @@ function traceSteps(
       hop.evidence === undefined
         ? ""
         : ` at ${hop.evidence.file}:${hop.evidence.startLine}`;
-    const aliases =
-      hop.aliases === undefined ? "" : ` aliases ${hop.aliases.join(", ")}`;
-    return `${lhs} -[${hop.kind}${evidence}${aliases}]-> ${rhs}`;
+    return `${lhs} -[${hop.kind}${evidence}]-> ${rhs}`;
   });
 }
 
@@ -242,6 +294,94 @@ function traceSteps(
  * structural) forward edges, breadth-first, or null when `targetId` is not
  * reachable within maxDepth. Returns the nodes in order and the hops between.
  */
+/**
+ * The symbols both ends of an unreachable path touch.
+ *
+ * A call graph cannot cross a callback: the registration hands a listener to an
+ * emitter, and `emit()` runs whatever the registration put in an array. But the
+ * registration and the emit both reference the emitter, and those are edges the
+ * checker resolved — Excalidraw's `App.componentDidMount` and its
+ * `Store.emitDurableIncrement` both touch `Store.onDurableIncrementEmitter`,
+ * which is the exact seam the path walk stops at.
+ *
+ * So when the path is empty, name what the two ends share. It is not a path and
+ * the result says so; it is the symbol to inspect next, with the two edges that
+ * make it the seam. Nothing here is matched or inferred: a junction is an edge
+ * from each end to the same node.
+ */
+function junctionsBetween(
+  graph: TtscGraphMemory,
+  startId: string,
+  targetId: string,
+  focus: ITtscGraphTrace.IRequest["focus"],
+): ITtscGraphTrace.IJunction[] {
+  const startTouches = touchedBy(graph, startId, focus);
+  const targetTouches = touchedBy(graph, targetId, focus);
+  const out: ITtscGraphTrace.IJunction[] = [];
+  for (const [id, fromStart] of startTouches) {
+    const fromTarget = targetTouches.get(id);
+    if (fromTarget === undefined) continue;
+    const node = graph.node(id);
+    if (node === undefined || node.kind === "file" || isExternalNode(node))
+      continue;
+    out.push({
+      id: node.id,
+      name: node.qualifiedName ?? node.name,
+      kind: node.kind,
+      file: node.file,
+      ...(node.evidence?.startLine !== undefined
+        ? { line: node.evidence.startLine }
+        : {}),
+      fromStart,
+      fromTarget,
+    });
+  }
+  // A shared leaf helper is noise; a shared emitter, store, or registry is the
+  // seam. What both ends hold onto rather than merely call is the thing standing
+  // between them, so state comes first.
+  out.sort((a, b) => junctionRank(b) - junctionRank(a));
+  return out.slice(0, MAX_JUNCTIONS);
+}
+
+const MAX_JUNCTIONS = 4;
+
+/** How much a shared symbol looks like a seam rather than a shared utility. */
+function junctionRank(junction: ITtscGraphTrace.IJunction): number {
+  let rank = 0;
+  if (junction.kind === "variable" || junction.kind === "property") rank += 3;
+  if (junction.fromStart.kind === "accesses") rank += 2;
+  if (junction.fromTarget.kind === "accesses") rank += 2;
+  return rank;
+}
+
+/** Every node an end touches, with the edge that touches it. */
+function touchedBy(
+  graph: TtscGraphMemory,
+  id: string,
+  focus: ITtscGraphTrace.IRequest["focus"],
+): Map<string, ITtscGraphTrace.IJunctionEdge> {
+  const touched = new Map<string, ITtscGraphTrace.IJunctionEdge>();
+  for (const edge of graph.outgoing(id)) {
+    if (!traversable(edge.kind, focus)) continue;
+    if (!touched.has(edge.to))
+      touched.set(edge.to, {
+        kind: edge.kind,
+        outgoing: true,
+        ...(edge.evidence !== undefined ? { evidence: edge.evidence } : {}),
+      });
+  }
+  for (const edge of graph.incoming(id)) {
+    if (!traversable(edge.kind, focus)) continue;
+    if (!touched.has(edge.from))
+      touched.set(edge.from, {
+        kind: edge.kind,
+        outgoing: false,
+        ...(edge.evidence !== undefined ? { evidence: edge.evidence } : {}),
+      });
+  }
+  return touched;
+}
+
 function findPath(
   graph: TtscGraphMemory,
   startId: string,
@@ -259,7 +399,6 @@ function findPath(
       via: string;
       kind: string;
       evidence?: ITtscGraphEvidence;
-      evidenceText?: string;
     }
   >();
   const visited = new Set<string>([startId]);
@@ -268,7 +407,10 @@ function findPath(
     const next: Array<{ id: string; depth: number }> = [];
     for (const { id, depth } of queue) {
       if (depth >= maxDepth) continue;
-      for (const edge of graph.outgoing(id)) {
+      for (const edge of [
+        ...graph.outgoing(id),
+        ...dispatchEdges(graph, id, focus),
+      ]) {
         if (!traversable(edge.kind, focus)) continue;
         const otherId = edge.to;
         if (visited.has(otherId)) continue;
@@ -281,7 +423,6 @@ function findPath(
           via: id,
           kind: edge.kind,
           evidence,
-          evidenceText: edgeEvidenceTextOf(edge),
         });
         if (otherId === targetId) {
           const ids: string[] = [otherId];
@@ -309,8 +450,6 @@ function findPath(
             };
             if (parentEdge?.evidence !== undefined)
               hop.evidence = parentEdge.evidence;
-            const aliases = accessAliasesFor(node, parentEdge?.evidenceText);
-            if (aliases !== undefined) hop.aliases = aliases;
             hops.push(hop);
           }
           return { path, hops };
@@ -417,6 +556,55 @@ function summary(
   return out;
 }
 
+/**
+ * The implementations a call that lands here actually runs.
+ *
+ * A call resolved to an abstract method or an interface member lands on a
+ * declaration with no body. A forward walk stops there — and the code that
+ * executes is one _incoming_ `overrides`/`implements` edge away, which no
+ * forward traversal crosses. NestJS's whole request pipeline sits behind one:
+ * `ContextCreator.createContext` calls the abstract `createConcreteContext`,
+ * and the guards, pipes and interceptors contexts are its overrides, so the
+ * graph said a request reaches an abstract declaration and stops, and the guard
+ * it runs was reachable from nothing but its own unit test. Between 1% and 8%
+ * of every called symbol in the benchmark projects is such a declaration; every
+ * codebase with an abstract base, a strategy, an adapter or a visitor has
+ * them.
+ *
+ * So the walk dispatches: a called declaration with no body continues in the
+ * implementations that have one, as a `dispatches` hop cited at the
+ * implementation — which is the fact, since the call site named the base and
+ * the runtime lands in the override.
+ */
+function dispatchEdges(
+  graph: TtscGraphMemory,
+  id: string,
+  focus: ITtscGraphTrace.IRequest["focus"],
+): ITtscGraphEdge[] {
+  if (focus === "types" || hasExecutionBody(graph, id)) return [];
+  const out: ITtscGraphEdge[] = [];
+  for (const edge of graph.incoming(id)) {
+    if (!DISPATCH_KINDS.has(edge.kind)) continue;
+    const implementation = graph.node(edge.from);
+    if (implementation === undefined || !hasExecutionBody(graph, edge.from))
+      continue;
+    out.push({
+      from: id,
+      to: edge.from,
+      kind: "dispatches",
+      ...(edge.evidence !== undefined ? { evidence: edge.evidence } : {}),
+    });
+  }
+  return out.length >= DISPATCH_HUB ? [] : out;
+}
+
+/** Whether the declaration has a body: something it calls, reads, or renders. */
+function hasExecutionBody(graph: TtscGraphMemory, id: string): boolean {
+  for (const edge of graph.outgoing(id))
+    if (EXECUTION_KINDS.has(edge.kind)) return true;
+  return false;
+}
+
 /** An edge the trace should follow: a real dependency, not a structural edge. */
 function traversable(
   kind: string,
@@ -425,6 +613,7 @@ function traversable(
   if (kind === "contains" || kind === "exports" || kind === "imports") {
     return false;
   }
+  if (kind === "dispatches") return focus !== "types";
   if (focus === "execution") {
     return (
       kind === "calls" ||
@@ -449,6 +638,11 @@ function edgeKindRank(kind: string): number {
   switch (kind) {
     case "calls":
       return 0;
+    // Where a call landed on a declaration, the implementation it dispatches to
+    // is the continuation of that call, not an afterthought behind the
+    // declaration's type references.
+    case "dispatches":
+      return 1;
     case "instantiates":
       return 1;
     case "renders":