@ttsc/graph 0.19.2 → 0.20.0

package/src/server/runTrace.ts

@@ -3,7 +3,7 @@ import { ITtscGraphEdge } from "../structures/ITtscGraphEdge";
 import { ITtscGraphEvidence } from "../structures/ITtscGraphEvidence";
 import { ITtscGraphNode } from "../structures/ITtscGraphNode";
 import { ITtscGraphTrace } from "../structures/ITtscGraphTrace";
-import { isExternalNode, isTestPath } from "./pathPolicy";
+import { isDeclarationFile, isExternalNode, isTestPath } from "./pathPolicy";
 import { resolveGraphHandle } from "./resolveHandle";
 import { IRunnerOutput, resultNext } from "./resultNext";
 import { edgeEvidenceOf, signatureOf } from "./runDetails";
@@ -20,15 +20,23 @@ const MAX_OPEN_DEPTH = 8;
 const MAX_OPEN_NODES = 32;
 const MAX_IMPACT_DEPTH = 4;
 const MAX_IMPACT_NODES = 16;
+// Path mode walks further than an open trace because it is looking for one
+// named end, not building a picture. The cap is the one the request contract
+// publishes for path mode.
+const MAX_PATH_DEPTH = 12;
 const MAX_HOPS_PER_NODE = 2;
 const MAX_STEPS = 12;
-const EXECUTION_KINDS = new Set<string>([
-  "calls",
-  "instantiates",
-  "accesses",
-  "renders",
-]);
 const DISPATCH_KINDS = new Set<string>(["overrides", "implements"]);
+// A declaration whose kind is a type surface never carries a body, and an
+// external leaf carries one the graph deliberately does not hold.
+const BODYLESS_KINDS = new Set<string>([
+  "interface",
+  "type",
+  "external_symbol",
+]);
+// `abstract` and `declare` are the two keywords that take the body away from a
+// declaration that would otherwise have to have one.
+const BODYLESS_MODIFIERS = new Set<string>(["abstract", "declare"]);
 // 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
@@ -143,18 +151,24 @@ export function runTrace(
         ),
       };
     }
-    const found = findPath(
+    const pathDepth = bound(props.maxDepth, MAX_PATH_DEPTH, 1, MAX_PATH_DEPTH);
+    const search = findPath(
       graph,
       start.node.id,
       target.node.id,
-      bound(props.maxDepth, 12, 1, 12),
+      pathDepth,
       focus,
       includeExternal,
     );
-    const path = found?.path ?? [];
-    const hops = found?.hops ?? [];
+    const hasPath = search.found !== undefined;
+    const path = search.found?.path ?? [];
+    const hops = search.found?.hops ?? [];
+    // Junctions explain an absence, so they are only computed once absence is
+    // established: a walk the depth bound stopped has not established one, and
+    // presenting a shared symbol as "the seam" when a direct call path may run
+    // past the bound sends the caller to a seam that is not there.
     const junctions =
-      hops.length > 0
+      hasPath || search.bounded
         ? []
         : junctionsBetween(graph, start.node.id, target.node.id, focus);
     return {
@@ -167,18 +181,23 @@ export function runTrace(
         steps: traceSteps(graph, hops),
         ...(junctions.length > 0 ? { junctions } : {}),
       },
-      // An empty path is a fact, not an answer, and the old message called it
+      // A missing 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
+      // between the two ends" — of a result that held nothing. `findPath` says
+      // which fact it is; zero hops is instead the valid path from a node to
+      // itself. A walk the depth bound stopped establishes nothing at all, so
+      // it reports the bound. A walk that ran out of eligible graph did
+      // establish an absence, and distinct nodes without a path 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
+      next: hasPath
+        ? pathNext
+        : search.bounded
+          ? resultNext("inspect", boundedPathReason(pathDepth), "trace")
           : junctions.length > 0
             ? resultNext(
                 "inspect",
@@ -203,24 +222,58 @@ export function runTrace(
   while (queue.length > 0) {
     const next: Array<{ id: string; depth: number }> = [];
     for (const { id, depth } of queue) {
-      if (depth >= maxDepth) {
-        truncated = true;
-        continue;
-      }
-      const edges = orderedEdges(
+      const { edges: candidates, omitted } = traceEdges(
         graph,
-        reverse
-          ? graph.incoming(id)
-          : [...graph.outgoing(id), ...dispatchEdges(graph, id, focus)],
-        direction,
+        id,
         reverse,
+        focus,
       );
+      // A hop the hub bound withheld is omitted whatever the depth budget does
+      // next, so the flag is set before the boundary check consumes the step.
+      if (
+        !truncated &&
+        omitted.some(
+          (edge) =>
+            eligibleTraceEndpoint(
+              graph,
+              edge,
+              reverse,
+              focus,
+              includeExternal,
+            ) !== undefined,
+        )
+      )
+        truncated = true;
+      if (depth >= maxDepth) {
+        // Reaching the configured boundary does not itself omit data. The
+        // response is truncated only when the selected walk has another hop
+        // (and, for an unseen endpoint, another node) beyond the boundary.
+        if (
+          candidates.some(
+            (edge) =>
+              eligibleTraceEndpoint(
+                graph,
+                edge,
+                reverse,
+                focus,
+                includeExternal,
+              ) !== undefined,
+          )
+        )
+          truncated = true;
+        continue;
+      }
+      const edges = orderedEdges(graph, candidates, direction, reverse);
       for (const edge of edges) {
-        if (!traversable(edge.kind, focus)) continue;
-        const otherId = reverse ? edge.from : edge.to;
-        const other = graph.node(otherId);
-        if (other === undefined || other.kind === "file") continue;
-        if (!includeExternal && isExternalNode(other)) continue;
+        const endpoint = eligibleTraceEndpoint(
+          graph,
+          edge,
+          reverse,
+          focus,
+          includeExternal,
+        );
+        if (endpoint === undefined) continue;
+        const { otherId, other } = endpoint;
         const hop: ITtscGraphTrace.IHop = {
           from: edge.from,
           to: edge.to,
@@ -272,6 +325,72 @@ export function runTrace(
   };
 }
 
+interface ITraceEndpoint {
+  otherId: string;
+  other: ITtscGraphNode;
+}
+
+/**
+ * Candidate edges in the selected direction before focus and node policy,
+ * together with the dispatch hops a bound withheld.
+ *
+ * The two have to travel together. A hub-suppressed fanout used to arrive as an
+ * empty dispatch list, which reads exactly like "this declaration dispatches to
+ * nothing", and the caller then reported a complete result while eligible hops
+ * had been dropped.
+ */
+function traceEdges(
+  graph: TtscGraphMemory,
+  id: string,
+  reverse: boolean,
+  focus: ITtscGraphTrace.IRequest["focus"],
+): { edges: readonly ITtscGraphEdge[]; omitted: readonly ITtscGraphEdge[] } {
+  const edges = reverse ? graph.incoming(id) : graph.outgoing(id);
+  const dispatched = reverse
+    ? reverseDispatchEdges(graph, id, focus)
+    : dispatchEdges(graph, id, focus);
+  // Nothing to add is the common case, and a walk visits the nodes with the
+  // largest edge lists, so hand back the stored list rather than a copy of it.
+  return {
+    edges:
+      dispatched.selected.length === 0
+        ? edges
+        : [...edges, ...dispatched.selected],
+    omitted: dispatched.omitted,
+  };
+}
+
+/** A dispatch fanout split into what the walk follows and what a bound withheld. */
+interface IDispatchSelection {
+  readonly selected: readonly ITtscGraphEdge[];
+  readonly omitted: readonly ITtscGraphEdge[];
+}
+
+// Returned by every no-dispatch path rather than allocated per call, which is
+// why the lists above are readonly: one shared value that anything could push
+// onto would leak a hop from one node's walk into another's.
+const NO_DISPATCH: IDispatchSelection = { selected: [], omitted: [] };
+
+/**
+ * The endpoint the selected open trace would represent if no result bound
+ * stopped it. The depth probe and traversal share this decision so focus,
+ * external nodes, file nodes, and direction cannot disagree about omission.
+ */
+function eligibleTraceEndpoint(
+  graph: TtscGraphMemory,
+  edge: ITtscGraphEdge,
+  reverse: boolean,
+  focus: ITtscGraphTrace.IRequest["focus"],
+  includeExternal: boolean,
+): ITraceEndpoint | undefined {
+  if (!traversable(edge.kind, focus)) return undefined;
+  const otherId = reverse ? edge.from : edge.to;
+  const other = graph.node(otherId);
+  if (other === undefined || other.kind === "file") return undefined;
+  if (!includeExternal && isExternalNode(other)) return undefined;
+  return { otherId, other };
+}
+
 function traceSteps(
   graph: TtscGraphMemory,
   hops: ITtscGraphTrace.IHop[],
@@ -289,11 +408,6 @@ function traceSteps(
   });
 }
 
-/**
- * The shortest dependency path from `startId` to `targetId` over real (non-
- * 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.
  *
@@ -382,6 +496,57 @@ function touchedBy(
   return touched;
 }
 
+/**
+ * What to say when the depth bound, not the graph, ended a path search.
+ *
+ * The caller asked a bounded question and the old answer returned a claim about
+ * the whole graph — "they touch nothing in common, so the graph holds no
+ * connection between them" — which is the worst thing an index can say wrongly:
+ * the caller stops asking and either reads files or concludes the dependency is
+ * not there. So report the boundary, and make the continuation one the caller
+ * can actually take. At the 12-hop ceiling there is no larger `maxDepth` to
+ * retry with, and a message that only invites one would be a dead end of its
+ * own; two bounded walks from opposite ends cover twice the distance and are
+ * requests the tool already answers.
+ */
+function boundedPathReason(depth: number): string {
+  return (
+    `No path was found within the requested depth of ${depth}, but the walk stopped on that bound with eligible graph still ahead of it. ` +
+    `This is a boundary, not an absence: the two ends may be connected further out, and nothing here says they are not. ` +
+    (depth < MAX_PATH_DEPTH
+      ? `Re-run the same path request with a larger \`maxDepth\` (up to ${MAX_PATH_DEPTH}).`
+      : `\`maxDepth\` is already at its ${MAX_PATH_DEPTH}-hop maximum, so close the gap from both ends: trace forward from the start, trace the target with \`direction: "reverse"\`, then request the path between a symbol both results name.`)
+  );
+}
+
+/**
+ * What a bounded shortest-path walk learned: the path when it found one, and
+ * otherwise whether the walk was stopped by the caller's depth bound or ran the
+ * eligible graph out. The two are not the same answer and the caller must not
+ * be told the second when only the first happened.
+ */
+interface IPathSearch {
+  /** The shortest eligible path and its hops, when one was found. */
+  found?: { path: ITtscGraphNode[]; hops: ITtscGraphTrace.IHop[] };
+
+  /**
+   * True when the walk stopped at `maxDepth` with an eligible, unvisited node
+   * still ahead of it, so nothing was proven about the two ends.
+   */
+  bounded: boolean;
+}
+
+/**
+ * The shortest dependency path from `startId` to `targetId` over real (non-
+ * structural) forward edges, breadth-first, within `maxDepth` hops.
+ *
+ * When no path is found, the walk reports whether the bound stopped it. A
+ * boundary is a fact about the request; absence is a fact about the graph, and
+ * a search that never reached the far side of its own bound has not established
+ * one. Eligibility is the open trace's, so a frontier made only of nodes the
+ * selected focus, the external-node policy, a file node, or an earlier visit
+ * already excluded is not a frontier and the walk is exhausted.
+ */
 function findPath(
   graph: TtscGraphMemory,
   startId: string,
@@ -389,10 +554,11 @@ function findPath(
   maxDepth: number,
   focus: ITtscGraphTrace.IRequest["focus"],
   includeExternal: boolean,
-): { path: ITtscGraphNode[]; hops: ITtscGraphTrace.IHop[] } | null {
+): IPathSearch {
   const startNode = graph.node(startId);
-  if (startNode === undefined) return null;
-  if (startId === targetId) return { path: [startNode], hops: [] };
+  if (startNode === undefined) return { bounded: false };
+  if (startId === targetId)
+    return { found: { path: [startNode], hops: [] }, bounded: false };
   const parent = new Map<
     string,
     {
@@ -402,21 +568,35 @@ function findPath(
     }
   >();
   const visited = new Set<string>([startId]);
+  let bounded = false;
   let queue: Array<{ id: string; depth: number }> = [{ id: startId, depth: 0 }];
   while (queue.length > 0) {
     const next: Array<{ id: string; depth: number }> = [];
     for (const { id, depth } of queue) {
-      if (depth >= maxDepth) continue;
-      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;
-        const other = graph.node(otherId);
-        if (other === undefined || other.kind === "file") continue;
-        if (!includeExternal && isExternalNode(other)) continue;
+      // The forward step the open trace would take, built in one place so the
+      // two walks cannot disagree about what a step follows.
+      const { edges: candidates } = traceEdges(graph, id, false, focus);
+      if (depth >= maxDepth) {
+        if (
+          candidates.some(
+            (edge) =>
+              pathEndpoint(graph, edge, focus, includeExternal, visited) !==
+              undefined,
+          )
+        )
+          bounded = true;
+        continue;
+      }
+      for (const edge of candidates) {
+        const endpoint = pathEndpoint(
+          graph,
+          edge,
+          focus,
+          includeExternal,
+          visited,
+        );
+        if (endpoint === undefined) continue;
+        const otherId = endpoint.otherId;
         visited.add(otherId);
         const evidence = edgeEvidenceOf(edge);
         parent.set(otherId, {
@@ -452,14 +632,42 @@ function findPath(
               hop.evidence = parentEdge.evidence;
             hops.push(hop);
           }
-          return { path, hops };
+          return { found: { path, hops }, bounded };
         }
         next.push({ id: otherId, depth: depth + 1 });
       }
     }
     queue = next;
   }
-  return null;
+  return { bounded };
+}
+
+/**
+ * The node a path expansion would represent, or undefined when the selected
+ * policy or an earlier visit excludes it. The expansion and the boundary probe
+ * share this decision, so what the walk would have followed and what counts as
+ * unexplored graph beyond the bound cannot disagree.
+ *
+ * A path walk is always forward and, unlike the open trace, a node it already
+ * reached is not a continuation: the shortest path to it is already known, so a
+ * second arrival adds nothing to explore.
+ */
+function pathEndpoint(
+  graph: TtscGraphMemory,
+  edge: ITtscGraphEdge,
+  focus: ITtscGraphTrace.IRequest["focus"],
+  includeExternal: boolean,
+  visited: ReadonlySet<string>,
+): ITraceEndpoint | undefined {
+  const endpoint = eligibleTraceEndpoint(
+    graph,
+    edge,
+    false,
+    focus,
+    includeExternal,
+  );
+  if (endpoint === undefined || visited.has(endpoint.otherId)) return undefined;
+  return endpoint;
 }
 
 function orderedEdges(
@@ -544,7 +752,7 @@ function summary(
   }
   if (depth !== undefined) out.depth = depth;
   if (withSignature) {
-    const sig = signatureOf(graph.project, node);
+    const sig = signatureOf(graph, node);
     if (sig !== undefined) out.signature = sig;
   }
   if (withRoles) {
@@ -580,14 +788,36 @@ function dispatchEdges(
   graph: TtscGraphMemory,
   id: string,
   focus: ITtscGraphTrace.IRequest["focus"],
-): ITtscGraphEdge[] {
-  if (focus === "types" || hasExecutionBody(graph, id)) return [];
-  const out: ITtscGraphEdge[] = [];
+): IDispatchSelection {
+  if (focus === "types") return NO_DISPATCH;
+  // The checker relations first: almost no node has one, and reading a
+  // declaration's own facts walks its ownership chain, which is work worth
+  // doing only where there is something to dispatch to.
+  let relations: ITtscGraphEdge[] | undefined;
   for (const edge of graph.incoming(id)) {
-    if (!DISPATCH_KINDS.has(edge.kind)) continue;
+    if (DISPATCH_KINDS.has(edge.kind)) (relations ??= []).push(edge);
+  }
+  if (relations === undefined) return NO_DISPATCH;
+  const declaration = graph.node(id);
+  if (declaration === undefined || hasDeclarationBody(graph, declaration))
+    return NO_DISPATCH;
+  const out: ITtscGraphEdge[] = [];
+  // Per implementation, not per relation. A class may name one base in two
+  // heritage clauses — `class Impl extends Base implements Base` is legal — and
+  // the producer records the member pair once per clause, as `overrides` and as
+  // `implements`. That is one implementation and one crossing: emitting it
+  // twice would repeat the hop and count the same class twice against the hub
+  // cut.
+  const dispatched = new Set<string>();
+  for (const edge of relations) {
+    if (dispatched.has(edge.from)) continue;
     const implementation = graph.node(edge.from);
-    if (implementation === undefined || !hasExecutionBody(graph, edge.from))
+    if (
+      implementation === undefined ||
+      !hasDeclarationBody(graph, implementation)
+    )
       continue;
+    dispatched.add(edge.from);
     out.push({
       from: id,
       to: edge.from,
@@ -595,16 +825,122 @@ function dispatchEdges(
       ...(edge.evidence !== undefined ? { evidence: edge.evidence } : {}),
     });
   }
-  return out.length >= DISPATCH_HUB ? [] : out;
+  // Above the hub cut the fanout stops being a trace and starts being a
+  // listing, so the walk does not follow it — but the hops are real and their
+  // absence is an omission the caller has to be able to report.
+  return out.length >= DISPATCH_HUB
+    ? { selected: [], omitted: out }
+    : { selected: out, omitted: [] };
+}
+
+/**
+ * The declaration a change to this implementation is a change to.
+ *
+ * `dispatches` is one fact and both directions have to see it. Forward, a call
+ * that lands on a bodyless declaration continues in the implementation that
+ * runs; reverse, a change to that implementation is a change every caller of
+ * the declaration feels — and `impact` is the query an agent runs _before_
+ * editing a method. The checker relation is oriented implementation-to-base, so
+ * from the implementation it is an outgoing edge and a reverse walk, which only
+ * reads incoming edges, never sees it. Both halves of the path are one step
+ * away in a direction the traversal does not take.
+ *
+ * The synthetic edge is the forward one, unchanged, so eligibility, checker
+ * validity, and the hub cut cannot drift apart between the two directions: ask
+ * the base what it dispatches to, and keep the edges that land here.
+ */
+function reverseDispatchEdges(
+  graph: TtscGraphMemory,
+  id: string,
+  focus: ITtscGraphTrace.IRequest["focus"],
+): IDispatchSelection {
+  if (focus === "types") return NO_DISPATCH;
+  const selected: ITtscGraphEdge[] = [];
+  const omitted: ITtscGraphEdge[] = [];
+  const bases = new Set<string>();
+  for (const edge of graph.outgoing(id)) {
+    if (!DISPATCH_KINDS.has(edge.kind) || bases.has(edge.to)) continue;
+    bases.add(edge.to);
+    const fanout = dispatchEdges(graph, edge.to, focus);
+    for (const dispatch of fanout.selected)
+      if (dispatch.to === id) selected.push(dispatch);
+    // The base's fanout is bounded as a whole, so a reverse walk that lands on
+    // a suppressed sibling has the same omission to report as the forward one.
+    for (const dispatch of fanout.omitted)
+      if (dispatch.to === id) omitted.push(dispatch);
+  }
+  return { selected, omitted };
+}
+
+/**
+ * Whether the declaration this node stands for has a body of its own.
+ *
+ * Having a body and naming a modeled dependency are different facts. Counting
+ * outgoing `calls`/`accesses`/`instantiates`/`renders` edges measures the
+ * second and answers as though it were the first, and it is wrong in both
+ * directions: an implementation whose body returns a literal, throws, or only
+ * moves locals around has degree zero and was refused as a dispatch target,
+ * while a concrete base method was promoted through its own override the moment
+ * its body stopped naming anything the graph models. Two graphs identical in
+ * every declaration fact then answered differently because of one statement
+ * inside a body.
+ *
+ * So read the declaration instead. A type surface has no body; `abstract` and
+ * `declare` take it away; an interface member and anything inside an ambient
+ * container never had one; a `.d.ts` declaration is ambient whether or not the
+ * keyword is written; and an external leaf has a body the graph deliberately
+ * does not hold. Everything else is a concrete declaration, which is a real
+ * destination and is never promoted through an override, whatever it calls.
+ */
+export function hasDeclarationBody(
+  graph: TtscGraphMemory,
+  node: ITtscGraphNode,
+): boolean {
+  if (BODYLESS_KINDS.has(node.kind)) return false;
+  if (isExternalNode(node)) return false;
+  if (isDeclarationFile(node.file)) return false;
+  if (hasBodylessModifier(node)) return false;
+  return !inBodylessContainer(graph, node);
 }
 
-/** 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;
+function hasBodylessModifier(node: ITtscGraphNode): boolean {
+  return node.modifiers?.some((m) => BODYLESS_MODIFIERS.has(m)) === true;
+}
+
+/**
+ * Whether an owner up the `contains` tree makes this declaration bodyless: an
+ * interface, or an ambient container. A member writes no keyword of its own —
+ * `declare` on a class or namespace is not repeated on what it holds — so the
+ * fact lives on the owner and the walk has to go get it.
+ */
+function inBodylessContainer(
+  graph: TtscGraphMemory,
+  node: ITtscGraphNode,
+): boolean {
+  const seen = new Set<string>([node.id]);
+  let current: ITtscGraphNode | undefined = node;
+  while (current !== undefined) {
+    const container: ITtscGraphNode | undefined = containerOf(graph, current);
+    if (container === undefined || container.kind === "file") return false;
+    if (seen.has(container.id)) return false;
+    seen.add(container.id);
+    if (container.kind === "interface" || hasBodylessModifier(container))
+      return true;
+    current = container;
+  }
   return false;
 }
 
+/** The declaration that owns this one, through the synthesized ownership tree. */
+function containerOf(
+  graph: TtscGraphMemory,
+  node: ITtscGraphNode,
+): ITtscGraphNode | undefined {
+  for (const edge of graph.incoming(node.id))
+    if (edge.kind === "contains") return graph.node(edge.from);
+  return undefined;
+}
+
 /** An edge the trace should follow: a real dependency, not a structural edge. */
 function traversable(
   kind: string,

package/src/structures/ITtscGraphApplication.ts

@@ -169,13 +169,14 @@ export namespace ITtscGraphApplication {
      * resolves to the type-checked program for the snapshot the call synced to,
      * so opening a file it cites only returns a fact already in it.
      *
-     * The audit is operation-aware. For the exact operations (`trace`,
-     * `details`, `overview`) it reports the result as the structure the graph
-     * holds for the handles named, bounded only where `truncated` says. For the
-     * ranked operations (`lookup`, `entrypoints`, `tour`) it adds that the
-     * selection is heuristic — matched, scored, ranked, and limited against the
-     * question — so the facts are verified but the shortlist's coverage is the
-     * caller's to judge.
+     * The audit is operation-aware. For the walks from a named handle (`trace`,
+     * `overview`) it reports the result as the structure the graph holds,
+     * bounded where `truncated` says. For `details` it reports the two halves of
+     * a resolved symbol: its own shape returned whole, its fan-out returned as a
+     * slice with `trace` for the rest. For the ranked operations (`lookup`,
+     * `entrypoints`, `tour`) it adds that the selection is heuristic — matched,
+     * scored, ranked, and limited against the question — so the facts are
+     * verified but the shortlist's coverage is the caller's to judge.
      */
     audit: string;
 

package/src/structures/ITtscGraphDetails.ts

@@ -49,24 +49,26 @@ export namespace ITtscGraphDetails {
     neighbors?: boolean;
 
     /**
-     * Maximum dependencies and dependents per side when `neighbors:true`. Above
-     * a few is usually overfetch; call `trace` for flow instead.
+     * Dependencies and dependents per side when `neighbors:true`. A small
+     * orientation slice by default; what uses a symbol grows with its
+     * popularity, so `trace` answers the whole "who uses this".
      *
      * @default 2
      */
     neighborLimit?: number;
 
     /**
-     * Maximum owned members for a container or object literal.
-     *
-     * @default 6
+     * Owned members for a container or object literal. The complete outline by
+     * default — a class's members and an enum's are the symbol itself, so they
+     * are not sampled. Pass a number to cap.
      */
     memberLimit?: number;
 
     /**
-     * Maximum direct execution and type references per group.
+     * Direct execution and type references per group. A small orientation slice
+     * by default; `trace` follows the whole fan-out.
      *
-     * @default 1
+     * @default 2
      */
     dependencyLimit?: number;
 
@@ -145,7 +147,15 @@ export namespace ITtscGraphDetails {
     /** Concrete nodes that implement or override this interface/base member. */
     implementedBy?: IReference[];
 
-    /** String literal values from the signature. */
+    /**
+     * The complete value set a type alias or enum admits, in TypeScript source
+     * form (`"a"`, `1`, `true`, `null`) — the checker's resolved union members,
+     * not the quoted tokens that happened to fit in `signature`.
+     *
+     * Absent when the type has no enumerable value set. A `signature` is capped
+     * at the declaration head, so for a union or enum written across several
+     * lines this is the field that carries the members.
+     */
     literals?: string[];
 
     /**