@ttsc/graph 0.16.5 → 0.16.6

package/src/server/runTrace.ts

@@ -1,11 +1,18 @@
 import { TtscGraphMemory } from "../model/TtscGraphMemory";
+import { ITtscGraphEvidence } from "../structures/ITtscGraphEvidence";
 import { ITtscGraphNode } from "../structures/ITtscGraphNode";
 import { ITtscGraphTrace } from "../structures/ITtscGraphTrace";
+import { accessAliasesFor } from "./accessAliases";
 import { resolveGraphHandle } from "./resolveHandle";
-import { signatureOf } from "./runExpand";
+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_HOPS_PER_NODE = 1;
+const MAX_STEPS = 6;
+const MAX_NEXT_HANDLES = 2;
 
 /**
  * Breadth-first trace along the dependency graph. Structural
@@ -16,11 +23,13 @@ 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 maxDepth = bound(props.maxDepth, DEFAULT_DEPTH, 1, MAX_OPEN_DEPTH);
+  const maxNodes = bound(props.maxNodes, DEFAULT_MAX_NODES, 1, MAX_OPEN_NODES);
+  const maxHops = maxNodes * MAX_HOPS_PER_NODE;
   const reverse = direction === "reverse" || direction === "impact";
   // Only an impact trace tags reached nodes with their public-surface role; for
   // forward/reverse the role is noise.
@@ -29,49 +38,62 @@ 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)),
+      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,
+    };
   }
 
-  // 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,
+    };
     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,
     );
+    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),
+      next: nextFromPath(path),
     };
   }
 
@@ -92,30 +114,42 @@ export function runTrace(
       }
       const edges = reverse ? graph.incoming(id) : graph.outgoing(id);
       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 = {
+        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 +158,46 @@ 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: {
+      details: [start.node.id, ...reached.keys()].slice(0, MAX_NEXT_HANDLES),
+      traceFrom: [...reached.keys()].slice(0, MAX_NEXT_HANDLES),
+    },
     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[],
+): 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 +208,20 @@ function findPath(
   startId: string,
   targetId: string,
   maxDepth: number,
+  focus: ITtscGraphTrace.IRequest["focus"],
 ): { 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 +229,19 @@ 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;
         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 +259,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 };
         }
@@ -200,9 +287,11 @@ function findPath(
  * 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,
@@ -211,6 +300,10 @@ function summary(
     file: node.file,
   };
   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");
@@ -221,8 +314,31 @@ function summary(
 }
 
 /** 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 {
@@ -231,3 +347,13 @@ function isTestFile(file: string): boolean {
     /\.(test|spec)\.[cm]?tsx?$/.test(file)
   );
 }
+
+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,116 @@
-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 { 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 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.
  */
 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.
+   * Query the TypeScript project graph for code evidence.
    *
-   * @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 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.
    *
-   * @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.
+   * Fill properties in order: question, graphNeed, draft, review, request.
+   * Write `draft.reason` before `draft.type`, then choose `entrypoints`,
+   * `lookup`, `trace`, `details`, `overview`, or `escape`.
    *
-   * @param props The handles to expand
-   * @returns The resolved nodes, and any handles that did not resolve
-   */
-  graph_expand(props: ITtscGraphExpand.IProps): ITtscGraphExpand;
-
-  /**
-   * 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.
+   * 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 query and result cap
-   * @returns Ranked hits with handles
+   * @param props The reasoning and selected graph request
+   * @returns One `result` union member matching the selected request type
    */
-  graph_query(props: ITtscGraphQuery.IProps): ITtscGraphQuery;
+  query(props: ITtscGraphApplication.IProps): ITtscGraphApplication.IResult;
+}
 
-  /**
-   * 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;
+export namespace ITtscGraphApplication {
+  /** Think, review, then submit exactly one graph request. */
+  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.
+     */
+    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.
+     *
+     * 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`.
+     */
+    draft: IRequestDraft;
+
+    /**
+     * Critical review of the draft request.
+     *
+     * 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`.
+     */
+    review: string;
+
+    /** The graph operation chosen from the reasoning above, or a no-op escape. */
+    request:
+      | ITtscGraphEntrypoints.IRequest
+      | ITtscGraphLookup.IRequest
+      | ITtscGraphTrace.IRequest
+      | ITtscGraphDetails.IRequest
+      | ITtscGraphOverview.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:
+      | ITtscGraphEntrypoints
+      | ITtscGraphLookup
+      | ITtscGraphTrace
+      | ITtscGraphDetails
+      | ITtscGraphOverview
+      | ITtscGraphEscape;
+  }
 }

package/src/structures/ITtscGraphDecorator.ts

@@ -1,32 +1,30 @@
 /**
  * A decorator as written on a declaration, carried on the decorated
- * {@link ITtscGraphNode}'s `decorators`. The graph reports the decorator
- * faithfully rather than interpreting any framework's convention: the `name` is
- * the decorator as written (`Controller`, `Get`, `TypedRoute.Get`, …) and the
- * statically resolvable `arguments` are preserved, so a consumer can apply its
- * own meaning without re-parsing source.
+ * {@link ITtscGraphNode}'s `decorators`.
+ *
+ * The graph reports the decorator faithfully rather than interpreting any
+ * framework's convention: the `name` is the decorator as written (`Controller`,
+ * `Get`, `TypedRoute.Get`, ...), and statically resolvable literal arguments
+ * are preserved so a consumer can apply its own meaning without re-parsing
+ * source.
  */
 export interface ITtscGraphDecorator {
   /**
-   * The decorator name as written, qualified through its access path —
+   * The decorator name as written, qualified through its access path:
    * `Controller`, `Get`, `TypedRoute.Get`, `MessagePattern`.
    */
   name: string;
 
-  /** The call arguments, in source order. Empty for a bare decorator. */
+  /** The literal call arguments, in source order. Empty for a bare decorator. */
   arguments: ITtscGraphDecorator.IArgument[];
 }
 export namespace ITtscGraphDecorator {
   /**
-   * One argument of an {@link ITtscGraphDecorator}. `text` is always the source
-   * of the argument expression; `literal` is set only when the argument is a
-   * string, number, or boolean literal the producer could resolve statically,
-   * so a consumer can use it without evaluating code.
+   * One argument of an {@link ITtscGraphDecorator}. `literal` is set only when
+   * the argument is a string, number, or boolean literal the producer could
+   * resolve statically, so a consumer can use it without evaluating code.
    */
   export interface IArgument {
-    /** The argument expression's source text. */
-    text: string;
-
     /** The statically-resolved literal value, when the argument is a literal. */
     literal?: string | number | boolean;
   }