@ttsc/graph 0.16.4 → 0.16.5

package/src/reduce.ts

@@ -0,0 +1,165 @@
+// Reduce a raw `ttscgraph dump` to the payload the bundled 3D viewer renders.
+// This mirrors website/src/components/graph/graphReduce.ts (the same pure
+// transform); keep the two in sync. The CLI reduces in Node before serving, so
+// the browser viewer only ever renders a ready `{ nodes, links }`.
+
+export interface RawNode {
+  id: string;
+  name: string;
+  kind: string;
+  file: string;
+  external?: boolean;
+}
+
+export interface RawEdge {
+  from: string;
+  to: string;
+  kind: string;
+}
+
+export interface RawDump {
+  project?: string;
+  nodes: RawNode[];
+  edges: RawEdge[];
+}
+
+export interface ViewerNode {
+  id: string;
+  name: string;
+  kind: string;
+  file: string;
+  degree: number;
+}
+
+export interface ViewerLink {
+  source: string;
+  target: string;
+  kind: string;
+}
+
+export interface ViewerPayload {
+  project: string;
+  counts: {
+    rawNodes: number;
+    rawEdges: number;
+    nodes: number;
+    links: number;
+    droppedExternal: number;
+    droppedByCap: number;
+  };
+  nodes: ViewerNode[];
+  links: ViewerLink[];
+}
+
+function posix(p: string): string {
+  return p.replace(/\\/g, "/");
+}
+
+function commonRoot(files: string[]): string {
+  if (files.length === 0) return "";
+  let parts = posix(files[0]!).split("/");
+  for (const file of files.slice(1)) {
+    const other = posix(file).split("/");
+    let i = 0;
+    while (i < parts.length && i < other.length && parts[i] === other[i]) i++;
+    parts = parts.slice(0, i);
+    if (parts.length === 0) break;
+  }
+  return parts.join("/");
+}
+
+function relativize(abs: string, root: string): string {
+  const a = posix(abs);
+  const r = posix(root).replace(/\/+$/, "");
+  if (r && (a === r || a.startsWith(r + "/")))
+    return a.slice(r.length).replace(/^\/+/, "");
+  const nm = a.lastIndexOf("node_modules/");
+  if (nm >= 0) return a.slice(nm);
+  const slash = a.lastIndexOf("/");
+  return slash >= 0 ? a.slice(slash + 1) : a;
+}
+
+function rewriteId(id: string, root: string): string {
+  const hash = id.indexOf("#");
+  if (hash < 0) return id;
+  return relativize(id.slice(0, hash), root) + id.slice(hash);
+}
+
+function degreeOf(
+  nodes: { id: string }[],
+  edges: { from: string; to: string }[],
+): Map<string, number> {
+  const degree = new Map<string, number>(nodes.map((n) => [n.id, 0]));
+  for (const e of edges) {
+    if (degree.has(e.from)) degree.set(e.from, degree.get(e.from)! + 1);
+    if (degree.has(e.to)) degree.set(e.to, degree.get(e.to)! + 1);
+  }
+  return degree;
+}
+
+export function reduce(
+  raw: RawDump,
+  {
+    maxNodes = 1200,
+    keepExternal = false,
+  }: { maxNodes?: number; keepExternal?: boolean } = {},
+): ViewerPayload {
+  const keptByExternal = raw.nodes.filter((n) => keepExternal || !n.external);
+  const root = commonRoot(
+    raw.nodes.filter((n) => !n.external).map((n) => n.file),
+  );
+
+  const liveIds = new Set(keptByExternal.map((n) => n.id));
+  const liveEdges = raw.edges.filter(
+    (e) => liveIds.has(e.from) && liveIds.has(e.to),
+  );
+
+  const degree = degreeOf(keptByExternal, liveEdges);
+  let kept = keptByExternal;
+  let droppedByCap = 0;
+  if (kept.length > maxNodes) {
+    kept = [...kept]
+      .sort((a, b) => (degree.get(b.id) ?? 0) - (degree.get(a.id) ?? 0))
+      .slice(0, maxNodes);
+    droppedByCap = keptByExternal.length - kept.length;
+  }
+
+  const keptIds = new Set(kept.map((n) => n.id));
+  const edges = liveEdges.filter(
+    (e) => keptIds.has(e.from) && keptIds.has(e.to),
+  );
+  const finalDegree = degreeOf(kept, edges);
+
+  const nodes: ViewerNode[] = kept
+    .filter((n) => (finalDegree.get(n.id) ?? 0) > 0)
+    .map((n) => ({
+      id: rewriteId(n.id, root),
+      name: n.name,
+      kind: n.kind,
+      file: relativize(n.file, root),
+      degree: finalDegree.get(n.id) ?? 0,
+    }));
+
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  const links: ViewerLink[] = edges
+    .map((e) => ({
+      source: rewriteId(e.from, root),
+      target: rewriteId(e.to, root),
+      kind: e.kind,
+    }))
+    .filter((e) => nodeIds.has(e.source) && nodeIds.has(e.target));
+
+  return {
+    project: raw.project ?? "",
+    counts: {
+      rawNodes: raw.nodes.length,
+      rawEdges: raw.edges.length,
+      nodes: nodes.length,
+      links: links.length,
+      droppedExternal: raw.nodes.length - keptByExternal.length,
+      droppedByCap,
+    },
+    nodes,
+    links,
+  };
+}

package/src/resolveGraphBinary.ts

@@ -0,0 +1,40 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+
+/**
+ * Resolve the per-platform `ttscgraph` 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;
+  }
+}

package/src/server/createServer.ts

@@ -0,0 +1,104 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import typia from "typia";
+
+import { TtscGraphApplication, TtscGraphSource } from "../TtscGraphApplication";
+import { TtscGraphMemory } from "../model/TtscGraphMemory";
+import { ITtscGraphApplication } from "../structures/ITtscGraphApplication";
+import { instructions } from "./instructions";
+
+/**
+ * Build the MCP server for a graph. `typia.llm.controller` reflects
+ * {@link ITtscGraphApplication} into a validated tool application — every tool's
+ * JSON schema and argument validator is generated from the method's TypeScript
+ * types and JSDoc, so there is no hand-written schema. The list/call handlers
+ * below are the minimal standalone registration: list the generated functions,
+ * and on a call validate the arguments (returning typia's errors for the model
+ * to self-correct) before invoking the method.
+ *
+ * Registration is inlined rather than pulled from `@typia/mcp` to keep the
+ * dependency surface to `typia` plus the MCP SDK and avoid version-pinning the
+ * wider typia ecosystem; the shape it relies on is `typia.llm.controller`'s
+ * public output.
+ */
+export function createServer(
+  graph: TtscGraphSource,
+  version: string,
+): McpServer {
+  const controller = typia.llm.controller<ITtscGraphApplication>(
+    "graph",
+    new TtscGraphApplication(graph),
+  );
+  const functions = controller.application.functions;
+  const execute = controller.execute as unknown as Record<
+    string,
+    (input: unknown) => unknown
+  >;
+
+  const server = new McpServer(
+    { name: "ttsc-graph", version },
+    { capabilities: { tools: {} }, instructions },
+  );
+  const raw = server.server;
+
+  raw.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: functions.map((func) => ({
+      name: func.name,
+      description: func.description,
+      inputSchema: {
+        type: "object" as const,
+        properties: func.parameters.properties,
+        required: func.parameters.required,
+        additionalProperties: false,
+        $defs: func.parameters.$defs,
+      },
+    })),
+  }));
+
+  raw.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const func = functions.find((f) => f.name === request.params.name);
+    const method = execute[request.params.name];
+    if (func === undefined || method === undefined) {
+      return error(`Unknown tool: ${request.params.name}`);
+    }
+    // A client may omit `arguments` for an all-optional tool (e.g. graph_overview);
+    // validate an empty object so that call succeeds instead of failing on "expected object".
+    const validation = func.validate(request.params.arguments ?? {});
+    if (!validation.success) {
+      // Hand typia's validation errors back so the model can correct its call.
+      return error(JSON.stringify(validation.errors, null, 2));
+    }
+    try {
+      const result = await method.call(execute, validation.data);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text:
+              result === undefined
+                ? "Success"
+                : JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    } catch (exception) {
+      return error(
+        exception instanceof Error
+          ? `${exception.name}: ${exception.message}`
+          : String(exception),
+      );
+    }
+  });
+
+  return server;
+}
+
+function error(text: string): {
+  isError: true;
+  content: { type: "text"; text: string }[];
+} {
+  return { isError: true, content: [{ type: "text", text }] };
+}

package/src/server/instructions.ts

@@ -0,0 +1,28 @@
+/**
+ * The guidance delivered in the MCP initialize response. It is the only place
+ * the agent is told how to use the graph; nothing is written to its config
+ * files. Keep it short; the per-tool descriptions carry the detail.
+ */
+export const instructions = `
+This TypeScript project is indexed by the compiler. Use the graph as the first
+source of codebase coordinates: it has already resolved symbols and the
+relationships between them.
+
+- graph_index: first call for source questions. It returns ranked symbols,
+  declaration signatures, directly mentioned code handles, and nearby dependency
+  context without source bodies.
+- graph_overview: the architecture, layers, hotspots, and public API.
+- graph_query: find any symbol by name or description; each hit carries its
+  signature, usually enough to answer without expanding. Use next.expand when
+  you need bodies.
+- graph_trace: follow a flow forward, reverse, or to its impact; or give dotted
+  from/to names for the path between two symbols, how A reaches B, in one call.
+- graph_expand: a symbol's declared shape, its signature, and a container's
+  members; source:true to read a specific TypeScript body after graph_index,
+  graph_query, or graph_trace has located it.
+
+Answer in as few calls as you can. For TypeScript declarations, read source with
+graph_expand(source:true) on the resolved handles. Use shell or file reads only
+for a non-TypeScript file, generated output, or an exact literal text search that
+is not represented as symbols or edges.
+`.trim();

package/src/server/resolveHandle.ts

@@ -0,0 +1,34 @@
+import { TtscGraphMemory } from "../model/TtscGraphMemory";
+import { ITtscGraphNode } from "../structures/ITtscGraphNode";
+
+export interface IResolvedGraphHandle {
+  node?: ITtscGraphNode;
+  candidates?: ITtscGraphNode[];
+}
+
+/** Resolve a tool handle as an id, exact symbol name, or dotted suffix. */
+export function resolveGraphHandle(
+  graph: TtscGraphMemory,
+  handle: string,
+  candidateLimit = 12,
+): IResolvedGraphHandle {
+  const byId = graph.node(handle);
+  if (byId !== undefined) return { node: byId };
+
+  const exact = graph.symbols(handle);
+  if (exact.length === 1) return { node: exact[0] };
+  if (exact.length > 1) return { candidates: exact.slice(0, candidateLimit) };
+
+  if (handle.includes(".")) {
+    const suffix = `.${handle}`;
+    const suffixMatches = graph.nodes.filter(
+      (node) =>
+        node.kind !== "file" && node.qualifiedName?.endsWith(suffix) === true,
+    );
+    if (suffixMatches.length === 1) return { node: suffixMatches[0] };
+    if (suffixMatches.length > 1) {
+      return { candidates: suffixMatches.slice(0, candidateLimit) };
+    }
+  }
+  return {};
+}

package/src/server/runExpand.ts

@@ -0,0 +1,186 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { TtscGraphMemory } from "../model/TtscGraphMemory";
+import { ITtscGraphEdge } from "../structures/ITtscGraphEdge";
+import { ITtscGraphExpand } from "../structures/ITtscGraphExpand";
+import { ITtscGraphNode } from "../structures/ITtscGraphNode";
+import { resolveGraphHandle } from "./resolveHandle";
+
+// A whole declaration body can be large, so the full source is opt-in and capped
+// when asked for; the default response carries only the declared shape.
+const MAX_SOURCE_LINES = 200;
+// A signature is the declaration head up to the body brace — a handful of lines.
+const MAX_SIGNATURE_LINES = 6;
+// Neighbor lists are a map, not a dump; keep them scannable.
+const MAX_NEIGHBORS = 40;
+// A container's outline can be long (a big class); keep it bounded.
+const MAX_MEMBERS = 80;
+// Structural relationships are navigation, not the dependency picture expand is for.
+const STRUCTURAL_KINDS = new Set<string>(["contains", "exports", "imports"]);
+// Kinds whose value is their member outline, not a source body.
+const CONTAINER_KINDS = new Set<string>([
+  "class",
+  "interface",
+  "namespace",
+  "module",
+  "enum",
+  "file",
+]);
+
+/**
+ * Resolve each handle to its declared shape — its signature, and for a
+ * container the outline of its members — and, only when asked, its full source
+ * body. This is the graph's edge over a plain file read: it answers from the
+ * resolved structure it already holds, so the agent reads compact shape, not
+ * inlined code, unless it explicitly needs a body's logic.
+ */
+export function runExpand(
+  graph: TtscGraphMemory,
+  props: ITtscGraphExpand.IProps,
+): ITtscGraphExpand {
+  const wantSource = props.source === true;
+  const nodes: ITtscGraphExpand.INode[] = [];
+  const unknown: string[] = [];
+  for (const handle of props.handles) {
+    const resolved = resolveGraphHandle(graph, handle);
+    if (resolved.node === undefined) {
+      unknown.push(handle);
+      continue;
+    }
+    const node = resolved.node;
+    const expanded: ITtscGraphExpand.INode = {
+      id: node.id,
+      name: node.qualifiedName ?? node.name,
+      kind: node.kind,
+      file: node.file,
+    };
+    if (node.evidence?.startLine) expanded.line = node.evidence.startLine;
+    const sig = signatureOf(graph.project, node);
+    if (sig !== undefined) expanded.signature = sig;
+    if (CONTAINER_KINDS.has(node.kind)) {
+      const list = members(graph, node);
+      if (list.length > 0) expanded.members = list;
+    }
+    if (wantSource) {
+      const source = readSource(graph.project, node);
+      if (source !== undefined) {
+        expanded.source = source.text;
+        if (source.truncated) expanded.truncated = true;
+      }
+    }
+    if (props.neighbors === true) {
+      expanded.dependsOn = refs(graph, graph.outgoing(node.id), "to");
+      expanded.dependedOnBy = refs(graph, graph.incoming(node.id), "from");
+    }
+    nodes.push(expanded);
+  }
+  return { nodes, unknown };
+}
+
+/** The members a container owns (via `contains`), each with its own signature. */
+function members(
+  graph: TtscGraphMemory,
+  node: ITtscGraphNode,
+): ITtscGraphExpand.IMember[] {
+  const out: ITtscGraphExpand.IMember[] = [];
+  for (const edge of graph.outgoing(node.id)) {
+    if (edge.kind !== "contains") continue;
+    const member = graph.node(edge.to);
+    if (member === undefined) continue;
+    const m: ITtscGraphExpand.IMember = {
+      name: member.qualifiedName ?? member.name,
+      kind: member.kind,
+    };
+    if (member.evidence?.startLine) m.line = member.evidence.startLine;
+    const sig = signatureOf(graph.project, member);
+    if (sig !== undefined) m.signature = sig;
+    out.push(m);
+    if (out.length >= MAX_MEMBERS) break;
+  }
+  return out;
+}
+
+/** Map dependency edges to references on their far endpoint, dropping structure. */
+function refs(
+  graph: TtscGraphMemory,
+  edges: readonly ITtscGraphEdge[],
+  end: "to" | "from",
+): ITtscGraphExpand.IReference[] {
+  const out: ITtscGraphExpand.IReference[] = [];
+  for (const edge of edges) {
+    if (STRUCTURAL_KINDS.has(edge.kind)) continue;
+    const other = graph.node(end === "to" ? edge.to : edge.from);
+    if (other === undefined) continue;
+    out.push({
+      id: other.id,
+      name: other.qualifiedName ?? other.name,
+      kind: other.kind,
+      relation: edge.kind,
+    });
+    if (out.length >= MAX_NEIGHBORS) break;
+  }
+  return out;
+}
+
+/** Read a file's lines once, or undefined when it cannot be read. */
+function fileLines(
+  project: string,
+  node: ITtscGraphNode,
+): string[] | undefined {
+  if (node.evidence === undefined || node.file === "") return undefined;
+  try {
+    return fs
+      .readFileSync(path.join(project, node.file), "utf8")
+      .split(/\r?\n/);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The declaration signature: the head of the declaration up to and including
+ * the line that opens its body (`{`), or the single declaration line when there
+ * is no brace, capped so a wrapped signature cannot run away.
+ */
+export function signatureOf(
+  project: string,
+  node: ITtscGraphNode,
+): string | undefined {
+  const lines = fileLines(project, node);
+  const evidence = node.evidence;
+  if (lines === undefined || evidence === undefined) return undefined;
+  const start = Math.max(0, evidence.startLine - 1);
+  const out: string[] = [];
+  for (
+    let i = start;
+    i < lines.length && out.length < MAX_SIGNATURE_LINES;
+    i++
+  ) {
+    const line = lines[i];
+    if (line === undefined) break;
+    out.push(line);
+    if (line.includes("{")) break;
+  }
+  const text = out.join("\n").trim();
+  return text === "" ? undefined : text;
+}
+
+/** Slice a node's full declaration source from disk, capped at MAX_SOURCE_LINES. */
+function readSource(
+  project: string,
+  node: ITtscGraphNode,
+): { text: string; truncated: boolean } | undefined {
+  const lines = fileLines(project, node);
+  const evidence = node.evidence;
+  if (lines === undefined || evidence === undefined) return undefined;
+  const start = Math.max(0, evidence.startLine - 1);
+  const end = Math.min(evidence.endLine ?? evidence.startLine, lines.length);
+  let slice = lines.slice(start, Math.max(start + 1, end));
+  let truncated = false;
+  if (slice.length > MAX_SOURCE_LINES) {
+    slice = slice.slice(0, MAX_SOURCE_LINES);
+    truncated = true;
+  }
+  return { text: slice.join("\n"), truncated };
+}