@ttsc/graph 0.30.3 → 0.31.0

package/src/server/runTour.ts

@@ -1,10 +1,11 @@
 import { TtscGraphMemory } from "../model/TtscGraphMemory";
+import { TtscGraphReadonly } from "../model/TtscGraphReadonly";
 import { ITtscGraphDetails } from "../structures/ITtscGraphDetails";
 import { ITtscGraphEdge } from "../structures/ITtscGraphEdge";
 import { ITtscGraphEntrypoints } from "../structures/ITtscGraphEntrypoints";
 import { ITtscGraphEvidence } from "../structures/ITtscGraphEvidence";
 import { ITtscGraphNext } from "../structures/ITtscGraphNext";
-import { ITtscGraphNode } from "../structures/ITtscGraphNode";
+import { ITtscGraphNode as NodeShape } from "../structures/ITtscGraphNode";
 import { ITtscGraphTour } from "../structures/ITtscGraphTour";
 import { ITtscGraphTrace } from "../structures/ITtscGraphTrace";
 import { exportFanIn, hasExportSurface } from "./exportSurface";
@@ -15,6 +16,8 @@ import { decoratorsOf, docOf, runDetails, signatureOf } from "./runDetails";
 import { runEntrypoints } from "./runEntrypoints";
 import { hasDeclarationBody, runTrace } from "./runTrace";
 
+type ITtscGraphNode = TtscGraphReadonly<NodeShape>;
+
 const DEFAULT_LIMIT = 5;
 const MAX_LIMIT = 5;
 /**
@@ -69,6 +72,15 @@ const TOUR_SEED_KINDS = new Set<ITtscGraphNode["kind"]>([
  * Compose a repository-orientation/code-tour answer surface from existing graph
  * operations. It returns selected symbols, flows, nearby edges, test anchors,
  * and answer anchors without reading or embedding source bodies.
+ *
+ * @evidence contracts/common.md#principled-implementation The tour combines bounded execution traces and graph-derived ranking; named seeds and graph-selected seeds retain separate shares rather than treating identifier matches as question coverage.
+ * @evidence contracts/common.md#clear-and-simple-design Existing entrypoint, trace and detail operations own their projections; this composer owns seed selection, flow overlap and orientation anchors.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Ranking is an explicit heuristic over graph facts, not a fabricated completeness claim or a lexical patch for the user's question.
+ * @evidence contracts/common.md#meaningful-documentation Native prose names the composition and body-free output; centrality documentation states the implemented heuristic rather than claiming PageRank.
+ * @evidence contracts/performance.md#efficient-algorithms Centrality scans graph candidates once, with per-candidate reach limited to four levels and not deepened once 400 nodes have been seen, so a single dense level can exceed 400 and the reach work is bounded by depth rather than by that budget; sorting costs O(V log V), while returned flows have fixed seed and trace budgets.
+ * @evidence contracts/performance.md#reuse-equivalent-work Centrality is shared through a WeakMap keyed by the owned frozen graph generation; a new graph computes its own ranks, while request-specific query alignment remains separate.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Cached rank maps remain reachable only while their graph key is reachable; request-local candidate sets and bounded flows are returned or released at completion.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation composes in-memory runners; its only source reads go through graph.source.
  */
 export function runTour(
   graph: TtscGraphMemory,
@@ -466,22 +478,8 @@ function flowStartOf(node: ITtscGraphTrace.INode): ITtscGraphTour.INode {
   };
 }
 
-function flowAnchorsOf(
-  trace: ITtscGraphTrace,
-  hops: ITtscGraphTrace.IHop[],
-  reached: ITtscGraphTrace.INode[],
-): ITtscGraphTour.IAnchor[] {
-  return uniqueAnchors([
-    ...anchorFromNode("flow start", trace.start),
-    ...reached.flatMap((node) => anchorFromNode("flow node", node)),
-    ...hops.flatMap((hop) =>
-      anchorFromEvidence("flow edge", `${hop.from} -> ${hop.to}`, hop.evidence),
-    ),
-  ]);
-}
-
 /**
- * The words of the question that could name code: the ranking's own terms.
+ * Identifier terms from the caller's symbol guesses used to align ranking.
  *
  * A question about TypeORM says "TypeORM", which splits into `type` and `orm`,
  * and both are inside the project's own name — they say nothing about which
@@ -526,23 +524,11 @@ function rankedTourSeeds(
 }
 
 /**
- * How central a symbol is to running this codebase, as one standard algorithm
- * instead of a ledger of hand-tuned bonuses.
+ * Rank a seed by normalized publication, bounded execution reach and fan-in,
+ * then apply the caller's identifier alignment and broad-tour damping.
  *
- * This score used to be a sum: so many points for the symbol's kind, so many
- * per log of each degree, a capped term for its reach, another for what its
- * package exports, another for what the tests call — nine signals, each with a
- * multiplier and a cap that someone picked while watching a benchmark. Word
- * lists in numeric form. All of it was approximating one question the graph can
- * answer exactly: _if you use what this package publishes, what runs?_
- *
- * Personalized PageRank answers it. The walker starts on the export surface —
- * the symbols the package puts on the wire, members included — and follows the
- * execution edges, crossing from an abstract declaration to its implementations
- * the way `runTrace` does. Public entries hold mass because the walk starts on
- * them; the spine holds mass because every path runs through it. One damping
- * constant, 0.85, from the literature — the same algorithm aider's repo map
- * ranks symbols with.
+ * This is a graph-structure heuristic, not PageRank or proof that a seed
+ * answers the question. `computeCentrality` owns the underlying score.
  */
 function tourSeedScore(
   graph: TtscGraphMemory,
@@ -561,6 +547,10 @@ function tourSeedScore(
 const CENTRALITY_SCALE = 100;
 /** Execution reach is walked this deep and no further. */
 const REACH_DEPTH = 4;
+/**
+ * Reach stops descending to another level once this many nodes are seen. The
+ * check runs between levels, so one level may add more than this budget.
+ */
 const REACH_NODE_BUDGET = 400;
 /** Invocation: the edges that mean "this makes that run". */
 const INVOKE_KINDS = new Set<string>(["calls", "instantiates", "renders"]);
@@ -764,6 +754,25 @@ function isTourTraceNode(
   return graph.node(node.id)?.closure !== true && !isNoisePath(node.file);
 }
 
+/**
+ * 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),
+  );
+}
+
 /**
  * The hops a flow keeps, and the hops it would keep if the cut were not
  * applied.
@@ -785,25 +794,6 @@ function isTourTraceNode(
  * 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[],
@@ -895,16 +885,6 @@ function executionDegree(
   return { in: incoming, out: outgoing };
 }
 
-/**
- * What the declaration is, scored by what it does rather than how it was
- * written. `export const parse = (input) => ...` is a function that happens to
- * be bound to a name, and the checker sees it call things; scoring it eight
- * points against a method's twenty-eight is a bias toward one syntax, and it
- * cost zod its own public API — `parse` and `safeParse`, both const arrows,
- * lost their tour seats to `ZodType.safeParse`, a method of the previous
- * major.
- */
-
 /**
  * How many modules put a symbol on the wire — counting the one that owns it.
  *
@@ -937,25 +917,6 @@ function ownerOf(graph: TtscGraphMemory, id: string): string | undefined {
   return undefined;
 }
 
-/**
- * What a user of this package can call, as the graph knows it.
- *
- * This used to pay for an English verb anywhere in the name — `create`,
- * `parse`, `render`, `subscribe` — and for a class whose name contained `app`,
- * `server` or `factory`. Neither is a fact about the code. They are a guess
- * about the language its authors happened to write in, and a codebase that
- * names its entry `起動` or `mk` or `boot` is one the guess is simply wrong
- * about. It was also wrong in English: `onRenderTracked` is a devtools hook and
- * it took the bonus for the "render" inside it, outranking `track`, the
- * function it is named after.
- *
- * Two facts say the same thing without reading a word of the name. The package
- * _publishes_ this symbol — that is its export surface, counted in
- * {@link exportFanIn} — and it is a _callable_, so publishing it is publishing
- * something to run. A user calls what a package exports and what a package
- * exports to be called.
- */
-
 function queryMatchScore(node: ITtscGraphNode, terms: string[]): number {
   return (
     matchedQueryTerms(node, terms).size * 8 +
@@ -998,8 +959,9 @@ function matchedTerms(words: string[], terms: string[]): Set<string> {
  * It picks `count` of them, not all of them. Ordering every candidate cost
  * O(n²) — on VS Code, where tens of thousands of symbols score above zero, one
  * tour spent six minutes ranking seeds it then threw away, because the caller
- * keeps only the first few. Stopping at `count` makes the cover O(count · n),
- * and the picks it does make are the same ones.
+ * keeps only the first few. Stopping at `count` makes the cover O(count · n)
+ * candidate visits, each comparing against the picks so far, and the picks it
+ * does make are the same ones.
  */
 function diverseTourSeeds<
   T extends {