@ttsc/graph 0.18.3 → 0.19.0

package/lib/structures/ITtscGraphTrace.d.ts

@@ -1,5 +1,4 @@
 import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
-import { ITtscGraphNext } from "./ITtscGraphNext";
 /** The compact dependency or caller flow returned from a selected start symbol. */
 export interface ITtscGraphTrace {
     /** Discriminator for dependency tracing. */
@@ -12,86 +11,119 @@ export interface ITtscGraphTrace {
     hops: ITtscGraphTrace.IHop[];
     /** Unique nodes reached (excluding the start), each with its depth and roles. */
     reached: ITtscGraphTrace.INode[];
-    /** True when the trace hit maxNodes or maxDepth and more flow exists. */
+    /** True when the trace hit its node or depth cap; the returned flow stands. */
     truncated: boolean;
     /** The resolved `to` target, when a path was requested. */
     target?: ITtscGraphTrace.INode;
     /**
-     * When `to` was given: the ordered dependency path from `from` to `to`
-     * (`from` first, `to` last), or empty when `to` is not reachable from
-     * `from`.
+     * Ordered dependency path from `from` to `to` when `to` was given (`from`
+     * first, `to` last), empty when `to` is unreachable.
      */
     path?: ITtscGraphTrace.INode[];
     /** Compact hop summaries preserving node names and edge evidence, capped. */
     steps?: string[];
-    /** How to use this source-free result next. */
-    next: ITtscGraphNext;
-    /** Human-readable compatibility note mirroring `next`. */
-    guide: string;
+    /**
+     * Symbols both ends touch, when no call path runs between them.
+     *
+     * Nothing calls across the gap because in an event-driven codebase nothing
+     * does: a handler registers a listener on an emitter, the emitter's `emit()`
+     * runs whatever a registration put in an array, and no call edge crosses that
+     * array. But both ends touch the emitter, and that is an edge, not a guess —
+     * Excalidraw's pointer handler and its store's emit both reference
+     * `Store.onDurableIncrementEmitter`, which is exactly the seam the call graph
+     * cannot walk.
+     *
+     * A junction is not a path. It is the symbol to look at next, and the edges
+     * that say why.
+     */
+    junctions?: ITtscGraphTrace.IJunction[];
     /** When `from` was an ambiguous name, the matches to disambiguate with. */
     candidates?: ITtscGraphTrace.INode[];
 }
 export declare namespace ITtscGraphTrace {
+    /** A symbol both ends of an unreachable path touch, and how each touches it. */
+    interface IJunction {
+        /** Stable node id: trace or inspect this symbol to cross the seam. */
+        id: string;
+        /** Qualified symbol name when available, otherwise the simple name. */
+        name: string;
+        /** Declaration kind (`variable`, `method`, `class`, ...). */
+        kind: string;
+        /** Project-relative path of the file that declares it. */
+        file: string;
+        /** 1-based declaration line, when known. */
+        line?: number;
+        /** How the start reaches it: the edge kind, and where that edge sits. */
+        fromStart: IJunctionEdge;
+        /** How the target reaches it, or is reached from it. */
+        fromTarget: IJunctionEdge;
+    }
+    /** One edge between an end of the requested path and the junction. */
+    interface IJunctionEdge {
+        /** `calls`, `accesses`, `instantiates`, `type_ref`, ... */
+        kind: string;
+        /** True when the end is the edge's source, false when it is the target. */
+        outgoing: boolean;
+        /** Where the reference sits in source. */
+        evidence?: ITtscGraphEvidence;
+    }
     /** Where and how far to trace dependency flow. */
     interface IRequest {
         /** Discriminator for dependency tracing. */
         type: "trace";
         /**
-         * Where to start: a node id from another tool, a simple symbol name, or a
-         * dotted member name such as `OrderService.create`. An ambiguous name
-         * returns its candidates instead of a trace.
+         * Where to start: a node id, a simple symbol name, or a dotted member
+         * (`OrderService.create`). An ambiguous name returns its candidates instead
+         * of a trace.
          */
         from: string;
         /**
-         * A target symbol: node id, simple symbol name, or dotted member name. When
-         * given, the tool returns the dependency path from `from` to this target,
-         * the one-call answer for "how does A reach B", instead of an open-ended
-         * trace. Prefer this path mode whenever both ends are known.
+         * Target symbol (node id, simple name, or dotted member). When given, the
+         * tool returns the dependency path from `from` to it, the one-call answer
+         * for "how does A reach B". Prefer this path mode whenever both ends are
+         * known.
          */
         to?: string;
         /**
-         * `forward` follows what the start uses (callees, instantiations, renders);
-         * `reverse` follows what uses the start (callers); `impact` is a reverse
-         * trace that prioritizes public API and test nodes a change would reach.
-         * Its test nodes are semantic usage edges, not a text-search inventory.
-         * Caller questions usually fit `reverse`.
+         * Trace direction:
+         *
+         * - `forward`: what the start uses (callees, instantiations, renders)
+         * - `reverse`: what uses the start (callers); the usual fit for caller
+         *   questions
+         * - `impact`: reverse trace prioritizing public API and test nodes a change
+         *   reaches; its test nodes are semantic usage edges, not a text search
          *
          * @default "forward"
          */
         direction?: "forward" | "reverse" | "impact";
         /**
-         * Which non-structural edge family to follow: `execution` follows runtime
-         * calls, instantiations, property access, and JSX renders; `types` follows
-         * type references and inheritance; `all` preserves the full graph. Flow
-         * questions should usually choose `execution` rather than `all`.
+         * Non-structural edge family to follow:
+         *
+         * - `execution`: runtime calls, instantiations, property access, JSX renders
+         * - `types`: type references and inheritance
+         * - `all`: the full graph
+         *
+         * Flow questions usually want `execution`, not `all`.
          *
          * @default "all"
          */
         focus?: "all" | "execution" | "types";
         /**
-         * How many hops deep to follow. Open forward/reverse traces are capped at
-         * 2; impact traces at 4; path mode at 12.
-         *
-         * Prefer the default for open traces. Raise only for path mode or when the
-         * previous trace named the missing next hop.
+         * Hops deep to follow (open forward/reverse cap at 8, impact at 4, path
+         * mode at 12). Raise it to follow a runtime chain to its end in one call.
          *
-         * @default 2
+         * @default 3
          */
         maxDepth?: number;
         /**
-         * Cap on reached nodes; the trace stops and marks itself truncated past it.
-         * Open forward/reverse traces are capped at 8 nodes, impact at 16 nodes.
+         * Cap on reached nodes (open forward/reverse cap at 32, impact at 16).
          *
-         * Prefer the default; use larger open traces only when a named missing edge
-         * requires it.
-         *
-         * @default 6
+         * @default 12
          */
         maxNodes?: number;
         /**
          * Include dependency-boundary nodes from node_modules or bundled `.d.ts`
-         * libraries. Leave false for source-flow tours; enable only when the user
-         * asks about external type/API boundaries.
+         * libraries. Enable only for questions about external type/API boundaries.
          *
          * @default false
          */
@@ -107,17 +139,8 @@ export declare namespace ITtscGraphTrace {
         kind: string;
         /** Hops from the start (1 = direct). */
         depth: number;
-        /**
-         * Source span for the expression that produced this hop. It is repository
-         * evidence for the hop and can be cited without opening the file.
-         */
+        /** Source span that produced the hop: citable without opening the file. */
         evidence?: ITtscGraphEvidence;
-        /**
-         * Stable access-path aliases derived from edge evidence. These preserve a
-         * resolved member's owner and the concrete property path used at the call
-         * site.
-         */
-        aliases?: string[];
     }
     /** A node on the trace: the start, a reached node, or a candidate. */
     interface INode {

package/lib/structures/TtscGraphEdgeKind.d.ts

@@ -6,5 +6,11 @@
  * `extends`, `implements`, `overrides`, `renders`) are resolved by the checker
  * — `renders` is a JSX component use. `decorates` carries a decorator fact and
  * `tests` a test-to-subject relationship.
+ *
+ * `dispatches` is the runtime counterpart of `overrides`/`implements`: the
+ * checker resolves a call to the declaration it names, and where that
+ * declaration is abstract or an interface member, the code that runs is its
+ * implementation. It carries the implementation's declaration span, and a
+ * traversal that follows what executes emits it in place of the dead end.
  */
-export type TtscGraphEdgeKind = "contains" | "exports" | "imports" | "calls" | "accesses" | "instantiates" | "type_ref" | "extends" | "implements" | "overrides" | "decorates" | "renders" | "tests";
+export type TtscGraphEdgeKind = "contains" | "exports" | "imports" | "calls" | "accesses" | "instantiates" | "type_ref" | "extends" | "implements" | "overrides" | "dispatches" | "decorates" | "renders" | "tests";

package/lib/structures/index.d.ts

@@ -1,6 +1,5 @@
 export * from "./ITtscGraphApplication";
 export * from "./ITtscGraphDecorator";
-export * from "./ITtscGraphDiagnostic";
 export * from "./ITtscGraphDump";
 export * from "./ITtscGraphEdge";
 export * from "./ITtscGraphEvidence";
@@ -12,6 +11,7 @@ export * from "./ITtscGraphOverview";
 export * from "./ITtscGraphLookup";
 export * from "./ITtscGraphNext";
 export * from "./ITtscGraphTrace";
+export * from "./ITtscGraphSpan";
 export * from "./ITtscGraphTour";
 export * from "./TtscGraphEdgeKind";
 export * from "./TtscGraphNodeKind";

package/lib/structures/index.js

@@ -21,7 +21,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./ITtscGraphApplication"), exports);
 __exportStar(require("./ITtscGraphDecorator"), exports);
-__exportStar(require("./ITtscGraphDiagnostic"), exports);
 __exportStar(require("./ITtscGraphDump"), exports);
 __exportStar(require("./ITtscGraphEdge"), exports);
 __exportStar(require("./ITtscGraphEvidence"), exports);
@@ -33,6 +32,7 @@ __exportStar(require("./ITtscGraphOverview"), exports);
 __exportStar(require("./ITtscGraphLookup"), exports);
 __exportStar(require("./ITtscGraphNext"), exports);
 __exportStar(require("./ITtscGraphTrace"), exports);
+__exportStar(require("./ITtscGraphSpan"), exports);
 __exportStar(require("./ITtscGraphTour"), exports);
 __exportStar(require("./TtscGraphEdgeKind"), exports);
 __exportStar(require("./TtscGraphNodeKind"), exports);

package/lib/structures/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/structures/index.ts"],"names":[],"mappings":";AAAA,uEAAuE;AACvE,0EAA0E;AAC1E,8EAA8E;AAC9E,gFAAgF;AAChF,6BAA6B;;;;;;;;;;;;;;;;AAE7B,0DAAwC;AACxC,wDAAsC;AACtC,yDAAuC;AACvC,mDAAiC;AACjC,mDAAiC;AACjC,uDAAqC;AACrC,qDAAmC;AACnC,sDAAoC;AACpC,0DAAwC;AACxC,mDAAiC;AACjC,uDAAqC;AACrC,qDAAmC;AACnC,mDAAiC;AACjC,oDAAkC;AAClC,mDAAiC;AACjC,sDAAoC;AACpC,sDAAoC;AACpC,0DAAwC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/structures/index.ts"],"names":[],"mappings":";AAAA,uEAAuE;AACvE,0EAA0E;AAC1E,8EAA8E;AAC9E,gFAAgF;AAChF,6BAA6B;;;;;;;;;;;;;;;;AAE7B,0DAAwC;AACxC,wDAAsC;AACtC,mDAAiC;AACjC,mDAAiC;AACjC,uDAAqC;AACrC,qDAAmC;AACnC,sDAAoC;AACpC,0DAAwC;AACxC,mDAAiC;AACjC,uDAAqC;AACrC,qDAAmC;AACnC,mDAAiC;AACjC,oDAAkC;AAClC,mDAAiC;AACjC,mDAAiC;AACjC,sDAAoC;AACpC,sDAAoC;AACpC,0DAAwC"}

package/lib/view.js

@@ -50,7 +50,9 @@ function parseViewArgs(argv) {
  */
 function runView(argv) {
     const opts = parseViewArgs(argv);
-    const binary = (0, resolveGraphBinary_1.resolveGraphBinary)();
+    // Anchor binary resolution at the project selected by `--cwd`, so `view` from
+    // an unrelated directory still finds the `ttsc` installed under the target.
+    const binary = (0, resolveGraphBinary_1.resolveGraphBinary)(process.env, opts.cwd);
     if (binary === null) {
         process.stderr.write("@ttsc/graph: could not resolve the ttscgraph binary. " +
             "Install `ttsc` so its platform package is present, " +

package/lib/view.js.map

@@ -1 +1 @@
-{"version":3,"file":"view.js","sourceRoot":"","sources":["../src/view.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"view.js","sourceRoot":"","sources":["../src/view.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/graph",
-  "version": "0.18.3",
+  "version": "0.19.0",
   "description": "Checker-resolved architecture graph over MCP for coding agents, backed by ttsc's in-process TypeScript-Go compiler.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -16,8 +16,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@typia/mcp": "^13.0.0",
-    "typia": "^13.0.0"
+    "@typia/mcp": "13.1.0",
+    "typia": "13.1.0"
   },
   "keywords": [
     "ttsc",
@@ -39,7 +39,7 @@
     "three": "^0.184.0",
     "three-forcegraph": "^1.43.4",
     "typescript": "^7.0.2",
-    "ttsc": "0.18.3"
+    "ttsc": "0.19.0"
   },
   "repository": {
     "type": "git",

package/src/TtscGraphApplication.ts

@@ -1,5 +1,10 @@
 import { TtscGraphMemory } from "./model/TtscGraphMemory";
-import { resultGuide, resultNext } from "./server/resultGuide";
+import {
+  RESULT_AUDIT,
+  RESULT_AUDIT_ESCAPE,
+  RESULT_AUDIT_SELECTION,
+} from "./server/resultAudit";
+import { resultNext } from "./server/resultNext";
 import { runDetails } from "./server/runDetails";
 import { runEntrypoints } from "./server/runEntrypoints";
 import { runLookup } from "./server/runLookup";
@@ -9,7 +14,9 @@ import { runTrace } from "./server/runTrace";
 import { ITtscGraphApplication } from "./structures/ITtscGraphApplication";
 import { ITtscGraphEscape } from "./structures/ITtscGraphEscape";
 
-export type TtscGraphSource = TtscGraphMemory | (() => TtscGraphMemory);
+export type TtscGraphSource =
+  | TtscGraphMemory
+  | (() => TtscGraphMemory | Promise<TtscGraphMemory>);
 
 /**
  * The MCP tool surface as a plain class over the resident
@@ -22,77 +29,105 @@ export type TtscGraphSource = TtscGraphMemory | (() => TtscGraphMemory);
  * The method delegates to the pure graph functions in `./server`, which are
  * unit-testable without a transport; this class only binds them to the graph.
  *
- * Every method answers from the resident graph; none recompiles. Output is kept
+ * Every method answers from the current resident graph. The source may refresh
+ * that graph before the operation when project files changed. Output is kept
  * compact and bounded so a model can read structure without a file read, which
  * is the token win the redesign exists for.
  */
 export class TtscGraphApplication implements ITtscGraphApplication {
-  private readonly graph: () => TtscGraphMemory;
+  private readonly graph: () => TtscGraphMemory | Promise<TtscGraphMemory>;
 
   public constructor(source: TtscGraphSource) {
     this.graph = typeof source === "function" ? source : () => source;
   }
 
-  public inspect_typescript_graph(
+  public async inspect_typescript_graph(
     props: ITtscGraphApplication.IProps,
-  ): ITtscGraphApplication.IResult {
+  ): Promise<ITtscGraphApplication.IOutput> {
     if (props.request.type === "escape") {
       const result = this.escape(props.request.reason);
       if (props.request.nextStep !== undefined) {
         result.nextStep = props.request.nextStep;
       }
       return {
+        audit: RESULT_AUDIT_ESCAPE,
+        next: resultNext(
+          "outside",
+          "The caller chose to leave the graph, so this call carries no graph facts.",
+        ),
         result,
       };
     }
+    const graph = await this.graph();
     switch (props.request.type) {
-      case "entrypoints":
+      case "entrypoints": {
+        // A ranked shortlist matched against the question: its facts are
+        // compiler-verified, but its selection is heuristic, so it carries the
+        // selection audit rather than the exact-structure one.
+        const r = runEntrypoints(graph, props.request);
         return {
-          result: runEntrypoints(this.graph(), props.request),
+          audit: RESULT_AUDIT_SELECTION,
+          next: r.next,
+          result: r.result,
         };
-      case "lookup":
+      }
+      case "lookup": {
+        // Natural-query ranker (see `runLookup`): scored, ranked, per-file
+        // capped, and limited, so the selection is heuristic.
+        const r = runLookup(graph, props.request);
         return {
-          result: runLookup(this.graph(), props.request),
+          audit: RESULT_AUDIT_SELECTION,
+          next: r.next,
+          result: r.result,
         };
-      case "trace":
+      }
+      case "trace": {
+        const r = runTrace(graph, props.request);
         return {
-          result: runTrace(this.graph(), props.request),
+          audit: RESULT_AUDIT,
+          next: r.next,
+          result: r.result,
         };
-      case "details":
+      }
+      case "details": {
+        const r = runDetails(graph, props.request);
         return {
-          result: runDetails(this.graph(), props.request),
+          audit: RESULT_AUDIT,
+          next: r.next,
+          result: r.result,
         };
-      case "overview":
+      }
+      case "overview": {
+        const r = runOverview(graph, props.request);
         return {
-          result: runOverview(this.graph(), props.request),
+          audit: RESULT_AUDIT,
+          next: r.next,
+          result: r.result,
         };
-      case "tour":
+      }
+      case "tour": {
+        // The tour ranks against the question, and the question is `props`
+        // — the caller wrote it once, at the top, in the user's words. It
+        // ranks seeds, walks bounded flows, and slices to a limit, so its
+        // selection is heuristic.
+        const r = runTour(graph, props.request, props.question);
         return {
-          result: runTour(this.graph(), props.request),
+          audit: RESULT_AUDIT_SELECTION,
+          next: r.next,
+          result: r.result,
         };
+      }
       default:
         props.request satisfies never;
         throw new Error("Unknown graph request type");
     }
   }
 
-  private escape(
-    reason: string,
-    nextStep?: string,
-    action: "answer" | "outside" | "clarify" = "outside",
-  ): ITtscGraphEscape {
+  private escape(reason: string, nextStep?: string): ITtscGraphEscape {
     return {
       type: "escape",
       skipped: true,
       reason,
-      next: resultNext(
-        action,
-        nextStep ??
-          "Graph evidence is exhausted or not the next evidence source.",
-      ),
-      guide: resultGuide(
-        "Finish from existing graph evidence, state the graph gap, or ask for clarification.",
-      ),
       ...(nextStep !== undefined ? { nextStep } : {}),
     };
   }

package/src/index.ts

@@ -6,6 +6,21 @@ import { resolveGraphBinary } from "./resolveGraphBinary";
 import { startServer } from "./server/startServer";
 import { runView } from "./view";
 
+/** What a graph result says about where its facts came from. */
+export {
+  RESULT_AUDIT,
+  RESULT_AUDIT_ESCAPE,
+  RESULT_AUDIT_SELECTION,
+} from "./server/resultAudit";
+
+// Programmatic entry points. Each resolves its native binary from the project
+// `cwd` it is given (see `resolveGraphBinary`), so a caller that graphs a
+// project other than its own process directory names it once and the binary is
+// found under that project's installed `ttsc`.
+export { resolveGraphBinary } from "./resolveGraphBinary";
+export { loadGraph } from "./model/loadGraph";
+export { TtscGraphSession } from "./model/TtscGraphSession";
+
 // The server version reported in the MCP handshake; read from this package.
 const VERSION: string = (require("../package.json") as { version: string })
   .version;
@@ -38,10 +53,10 @@ function parseProjectArgs(argv: readonly string[]): {
  * - `view`: JS-orchestrated 3D viewer (dump -> reduce -> serve -> open).
  * - `dump`: pass through to the native `ttscgraph dump`, which prints the whole
  *   graph as JSON for piping or the viewer.
- * - Default: serve the MCP graph over stdio. The TypeScript server runs
- *   `ttscgraph dump` once to build the resident graph, then answers tool calls
- *   from memory; the agent's MCP client speaks JSON-RPC over this process's
- *   stdin/stdout. The process stays alive on the stdio transport.
+ * - Default: serve the MCP graph over stdio. The TypeScript server keeps a native
+ *   incremental compiler session resident, checks the disk snapshot before each
+ *   graph operation, and reuses the in-memory graph when unchanged; the agent's
+ *   MCP client speaks JSON-RPC over this process's stdin/stdout.
  */
 export function runGraph(
   argv: readonly string[] = process.argv.slice(2),
@@ -65,7 +80,10 @@ export function runGraph(
  * on this process's stdout. Returns the child's exit code.
  */
 function runDump(argv: readonly string[]): number {
-  const binary = resolveGraphBinary();
+  // Resolve the native binary from the target project the caller named with
+  // `--cwd`, not from wherever the launcher process happened to start.
+  const { cwd } = parseProjectArgs(argv);
+  const binary = resolveGraphBinary(process.env, cwd);
   if (binary === null) {
     process.stderr.write(
       "@ttsc/graph: could not resolve the ttscgraph binary. " +