@ttsc/graph 0.18.2 → 0.18.4

package/lib/server/startServer.js.map

@@ -1 +1 @@
-{"version":3,"file":"startServer.js","sourceRoot":"","sources":["../../src/server/startServer.ts"],"names":[],"mappings":";;;AAAA,wEAAiF;AAGjF,kDAA+C;AAC/C,iDAA8C;AAE9C;;;;GAIG;AACI,KAAK,sBAAsB,OAKjC;IACC,IAAI,KAAkC,CAAC;IACvC,MAAM,MAAM,GAAG,IAAA,2BAAY,EAAC,GAAG,EAAE;QAC/B,KAAK,KAAK,IAAA,qBAAS,EAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;QACtE,OAAO,KAAK,CAAC;IACf,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,MAAM,SAAS,GAAG,IAAI,+BAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}
+{"version":3,"file":"startServer.js","sourceRoot":"","sources":["../../src/server/startServer.ts"],"names":[],"mappings":";;;AAAA,wEAAiF;AAEjF,gEAA6D;AAC7D,iDAA8C;AAE9C;;;;;GAKG;AACI,KAAK,sBAAsB,OAKjC;IACC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACzC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,eAAe,CAAC;IACrD,IAAI,OAAqC,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAA,2BAAY,EAAC,KAAK,IAAI,EAAE;QACrC,OAAO,KAAK,IAAI,mCAAgB,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;QACpD,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,MAAM,SAAS,GAAG,IAAI,+BAAoB,EAAE,CAAC;IAC7C,MAAM,YAAY,GAAG,GAAG,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC;IAC5C,SAAS,CAAC,OAAO,GAAG,YAAY,CAAC;IACjC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;IACxC,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}

package/lib/structures/ITtscGraphApplication.d.ts

@@ -9,14 +9,16 @@ import { ITtscGraphTrace } from "./ITtscGraphTrace";
  * ## What This MCP Is
  *
  * `inspect_typescript_graph` returns a compiler-built TypeScript graph contract
- * for the current source snapshot.
+ * for the current on-disk source snapshot. Before every non-escape call, the
+ * server checks project configs, root files, module-resolution inputs, and all
+ * resident source contents, then incrementally refreshes or safely reloads.
  *
  * 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.
+ * Returned graph facts are sacred, infallible compiler truth for the snapshot
+ * synchronized by that call. Never verify them with files or more graph calls.
  *
  * ## Result Contract
  *
@@ -32,15 +34,17 @@ import { ITtscGraphTrace } from "./ITtscGraphTrace";
  * - 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.
+ * - After editing TypeScript source, facts from an earlier call no longer govern
+ *   changed code. Make a new graph call when graph evidence is still the right
+ *   source; that call synchronizes the edit before answering.
  *
  * ## 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.
+ * For the source snapshot synchronized by a call, 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
  *
@@ -101,13 +105,13 @@ export interface ITtscGraphApplication {
      *
      * 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.
+     * from that result. Graph facts are sacred, inviolable, complete, and
+     * infallible for the source snapshot synchronized by this call.
      *
      * @param props Reasoning plus one graph request
      * @returns Matching `result` union member
      */
-    inspect_typescript_graph(props: ITtscGraphApplication.IProps): ITtscGraphApplication.IResult;
+    inspect_typescript_graph(props: ITtscGraphApplication.IProps): Promise<ITtscGraphApplication.IResult>;
 }
 export declare namespace ITtscGraphApplication {
     /** Draft, review, then submit exactly one graph request or escape. */

package/lib/structures/ITtscGraphDump.d.ts

@@ -6,9 +6,10 @@ import { ITtscGraphNode } from "./ITtscGraphNode";
  * wire contract between the Go fact-builder and the TypeScript graph engine.
  *
  * It is the complete graph with none of the per-response caps the MCP tools
- * apply: every node and edge the build resolved. The server parses it once at
- * startup (typia-validated) into an in-memory resident graph and answers every
- * tool call from that warm model; the bundled 3D viewer reduces the same dump.
+ * apply: every node and edge the build resolved. The server parses each changed
+ * native snapshot (typia-validated) into an in-memory resident graph and reuses
+ * that warm model while project inputs stay unchanged; the bundled 3D viewer
+ * reduces the same dump.
  *
  * Paths in `project` and `tsconfig` are absolute; `file` fields on nodes,
  * edges, and diagnostics are project-relative.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/graph",
-  "version": "0.18.2",
+  "version": "0.18.4",
   "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",
@@ -39,7 +39,7 @@
     "three": "^0.184.0",
     "three-forcegraph": "^1.43.4",
     "typescript": "^7.0.2",
-    "ttsc": "0.18.2"
+    "ttsc": "0.18.4"
   },
   "repository": {
     "type": "git",

package/src/TtscGraphApplication.ts

@@ -9,7 +9,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,20 +24,21 @@ 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.IResult> {
     if (props.request.type === "escape") {
       const result = this.escape(props.request.reason);
       if (props.request.nextStep !== undefined) {
@@ -45,30 +48,31 @@ export class TtscGraphApplication implements ITtscGraphApplication {
         result,
       };
     }
+    const graph = await this.graph();
     switch (props.request.type) {
       case "entrypoints":
         return {
-          result: runEntrypoints(this.graph(), props.request),
+          result: runEntrypoints(graph, props.request),
         };
       case "lookup":
         return {
-          result: runLookup(this.graph(), props.request),
+          result: runLookup(graph, props.request),
         };
       case "trace":
         return {
-          result: runTrace(this.graph(), props.request),
+          result: runTrace(graph, props.request),
         };
       case "details":
         return {
-          result: runDetails(this.graph(), props.request),
+          result: runDetails(graph, props.request),
         };
       case "overview":
         return {
-          result: runOverview(this.graph(), props.request),
+          result: runOverview(graph, props.request),
         };
       case "tour":
         return {
-          result: runTour(this.graph(), props.request),
+          result: runTour(graph, props.request),
         };
       default:
         props.request satisfies never;

package/src/index.ts

@@ -38,10 +38,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),

package/src/model/TtscGraphSession.ts

@@ -0,0 +1,200 @@
+import { ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import readline from "node:readline";
+import typia from "typia";
+
+import { ensureExecutable } from "../nativeExecutable";
+import { resolveGraphBinary } from "../resolveGraphBinary";
+import { ITtscGraphDump } from "../structures/ITtscGraphDump";
+import { TtscGraphMemory } from "./TtscGraphMemory";
+
+interface SessionResponse {
+  id: number;
+  changed: boolean;
+  mode?: "initial" | "unchanged" | "incremental" | "rebuild" | "reload";
+  dump?: unknown;
+  error?: string;
+}
+
+interface Pending {
+  resolve: (response: SessionResponse) => void;
+  reject: (error: Error) => void;
+}
+
+/**
+ * Resident bridge to `ttscgraph serve`.
+ *
+ * Every graph request first asks the native session for the current disk
+ * snapshot. Unchanged requests reuse the existing {@link TtscGraphMemory}; an
+ * edited source reuses tsgo's resident Program through `driver.Session`, while
+ * config and root-file-set changes force a safe full reload.
+ */
+export class TtscGraphSession {
+  private readonly cwd: string;
+  private readonly tsconfig: string;
+  private readonly binary: string;
+  private child: ChildProcessWithoutNullStreams | undefined;
+  private stderr = "";
+  private nextId = 0;
+  private readonly pending = new Map<number, Pending>();
+  private queue: Promise<void> = Promise.resolve();
+  private current: TtscGraphMemory | undefined;
+  private closed = false;
+
+  public constructor(options: {
+    cwd: string;
+    tsconfig: string;
+    binary?: string;
+  }) {
+    const binary = options.binary ?? resolveGraphBinary();
+    if (binary === null) {
+      throw new Error(
+        "@ttsc/graph: could not resolve the ttscgraph binary. " +
+          "Install `ttsc` so its platform package is present, " +
+          "or set TTSC_GRAPH_BINARY to an absolute path.",
+      );
+    }
+    ensureExecutable(binary);
+    this.cwd = options.cwd;
+    this.tsconfig = options.tsconfig;
+    this.binary = binary;
+  }
+
+  /** Return a graph for the current disk snapshot, serialized per tool call. */
+  public graph(): Promise<TtscGraphMemory> {
+    let resolve!: (graph: TtscGraphMemory) => void;
+    let reject!: (error: Error) => void;
+    const result = new Promise<TtscGraphMemory>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    this.queue = this.queue
+      .catch(() => undefined)
+      .then(async () => {
+        try {
+          resolve(await this.refresh());
+        } catch (error) {
+          reject(asError(error));
+        }
+      });
+    return result;
+  }
+
+  /** Close the native session. Safe to call more than once. */
+  public close(): void {
+    this.closed = true;
+    const child = this.child;
+    this.child = undefined;
+    if (child !== undefined && !child.killed) child.stdin.end();
+    this.failPending(new Error("@ttsc/graph: native session closed"));
+  }
+
+  private async refresh(): Promise<TtscGraphMemory> {
+    const response = await this.request();
+    if (response.error !== undefined) {
+      throw new Error(`@ttsc/graph: ${response.error}`);
+    }
+    if (response.changed) {
+      if (response.dump === undefined) {
+        throw new Error(
+          `@ttsc/graph: native ${response.mode ?? "changed"} response omitted its dump`,
+        );
+      }
+      const dump = typia.assert<ITtscGraphDump>(response.dump);
+      this.current = TtscGraphMemory.from(dump);
+    }
+    if (this.current === undefined) {
+      throw new Error(
+        "@ttsc/graph: native session returned no initial graph snapshot",
+      );
+    }
+    return this.current;
+  }
+
+  private request(): Promise<SessionResponse> {
+    const child = this.ensureChild();
+    const id = ++this.nextId;
+    return new Promise<SessionResponse>((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      child.stdin.write(`${JSON.stringify({ id })}\n`, (error) => {
+        if (error === null || error === undefined) return;
+        this.pending.delete(id);
+        reject(
+          new Error(
+            `@ttsc/graph: could not request native snapshot: ${error.message}`,
+          ),
+        );
+      });
+    });
+  }
+
+  private ensureChild(): ChildProcessWithoutNullStreams {
+    if (this.closed) {
+      // A request queued behind the close must not respawn the native
+      // process; an orphaned resident compiler would outlive the MCP server.
+      throw new Error("@ttsc/graph: native session is closed");
+    }
+    if (this.child !== undefined && this.child.exitCode === null) {
+      return this.child;
+    }
+    this.stderr = "";
+    const child = spawn(
+      this.binary,
+      ["serve", "--cwd", this.cwd, "--tsconfig", this.tsconfig],
+      { stdio: ["pipe", "pipe", "pipe"], windowsHide: true },
+    );
+    this.child = child;
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk: string) => {
+      this.stderr = (this.stderr + chunk).slice(-64 * 1024);
+    });
+    const lines = readline.createInterface({ input: child.stdout });
+    lines.on("line", (line) => this.onLine(line));
+    child.on("error", (error) => this.failChild(child, error));
+    child.on("exit", (code, signal) => {
+      if (this.child !== child) return;
+      this.child = undefined;
+      this.failPending(
+        new Error(
+          `@ttsc/graph: native session exited (code=${String(code)}, signal=${String(signal)})${
+            this.stderr.trim() === "" ? "" : `: ${this.stderr.trim()}`
+          }`,
+        ),
+      );
+    });
+    return child;
+  }
+
+  private onLine(line: string): void {
+    let response: SessionResponse;
+    try {
+      response = JSON.parse(line) as SessionResponse;
+    } catch (error) {
+      this.failPending(
+        new Error(
+          `@ttsc/graph: native session returned invalid JSON: ${asError(error).message}`,
+        ),
+      );
+      return;
+    }
+    const pending = this.pending.get(response.id);
+    if (pending === undefined) return;
+    this.pending.delete(response.id);
+    pending.resolve(response);
+  }
+
+  private failChild(child: ChildProcessWithoutNullStreams, error: Error): void {
+    if (this.child === child) this.child = undefined;
+    this.failPending(
+      new Error(`@ttsc/graph: native session failed: ${error.message}`),
+    );
+  }
+
+  private failPending(error: Error): void {
+    for (const pending of this.pending.values()) pending.reject(error);
+    this.pending.clear();
+  }
+}
+
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}

package/src/model/loadGraph.ts

@@ -13,9 +13,9 @@ const MAX_DUMP_BYTES = 1024 * 1024 * 1024;
 
 /**
  * Build the resident {@link TtscGraphMemory} for a project by running `ttscgraph
- * dump` once and loading its JSON. This is the cold path behind the MCP tool
- * calls: one type-check in Go produces the checker-resolved fact graph, then
- * every later tool call is answered from the in-memory model.
+ * dump` once and loading its JSON. This is the one-shot path for direct callers
+ * and the viewer. The MCP server uses `TtscGraphSession` instead so source
+ * edits refresh a resident compiler session.
  *
  * Throws when the binary cannot be resolved, the dump command fails, or its
  * output is not a readable graph — the server surfaces the failure rather than

package/src/server/startServer.ts

@@ -1,13 +1,13 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
-import { TtscGraphMemory } from "../model/TtscGraphMemory";
-import { loadGraph } from "../model/loadGraph";
+import { TtscGraphSession } from "../model/TtscGraphSession";
 import { createServer } from "./createServer";
 
 /**
  * Serve the graph tools over MCP on stdio. The server answers the MCP handshake
- * immediately and builds the resident graph on the first tool call, so a large
- * project cannot make the client give up before tools are advertised.
+ * immediately and opens the resident incremental graph session on the first
+ * real tool call, so a large project cannot make the client give up before
+ * tools are advertised and an escape request still performs no graph work.
  */
 export async function startServer(options: {
   cwd?: string;
@@ -15,11 +15,16 @@ export async function startServer(options: {
   /** Server version reported in the MCP handshake. */
   version: string;
 }): Promise<void> {
-  let graph: TtscGraphMemory | undefined;
-  const server = createServer(() => {
-    graph ??= loadGraph({ cwd: options.cwd, tsconfig: options.tsconfig });
-    return graph;
+  const cwd = options.cwd ?? process.cwd();
+  const tsconfig = options.tsconfig ?? "tsconfig.json";
+  let session: TtscGraphSession | undefined;
+  const server = createServer(async () => {
+    session ??= new TtscGraphSession({ cwd, tsconfig });
+    return session.graph();
   }, options.version);
   const transport = new StdioServerTransport();
+  const closeSession = () => session?.close();
+  transport.onclose = closeSession;
+  process.stdin.once("end", closeSession);
   await server.connect(transport);
 }

package/src/structures/ITtscGraphApplication.ts

@@ -10,14 +10,16 @@ import { ITtscGraphTrace } from "./ITtscGraphTrace";
  * ## What This MCP Is
  *
  * `inspect_typescript_graph` returns a compiler-built TypeScript graph contract
- * for the current source snapshot.
+ * for the current on-disk source snapshot. Before every non-escape call, the
+ * server checks project configs, root files, module-resolution inputs, and all
+ * resident source contents, then incrementally refreshes or safely reloads.
  *
  * 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.
+ * Returned graph facts are sacred, infallible compiler truth for the snapshot
+ * synchronized by that call. Never verify them with files or more graph calls.
  *
  * ## Result Contract
  *
@@ -33,15 +35,17 @@ import { ITtscGraphTrace } from "./ITtscGraphTrace";
  * - 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.
+ * - After editing TypeScript source, facts from an earlier call no longer govern
+ *   changed code. Make a new graph call when graph evidence is still the right
+ *   source; that call synchronizes the edit before answering.
  *
  * ## 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.
+ * For the source snapshot synchronized by a call, 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
  *
@@ -102,15 +106,15 @@ export interface ITtscGraphApplication {
    *
    * 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.
+   * from that result. Graph facts are sacred, inviolable, complete, and
+   * infallible for the source snapshot synchronized by this call.
    *
    * @param props Reasoning plus one graph request
    * @returns Matching `result` union member
    */
   inspect_typescript_graph(
     props: ITtscGraphApplication.IProps,
-  ): ITtscGraphApplication.IResult;
+  ): Promise<ITtscGraphApplication.IResult>;
 }
 
 export namespace ITtscGraphApplication {

package/src/structures/ITtscGraphDump.ts

@@ -7,9 +7,10 @@ import { ITtscGraphNode } from "./ITtscGraphNode";
  * wire contract between the Go fact-builder and the TypeScript graph engine.
  *
  * It is the complete graph with none of the per-response caps the MCP tools
- * apply: every node and edge the build resolved. The server parses it once at
- * startup (typia-validated) into an in-memory resident graph and answers every
- * tool call from that warm model; the bundled 3D viewer reduces the same dump.
+ * apply: every node and edge the build resolved. The server parses each changed
+ * native snapshot (typia-validated) into an in-memory resident graph and reuses
+ * that warm model while project inputs stay unchanged; the bundled 3D viewer
+ * reduces the same dump.
  *
  * Paths in `project` and `tsconfig` are absolute; `file` fields on nodes,
  * edges, and diagnostics are project-relative.