@ttsc/graph 0.16.4 → 0.16.5

package/src/viewer/main.ts

@@ -0,0 +1,209 @@
+// Vanilla 3D code-graph viewer bundled into @ttsc/graph by esbuild and served by
+// `ttsc-graph view`. Mirrors website/src/components/graph/GraphViewer3D.tsx, but
+// standalone (no React): fetch the reduced graph the CLI serves, render it on
+// three.js + three-forcegraph, and let the user orbit it.
+import * as THREE from "three";
+import ThreeForceGraph from "three-forcegraph";
+import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
+
+interface GNode {
+  id: string;
+  name: string;
+  kind: string;
+  file: string;
+  degree: number;
+}
+
+interface GLink {
+  source: string;
+  target: string;
+  kind: string;
+}
+
+interface Payload {
+  project: string;
+  counts: { nodes: number; links: number };
+  nodes: GNode[];
+  links: GLink[];
+}
+
+const NODE_COLORS: Record<string, string> = {
+  class: "#36e2ee",
+  interface: "#6ea8ff",
+  function: "#3fb950",
+  method: "#2bb673",
+  type: "#f5b042",
+  enum: "#c792ea",
+  variable: "#8b97a8",
+};
+
+const LINK_COLORS: Record<string, string> = {
+  "value-call": "#3fb950",
+  "type-ref": "#f5b042",
+  heritage: "#6ea8ff",
+};
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function setText(id: string, text: string): void {
+  const el = document.getElementById(id);
+  if (el) el.textContent = text;
+}
+
+async function main(): Promise<void> {
+  const container = document.getElementById("graph");
+  if (!container) return;
+
+  let data: Payload;
+  try {
+    const res = await fetch("graph.json");
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    data = (await res.json()) as Payload;
+  } catch (err) {
+    container.textContent = `could not load the graph (${String(err)})`;
+    return;
+  }
+
+  if (data.project) setText("project", data.project);
+  setText(
+    "counts",
+    `${data.nodes.length.toLocaleString()} nodes · ${data.links.length.toLocaleString()} edges`,
+  );
+
+  const width = container.clientWidth || 800;
+  const height = container.clientHeight || 600;
+
+  const scene = new THREE.Scene();
+  scene.background = new THREE.Color(0x0a0c10);
+  scene.add(new THREE.AmbientLight(0xffffff, 2));
+  const keyLight = new THREE.DirectionalLight(0xffffff, 0.8);
+  keyLight.position.set(1, 1, 1);
+  scene.add(keyLight);
+
+  const camera = new THREE.PerspectiveCamera(50, width / height, 0.1, 1e6);
+  camera.position.set(0, 0, 320);
+
+  const renderer = new THREE.WebGLRenderer({ antialias: true });
+  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+  renderer.setSize(width, height);
+  container.appendChild(renderer.domElement);
+
+  const controls = new OrbitControls(camera, renderer.domElement);
+  controls.enableDamping = true;
+  controls.dampingFactor = 0.18;
+
+  const graph = new ThreeForceGraph<GNode, GLink>()
+    .nodeId("id")
+    .nodeRelSize(4)
+    .nodeResolution(12)
+    .nodeOpacity(0.95)
+    .nodeVal((node) => 1 + Math.sqrt(node.degree))
+    .nodeColor((node) => NODE_COLORS[node.kind] ?? "#8b97a8")
+    .linkColor((link) => LINK_COLORS[link.kind] ?? "#ffffff55")
+    .linkOpacity(0.4)
+    .linkWidth(0)
+    .warmupTicks(20)
+    .cooldownTicks(160);
+  scene.add(graph);
+
+  const fit = (): void => {
+    const b = graph.getGraphBbox();
+    if (!b) return;
+    const cx = (b.x[0] + b.x[1]) / 2;
+    const cy = (b.y[0] + b.y[1]) / 2;
+    const cz = (b.z[0] + b.z[1]) / 2;
+    const radius = Math.max(
+      (b.x[1] - b.x[0]) / 2,
+      (b.y[1] - b.y[0]) / 2,
+      (b.z[1] - b.z[0]) / 2,
+      10,
+    );
+    const dist = radius * 2.6;
+    camera.position.set(cx + dist * 0.5, cy + dist * 0.32, cz + dist * 0.8);
+    camera.near = Math.max(0.1, dist / 200);
+    camera.far = dist * 20;
+    camera.updateProjectionMatrix();
+    controls.target.set(cx, cy, cz);
+    controls.update();
+  };
+  // `?static` settles the layout, frames it, then stops the render loop, for a
+  // low-CPU snapshot (and headless screenshots). Default mode keeps animating.
+  const staticMode = new URLSearchParams(window.location.search).has("static");
+  let stopAtFrame = -1;
+  let frame = 0;
+  graph.onEngineStop(() => {
+    fit();
+    if (staticMode && stopAtFrame < 0) stopAtFrame = frame + 4;
+  });
+
+  // Hover tooltip via raycasting the node objects (each carries __data).
+  const tooltip = document.createElement("div");
+  tooltip.className = "tooltip";
+  container.appendChild(tooltip);
+  const raycaster = new THREE.Raycaster();
+  const pointer = new THREE.Vector2();
+  renderer.domElement.addEventListener("pointermove", (event) => {
+    const rect = renderer.domElement.getBoundingClientRect();
+    pointer.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
+    pointer.y = -((event.clientY - rect.top) / rect.height) * 2 + 1;
+    raycaster.setFromCamera(pointer, camera);
+    const hits = raycaster.intersectObjects(graph.children, true);
+    let node: GNode | null = null;
+    for (const hit of hits) {
+      let obj: THREE.Object3D | null = hit.object;
+      while (obj) {
+        const meta = obj as { __graphObjType?: string; __data?: unknown };
+        if (meta.__graphObjType === "node" && meta.__data) {
+          node = meta.__data as GNode;
+          break;
+        }
+        obj = obj.parent;
+      }
+      if (node) break;
+    }
+    if (!node) {
+      tooltip.style.display = "none";
+      return;
+    }
+    tooltip.style.display = "block";
+    tooltip.style.left = `${event.clientX - rect.left + 12}px`;
+    tooltip.style.top = `${event.clientY - rect.top + 12}px`;
+    tooltip.innerHTML =
+      `${escapeHtml(node.name)}<br/>` +
+      `<span class="muted">${escapeHtml(node.kind)} · ${escapeHtml(node.file)}</span>`;
+  });
+  renderer.domElement.addEventListener("pointerleave", () => {
+    tooltip.style.display = "none";
+  });
+
+  const animate = (): void => {
+    if (stopAtFrame >= 0 && frame > stopAtFrame) {
+      renderer.render(scene, camera);
+      return;
+    }
+    requestAnimationFrame(animate);
+    graph.tickFrame();
+    controls.update();
+    renderer.render(scene, camera);
+    frame++;
+  };
+  animate();
+
+  window.addEventListener("resize", () => {
+    const w = container.clientWidth || width;
+    const h = container.clientHeight || height;
+    camera.aspect = w / h;
+    camera.updateProjectionMatrix();
+    renderer.setSize(w, h);
+  });
+
+  graph.graphData({ nodes: data.nodes, links: data.links });
+  window.setTimeout(fit, 700);
+}
+
+void main();

package/lib/bin.d.ts

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

package/lib/diagnostics.d.ts

@@ -1,23 +0,0 @@
-/**
- * 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

@@ -1,84 +0,0 @@
-"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

@@ -1 +0,0 @@
-{"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

@@ -1,29 +0,0 @@
-/**
- * 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/src/diagnostics.ts

@@ -1,93 +0,0 @@
-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();
-}