@ttsc/graph 0.19.2 → 0.20.0

package/src/server/runTour.ts

@@ -13,7 +13,7 @@ import { resolveGraphHandle } from "./resolveHandle";
 import { IRunnerOutput, resultNext } from "./resultNext";
 import { decoratorsOf, docOf, runDetails, signatureOf } from "./runDetails";
 import { runEntrypoints } from "./runEntrypoints";
-import { runTrace } from "./runTrace";
+import { hasDeclarationBody, runTrace } from "./runTrace";
 
 const DEFAULT_LIMIT = 5;
 const MAX_LIMIT = 5;
@@ -110,6 +110,24 @@ export function runTour(
   // so keep the first and walk on to one that tells something else.
   const primaryFlow: ITtscGraphTour.IFlow[] = [];
   const told: Set<string>[] = [];
+  // A flow whose every hop the hub cut would remove is demoted, not deleted.
+  // Deleting it is what #809 reports: eleven callers kept the flow and a
+  // twelfth erased it, so the tour answered a question about a terminal action
+  // with nothing. Telling it regardless is what the cut was written against: a
+  // one-line wrapper around a logger became one of the tour's four flows.
+  //
+  // Demotion settles both without a rule that can tell a commit from a logger,
+  // which the graph cannot: the flow is held back, and told only if the tour
+  // finishes with nothing else to say. The first such candidate is kept because
+  // the seeds arrive ranked.
+  let demoted:
+    | {
+        start: ITtscGraphTrace.INode;
+        hops: ITtscGraphTrace.IHop[];
+        reached: ITtscGraphTrace.INode[];
+        truncated: boolean;
+      }
+    | undefined;
 
   for (const id of flowSeedIdsOf(
     tourSeedsOf(
@@ -132,11 +150,28 @@ export function runTour(
     }).result;
     const start = trace.start;
     if (start === undefined) continue;
-    const hops = trace.hops.filter((hop) => isTourHop(graph, hop));
-    if (hops.length === 0) continue;
-    const reached = trace.reached.filter((node) =>
-      isTourTraceNode(graph, node),
-    );
+    const { kept: hops, demotable } = tourHops(graph, trace.hops);
+    if (hops.length === 0) {
+      // Held back under the same rule the published path uses: a candidate that
+      // reached nothing is not a flow, so it is not worth holding either.
+      const demotedReach =
+        demotable.length === 0 ? [] : reachedOf(graph, trace, demotable);
+      if (demoted === undefined && demotedReach.length > 0)
+        demoted = {
+          start,
+          hops: demotable,
+          reached: demotedReach,
+          truncated: trace.truncated === true,
+        };
+      continue;
+    }
+    const reached = reachedOf(graph, trace, hops);
+    // A flow that reached nothing is not a flow. It can still have a hop —
+    // `runTrace` records a back-edge to the start without adding a node,
+    // because the start travels separately — so `hops.length` does not answer
+    // this. What a flow is for is the handles a caller goes on with, and this
+    // one has none.
+    if (reached.length === 0) continue;
     const landed = new Set(reached.map((node) => node.id));
     if (told.some((earlier) => overlaps(landed, earlier))) continue;
     told.push(landed);
@@ -160,6 +195,16 @@ export function runTour(
     });
   }
 
+  if (primaryFlow.length === 0 && demoted !== undefined)
+    primaryFlow.push({
+      start: flowStartOf(demoted.start),
+      steps: demoted.hops
+        .slice(0, MAX_FLOW_ANCHORS)
+        .map((hop) => flowStepOf(graph, hop)),
+      reached: demoted.reached.map(traceNodeOf),
+      ...(demoted.truncated ? { truncated: true } : {}),
+    });
+
   const details =
     seedIds.length === 0
       ? undefined
@@ -354,8 +399,8 @@ function graphNodeOf(
   node: ITtscGraphNode,
 ): ITtscGraphTour.INode {
   const span = node.implementation ?? node.evidence;
-  const signature = signatureOf(graph.project, node);
-  const doc = docOf(graph.project, node);
+  const signature = signatureOf(graph, node);
+  const doc = docOf(graph, node);
   const decorators = decoratorsOf(node);
   return {
     id: node.id,
@@ -561,13 +606,17 @@ function computeCentrality(graph: TtscGraphMemory): Map<string, number> {
 
   const invoked = (id: string): string[] => {
     const out: string[] = [];
-    let hasBody = false;
     for (const edge of graph.outgoing(id)) {
-      if (!INVOKE_KINDS.has(edge.kind)) continue;
-      hasBody = true;
-      out.push(edge.to);
+      if (INVOKE_KINDS.has(edge.kind)) out.push(edge.to);
     }
-    if (!hasBody) {
+    // Whether the declaration has a body is a declaration fact, not an edge
+    // count. A concrete method that returns a literal, does local arithmetic or
+    // throws has a body and no invocation edges at all, and counting edges
+    // ranked it as though it were an abstract member — then walked its
+    // implementations as if the call had to dispatch. `runTrace` stopped using
+    // that proxy in #828; this was the second copy of it.
+    const node = graph.node(id);
+    if (node !== undefined && !hasDeclarationBody(graph, node)) {
       for (const edge of graph.incoming(id)) {
         if (DISPATCH_KINDS.has(edge.kind)) out.push(edge.from);
       }
@@ -691,11 +740,20 @@ function flowSeedIdsOf(seeds: ITtscGraphNode[]): string[] {
  * twice. Overlap is measured against the smaller flow, so a short chain fully
  * contained in a longer one counts as told, which is what a sibling entry
  * (`parse` beside `safeParse`) actually is.
+ *
+ * Neither side matches when it is empty, and the two are empty for different
+ * reasons. An empty CANDIDATE reached nothing, so it is not a flow at all and
+ * the caller settles it before asking here. An empty TOLD would mean the tour
+ * had published a flow that reached nothing; it cannot now, and while it could,
+ * this function reported every later candidate as a synonym of that emptiness.
+ * One directly self-recursive function — a retry loop, a tree walk, a parser's
+ * descent — produced exactly that set, and the tour lost every real flow ranked
+ * after it.
  */
 function overlaps(candidate: Set<string>, told: Set<string>): boolean {
+  if (candidate.size === 0 || told.size === 0) return false;
   const smaller = candidate.size <= told.size ? candidate : told;
   const larger = smaller === candidate ? told : candidate;
-  if (smaller.size === 0) return true;
   let shared = 0;
   for (const id of smaller) if (larger.has(id)) shared++;
   return shared / smaller.size >= FLOW_OVERLAP;
@@ -705,13 +763,61 @@ function isTourTraceNode(
   graph: TtscGraphMemory,
   node: ITtscGraphTrace.INode,
 ): boolean {
-  return (
-    graph.node(node.id)?.closure !== true &&
-    !isNoisePath(node.file) &&
-    !isSharedUtility(graph, node.id)
+  return graph.node(node.id)?.closure !== true && !isNoisePath(node.file);
+}
+
+/**
+ * The hops a flow keeps, and the hops it would keep if the cut were not
+ * applied.
+ *
+ * Degree cannot tell a logger from a database commit. Both are called from many
+ * sites and call nothing onward, so no threshold on `isSharedUtility` separates
+ * the noise the cut exists to remove from the point where a runtime flow does
+ * its work. Rather than guess, this returns both readings and lets the caller
+ * demote instead of delete.
+ *
+ * A hub the flow continues past always keeps its inbound hop. Dropping it left
+ * the outbound step narrating a chain from a node the same flow reported it
+ * never reached, which is incoherent whatever that node means, so this one is
+ * not a judgement call and is applied unconditionally.
+ *
+ * `demotable` is non-empty exactly when the cut would empty the flow — when
+ * every hop it has lands on a hub. That is the shape the caller holds back and
+ * tells only if the tour finishes with nothing else, so a wrapper around a
+ * logger never displaces a real chain and a lone terminal action is never
+ * erased.
+ */
+/**
+ * The nodes a flow reached, derived from the hops that survived.
+ *
+ * Deriving it rather than filtering it beside them is what makes a dangling
+ * step impossible: a step can only name endpoints of a kept hop, and every such
+ * endpoint is here. Filtering the two independently is what let a step narrate
+ * a chain from a node the same flow reported it had never reached.
+ */
+function reachedOf(
+  graph: TtscGraphMemory,
+  trace: ITtscGraphTrace,
+  hops: readonly ITtscGraphTrace.IHop[],
+): ITtscGraphTrace.INode[] {
+  const touched = new Set(hops.flatMap((hop) => [hop.from, hop.to]));
+  return trace.reached.filter(
+    (node) => touched.has(node.id) && isTourTraceNode(graph, node),
   );
 }
 
+function tourHops(
+  graph: TtscGraphMemory,
+  hops: readonly ITtscGraphTrace.IHop[],
+): { kept: ITtscGraphTrace.IHop[]; demotable: ITtscGraphTrace.IHop[] } {
+  const eligible = hops.filter((hop) => isTourHop(graph, hop));
+  const departures = new Set(eligible.map((hop) => hop.from));
+  const kept = eligible.filter(
+    (hop) => !isSharedUtility(graph, hop.to) || departures.has(hop.to),
+  );
+  return { kept, demotable: kept.length === 0 ? eligible : [] };
+}
+
 function isTourHop(graph: TtscGraphMemory, hop: ITtscGraphTrace.IHop): boolean {
   const from = graph.node(hop.from);
   const to = graph.node(hop.to);
@@ -722,8 +828,7 @@ function isTourHop(graph: TtscGraphMemory, hop: ITtscGraphTrace.IHop): boolean {
     to.closure !== true &&
     !STRUCTURAL_KINDS.has(hop.kind) &&
     !isNoisePath(from.file) &&
-    !isNoisePath(to.file) &&
-    !isSharedUtility(graph, hop.to)
+    !isNoisePath(to.file)
   );
 }
 
@@ -739,8 +844,15 @@ function isTourHop(graph: TtscGraphMemory, hop: ITtscGraphTrace.IHop): boolean {
 // "top few percent of hubs" band regardless of project size, while the absolute
 // floor makes it a no-op on small graphs that have no genuine hub. The `out <= 1`
 // guard keeps thin pass-throughs out but never prunes a real branching step.
+//
+// The fan-in counted is EXECUTION fan-in. `realDegree` also counts `type_ref`,
+// `extends`, `decorates`, and `tests`, and a widely referenced type or a
+// widely decorated symbol is not a call hub: a `Config` class named in twelve
+// parameter positions and constructed once was read as a hub and cut out of the
+// flow that constructs it. Popularity as a name is not popularity as a call.
 function isSharedUtility(graph: TtscGraphMemory, id: string): boolean {
-  return realDegree(graph, id).in >= 12 && executionDegree(graph, id).out <= 1;
+  const execution = executionDegree(graph, id);
+  return execution.in >= 12 && execution.out <= 1;
 }
 
 function flowStepOf(graph: TtscGraphMemory, hop: ITtscGraphTrace.IHop): string {
@@ -767,24 +879,6 @@ function touchesClosure(graph: TtscGraphMemory, id: string): boolean {
   return graph.node(id)?.closure === true;
 }
 
-function realDegree(
-  graph: TtscGraphMemory,
-  id: string,
-): {
-  in: number;
-  out: number;
-} {
-  let incoming = 0;
-  let outgoing = 0;
-  for (const edge of graph.outgoing(id))
-    if (!STRUCTURAL_KINDS.has(edge.kind) && !touchesClosure(graph, edge.to))
-      outgoing++;
-  for (const edge of graph.incoming(id))
-    if (!STRUCTURAL_KINDS.has(edge.kind) && !touchesClosure(graph, edge.from))
-      incoming++;
-  return { in: incoming, out: outgoing };
-}
-
 function executionDegree(
   graph: TtscGraphMemory,
   id: string,