@ttsc/graph 0.16.6 → 0.16.7

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,85 @@ 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.
- *
- * 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.
- */
+/** The typed MCP surface; its single method becomes the single graph tool. */
 export interface ITtscGraphApplication {
   /**
-   * Query the TypeScript project graph for code evidence.
+   * Inspect the TypeScript compiler graph contract.
    *
-   * 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.
+   * 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`.
    *
-   * Fill properties in order: question, graphNeed, draft, review, request.
-   * Write `draft.reason` before `draft.type`, then choose `entrypoints`,
-   * `lookup`, `trace`, `details`, `overview`, or `escape`.
+   * 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.
    *
-   * 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.
-   *
-   * @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 and why it seems smallest. 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: string;
 
     /**
-     * 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. */
-    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 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;
   }
 }

package/src/structures/ITtscGraphDetails.ts

@@ -1,23 +1,32 @@
 import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
 import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
+import { ITtscGraphNext } from "./ITtscGraphNext";
 
 /**
- * The resolved symbol details returned for a set of handles.
+ * The source-free facts for a few selected handles.
  *
- * The default payload is source-free: signatures, member outlines, and direct
- * graph summaries with sourceSpan anchors.
+ * This is not a file reader. It returns signatures, member outlines, direct
+ * calls, direct types, implementation candidates, dependency summaries, and
+ * sourceSpan citation anchors.
  */
 export interface ITtscGraphDetails {
   /** Discriminator for selected symbol inspection. */
   type: "details";
 
+  /** Selected node facts, in the same order as resolved handles when possible. */
   nodes: ITtscGraphDetails.INode[];
 
+  /** How to use this source-free result next. */
+  next: ITtscGraphNext;
+
+  /** Human-readable compatibility note mirroring `next`. */
+  guide: string;
+
   /** Handles that resolved to no node, or that were ambiguous. */
   unknown: string[];
 }
 export namespace ITtscGraphDetails {
-  /** Which handles to inspect, and how much of each to return. */
+  /** Which selected handles to inspect, and how much of each to return. */
   export interface IRequest {
     /** Discriminator for selected symbol inspection. */
     type: "details";
@@ -25,14 +34,16 @@ export namespace ITtscGraphDetails {
     /**
      * Node ids from another tool, or dotted symbol handles such as
      * `OrderService.create`. Pass the few handles you need for source-free
-     * details; use `trace` when you need a path instead of widening this call.
+     * details. Prefer one to three handles. Use `trace` when you need a path
+     * instead of widening this call.
      */
     handles: string[];
 
     /**
      * Also list each node's direct dependencies and dependents (the symbols it
      * uses and the symbols that use it). The list is capped; raise
-     * `neighborLimit` only when the first slice is not enough.
+     * `neighborLimit` when the first slice is truncated and the missing
+     * relation is named. This remains a relationship summary, not a file body.
      *
      * @default false
      */
@@ -42,13 +53,17 @@ export namespace ITtscGraphDetails {
      * Maximum dependencies and dependents to return per side when
      * `neighbors:true`.
      *
+     * Prefer the default. Values above a few neighbors are usually overfetch;
+     * call `trace` for flow instead.
+     *
      * @default 2
      */
     neighborLimit?: number;
 
     /**
      * Maximum owned members to return for a container or object literal. Raise
-     * only when the first outline is truncated.
+     * only when the first outline is truncated and the missing member is
+     * named.
      *
      * @default 6
      */
@@ -56,73 +71,121 @@ export namespace ITtscGraphDetails {
 
     /**
      * Maximum direct execution and type references to return per group. Raise
-     * only when the first dependency slice is not enough.
+     * only when the first dependency slice is truncated and the missing
+     * dependency is named.
      *
      * @default 1
      */
     dependencyLimit?: number;
+
+    /**
+     * Include dependency-boundary references from node_modules or bundled
+     * `.d.ts` libraries. Leave false for source-architecture answers; enable
+     * only when external type/API boundaries are the question.
+     *
+     * @default false
+     */
+    includeExternal?: boolean;
   }
 
   /** One inspected node: its declared shape and graph coordinates. */
   export interface INode {
+    /** Stable node id for subsequent `details` or `trace` calls. */
     id: string;
+
+    /** Qualified symbol name when available, otherwise the simple name. */
     name: string;
+
+    /** Declaration kind (`class`, `method`, `function`, ...). */
     kind: string;
+
+    /** Project-relative path of the file that declares this node. */
     file: string;
+
     /** 1-based declaration line, when known. */
     line?: number;
+
     /** The declaration signature: its first line(s) up to the body. */
     signature?: string;
+
     /** Decorators written on this declaration, when any. */
     decorators?: ITtscGraphDecorator[];
+
     /** Assigned implementation span, when source comes from one. */
     implementation?: ITtscGraphEvidence;
+
     /** Direct execution dependencies in source order, with edge evidence. */
     calls?: IReference[];
+
     /** Direct type dependencies in source order, with edge evidence. */
     types?: IReference[];
+
+    /** Concrete nodes that implement or override this interface/base member. */
+    implementedBy?: IReference[];
+
     /** String literal values from the signature. */
     literals?: string[];
+
     /**
      * For a container or object-literal variable: the owned symbol or top-level
      * property outline a consumer reaches for, without bodies.
      */
     members?: IMember[];
-    /** The declaration or implementation file and line range, when known. */
+
+    /** Declaration or implementation citation range, when known. */
     sourceSpan?: Pick<ITtscGraphEvidence, "file" | "startLine" | "endLine">;
+
     /** Symbols this node uses (outgoing dependency edges). */
     dependsOn?: IReference[];
+
     /** Symbols that use this node (incoming dependency edges). */
     dependedOnBy?: IReference[];
   }
 
   /** One member of a container node, with its signature but not its body. */
   export interface IMember {
+    /** Member name, qualified when the graph records an owner-qualified handle. */
     name: string;
+
+    /** Member kind (`method`, `property`, `class`, ...). */
     kind: string;
+
     /** 1-based declaration line, when known. */
     line?: number;
+
     /** The member's declaration signature. */
     signature?: string;
+
     /** Decorators written on this member, when any. */
     decorators?: ITtscGraphDecorator[];
   }
 
   /** A dependency neighbor of an inspected node and the edge that links them. */
   export interface IReference {
+    /** Stable id of the neighboring node. */
     id: string;
+
+    /** Neighbor symbol name, qualified when available. */
     name: string;
+
+    /** Neighbor declaration kind. */
     kind: string;
+
+    /** Project-relative declaration file for the neighbor. */
     file: string;
+
     /** 1-based declaration line, when known. */
     line?: number;
+
     /** The edge kind connecting the two (`calls`, `type_ref`, ...). */
     relation: string;
+
     /**
-     * Source span for the expression that produced this relationship. It lets
-     * an agent see why the edge exists without opening the file.
+     * Source span for the expression that produced this relationship. It is
+     * repository evidence for the edge, not a file-read instruction.
      */
     evidence?: ITtscGraphEvidence;
+
     /**
      * Stable access-path aliases derived from edge evidence. For example, an
      * edge to `Owner.member` through `obj.slot.member` may expose