@ttsc/graph 0.16.4 → 0.16.6

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/accessAliases.ts

@@ -0,0 +1,55 @@
+import { ITtscGraphNode } from "../structures/ITtscGraphNode";
+
+/**
+ * Derive stable access-path aliases for a member edge from its source
+ * expression. If a hop reaches `Owner.member` through `obj.path.member`, the
+ * alias `Owner.path.member` keeps both the resolved owner and the concrete
+ * access path visible without reopening source.
+ */
+export function accessAliasesFor(
+  node: ITtscGraphNode | undefined,
+  evidenceText: string | undefined,
+): string[] | undefined {
+  if (
+    node === undefined ||
+    node.qualifiedName === undefined ||
+    evidenceText === undefined
+  ) {
+    return undefined;
+  }
+  const segments = dottedSegments(evidenceText);
+  if (segments.length < 2 || segments[segments.length - 1] !== node.name) {
+    return undefined;
+  }
+  const dot = node.qualifiedName.lastIndexOf(".");
+  if (dot < 0) return undefined;
+
+  const owner = node.qualifiedName.slice(0, dot);
+  const suffix = segments.slice(1).join(".");
+  const aliases = new Set<string>();
+  for (const candidate of [...ownerDisplayAliases(owner), owner]) {
+    const alias = `${candidate}.${suffix}`;
+    if (alias !== node.qualifiedName) aliases.add(alias);
+  }
+  return aliases.size > 0 ? [...aliases] : undefined;
+}
+
+function dottedSegments(text: string): string[] {
+  const normalized = text.trim().replace(/\?\./g, ".");
+  const parts = normalized.split(".");
+  if (parts.length < 2) return [];
+  return parts.every((part) => /^[A-Za-z_$][\w$]*$/.test(part)) ? parts : [];
+}
+
+function ownerDisplayAliases(owner: string): string[] {
+  const display = owner.replace(/^_+/, "");
+  const out = new Set<string>();
+  for (const suffix of ["Internals", "Internal"]) {
+    if (display.length > suffix.length && display.endsWith(suffix)) {
+      out.add(display.slice(0, -suffix.length));
+    }
+  }
+  if (out.size === 0 && display !== owner) out.add(display);
+  out.delete(owner);
+  return [...out];
+}

package/src/server/createServer.ts

@@ -0,0 +1,101 @@
+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}`);
+    }
+    // Validate an empty object when a client omits `arguments`, so typia can
+    // return field-level errors instead of a generic "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),
+          },
+        ],
+      };
+    } 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,76 @@
+/**
+ * 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 = `
+Before answering a TypeScript codebase question, call query. It is the
+code-evidence path:
+symbols, dependency paths, edge evidence ranges, and sourceSpan line anchors
+from the resident project graph. Do not answer from assumptions, ls, rg, cat,
+or Get-Content when graph evidence can answer the code question.
+
+The graph is a resident TypeScript fact map, not an answer writer. Fill
+arguments in order: question, graphNeed, draft, review, request. Write
+draft.reason before draft.type, review it for overfetch and non-graph fallback,
+then choose one final request.type:
+entrypoints, lookup, trace, details, overview, or escape. If the review shows the
+question is about scripts, config, generated output, prose docs, or evidence
+already in hand, choose escape instead of spending a graph
+operation. If more TypeScript evidence is needed, make another graph request
+instead of switching to shell search.
+
+Budget graph calls before the first request. Most answers need 1-3 calls, and
+four calls is the hard stop for one answer. A fifth graph call means the tool is
+being used as a source reader; answer from returned handles/ranges or choose
+escape and report the missing span.
+
+For behavior, lifecycle, request-flow, rendering-flow, or validation-flow
+questions, start with one default entrypoints call, then one trace from the best
+handle, then answer. Use overview only for broad architecture or public API
+orientation.
+
+The graph already knows resolved symbols, dependency edges, evidence spans,
+decorators, stable handles, and sourceSpan line anchors. Use returned ranges and
+handles as the evidence. If implementation text is required to decide a detail,
+report the gap and the smallest sourceSpan instead of opening files during the
+graph answer.
+
+For caller or call-site questions, do not use rg. Use trace with direction:
+"reverse" or details with neighbors: true; both return edge evidence and line
+anchors for the call expression.
+
+Request types:
+
+- entrypoints: compact shortlist for behavior-specific code questions. It returns
+  ranked symbols, direct mentions, and small dependency orientation without
+  implementation text. Do not use it as the first broad public API map.
+- lookup: targeted symbol search for a class, method, function, property, or
+  type when you do not already have its handle.
+- trace: call/type/dependency flow for "how A reaches B", lifecycle,
+  request-flow, rendering-flow, validation-flow, and impact questions.
+- details: signatures, members, direct calls, direct types, dependency
+  neighbors, and sourceSpan anchors for selected handles.
+- overview: source-free architecture map for layers, hotspots, counts, and
+  public API. Use it to choose a central exported TypeScript API or entry point
+  without reading package scripts.
+- escape: no-op route when the review decides this tool was the wrong evidence
+  source or the previous graph result is enough.
+
+For a flow question, use entrypoints once, then trace before details. Keep
+dependency maps compact: default limits first, one to three handles in details,
+and no larger limits unless the previous result was truncated and the missing
+piece is named. Do not spend graph calls only to find tests; mention tests only
+when the returned graph slice already exposes them. Stop once file/symbol/range
+evidence is enough to answer.
+
+Copy exact names from returned nodes, references, aliases, evidence ranges,
+sourceSpan anchors, and trace steps. Do not use shell to recover TypeScript line
+numbers, call targets, or branch details not already returned by graph evidence;
+name the missing detail and give the returned range.
+
+Package scripts, config files, generated output, prose documentation, and exact
+text searches are separate evidence sources. Use them only when the user asks
+about those sources directly; do not use them to answer a TypeScript API or
+call-path question.
+`.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 {};
+}