@ttsc/graph 0.16.4 → 0.16.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ttsc/graph",
-  "version": "0.16.4",
-  "description": "Checker-resolved code graph and diagnostics over MCP for coding agents, backed by ttsc's in-process TypeScript-Go compiler.",
+  "version": "0.16.5",
+  "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",
   "bin": {
@@ -14,6 +14,15 @@
     },
     "./package.json": "./package.json"
   },
+  "ttsc": {
+    "plugin": {
+      "transform": "typia/lib/transform"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "typia": "13.0.0-dev.20260605.1"
+  },
   "keywords": [
     "ttsc",
     "mcp",
@@ -28,9 +37,13 @@
   ],
   "devDependencies": {
     "@types/node": "^25.3.0",
+    "@types/three": "^0.184.1",
+    "esbuild": "^0.25.12",
     "rimraf": "^6.1.2",
+    "three": "^0.184.0",
+    "three-forcegraph": "^1.43.4",
     "typescript": "7.0.1-rc",
-    "ttsc": "0.16.4"
+    "ttsc": "0.16.5"
   },
   "repository": {
     "type": "git",
@@ -43,6 +56,6 @@
   },
   "homepage": "https://ttsc.dev",
   "scripts": {
-    "build": "rimraf lib && tsc"
+    "build": "rimraf lib && node node_modules/ttsc/lib/launcher/ttsc.js && node build/bundle-viewer.mjs"
   }
 }

package/src/TtscGraphApplication.ts

@@ -0,0 +1,57 @@
+import { TtscGraphMemory } from "./model/TtscGraphMemory";
+import { runExpand } from "./server/runExpand";
+import { runIndex } from "./server/runIndex";
+import { runOverview } from "./server/runOverview";
+import { runQuery } from "./server/runQuery";
+import { runTrace } from "./server/runTrace";
+import { ITtscGraphApplication } from "./structures/ITtscGraphApplication";
+import { ITtscGraphExpand } from "./structures/ITtscGraphExpand";
+import { ITtscGraphIndex } from "./structures/ITtscGraphIndex";
+import { ITtscGraphOverview } from "./structures/ITtscGraphOverview";
+import { ITtscGraphQuery } from "./structures/ITtscGraphQuery";
+import { ITtscGraphTrace } from "./structures/ITtscGraphTrace";
+
+export type TtscGraphSource = TtscGraphMemory | (() => TtscGraphMemory);
+
+/**
+ * The MCP tool surface as a plain class over the resident
+ * {@link TtscGraphMemory}.
+ *
+ * Each public method is one MCP tool — `typia.llm.controller` reflects
+ * {@link ITtscGraphApplication} to generate every tool's JSON schema and
+ * argument validator from these signatures and their JSDoc, with no
+ * hand-written schema. The methods delegate to the pure tool 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
+ * 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;
+
+  public constructor(source: TtscGraphSource) {
+    this.graph = typeof source === "function" ? source : () => source;
+  }
+
+  public graph_index(props: ITtscGraphIndex.IProps): ITtscGraphIndex {
+    return runIndex(this.graph(), props);
+  }
+
+  public graph_overview(props: ITtscGraphOverview.IProps): ITtscGraphOverview {
+    return runOverview(this.graph(), props);
+  }
+
+  public graph_expand(props: ITtscGraphExpand.IProps): ITtscGraphExpand {
+    return runExpand(this.graph(), props);
+  }
+
+  public graph_query(props: ITtscGraphQuery.IProps): ITtscGraphQuery {
+    return runQuery(this.graph(), props);
+  }
+
+  public graph_trace(props: ITtscGraphTrace.IProps): ITtscGraphTrace {
+    return runTrace(this.graph(), props);
+  }
+}

package/src/index.ts

@@ -1,50 +1,19 @@
-import { spawn, spawnSync } from "node:child_process";
-import fs from "node:fs";
-import { createRequire } from "node:module";
-import os from "node:os";
+import { spawnSync } from "node:child_process";
 import path from "node:path";
 
+import { resolveGraphBinary } from "./resolveGraphBinary";
+import { startServer } from "./server/startServer";
+import { runView } from "./view";
+
+// The server version reported in the MCP handshake; read from this package.
+const VERSION: string = (require("../package.json") as { version: string })
+  .version;
+
 /**
- * Resolve the per-platform `ttscgraph` MCP server binary, or `null` when it
- * cannot be located.
- *
- * `ttsc` is a peer the user installs alongside `@ttsc/graph` (not a dependency
- * of this launcher), so resolution starts from the user's project, not from
- * this package's own tree.
- *
- * Resolution order:
- *
- * 1. `TTSC_GRAPH_BINARY` env var, when set to an absolute path.
- * 2. The per-platform npm package `@ttsc/<platform>-<arch>/bin/ttscgraph[.exe]`.
- *    That package carries `ttsc`, `ttscserver`, and `ttscgraph` together and is
- *    an `optionalDependency` of `ttsc`, so it is resolved from `ttsc`'s
- *    location — found from `process.cwd()` (the project where the agent ran the
- *    server).
+ * The project root and tsconfig to build the graph for, from the `--cwd` /
+ * `--tsconfig` flags (the same ones `ttscgraph dump` accepts). Defaults are the
+ * process working directory and `tsconfig.json`.
  */
-export function resolveGraphBinary(
-  env: NodeJS.ProcessEnv = process.env,
-  cwd: string = process.cwd(),
-): string | null {
-  if (env.TTSC_GRAPH_BINARY && path.isAbsolute(env.TTSC_GRAPH_BINARY)) {
-    return env.TTSC_GRAPH_BINARY;
-  }
-  const exe = process.platform === "win32" ? "ttscgraph.exe" : "ttscgraph";
-  try {
-    const ttscPackageJson = require.resolve("ttsc/package.json", {
-      paths: [cwd],
-    });
-    const fromTtsc = createRequire(ttscPackageJson);
-    return fromTtsc.resolve(
-      `@ttsc/${process.platform}-${process.arch}/bin/${exe}`,
-    );
-  } catch {
-    return null;
-  }
-}
-
-/** The project root and tsconfig the server was pointed at, mirroring the
- * `--cwd` / `--tsconfig` flags ttscgraph itself parses, so the background
- * diagnostics worker checks the same project. */
 function parseProjectArgs(argv: readonly string[]): {
   cwd: string;
   tsconfig: string;
@@ -56,62 +25,45 @@ function parseProjectArgs(argv: readonly string[]): {
     if (arg === "--cwd" && i + 1 < argv.length) cwd = argv[++i]!;
     else if (arg.startsWith("--cwd=")) cwd = arg.slice("--cwd=".length);
     else if (arg === "--tsconfig" && i + 1 < argv.length) tsconfig = argv[++i]!;
-    else if (arg.startsWith("--tsconfig=")) tsconfig = arg.slice("--tsconfig=".length);
+    else if (arg.startsWith("--tsconfig="))
+      tsconfig = arg.slice("--tsconfig=".length);
   }
   return { cwd: path.resolve(cwd), tsconfig };
 }
 
-/** A `--connect` proxy pipes stdio to a running daemon and serves no graph of
- * its own, so it needs no diagnostics computed locally. */
-function isConnectProxy(argv: readonly string[]): boolean {
-  return argv.some((a) => a === "--connect" || a.startsWith("--connect="));
-}
-
 /**
- * Start the background worker that computes the project's plugin diagnostics
- * (`@ttsc/lint` and transform-plugin findings) and writes them to
- * `diagnosticsFile`, where the server picks them up. Returns the child handle
- * for cleanup, or `null` when it could not be spawned.
+ * Run the `@ttsc/graph` launcher.
  *
- * It runs in parallel with the server so the MCP handshake is never blocked on
- * a compile; the server shows its tsc diagnostics immediately and fuses the
- * plugin findings once the file lands. Any failure is non-fatal — the graph
- * simply stays tsc-only.
+ * - `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.
  */
-function startDiagnosticsWorker(
-  argv: readonly string[],
-  diagnosticsFile: string,
-): ReturnType<typeof spawn> | null {
-  try {
-    const { cwd, tsconfig } = parseProjectArgs(argv);
-    const worker = spawn(
-      process.execPath,
-      [require.resolve("./diagnostics.js"), cwd, tsconfig, diagnosticsFile],
-      { stdio: "ignore", windowsHide: true },
-    );
-    worker.on("error", () => {
-      /* resilient: a worker that cannot start leaves no file */
-    });
-    worker.unref();
-    return worker;
-  } catch {
-    return null;
-  }
+export function runGraph(
+  argv: readonly string[] = process.argv.slice(2),
+): number | void {
+  if (argv[0] === "view") return runView(argv.slice(1));
+  if (argv[0] === "dump") return runDump(argv);
+
+  const { cwd, tsconfig } = parseProjectArgs(argv);
+  void startServer({ cwd, tsconfig, version: VERSION }).catch(
+    (error: unknown) => {
+      process.stderr.write(
+        `@ttsc/graph: ${error instanceof Error ? error.message : String(error)}\n`,
+      );
+      process.exit(1);
+    },
+  );
 }
 
 /**
- * Spawn the resident MCP server, inheriting stdio so the agent's MCP client
- * speaks JSON-RPC to it directly over this process's stdin/stdout. Returns the
- * child's exit code.
- *
- * Before spawning, it kicks off the background diagnostics worker (except in
- * `--connect` proxy mode) and points the server at its output file, so a
- * plugin-using project's lint and transform-plugin diagnostics fuse onto the
- * graph without blocking startup.
+ * Pass `dump` through to the native binary, inheriting stdio so the JSON lands
+ * on this process's stdout. Returns the child's exit code.
  */
-export function runGraph(
-  argv: readonly string[] = process.argv.slice(2),
-): number {
+function runDump(argv: readonly string[]): number {
   const binary = resolveGraphBinary();
   if (binary === null) {
     process.stderr.write(
@@ -121,48 +73,10 @@ export function runGraph(
     );
     return 1;
   }
-
-  const env: NodeJS.ProcessEnv = { ...process.env };
-  let diagnosticsFile: string | null = null;
-  let worker: ReturnType<typeof spawn> | null = null;
-  if (!isConnectProxy(argv)) {
-    diagnosticsFile = path.join(
-      os.tmpdir(),
-      `ttsc-graph-diagnostics-${process.pid}.json`,
-    );
-    env.TTSC_GRAPH_DIAGNOSTICS_FILE = diagnosticsFile;
-    worker = startDiagnosticsWorker(argv, diagnosticsFile);
-  }
-
   const result = spawnSync(binary, [...argv], {
     stdio: "inherit",
-    env,
     windowsHide: true,
   });
-
-  const workerPid = worker?.pid;
-  try {
-    worker?.kill();
-  } catch {
-    /* ignore */
-  }
-  if (diagnosticsFile) {
-    try {
-      fs.rmSync(diagnosticsFile, { force: true });
-    } catch {
-      /* ignore */
-    }
-    // The worker writes atomically through `<file>.<pid>.tmp`; remove a leftover
-    // if it was killed mid-write, so a churning daemon does not litter tmpdir.
-    if (workerPid !== undefined) {
-      try {
-        fs.rmSync(`${diagnosticsFile}.${workerPid}.tmp`, { force: true });
-      } catch {
-        /* ignore */
-      }
-    }
-  }
-
   if (result.error) {
     process.stderr.write(`@ttsc/graph: ${result.error.message}\n`);
     return 1;

package/src/model/TtscGraphMemory.ts

@@ -0,0 +1,204 @@
+import { ITtscGraphDump } from "../structures/ITtscGraphDump";
+import { ITtscGraphEdge } from "../structures/ITtscGraphEdge";
+import { ITtscGraphNode } from "../structures/ITtscGraphNode";
+import { TtscGraphEdgeKind } from "../structures/TtscGraphEdgeKind";
+
+/**
+ * The in-memory resident graph the MCP tools answer from.
+ *
+ * It loads one `ttscgraph dump` — the checker-resolved fact graph — then
+ * synthesizes the structural relationships the dump deliberately leaves to this
+ * layer: `file` container nodes, the `contains` ownership tree, and `exports`
+ * edges, plus the refinement of a class-member `variable` to a `property`.
+ * Every tool call is then a lookup or a traversal over the indexes built here;
+ * nothing recompiles.
+ */
+export class TtscGraphMemory {
+  private readonly byId: Map<string, ITtscGraphNode>;
+  private readonly outEdges: Map<string, ITtscGraphEdge[]>;
+  private readonly inEdges: Map<string, ITtscGraphEdge[]>;
+  private readonly byNameIndex: Map<string, ITtscGraphNode[]>;
+  private readonly bySymbolIndex: Map<string, ITtscGraphNode[]>;
+
+  /** The absolute project root the dump was built for. */
+  readonly project: string;
+  /** Every node, raw plus synthesized (file containers). */
+  readonly nodes: readonly ITtscGraphNode[];
+  /** Every edge, raw plus synthesized (contains, exports). */
+  readonly edges: readonly ITtscGraphEdge[];
+
+  private constructor(
+    project: string,
+    nodes: ITtscGraphNode[],
+    edges: ITtscGraphEdge[],
+  ) {
+    this.project = project;
+    this.nodes = nodes;
+    this.edges = edges;
+
+    this.byId = new Map(nodes.map((n) => [n.id, n]));
+    this.byNameIndex = new Map();
+    this.bySymbolIndex = new Map();
+    for (const node of nodes) {
+      const bucket = this.byNameIndex.get(node.name);
+      if (bucket) bucket.push(node);
+      else this.byNameIndex.set(node.name, [node]);
+      if (node.kind !== "file") {
+        push(this.bySymbolIndex, node.name, node);
+        if (node.qualifiedName !== undefined) {
+          push(this.bySymbolIndex, node.qualifiedName, node);
+        }
+      }
+    }
+    this.outEdges = new Map();
+    this.inEdges = new Map();
+    for (const edge of edges) {
+      push(this.outEdges, edge.from, edge);
+      push(this.inEdges, edge.to, edge);
+    }
+  }
+
+  /** Build a model from a parsed dump, synthesizing structural relationships. */
+  static from(dump: ITtscGraphDump): TtscGraphMemory {
+    const { nodes, edges } = synthesize(dump);
+    return new TtscGraphMemory(dump.project, nodes, edges);
+  }
+
+  /** The node with this id, or undefined. */
+  node(id: string): ITtscGraphNode | undefined {
+    return this.byId.get(id);
+  }
+
+  /** Edges leaving a node (the node is the `from`). */
+  outgoing(id: string): readonly ITtscGraphEdge[] {
+    return this.outEdges.get(id) ?? [];
+  }
+
+  /** Edges entering a node (the node is the `to`). */
+  incoming(id: string): readonly ITtscGraphEdge[] {
+    return this.inEdges.get(id) ?? [];
+  }
+
+  /** Every node whose simple name equals `name`. */
+  named(name: string): readonly ITtscGraphNode[] {
+    return this.byNameIndex.get(name) ?? [];
+  }
+
+  /** Every non-file node whose simple or owner-qualified symbol handle matches. */
+  symbols(handle: string): readonly ITtscGraphNode[] {
+    return this.bySymbolIndex.get(handle) ?? [];
+  }
+
+  /** Every workspace node on its module's export surface. */
+  exported(): ITtscGraphNode[] {
+    return this.nodes.filter((n) => n.exported && !n.external);
+  }
+}
+
+/** Append value to the slice stored at key, creating the slice on first use. */
+function push<K, V>(map: Map<K, V[]>, key: K, value: V): void {
+  const bucket = map.get(key);
+  if (bucket) bucket.push(value);
+  else map.set(key, [value]);
+}
+
+/**
+ * The within-file identity of a node: its owner-qualified name when it has one
+ * (`Class.method`), else its simple name. Two nodes in one file never share a
+ * key, so it is the handle the ownership synthesis looks owners up by.
+ */
+function keyOf(node: ITtscGraphNode): string {
+  return node.qualifiedName ?? node.name;
+}
+
+/** The owner key of a dotted key (`A.B.c` -> `A.B`), or "" for a top-level key. */
+function ownerKey(key: string): string {
+  const dot = key.lastIndexOf(".");
+  return dot >= 0 ? key.slice(0, dot) : "";
+}
+
+/** A file's id and node name from its project-relative path. */
+function fileNodeId(file: string): string {
+  return file;
+}
+
+function basename(file: string): string {
+  const slash = file.lastIndexOf("/");
+  return slash >= 0 ? file.slice(slash + 1) : file;
+}
+
+/**
+ * Derive the structural layer from a dump's faithful facts: refine class-member
+ * variables to properties, add a `file` node per workspace source, and connect
+ * the `contains` ownership tree and `exports` surface.
+ */
+function synthesize(dump: ITtscGraphDump): {
+  nodes: ITtscGraphNode[];
+  edges: ITtscGraphEdge[];
+} {
+  // Clone nodes so property refinement does not mutate the caller's dump.
+  const nodes: ITtscGraphNode[] = dump.nodes.map((n) => ({ ...n }));
+  const edges: ITtscGraphEdge[] = dump.edges.slice();
+
+  // Index workspace nodes by (file, within-file key) so ownership can resolve a
+  // member to its declaring class/namespace.
+  const byFileKey = new Map<string, ITtscGraphNode>();
+  for (const node of nodes) {
+    if (!node.external) byFileKey.set(node.file + "\0" + keyOf(node), node);
+  }
+  const owner = (node: ITtscGraphNode): ITtscGraphNode | undefined => {
+    const parent = ownerKey(keyOf(node));
+    if (parent === "") return undefined;
+    return byFileKey.get(node.file + "\0" + parent);
+  };
+
+  // Refine: a `variable` whose owner is a class or interface is a property.
+  for (const node of nodes) {
+    if (node.kind !== "variable" || node.external) continue;
+    const parent = owner(node);
+    if (parent && (parent.kind === "class" || parent.kind === "interface")) {
+      node.kind = "property";
+    }
+  }
+
+  // One file container node per distinct workspace source file.
+  const fileNodes = new Map<string, ITtscGraphNode>();
+  for (const node of nodes) {
+    if (node.external || node.file === "") continue;
+    if (!fileNodes.has(node.file)) {
+      fileNodes.set(node.file, {
+        id: fileNodeId(node.file),
+        kind: "file",
+        name: basename(node.file),
+        file: node.file,
+        external: false,
+      });
+    }
+  }
+
+  // Ownership: a member is contained by its owner; a top-level declaration by
+  // its file. Exports: a file exports each of its public nodes.
+  const structural: ITtscGraphEdge[] = [];
+  for (const node of nodes) {
+    if (node.external || node.file === "") continue;
+    const parent = owner(node);
+    const container = parent ? parent.id : fileNodeId(node.file);
+    structural.push({
+      from: container,
+      to: node.id,
+      kind: "contains",
+    });
+    if (node.exported) {
+      structural.push({
+        from: fileNodeId(node.file),
+        to: node.id,
+        kind: "exports" satisfies TtscGraphEdgeKind,
+      });
+    }
+  }
+
+  return {
+    nodes: [...nodes, ...fileNodes.values()],
+    edges: [...edges, ...structural],
+  };
+}

package/src/model/loadGraph.ts

@@ -0,0 +1,85 @@
+import { spawnSync } from "node:child_process";
+import typia from "typia";
+
+import { resolveGraphBinary } from "../resolveGraphBinary";
+import { ITtscGraphDump } from "../structures/ITtscGraphDump";
+import { TtscGraphMemory } from "./TtscGraphMemory";
+
+// A full-project dump is the whole fact graph as one JSON document; a large
+// monorepo runs to many megabytes, well past spawnSync's 1 MiB default, so the
+// buffer is raised to a ceiling no real graph reaches.
+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.
+ *
+ * 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
+ * answering from an empty graph.
+ */
+export function loadGraph(
+  options: {
+    /** Project root the graph is built for (default: `process.cwd()`). */
+    cwd?: string;
+    /** Project tsconfig, relative to `cwd` (default: `tsconfig.json`). */
+    tsconfig?: string;
+    /**
+     * Absolute path to the `ttscgraph` binary. Defaults to the per-platform
+     * binary resolved from the project's installed `ttsc`; pass it explicitly
+     * to point at a custom build.
+     */
+    binary?: string;
+  } = {},
+): TtscGraphMemory {
+  const cwd = options.cwd ?? process.cwd();
+  const tsconfig = options.tsconfig ?? "tsconfig.json";
+  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.",
+    );
+  }
+
+  const result = spawnSync(
+    binary,
+    ["dump", "--cwd", cwd, "--tsconfig", tsconfig],
+    { encoding: "utf8", maxBuffer: MAX_DUMP_BYTES, windowsHide: true },
+  );
+  if (result.error) {
+    throw new Error(
+      `@ttsc/graph: ttscgraph dump failed: ${result.error.message}`,
+    );
+  }
+  if (result.status !== 0) {
+    throw new Error(
+      `@ttsc/graph: ttscgraph dump exited with ${result.status}: ${(result.stderr ?? "").trim()}`,
+    );
+  }
+
+  return TtscGraphMemory.from(parseDump(result.stdout));
+}
+
+/**
+ * Parse and validate `ttscgraph dump` output. typia asserts the full
+ * {@link ITtscGraphDump} shape so a malformed or stale dump fails loudly here
+ * rather than producing wrong answers downstream, and the schema version is
+ * checked so an incompatible producer is refused.
+ */
+function parseDump(json: string): ITtscGraphDump {
+  let value: unknown;
+  try {
+    value = JSON.parse(json);
+  } catch (error) {
+    throw new Error(
+      `@ttsc/graph: dump output is not valid JSON: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+  return typia.assert<ITtscGraphDump>(value);
+}