@ttsc/graph 0.16.5 → 0.16.7

package/src/server/runTrace.ts

@@ -1,11 +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 { signatureOf } from "./runExpand";
+import { resultGuide, resultNext } from "./resultGuide";
+import { edgeEvidenceOf, edgeEvidenceTextOf, signatureOf } from "./runDetails";
 
-const DEFAULT_DEPTH = 6;
-const DEFAULT_MAX_NODES = 60;
+const DEFAULT_DEPTH = 2;
+const DEFAULT_MAX_NODES = 6;
+const MAX_OPEN_DEPTH = 2;
+const MAX_OPEN_NODES = 8;
+const MAX_IMPACT_DEPTH = 4;
+const MAX_IMPACT_NODES = 16;
+const MAX_HOPS_PER_NODE = 2;
+const MAX_STEPS = 6;
 
 /**
  * Breadth-first trace along the dependency graph. Structural
@@ -16,12 +27,26 @@ const DEFAULT_MAX_NODES = 60;
  */
 export function runTrace(
   graph: TtscGraphMemory,
-  props: ITtscGraphTrace.IProps,
+  props: ITtscGraphTrace.IRequest,
 ): ITtscGraphTrace {
   const direction = props.direction ?? "forward";
-  const maxDepth = Math.max(1, props.maxDepth ?? DEFAULT_DEPTH);
-  const maxNodes = Math.max(1, props.maxNodes ?? DEFAULT_MAX_NODES);
+  const focus = props.focus ?? "all";
+  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";
@@ -29,49 +54,83 @@ export function runTrace(
   const start = resolveGraphHandle(graph, props.from);
   if (start.candidates) {
     return {
+      type: "trace",
       direction,
       hops: [],
       reached: [],
       truncated: false,
-      candidates: start.candidates.map((n) => summary(n)),
+      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)),
     };
   }
   if (start.node === undefined) {
-    return { direction, hops: [], reached: [], truncated: false };
+    return {
+      type: "trace",
+      direction,
+      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.",
+      ),
+    };
   }
 
-  // Path mode: with `to`, return the dependency path from `from` to `to` — the
-  // one-call answer for "how does A reach B" — instead of an open-ended trace.
+  // Path mode: with `to`, return the dependency path from `from` to `to`, the
+  // one-call answer for "how does A reach B", instead of an open-ended trace.
   if (props.to !== undefined && props.to !== "") {
-    const base = { direction: "path", hops: [], reached: [], truncated: false };
+    const base = {
+      type: "trace" as const,
+      direction: "path",
+      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) {
       return {
         ...base,
-        start: summary(start.node),
-        candidates: target.candidates.map((n) => summary(n)),
+        start: summary(graph, start.node),
+        candidates: target.candidates.map((n) => summary(graph, n)),
       };
     }
     if (target.node === undefined) {
-      return { ...base, start: summary(start.node) };
+      return { ...base, start: summary(graph, start.node) };
     }
     const found = findPath(
       graph,
       start.node.id,
       target.node.id,
-      Math.max(1, props.maxDepth ?? 12),
+      bound(props.maxDepth, 12, 1, 12),
+      focus,
+      includeExternal,
     );
+    const path = found?.path ?? [];
+    const hops = found?.hops ?? [];
     return {
       ...base,
-      start: summary(start.node),
-      target: summary(target.node),
-      hops: found?.hops ?? [],
-      path: (found?.path ?? []).map((node, i) => {
-        const node_ = summary(node, i);
-        const sig = signatureOf(graph.project, node);
-        if (sig !== undefined) node_.signature = sig;
-        return node_;
-      }),
+      start: summary(graph, start.node),
+      target: summary(graph, target.node),
+      hops,
+      path: path.map((node, i) => summary(graph, node, i, false, true)),
+      steps: traceSteps(graph, hops),
     };
   }
 
@@ -90,32 +149,50 @@ 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)) continue;
+        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;
-        const hop = {
+        if (!includeExternal && isExternalNode(other)) continue;
+        const hop: ITtscGraphTrace.IHop = {
           from: edge.from,
           to: edge.to,
           kind: edge.kind,
           depth: depth + 1,
         };
+        const evidence = edgeEvidenceOf(edge);
+        if (evidence !== undefined) hop.evidence = evidence;
+        const aliases = accessAliasesFor(
+          graph.node(edge.to),
+          edgeEvidenceTextOf(edge),
+        );
+        if (aliases !== undefined) hop.aliases = aliases;
         // A back-edge to the start or an already-reached node: record the hop;
         // its endpoints are already represented.
         if (visited.has(otherId)) {
-          hops.push(hop);
+          if (hops.length >= maxHops) truncated = true;
+          else hops.push(hop);
           continue;
         }
-        // A new node past the cap is left unrepresented, so drop its hop too —
+        // A new node past the cap is left unrepresented, so drop its hop too:
         // every hop's endpoints stay resolvable in `reached`/`start`.
         if (reached.size >= maxNodes) {
           truncated = true;
           continue;
         }
+        if (hops.length >= maxHops) {
+          truncated = true;
+          continue;
+        }
         visited.add(otherId);
-        reached.set(otherId, summary(other, depth + 1, withRoles));
+        reached.set(otherId, summary(graph, other, depth + 1, withRoles));
         next.push({ id: otherId, depth: depth + 1 });
         hops.push(hop);
       }
@@ -124,14 +201,42 @@ export function runTrace(
   }
 
   return {
-    start: summary(start.node),
+    type: "trace",
+    start: summary(graph, start.node),
     direction,
     hops,
     reached: [...reached.values()],
+    steps: traceSteps(graph, hops),
+    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 traceSteps(
+  graph: TtscGraphMemory,
+  hops: ITtscGraphTrace.IHop[],
+): string[] {
+  return hops.slice(0, MAX_STEPS).map((hop) => {
+    const from = graph.node(hop.from);
+    const to = graph.node(hop.to);
+    const lhs = from?.qualifiedName ?? from?.name ?? hop.from;
+    const rhs = to?.qualifiedName ?? to?.name ?? hop.to;
+    const evidence =
+      hop.evidence === undefined
+        ? ""
+        : ` at ${hop.evidence.file}:${hop.evidence.startLine}`;
+    const aliases =
+      hop.aliases === undefined ? "" : ` aliases ${hop.aliases.join(", ")}`;
+    return `${lhs} -[${hop.kind}${evidence}${aliases}]-> ${rhs}`;
+  });
+}
+
 /**
  * The shortest dependency path from `startId` to `targetId` over real (non-
  * structural) forward edges, breadth-first, or null when `targetId` is not
@@ -142,11 +247,21 @@ function findPath(
   startId: string,
   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;
   if (startId === targetId) return { path: [startNode], hops: [] };
-  const parent = new Map<string, { via: string; kind: string }>();
+  const parent = new Map<
+    string,
+    {
+      via: string;
+      kind: string;
+      evidence?: ITtscGraphEvidence;
+      evidenceText?: string;
+    }
+  >();
   const visited = new Set<string>([startId]);
   let queue: Array<{ id: string; depth: number }> = [{ id: startId, depth: 0 }];
   while (queue.length > 0) {
@@ -154,13 +269,20 @@ function findPath(
     for (const { id, depth } of queue) {
       if (depth >= maxDepth) continue;
       for (const edge of graph.outgoing(id)) {
-        if (!traversable(edge.kind)) continue;
+        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;
         visited.add(otherId);
-        parent.set(otherId, { via: id, kind: edge.kind });
+        const evidence = edgeEvidenceOf(edge);
+        parent.set(otherId, {
+          via: id,
+          kind: edge.kind,
+          evidence,
+          evidenceText: edgeEvidenceTextOf(edge),
+        });
         if (otherId === targetId) {
           const ids: string[] = [otherId];
           let cur = otherId;
@@ -178,12 +300,18 @@ function findPath(
           const hops: ITtscGraphTrace.IHop[] = [];
           for (let i = 1; i < path.length; i++) {
             const node = path[i]!;
-            hops.push({
+            const parentEdge = parent.get(node.id);
+            const hop: ITtscGraphTrace.IHop = {
               from: path[i - 1]!.id,
               to: node.id,
-              kind: parent.get(node.id)?.kind ?? "calls",
+              kind: parentEdge?.kind ?? "calls",
               depth: i,
-            });
+            };
+            if (parentEdge?.evidence !== undefined)
+              hop.evidence = parentEdge.evidence;
+            const aliases = accessAliasesFor(node, parentEdge?.evidenceText);
+            if (aliases !== undefined) hop.aliases = aliases;
+            hops.push(hop);
           }
           return { path, hops };
         }
@@ -195,14 +323,69 @@ 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.
  */
 function summary(
+  graph: TtscGraphMemory,
   node: ITtscGraphNode,
   depth?: number,
   withRoles = false,
+  withSignature = false,
 ): ITtscGraphTrace.INode {
   const out: ITtscGraphTrace.INode = {
     id: node.id,
@@ -210,24 +393,95 @@ 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);
+    if (sig !== undefined) out.signature = sig;
+  }
   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;
 }
 
 /** An edge the trace should follow: a real dependency, not a structural edge. */
-function traversable(kind: string): boolean {
-  return kind !== "contains" && kind !== "exports" && kind !== "imports";
+function traversable(
+  kind: string,
+  focus: ITtscGraphTrace.IRequest["focus"],
+): boolean {
+  if (kind === "contains" || kind === "exports" || kind === "imports") {
+    return false;
+  }
+  if (focus === "execution") {
+    return (
+      kind === "calls" ||
+      kind === "instantiates" ||
+      kind === "accesses" ||
+      kind === "renders"
+    );
+  }
+  if (focus === "types") {
+    return (
+      kind === "type_ref" ||
+      kind === "extends" ||
+      kind === "implements" ||
+      kind === "overrides" ||
+      kind === "decorates"
+    );
+  }
+  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(
+  value: number | undefined,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  const n = value === undefined || !Number.isFinite(value) ? fallback : value;
+  return Math.max(min, Math.min(max, Math.floor(n)));
 }

package/src/structures/ITtscGraphApplication.ts

@@ -1,68 +1,87 @@
-import { ITtscGraphExpand } from "./ITtscGraphExpand";
-import { ITtscGraphIndex } from "./ITtscGraphIndex";
+import { ITtscGraphDetails } from "./ITtscGraphDetails";
+import { ITtscGraphEntrypoints } from "./ITtscGraphEntrypoints";
+import { ITtscGraphEscape } from "./ITtscGraphEscape";
+import { ITtscGraphLookup } from "./ITtscGraphLookup";
 import { ITtscGraphOverview } from "./ITtscGraphOverview";
-import { ITtscGraphQuery } from "./ITtscGraphQuery";
+import { ITtscGraphTour } from "./ITtscGraphTour";
 import { ITtscGraphTrace } from "./ITtscGraphTrace";
 
-/**
- * The MCP tool surface of `@ttsc/graph`, as a typed application.
- *
- * Each method is one MCP tool; its name is the tool name and its parameter
- * object becomes the tool's 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 {
   /**
-   * The first source-free index for a code question: ranked symbols, exact code
-   * handles mentioned in the query, declaration signatures, and direct
-   * dependency context. Use this before reading source.
+   * Inspect the TypeScript compiler graph contract.
    *
-   * @param props The natural code question or search phrase
-   * @returns Compact graph coordinates and dependency context
-   */
-  graph_index(props: ITtscGraphIndex.IProps): ITtscGraphIndex;
-
-  /**
-   * The project's architecture — folder layers, dependency hotspots, and the
-   * public API. Call first to orient on an unfamiliar codebase.
+   * 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`.
    *
-   * @param props Which facet to project
-   * @returns The requested architecture facets
-   */
-  graph_overview(props: ITtscGraphOverview.IProps): ITtscGraphOverview;
-
-  /**
-   * The declared shape of the given symbols: each one's signature, and for a
-   * class/interface/namespace its members. Handles may be ids or dotted symbol
-   * names. Set `source: true` to also read a specific body, `neighbors: true`
-   * to list what it uses and what uses it.
+   * 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 handles to expand
-   * @returns The resolved nodes, and any handles that did not resolve
+   * @param props Reasoning plus one graph request
+   * @returns Matching `result` union member
    */
-  graph_expand(props: ITtscGraphExpand.IProps): ITtscGraphExpand;
+  inspect_typescript_graph(
+    props: ITtscGraphApplication.IProps,
+  ): ITtscGraphApplication.IResult;
+}
 
-  /**
-   * Find any symbol — class, function, method, or field — by name or
-   * description. Each hit comes with its signature, so the query alone often
-   * answers the question, and `next.expand` gives handles for source
-   * follow-up.
-   *
-   * @param props The query and result cap
-   * @returns Ranked hits with handles
-   */
-  graph_query(props: ITtscGraphQuery.IProps): ITtscGraphQuery;
+export namespace ITtscGraphApplication {
+  /** Draft, review, then submit exactly one graph request or escape. */
+  export interface IProps {
+    /**
+     * User's TypeScript code question.
+     *
+     * 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;
 
-  /**
-   * Follow dependency flow from a symbol: `forward` to what it uses, `reverse`
-   * to what uses it, or `impact` to the public API and tests a change reaches.
-   * Give `from`/`to` as ids or dotted names to get the path between two symbols
-   * in one call — how A reaches B.
-   *
-   * @param props The start, optional target, direction, and bounds
-   * @returns The ordered hops and reached nodes, or candidates for an ambiguous
-   *   start
-   */
-  graph_trace(props: ITtscGraphTrace.IProps): ITtscGraphTrace;
+    /**
+     * Initial request plan before final arguments are filled.
+     *
+     * 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: string;
+
+    /**
+     * Final self-review before calling.
+     *
+     * 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;
+
+    /** 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;
+  }
+
+  /** 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;
+  }
 }