@ttsc/graph 0.16.6 → 0.16.8

package/src/server/runTrace.ts

@@ -1,18 +1,22 @@
 import { TtscGraphMemory } from "../model/TtscGraphMemory";
+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";
 
 const DEFAULT_DEPTH = 2;
 const DEFAULT_MAX_NODES = 6;
 const MAX_OPEN_DEPTH = 2;
 const MAX_OPEN_NODES = 8;
-const MAX_HOPS_PER_NODE = 1;
+const MAX_IMPACT_DEPTH = 4;
+const MAX_IMPACT_NODES = 16;
+const MAX_HOPS_PER_NODE = 2;
 const MAX_STEPS = 6;
-const MAX_NEXT_HANDLES = 2;
 
 /**
  * Breadth-first trace along the dependency graph. Structural
@@ -27,10 +31,22 @@ export function runTrace(
 ): ITtscGraphTrace {
   const direction = props.direction ?? "forward";
   const focus = props.focus ?? "all";
-  const maxDepth = bound(props.maxDepth, DEFAULT_DEPTH, 1, MAX_OPEN_DEPTH);
-  const maxNodes = bound(props.maxNodes, DEFAULT_MAX_NODES, 1, MAX_OPEN_NODES);
+  const impact = direction === "impact";
+  const maxDepth = bound(
+    props.maxDepth,
+    DEFAULT_DEPTH,
+    1,
+    impact ? MAX_IMPACT_DEPTH : MAX_OPEN_DEPTH,
+  );
+  const maxNodes = bound(
+    props.maxNodes,
+    DEFAULT_MAX_NODES,
+    1,
+    impact ? MAX_IMPACT_NODES : MAX_OPEN_NODES,
+  );
   const maxHops = maxNodes * MAX_HOPS_PER_NODE;
   const reverse = direction === "reverse" || direction === "impact";
+  const includeExternal = props.includeExternal === true;
   // Only an impact trace tags reached nodes with their public-surface role; for
   // forward/reverse the role is noise.
   const withRoles = direction === "impact";
@@ -43,6 +59,13 @@ export function runTrace(
       hops: [],
       reached: [],
       truncated: false,
+      next: resultNext(
+        "clarify",
+        "The start handle is ambiguous; choose one returned candidate.",
+      ),
+      guide: resultGuide(
+        "Disambiguate with the returned candidates, or ask the user for the intended symbol.",
+      ),
       candidates: start.candidates.map((n) => summary(graph, n)),
     };
   }
@@ -53,6 +76,13 @@ export function runTrace(
       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.",
+      ),
     };
   }
 
@@ -65,6 +95,13 @@ 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 target = resolveGraphHandle(graph, props.to);
     if (target.candidates) {
@@ -83,6 +120,7 @@ export function runTrace(
       target.node.id,
       bound(props.maxDepth, 12, 1, 12),
       focus,
+      includeExternal,
     );
     const path = found?.path ?? [];
     const hops = found?.hops ?? [];
@@ -93,7 +131,6 @@ export function runTrace(
       hops,
       path: path.map((node, i) => summary(graph, node, i, false, true)),
       steps: traceSteps(graph, hops),
-      next: nextFromPath(path),
     };
   }
 
@@ -112,12 +149,18 @@ export function runTrace(
         truncated = true;
         continue;
       }
-      const edges = reverse ? graph.incoming(id) : graph.outgoing(id);
+      const edges = orderedEdges(
+        graph,
+        reverse ? graph.incoming(id) : graph.outgoing(id),
+        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 hop: ITtscGraphTrace.IHop = {
           from: edge.from,
           to: edge.to,
@@ -164,21 +207,17 @@ export function runTrace(
     hops,
     reached: [...reached.values()],
     steps: traceSteps(graph, hops),
-    next: {
-      details: [start.node.id, ...reached.keys()].slice(0, MAX_NEXT_HANDLES),
-      traceFrom: [...reached.keys()].slice(0, MAX_NEXT_HANDLES),
-    },
+    next: resultNext(
+      "answer",
+      "Steps, hops, reached nodes, and evidence ranges are the flow answer surface.",
+    ),
+    guide: resultGuide(
+      "Use steps, hops, reached nodes, and evidence ranges as the flow answer or reading-list anchor.",
+    ),
     truncated,
   };
 }
 
-function nextFromPath(path: ITtscGraphNode[]): ITtscGraphTrace.INext {
-  return {
-    details: path.map((node) => node.id),
-    traceFrom: path.length > 0 ? [path[path.length - 1]!.id] : [],
-  };
-}
-
 function traceSteps(
   graph: TtscGraphMemory,
   hops: ITtscGraphTrace.IHop[],
@@ -209,6 +248,7 @@ function findPath(
   targetId: string,
   maxDepth: number,
   focus: ITtscGraphTrace.IRequest["focus"],
+  includeExternal: boolean,
 ): { path: ITtscGraphNode[]; hops: ITtscGraphTrace.IHop[] } | null {
   const startNode = graph.node(startId);
   if (startNode === undefined) return null;
@@ -234,6 +274,7 @@ function findPath(
         if (visited.has(otherId)) continue;
         const other = graph.node(otherId);
         if (other === undefined || other.kind === "file") continue;
+        if (!includeExternal && isExternalNode(other)) continue;
         visited.add(otherId);
         const evidence = edgeEvidenceOf(edge);
         parent.set(otherId, {
@@ -282,6 +323,59 @@ function findPath(
   return null;
 }
 
+function orderedEdges(
+  graph: TtscGraphMemory,
+  edges: readonly ITtscGraphEdge[],
+  direction: string,
+  reverse: boolean,
+): readonly ITtscGraphEdge[] {
+  if (direction !== "impact")
+    return [...edges].sort(
+      (a, b) =>
+        edgeKindRank(a.kind) - edgeKindRank(b.kind) ||
+        traceEndpointRank(graph, reverse ? a.from : a.to) -
+          traceEndpointRank(graph, reverse ? b.from : b.to) ||
+        evidenceRank(a) - evidenceRank(b),
+    );
+  return [...edges].sort(
+    (a, b) =>
+      impactEndpointRank(graph, reverse ? a.from : a.to) -
+        impactEndpointRank(graph, reverse ? b.from : b.to) ||
+      edgeKindRank(a.kind) - edgeKindRank(b.kind) ||
+      evidenceRank(a) - evidenceRank(b),
+  );
+}
+
+function impactEndpointRank(graph: TtscGraphMemory, id: string): number {
+  const node = graph.node(id);
+  if (node === undefined) return 9;
+  if (isTestPath(node.file)) return 0;
+  if (node.exported) return 1;
+  if (node.external || node.ignored) return 4;
+  return 2;
+}
+
+function traceEndpointRank(graph: TtscGraphMemory, id: string): number {
+  const node = graph.node(id);
+  if (node === undefined) return 9;
+  if (isTestPath(node.file)) return 6;
+  switch (node.kind) {
+    case "function":
+    case "method":
+    case "class":
+      return 0;
+    case "variable":
+      return 1;
+    case "property":
+      return 2;
+    case "interface":
+    case "type":
+      return 4;
+    default:
+      return 3;
+  }
+}
+
 /**
  * Summarize a node for a trace result. With `withRoles`, tag the public-surface
  * roles (exported / test) an impact trace reports; other directions omit them.
@@ -299,6 +393,16 @@ function summary(
     kind: node.kind,
     file: node.file,
   };
+  if (node.evidence?.startLine !== undefined)
+    out.line = node.evidence.startLine;
+  const span = node.implementation ?? node.evidence;
+  if (span !== undefined) {
+    out.sourceSpan = {
+      file: span.file,
+      startLine: span.startLine,
+      ...(span.endLine !== undefined ? { endLine: span.endLine } : {}),
+    };
+  }
   if (depth !== undefined) out.depth = depth;
   if (withSignature) {
     const sig = signatureOf(graph.project, node);
@@ -307,7 +411,7 @@ function summary(
   if (withRoles) {
     const roles: string[] = [];
     if (node.exported) roles.push("exported");
-    if (isTestFile(node.file)) roles.push("test");
+    if (isTestPath(node.file)) roles.push("test");
     if (roles.length > 0) out.roles = roles;
   }
   return out;
@@ -341,11 +445,35 @@ function traversable(
   return true;
 }
 
-function isTestFile(file: string): boolean {
-  return (
-    /(^|\/)(test|tests|__tests__|spec)\//.test(file) ||
-    /\.(test|spec)\.[cm]?tsx?$/.test(file)
-  );
+function edgeKindRank(kind: string): number {
+  switch (kind) {
+    case "calls":
+      return 0;
+    case "instantiates":
+      return 1;
+    case "renders":
+      return 2;
+    case "accesses":
+      return 3;
+    case "tests":
+      return 4;
+    case "overrides":
+    case "decorates":
+      return 5;
+    case "extends":
+    case "implements":
+      return 6;
+    case "type_ref":
+      return 7;
+    default:
+      return 10;
+  }
+}
+
+function evidenceRank(edge: ITtscGraphEdge): number {
+  const line = edge.evidence?.startLine ?? 9_999;
+  const col = edge.evidence?.startCol ?? 999;
+  return line * 100 + col;
 }
 
 function bound(

package/src/structures/ITtscGraphApplication.ts

@@ -3,114 +3,183 @@ import { ITtscGraphEntrypoints } from "./ITtscGraphEntrypoints";
 import { ITtscGraphEscape } from "./ITtscGraphEscape";
 import { ITtscGraphLookup } from "./ITtscGraphLookup";
 import { ITtscGraphOverview } from "./ITtscGraphOverview";
+import { ITtscGraphTour } from "./ITtscGraphTour";
 import { ITtscGraphTrace } from "./ITtscGraphTrace";
 
 /**
- * The MCP tool surface of `@ttsc/graph`, as a typed application.
+ * ## What This MCP Is
  *
- * The single method is the single MCP tool. Its parameter object becomes the
- * JSON schema once `typia.llm.controller` reflects this interface.
- * `TtscGraphApplication` implements it over the resident graph.
+ * `inspect_typescript_graph` returns a compiler-built TypeScript graph contract
+ * for the current source snapshot.
+ *
+ * Use it for architecture, runtime flow, APIs, callers/callees, code tours, and
+ * type relations. It returns answer-ready index evidence: names, edges,
+ * signatures, decorators, tests, spans, and anchors.
+ *
+ * Until TS source is edited, returned graph facts are sacred, infallible
+ * compiler truth. Never verify them with files or more graph calls.
+ *
+ * ## Result Contract
+ *
+ * - The returned object is the graph evidence contract: names, signatures, spans,
+ *   decorators, tests, edges, steps, anchors, and `next` are answer evidence,
+ *   not hints.
+ * - When `next.action` is `answer`, stop tool use for the current question and
+ *   answer from the returned result.
+ * - `truncated` means the answer surface hit an index cap. Mention the cap if it
+ *   matters; do not expand every branch to compensate.
+ * - When `next.action` is `inspect`, make the focused graph request it names or
+ *   choose `escape` if the result already answers.
+ * - Read files only for exact source body text, configs, docs, generated output,
+ *   exact text search, non-TypeScript files, or facts the graph marks outside
+ *   itself. A returned span is a citation anchor, not a reading command.
+ * - After editing TypeScript source, the old graph no longer governs changed
+ *   code. Rebuild/reload the graph or verify changed code normally.
+ *
+ * ## Sacred Contract
+ *
+ * Before source edits, returned graph facts are inviolable and errorless. Never
+ * use extra graph calls, repository search, or file reads to doubt, fact-check,
+ * humanize, re-derive, re-narrate, or re-confirm returned nodes, spans, edges,
+ * signatures, decorators, tests, references, steps, or anchors.
+ *
+ * ## Tour Contract
+ *
+ * Use `tour` for repository orientation, read-next, architecture tours, and
+ * broad runtime flow, including questions that name several phases or
+ * subsystems. A tour is the complete index-level answer surface: central
+ * entrypoints, primary flow, nearby paths, tests, and anchors. Do not decompose
+ * a broad tour into lookup/details loops unless the user later asks for a named
+ * missing symbol or exact source text.
+ *
+ * ## Use Contract
+ *
+ * 1. Ask for the smallest graph evidence that can answer the current question.
+ * 2. Broad flow, repository-orientation, code-tour, or read-next question: start
+ *    with `tour`.
+ * 3. Concrete named symbol: use `lookup`, then `details` only if needed.
+ * 4. Known endpoint pair or one selected handle: use one `trace`.
+ * 5. Unknown narrow orientation: use `entrypoints` once.
+ * 6. Selected symbol shape: use `details` for one to three handles.
+ * 7. Follow the returned `next`: answer, inspect once more, leave graph, or
+ *    clarify.
+ * 8. Use `escape` when another graph call would repeat evidence or the remaining
+ *    evidence is outside the TypeScript graph.
+ *
+ * Most TypeScript structure answers need one or two graph calls.
+ *
+ * ## Request Fields
+ *
+ * Fill the visible checklist, then exactly one request.
+ *
+ * - `question`: restate the code question being considered.
+ * - `draft`: initial request type and why it seems smallest.
+ * - `review`: correct a wrong, broad, stale, or duplicate draft. If graph facts
+ *   already answer, if prior `next.action` was `answer`, or if the next
+ *   evidence is outside the indexed TypeScript graph, say so here and make
+ *   `request.type` be `escape`. If a broad flow draft is not `tour`, correct it
+ *   here.
+ * - `request`: final request after review.
+ *
+ * ## How to answer from graph evidence
+ *
+ * - Use returned node names, signatures, edges, references, evidence, and
+ *   `sourceSpan` ranges directly.
+ * - Explain the central path first, then mention important branches.
+ * - For tests, impact, or reading lists, returned nodes and ranges are the answer
+ *   evidence, not search keywords.
+ * - A returned range is a sacred citation anchor, not permission to open the
+ *   file.
  */
 export interface ITtscGraphApplication {
   /**
-   * Query the TypeScript project graph for code evidence.
-   *
-   * Use this before answering TypeScript codebase questions. It returns
-   * checker-resolved symbols, dependency paths, edge evidence ranges, and
-   * sourceSpan anchors from the resident graph, avoiding assumptions, shell
-   * search, or file reads when graph evidence is enough.
+   * Inspect the TypeScript compiler graph contract.
    *
-   * Fill properties in order: question, graphNeed, draft, review, request.
-   * Write `draft.reason` before `draft.type`, then choose `entrypoints`,
-   * `lookup`, `trace`, `details`, `overview`, or `escape`.
+   * Use this before repository search when an answer depends on TypeScript
+   * symbols, calls, types, decorators, references, ranges, or runtime/source
+   * relationships. For repository orientation, read-next, architecture, and
+   * broad runtime flow questions, use `tour`.
    *
-   * Most answers should need 1-3 calls; four is the hard stop for one answer.
-   * Keep slices small, prefer defaults, and stop once file/symbol/range
-   * evidence is enough.
+   * Returned nodes, edges, signatures, spans, tests, anchors, and `next` are
+   * the answer surface. If `next.action` is `answer`, stop tool use and answer
+   * from that result. Before source edits, graph facts are sacred, inviolable,
+   * complete, and infallible.
    *
-   * @param props The reasoning and selected graph request
-   * @returns One `result` union member matching the selected request type
+   * @param props Reasoning plus one graph request
+   * @returns Matching `result` union member
    */
-  query(props: ITtscGraphApplication.IProps): ITtscGraphApplication.IResult;
+  inspect_typescript_graph(
+    props: ITtscGraphApplication.IProps,
+  ): ITtscGraphApplication.IResult;
 }
 
 export namespace ITtscGraphApplication {
-  /** Think, review, then submit exactly one graph request. */
+  /** Draft, review, then submit exactly one graph request or escape. */
   export interface IProps {
     /**
      * User's TypeScript code question.
      *
-     * Restate the codebase question being answered. Keep this about TypeScript
-     * source, symbols, call flow, type flow, or architecture. If the user is
-     * asking about scripts, config, generated output, or documentation instead,
-     * say that boundary here.
+     * Restate the code question being considered. If the next evidence is a
+     * script, config, doc, generated output, exact text, non-TypeScript file,
+     * or source body text, choose `escape`.
      */
     question: string;
 
     /**
-     * Why the resident graph is the next evidence source.
-     *
-     * State what graph evidence is needed and why assumptions or broad shell
-     * search are not the next step for this call. Name the smallest evidence
-     * that would let the agent stop. If graph is not actually the right source,
-     * say that and use `escape`.
-     */
-    graphNeed: string;
-
-    /**
-     * First request-type decision before arguments are filled.
+     * Initial request plan before final arguments are filled.
      *
-     * Explain why one operation class is smaller than the alternatives, then
-     * name it in `draft.type`. This is only the draft; the final arguments are
-     * in `request` after `review`.
+     * Name the intended request type in `type` and why it seems smallest in
+     * `reason`. Broad flow, architecture, repository-orientation, and read-next
+     * questions should normally draft `tour`; narrow named symbols can draft
+     * `lookup`, `trace`, or `details`.
      */
-    draft: IRequestDraft;
+    draft: IDraft;
 
     /**
-     * Critical review of the draft request.
+     * Final self-review before calling.
      *
-     * Check whether the draft avoids overfetch, non-graph fallback, broad
-     * reads, and unnecessary neighbor expansion. If this would be a fourth
-     * broad lookup, trace, or details call, prefer answering from evidence in
-     * hand or choose `escape`. Do not spend graph calls only to hunt for tests.
-     * If the draft is wrong, choose the corrected type in `request`.
+     * Correct a stale, broad, duplicate, or wrong draft here. If broad flow was
+     * split into search/detail steps, switch to `tour`. If graph facts already
+     * answer, or prior `next.action` was `answer`, make `request.type` be
+     * `escape`; do not call graph or read files to re-confirm returned facts.
      */
     review: string;
 
-    /** The graph operation chosen from the reasoning above, or a no-op escape. */
+    /** Final graph operation chosen after review, or a no-op escape. */
     request:
       | ITtscGraphEntrypoints.IRequest
       | ITtscGraphLookup.IRequest
       | ITtscGraphTrace.IRequest
       | ITtscGraphDetails.IRequest
       | ITtscGraphOverview.IRequest
+      | ITtscGraphTour.IRequest
       | ITtscGraphEscape.IRequest;
   }
 
-  /** First-pass operation choice before final request arguments. */
-  export interface IRequestDraft {
-    /** Why this operation type is the smallest useful next step. */
+  /**
+   * First-pass request plan, filled before the final `request` arguments.
+   *
+   * `reason` comes before `type` so the justification is written before the
+   * choice it justifies.
+   */
+  export interface IDraft {
+    /** Why this request type looks like the smallest useful next step. */
     reason: string;
 
-    /** Draft discriminator for the intended graph operation. */
-    type:
-      | ITtscGraphEntrypoints.IRequest["type"]
-      | ITtscGraphLookup.IRequest["type"]
-      | ITtscGraphTrace.IRequest["type"]
-      | ITtscGraphDetails.IRequest["type"]
-      | ITtscGraphOverview.IRequest["type"]
-      | ITtscGraphEscape.IRequest["type"];
+    /** The request type being considered, corrected later in `review`. */
+    type: IProps["request"]["type"];
   }
 
   /** The selected request's output. `result.type` mirrors `request.type`. */
   export interface IResult {
+    /** Result branch matching the submitted `request.type`. */
     result:
       | ITtscGraphEntrypoints
       | ITtscGraphLookup
       | ITtscGraphTrace
       | ITtscGraphDetails
       | ITtscGraphOverview
+      | ITtscGraphTour
       | ITtscGraphEscape;
   }
 }