@ttsc/graph 0.16.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeongho Nam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# `@ttsc/graph`
+
+![banner of @ttsc/graph](https://ttsc.dev/og.jpg)
+
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/samchon/ttsc/blob/master/LICENSE) [![NPM Version](https://img.shields.io/npm/v/@ttsc/graph.svg)](https://www.npmjs.com/package/@ttsc/graph) [![NPM Downloads](https://img.shields.io/npm/dm/@ttsc/graph.svg)](https://www.npmjs.com/package/@ttsc/graph) [![Build Status](https://github.com/samchon/ttsc/workflows/test/badge.svg)](https://github.com/samchon/ttsc/actions?query=workflow%3Atest) [![Guide Documents](https://img.shields.io/badge/Guide-Documents-forestgreen)](https://ttsc.dev/docs/graph) [![Discord Badge](https://img.shields.io/badge/discord-samchon-d91965?style=flat&labelColor=5866f2&logo=discord&logoColor=white&link=https://discord.gg/E94XhzrUCZ)](https://discord.gg/E94XhzrUCZ)
+
+Gives your AI coding assistant a **map of your codebase**. It can answer "how does this work?" without opening file after file.
+
+When you ask an AI agent (Claude Code, Codex, and the like) about your project, it pokes around. It opens a file, follows an import, opens another, and on and on.
+
+`@ttsc/graph` hands it the map up front: what calls what, what depends on what, and where each thing lives.
+
+The map comes from the real TypeScript compiler. So it is exact — not a guess from skimming text.
+
+## What your agent gets
+
+Say you ask: _"how does the editor draw a shape?"_
+
+Your agent looks it up once instead of reading a dozen files, and gets back something like this:
+
+```
+ShapeRenderer — src/render/shape.ts (line 18)
+  → calls    rasterize(), new Canvas()
+  ← used by  Editor
+  change it and 9 other things are affected
+  18  export class ShapeRenderer {
+  19    constructor(private canvas: Canvas) {}
+  ...
+```
+
+One step shows what this thing calls, what uses it, and its source.
+
+The answer comes from the compiler, so it is precise. When one file just re-exports something from another, the map still points at the file that really defines it.
+
+Anything from `node_modules` is left out, because that is not your code.
+
+On a public benchmark, a Claude agent answered reading zero files, cutting its token use by **77% to 86%** and its tool calls by **94% to 95%**.
+
+See the [benchmark](https://ttsc.dev/docs/benchmark#code-graph-mcp) for the full numbers.
+
+## Install
+
+```bash
+npm install -D ttsc @ttsc/graph typescript@rc
+```
+
+Install `ttsc` alongside it. `@ttsc/graph` runs through `ttsc`, so the two go together — the same pair as `@ttsc/lint`.
+
+There is nothing else to set up: no separate compiler, no Go.
+
+## Connect it to your agent
+
+Add this to your AI tool's config once. For Claude Code, that is a `.mcp.json` file in your project:
+
+```json
+{
+  "mcpServers": {
+    "ttsc-graph": {
+      "command": "npx",
+      "args": ["-y", "@ttsc/graph"]
+    }
+  }
+}
+```
+
+Start your agent from your project folder so it finds your `tsconfig.json`.
+
+Your agent now has two new abilities:
+
+| Ability | What it does |
+| --- | --- |
+| `graph_explore` | Look up a name or a file. Get back what it connects to — what it calls, what uses it, its types — and its source code. |
+| `graph_diagnostics` | Get the errors in one file: TypeScript type errors, plus your project's `@ttsc/lint` and plugin findings, as `ttsc` reports them. |
+
+You never call these yourself. Your agent uses them when it needs to.
+
+Claude Code does this on its own. Codex is more cautious with third-party MCP tools and often explores with the shell instead, so tell it directly — add a line to your `AGENTS.md` asking it to call `graph_explore` first. See the [setup guide](https://ttsc.dev/docs/setup#codex-and-other-tool-conservative-agents).
+
+## How it works
+
+`ttsc` already type-checks your project with the real TypeScript compiler and keeps the result in memory.
+
+`@ttsc/graph` reads the map straight out of that. Every connection it shows is the compiler's own answer, not a guess.
+
+That is why it is exact, and why it is fast: nothing is recompiled to answer a question.
+
+## References
+
+`@ttsc/graph` is inspired by [codegraph](https://github.com/colbymchenry/codegraph), which gives agents a code graph over MCP. The [benchmark](https://ttsc.dev/docs/benchmark#code-graph-mcp) here is a faithful port of codegraph's.
+
+The difference is how the map is built.
+
+codegraph reads your code with tree-sitter, across many languages, and saves the result in a database it keeps in sync as files change. Its edges are a best guess from the syntax.
+
+`@ttsc/graph` is TypeScript-only and keeps no database. It reads the graph live from the program `ttsc` already type-checked in memory.
+
+So every edge is the compiler's own answer: a re-export is followed to the file that really defines the symbol, an external library is left out, and nothing is guessed.

package/lib/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/lib/bin.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+const code = (0, index_1.runGraph)(process.argv.slice(2));
+if (typeof code === "number") {
+    process.exitCode = code;
+}
+//# sourceMappingURL=bin.js.map

package/lib/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";;;AAEA,mCAAmC;AAEnC,MAAM,IAAI,GAAG,IAAA,gBAAQ,EAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7C,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;IAC7B,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC"}

package/lib/diagnostics.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Background worker that computes the project's plugin diagnostics and writes
+ * them where the ttscgraph server reads them.
+ *
+ * The graph binary runs only the TypeScript semantic pass. Everything a plugin
+ * adds — `@ttsc/lint` rule violations and transform-plugin (typia, nestia, …)
+ * findings — comes from `ttsc`'s own check, which runs whatever plugins the
+ * project configured. This worker invokes that check through the public
+ * `TtscCompiler`, so nothing here is specific to any plugin: it forwards
+ * whatever diagnostics ttsc produces.
+ *
+ * A native plugin reports its findings with a string `code` (tsc uses numeric
+ * codes), so the string-coded diagnostics are exactly the plugin/lint set the
+ * graph does not already have. They are serialized with code 0 and the rule
+ * folded into the message, the shape ttscgraph's injected-diagnostics provider
+ * consumes.
+ *
+ * Every failure is swallowed: a missing `ttsc`, a go toolchain that cannot
+ * build a plugin, a project that does not compile — any of these simply leaves
+ * no file, and the graph shows its tsc diagnostics alone. The worker must never
+ * be able to break the server it feeds.
+ */
+export declare function runDiagnosticsWorker(argv?: readonly string[]): void;

package/lib/diagnostics.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDiagnosticsWorker = runDiagnosticsWorker;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_module_1 = require("node:module");
+/**
+ * Background worker that computes the project's plugin diagnostics and writes
+ * them where the ttscgraph server reads them.
+ *
+ * The graph binary runs only the TypeScript semantic pass. Everything a plugin
+ * adds — `@ttsc/lint` rule violations and transform-plugin (typia, nestia, …)
+ * findings — comes from `ttsc`'s own check, which runs whatever plugins the
+ * project configured. This worker invokes that check through the public
+ * `TtscCompiler`, so nothing here is specific to any plugin: it forwards
+ * whatever diagnostics ttsc produces.
+ *
+ * A native plugin reports its findings with a string `code` (tsc uses numeric
+ * codes), so the string-coded diagnostics are exactly the plugin/lint set the
+ * graph does not already have. They are serialized with code 0 and the rule
+ * folded into the message, the shape ttscgraph's injected-diagnostics provider
+ * consumes.
+ *
+ * Every failure is swallowed: a missing `ttsc`, a go toolchain that cannot
+ * build a plugin, a project that does not compile — any of these simply leaves
+ * no file, and the graph shows its tsc diagnostics alone. The worker must never
+ * be able to break the server it feeds.
+ */
+function runDiagnosticsWorker(argv = process.argv.slice(2)) {
+    const [cwd, tsconfig, outPath] = argv;
+    if (!cwd || !outPath) {
+        return;
+    }
+    try {
+        const ttscPackageJson = require.resolve("ttsc/package.json", {
+            paths: [cwd],
+        });
+        const fromProject = (0, node_module_1.createRequire)(ttscPackageJson);
+        const { TtscCompiler } = fromProject("ttsc");
+        const result = new TtscCompiler({
+            cwd,
+            tsconfig: tsconfig || undefined,
+        }).compile();
+        const raw = result &&
+            typeof result === "object" &&
+            Array.isArray(result.diagnostics)
+            ? (result.diagnostics)
+            : [];
+        const out = raw
+            .filter((d) => typeof d.file === "string" &&
+            (typeof d.line === "number" || typeof d.start === "number"))
+            .map((d) => ({
+            file: d.file,
+            // A byte offset when the structured lane gives one; otherwise null and
+            // the server attributes by line. @ttsc/lint and transform plugins reach
+            // the result through ttsc's text banner, which carries a line but no
+            // offset.
+            start: typeof d.start === "number" ? d.start : null,
+            line: typeof d.line === "number" ? d.line : 1,
+            column: typeof d.character === "number" ? d.character : 1,
+            // tsc diagnostics use numeric codes; @ttsc/lint and native plugins hash
+            // their rule to a code >= 9000. A rare string id is marked non-tsc (the
+            // server then drops the "TS" prefix); the rule name travels in the
+            // message regardless.
+            code: typeof d.code === "number" ? d.code : 9000,
+            message: String(d.messageText ?? ""),
+        }));
+        // Atomic publish: write to a sibling temp file and rename, so the server
+        // never reads a half-written file (a partial read would drop every finding
+        // for that query).
+        const tmp = `${outPath}.${process.pid}.tmp`;
+        node_fs_1.default.writeFileSync(tmp, JSON.stringify(out));
+        node_fs_1.default.renameSync(tmp, outPath);
+    }
+    catch {
+        // Resilient by contract: no file means the graph shows tsc-only diagnostics.
+    }
+}
+if (require.main === module) {
+    runDiagnosticsWorker();
+}
+//# sourceMappingURL=diagnostics.js.map

package/lib/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":";;;;;;AAAA,sDAAyB;AACzB,6CAA4C;AAE5C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,8BACE,IAAI,GAAsB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAE/C,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,OAAO;IACT,CAAC;IACD,IAAI,CAAC;QACH,MAAM,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,mBAAmB,EAAE;YAC3D,KAAK,EAAE,CAAC,GAAG,CAAC;SACb,CAAC,CAAC;QACH,MAAM,WAAW,GAAG,IAAA,2BAAa,EAAC,eAAe,CAAC,CAAC;QACnD,MAAM,EAAE,YAAY,EAAE,GAAG,WAAW,CAAC,MAAM,CAK1C,CAAC;QAEF,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC;YAC9B,GAAG;YACH,QAAQ,EAAE,QAAQ,IAAI,SAAS;SAChC,CAAC,CAAC,OAAO,EAAE,CAAC;QAEb,MAAM,GAAG,GACP,MAAM;YACN,OAAO,MAAM,KAAK,QAAQ;YAC1B,KAAK,CAAC,OAAO,CAAE,MAAoC,CAAC,WAAW,CAAC;YAC9D,CAAC,CAAC,CAAE,MAAqD,CAAC,WAAW,CAAC;YACtE,CAAC,CAAC,EAAE,CAAC;QAET,MAAM,GAAG,GAAG,GAAG;aACZ,MAAM,CACL,CAAC,CAAC,EAAE,EAAE,CACJ,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;YAC1B,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC,CAC9D;aACA,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACX,IAAI,EAAE,CAAC,CAAC,IAAc;YACtB,uEAAuE;YACvE,wEAAwE;YACxE,qEAAqE;YACrE,UAAU;YACV,KAAK,EAAE,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAE,CAAC,CAAC,KAAgB,CAAC,CAAC,CAAC,IAAI;YAC/D,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAE,CAAC,CAAC,IAAe,CAAC,CAAC,CAAC,CAAC;YACzD,MAAM,EAAE,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAE,CAAC,CAAC,SAAoB,CAAC,CAAC,CAAC,CAAC;YACrE,wEAAwE;YACxE,wEAAwE;YACxE,mEAAmE;YACnE,sBAAsB;YACtB,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAE,CAAC,CAAC,IAAe,CAAC,CAAC,CAAC,IAAI;YAC5D,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC;SACrC,CAAC,CAAC,CAAC;QAEN,yEAAyE;QACzE,2EAA2E;QAC3E,mBAAmB;QACnB,MAAM,GAAG,GAAG,GAAG,OAAO,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;QAC5C,iBAAE,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;QAC3C,iBAAE,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,6EAA6E;IAC/E,CAAC;AACH,CAAC;AAED,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;IAC5B,oBAAoB,EAAE,CAAC;AACzB,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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).
+ */
+export declare function resolveGraphBinary(env?: NodeJS.ProcessEnv, cwd?: string): string | null;
+/**
+ * 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.
+ */
+export declare function runGraph(argv?: readonly string[]): number;

package/lib/index.js

@@ -0,0 +1,157 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveGraphBinary = resolveGraphBinary;
+exports.runGraph = runGraph;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_module_1 = require("node:module");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * 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).
+ */
+function resolveGraphBinary(env = process.env, cwd = process.cwd()) {
+    if (env.TTSC_GRAPH_BINARY && node_path_1.default.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 = (0, node_module_1.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) {
+    let cwd = process.cwd();
+    let tsconfig = "tsconfig.json";
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        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);
+    }
+    return { cwd: node_path_1.default.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) {
+    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.
+ *
+ * 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.
+ */
+function startDiagnosticsWorker(argv, diagnosticsFile) {
+    try {
+        const { cwd, tsconfig } = parseProjectArgs(argv);
+        const worker = (0, node_child_process_1.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;
+    }
+}
+/**
+ * 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.
+ */
+function runGraph(argv = process.argv.slice(2)) {
+    const binary = resolveGraphBinary();
+    if (binary === null) {
+        process.stderr.write("@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.\n");
+        return 1;
+    }
+    const env = { ...process.env };
+    let diagnosticsFile = null;
+    let worker = null;
+    if (!isConnectProxy(argv)) {
+        diagnosticsFile = node_path_1.default.join(node_os_1.default.tmpdir(), `ttsc-graph-diagnostics-${process.pid}.json`);
+        env.TTSC_GRAPH_DIAGNOSTICS_FILE = diagnosticsFile;
+        worker = startDiagnosticsWorker(argv, diagnosticsFile);
+    }
+    const result = (0, node_child_process_1.spawnSync)(binary, [...argv], {
+        stdio: "inherit",
+        env,
+        windowsHide: true,
+    });
+    const workerPid = worker?.pid;
+    try {
+        worker?.kill();
+    }
+    catch {
+        /* ignore */
+    }
+    if (diagnosticsFile) {
+        try {
+            node_fs_1.default.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 {
+                node_fs_1.default.rmSync(`${diagnosticsFile}.${workerPid}.tmp`, { force: true });
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    if (result.error) {
+        process.stderr.write(`@ttsc/graph: ${result.error.message}\n`);
+        return 1;
+    }
+    return result.status ?? 1;
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

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

package/package.json

@@ -0,0 +1,48 @@
+{
+  "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.",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "bin": {
+    "ttsc-graph": "lib/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "ttsc",
+    "mcp",
+    "code-graph",
+    "typescript",
+    "tsgo"
+  ],
+  "files": [
+    "README.md",
+    "lib",
+    "src"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "rimraf": "^6.1.2",
+    "typescript": "7.0.1-rc",
+    "ttsc": "0.16.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/samchon/ttsc"
+  },
+  "author": "Jeongho Nam",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/samchon/ttsc/issues"
+  },
+  "homepage": "https://ttsc.dev",
+  "scripts": {
+    "build": "rimraf lib && tsc"
+  }
+}

package/src/bin.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runGraph } from "./index";
+
+const code = runGraph(process.argv.slice(2));
+if (typeof code === "number") {
+  process.exitCode = code;
+}

package/src/diagnostics.ts

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+
+/**
+ * Background worker that computes the project's plugin diagnostics and writes
+ * them where the ttscgraph server reads them.
+ *
+ * The graph binary runs only the TypeScript semantic pass. Everything a plugin
+ * adds — `@ttsc/lint` rule violations and transform-plugin (typia, nestia, …)
+ * findings — comes from `ttsc`'s own check, which runs whatever plugins the
+ * project configured. This worker invokes that check through the public
+ * `TtscCompiler`, so nothing here is specific to any plugin: it forwards
+ * whatever diagnostics ttsc produces.
+ *
+ * A native plugin reports its findings with a string `code` (tsc uses numeric
+ * codes), so the string-coded diagnostics are exactly the plugin/lint set the
+ * graph does not already have. They are serialized with code 0 and the rule
+ * folded into the message, the shape ttscgraph's injected-diagnostics provider
+ * consumes.
+ *
+ * Every failure is swallowed: a missing `ttsc`, a go toolchain that cannot
+ * build a plugin, a project that does not compile — any of these simply leaves
+ * no file, and the graph shows its tsc diagnostics alone. The worker must never
+ * be able to break the server it feeds.
+ */
+export function runDiagnosticsWorker(
+  argv: readonly string[] = process.argv.slice(2),
+): void {
+  const [cwd, tsconfig, outPath] = argv;
+  if (!cwd || !outPath) {
+    return;
+  }
+  try {
+    const ttscPackageJson = require.resolve("ttsc/package.json", {
+      paths: [cwd],
+    });
+    const fromProject = createRequire(ttscPackageJson);
+    const { TtscCompiler } = fromProject("ttsc") as {
+      TtscCompiler: new (context: {
+        cwd: string;
+        tsconfig?: string;
+      }) => { compile: () => unknown };
+    };
+
+    const result = new TtscCompiler({
+      cwd,
+      tsconfig: tsconfig || undefined,
+    }).compile();
+
+    const raw: ReadonlyArray<Record<string, unknown>> =
+      result &&
+      typeof result === "object" &&
+      Array.isArray((result as { diagnostics?: unknown }).diagnostics)
+        ? ((result as { diagnostics: Record<string, unknown>[] }).diagnostics)
+        : [];
+
+    const out = raw
+      .filter(
+        (d) =>
+          typeof d.file === "string" &&
+          (typeof d.line === "number" || typeof d.start === "number"),
+      )
+      .map((d) => ({
+        file: d.file as string,
+        // A byte offset when the structured lane gives one; otherwise null and
+        // the server attributes by line. @ttsc/lint and transform plugins reach
+        // the result through ttsc's text banner, which carries a line but no
+        // offset.
+        start: typeof d.start === "number" ? (d.start as number) : null,
+        line: typeof d.line === "number" ? (d.line as number) : 1,
+        column: typeof d.character === "number" ? (d.character as number) : 1,
+        // tsc diagnostics use numeric codes; @ttsc/lint and native plugins hash
+        // their rule to a code >= 9000. A rare string id is marked non-tsc (the
+        // server then drops the "TS" prefix); the rule name travels in the
+        // message regardless.
+        code: typeof d.code === "number" ? (d.code as number) : 9000,
+        message: String(d.messageText ?? ""),
+      }));
+
+    // Atomic publish: write to a sibling temp file and rename, so the server
+    // never reads a half-written file (a partial read would drop every finding
+    // for that query).
+    const tmp = `${outPath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(out));
+    fs.renameSync(tmp, outPath);
+  } catch {
+    // Resilient by contract: no file means the graph shows tsc-only diagnostics.
+  }
+}
+
+if (require.main === module) {
+  runDiagnosticsWorker();
+}

package/src/index.ts

@@ -0,0 +1,171 @@
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * 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).
+ */
+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;
+} {
+  let cwd = process.cwd();
+  let tsconfig = "tsconfig.json";
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    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);
+  }
+  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.
+ *
+ * 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.
+ */
+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;
+  }
+}
+
+/**
+ * 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.
+ */
+export function runGraph(
+  argv: readonly string[] = process.argv.slice(2),
+): number {
+  const binary = resolveGraphBinary();
+  if (binary === null) {
+    process.stderr.write(
+      "@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.\n",
+    );
+    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;
+  }
+  return result.status ?? 1;
+}