@ttsc/graph 0.16.4 → 0.16.5

package/src/server/runTrace.ts

@@ -0,0 +1,233 @@
+import { TtscGraphMemory } from "../model/TtscGraphMemory";
+import { ITtscGraphNode } from "../structures/ITtscGraphNode";
+import { ITtscGraphTrace } from "../structures/ITtscGraphTrace";
+import { resolveGraphHandle } from "./resolveHandle";
+import { signatureOf } from "./runExpand";
+
+const DEFAULT_DEPTH = 6;
+const DEFAULT_MAX_NODES = 60;
+
+/**
+ * Breadth-first trace along the dependency graph. Structural
+ * (contains/exports/imports) edges are excluded so the path is real call/type
+ * flow; forward walks callees, reverse and impact walk callers. Impact
+ * additionally tags each reached node's role so the blast radius on the public
+ * surface is legible.
+ */
+export function runTrace(
+  graph: TtscGraphMemory,
+  props: ITtscGraphTrace.IProps,
+): ITtscGraphTrace {
+  const direction = props.direction ?? "forward";
+  const maxDepth = Math.max(1, props.maxDepth ?? DEFAULT_DEPTH);
+  const maxNodes = Math.max(1, props.maxNodes ?? DEFAULT_MAX_NODES);
+  const reverse = direction === "reverse" || direction === "impact";
+  // Only an impact trace tags reached nodes with their public-surface role; for
+  // forward/reverse the role is noise.
+  const withRoles = direction === "impact";
+
+  const start = resolveGraphHandle(graph, props.from);
+  if (start.candidates) {
+    return {
+      direction,
+      hops: [],
+      reached: [],
+      truncated: false,
+      candidates: start.candidates.map((n) => summary(n)),
+    };
+  }
+  if (start.node === undefined) {
+    return { direction, hops: [], reached: [], truncated: false };
+  }
+
+  // Path mode: with `to`, return the dependency path from `from` to `to` — the
+  // one-call answer for "how does A reach B" — instead of an open-ended trace.
+  if (props.to !== undefined && props.to !== "") {
+    const base = { direction: "path", hops: [], reached: [], truncated: false };
+    const target = resolveGraphHandle(graph, props.to);
+    if (target.candidates) {
+      return {
+        ...base,
+        start: summary(start.node),
+        candidates: target.candidates.map((n) => summary(n)),
+      };
+    }
+    if (target.node === undefined) {
+      return { ...base, start: summary(start.node) };
+    }
+    const found = findPath(
+      graph,
+      start.node.id,
+      target.node.id,
+      Math.max(1, props.maxDepth ?? 12),
+    );
+    return {
+      ...base,
+      start: summary(start.node),
+      target: summary(target.node),
+      hops: found?.hops ?? [],
+      path: (found?.path ?? []).map((node, i) => {
+        const node_ = summary(node, i);
+        const sig = signatureOf(graph.project, node);
+        if (sig !== undefined) node_.signature = sig;
+        return node_;
+      }),
+    };
+  }
+
+  const hops: ITtscGraphTrace.IHop[] = [];
+  const reached = new Map<string, ITtscGraphTrace.INode>();
+  const visited = new Set<string>([start.node.id]);
+  let queue: Array<{ id: string; depth: number }> = [
+    { id: start.node.id, depth: 0 },
+  ];
+  let truncated = false;
+
+  while (queue.length > 0) {
+    const next: Array<{ id: string; depth: number }> = [];
+    for (const { id, depth } of queue) {
+      if (depth >= maxDepth) {
+        truncated = true;
+        continue;
+      }
+      const edges = reverse ? graph.incoming(id) : graph.outgoing(id);
+      for (const edge of edges) {
+        if (!traversable(edge.kind)) continue;
+        const otherId = reverse ? edge.from : edge.to;
+        const other = graph.node(otherId);
+        if (other === undefined || other.kind === "file") continue;
+        const hop = {
+          from: edge.from,
+          to: edge.to,
+          kind: edge.kind,
+          depth: depth + 1,
+        };
+        // A back-edge to the start or an already-reached node: record the hop;
+        // its endpoints are already represented.
+        if (visited.has(otherId)) {
+          hops.push(hop);
+          continue;
+        }
+        // A new node past the cap is left unrepresented, so drop its hop too —
+        // every hop's endpoints stay resolvable in `reached`/`start`.
+        if (reached.size >= maxNodes) {
+          truncated = true;
+          continue;
+        }
+        visited.add(otherId);
+        reached.set(otherId, summary(other, depth + 1, withRoles));
+        next.push({ id: otherId, depth: depth + 1 });
+        hops.push(hop);
+      }
+    }
+    queue = next;
+  }
+
+  return {
+    start: summary(start.node),
+    direction,
+    hops,
+    reached: [...reached.values()],
+    truncated,
+  };
+}
+
+/**
+ * The shortest dependency path from `startId` to `targetId` over real (non-
+ * structural) forward edges, breadth-first, or null when `targetId` is not
+ * reachable within maxDepth. Returns the nodes in order and the hops between.
+ */
+function findPath(
+  graph: TtscGraphMemory,
+  startId: string,
+  targetId: string,
+  maxDepth: number,
+): { path: ITtscGraphNode[]; hops: ITtscGraphTrace.IHop[] } | null {
+  const startNode = graph.node(startId);
+  if (startNode === undefined) return null;
+  if (startId === targetId) return { path: [startNode], hops: [] };
+  const parent = new Map<string, { via: string; kind: string }>();
+  const visited = new Set<string>([startId]);
+  let queue: Array<{ id: string; depth: number }> = [{ id: startId, depth: 0 }];
+  while (queue.length > 0) {
+    const next: Array<{ id: string; depth: number }> = [];
+    for (const { id, depth } of queue) {
+      if (depth >= maxDepth) continue;
+      for (const edge of graph.outgoing(id)) {
+        if (!traversable(edge.kind)) continue;
+        const otherId = edge.to;
+        if (visited.has(otherId)) continue;
+        const other = graph.node(otherId);
+        if (other === undefined || other.kind === "file") continue;
+        visited.add(otherId);
+        parent.set(otherId, { via: id, kind: edge.kind });
+        if (otherId === targetId) {
+          const ids: string[] = [otherId];
+          let cur = otherId;
+          while (cur !== startId) {
+            const p = parent.get(cur);
+            if (p === undefined) break;
+            ids.unshift(p.via);
+            cur = p.via;
+          }
+          const path: ITtscGraphNode[] = [];
+          for (const nid of ids) {
+            const n = graph.node(nid);
+            if (n !== undefined) path.push(n);
+          }
+          const hops: ITtscGraphTrace.IHop[] = [];
+          for (let i = 1; i < path.length; i++) {
+            const node = path[i]!;
+            hops.push({
+              from: path[i - 1]!.id,
+              to: node.id,
+              kind: parent.get(node.id)?.kind ?? "calls",
+              depth: i,
+            });
+          }
+          return { path, hops };
+        }
+        next.push({ id: otherId, depth: depth + 1 });
+      }
+    }
+    queue = next;
+  }
+  return null;
+}
+
+/**
+ * Summarize a node for a trace result. With `withRoles`, tag the public-surface
+ * roles (exported / test) an impact trace reports; other directions omit them.
+ */
+function summary(
+  node: ITtscGraphNode,
+  depth?: number,
+  withRoles = false,
+): ITtscGraphTrace.INode {
+  const out: ITtscGraphTrace.INode = {
+    id: node.id,
+    name: node.qualifiedName ?? node.name,
+    kind: node.kind,
+    file: node.file,
+  };
+  if (depth !== undefined) out.depth = depth;
+  if (withRoles) {
+    const roles: string[] = [];
+    if (node.exported) roles.push("exported");
+    if (isTestFile(node.file)) roles.push("test");
+    if (roles.length > 0) out.roles = roles;
+  }
+  return out;
+}
+
+/** An edge the trace should follow: a real dependency, not a structural edge. */
+function traversable(kind: string): boolean {
+  return kind !== "contains" && kind !== "exports" && kind !== "imports";
+}
+
+function isTestFile(file: string): boolean {
+  return (
+    /(^|\/)(test|tests|__tests__|spec)\//.test(file) ||
+    /\.(test|spec)\.[cm]?tsx?$/.test(file)
+  );
+}

package/src/server/startServer.ts

@@ -0,0 +1,25 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import { TtscGraphMemory } from "../model/TtscGraphMemory";
+import { loadGraph } from "../model/loadGraph";
+import { createServer } from "./createServer";
+
+/**
+ * Serve the graph tools over MCP on stdio. The server answers the MCP handshake
+ * immediately and builds the resident graph on the first tool call, so a large
+ * project cannot make the client give up before tools are advertised.
+ */
+export async function startServer(options: {
+  cwd?: string;
+  tsconfig?: string;
+  /** Server version reported in the MCP handshake. */
+  version: string;
+}): Promise<void> {
+  let graph: TtscGraphMemory | undefined;
+  const server = createServer(() => {
+    graph ??= loadGraph({ cwd: options.cwd, tsconfig: options.tsconfig });
+    return graph;
+  }, options.version);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/structures/ITtscGraphApplication.ts

@@ -0,0 +1,68 @@
+import { ITtscGraphExpand } from "./ITtscGraphExpand";
+import { ITtscGraphIndex } from "./ITtscGraphIndex";
+import { ITtscGraphOverview } from "./ITtscGraphOverview";
+import { ITtscGraphQuery } from "./ITtscGraphQuery";
+import { ITtscGraphTrace } from "./ITtscGraphTrace";
+
+/**
+ * The MCP tool surface of `@ttsc/graph`, as a typed application.
+ *
+ * Each method is one MCP tool; its name is the tool name and its parameter
+ * object becomes the tool's JSON schema once `typia.llm.controller` reflects
+ * this interface. `TtscGraphApplication` implements it over the resident
+ * graph.
+ */
+export interface ITtscGraphApplication {
+  /**
+   * The first source-free index for a code question: ranked symbols, exact code
+   * handles mentioned in the query, declaration signatures, and direct
+   * dependency context. Use this before reading source.
+   *
+   * @param props The natural code question or search phrase
+   * @returns Compact graph coordinates and dependency context
+   */
+  graph_index(props: ITtscGraphIndex.IProps): ITtscGraphIndex;
+
+  /**
+   * The project's architecture — folder layers, dependency hotspots, and the
+   * public API. Call first to orient on an unfamiliar codebase.
+   *
+   * @param props Which facet to project
+   * @returns The requested architecture facets
+   */
+  graph_overview(props: ITtscGraphOverview.IProps): ITtscGraphOverview;
+
+  /**
+   * The declared shape of the given symbols: each one's signature, and for a
+   * class/interface/namespace its members. Handles may be ids or dotted symbol
+   * names. Set `source: true` to also read a specific body, `neighbors: true`
+   * to list what it uses and what uses it.
+   *
+   * @param props The handles to expand
+   * @returns The resolved nodes, and any handles that did not resolve
+   */
+  graph_expand(props: ITtscGraphExpand.IProps): ITtscGraphExpand;
+
+  /**
+   * Find any symbol — class, function, method, or field — by name or
+   * description. Each hit comes with its signature, so the query alone often
+   * answers the question, and `next.expand` gives handles for source
+   * follow-up.
+   *
+   * @param props The query and result cap
+   * @returns Ranked hits with handles
+   */
+  graph_query(props: ITtscGraphQuery.IProps): ITtscGraphQuery;
+
+  /**
+   * Follow dependency flow from a symbol: `forward` to what it uses, `reverse`
+   * to what uses it, or `impact` to the public API and tests a change reaches.
+   * Give `from`/`to` as ids or dotted names to get the path between two symbols
+   * in one call — how A reaches B.
+   *
+   * @param props The start, optional target, direction, and bounds
+   * @returns The ordered hops and reached nodes, or candidates for an ambiguous
+   *   start
+   */
+  graph_trace(props: ITtscGraphTrace.IProps): ITtscGraphTrace;
+}

package/src/structures/ITtscGraphDecorator.ts

@@ -0,0 +1,33 @@
+/**
+ * A decorator as written on a declaration, carried on the decorated
+ * {@link ITtscGraphNode}'s `decorators`. The graph reports the decorator
+ * faithfully rather than interpreting any framework's convention: the `name` is
+ * the decorator as written (`Controller`, `Get`, `TypedRoute.Get`, …) and the
+ * statically resolvable `arguments` are preserved, so a consumer can apply its
+ * own meaning without re-parsing source.
+ */
+export interface ITtscGraphDecorator {
+  /**
+   * The decorator name as written, qualified through its access path —
+   * `Controller`, `Get`, `TypedRoute.Get`, `MessagePattern`.
+   */
+  name: string;
+
+  /** The call arguments, in source order. Empty for a bare decorator. */
+  arguments: ITtscGraphDecorator.IArgument[];
+}
+export namespace ITtscGraphDecorator {
+  /**
+   * One argument of an {@link ITtscGraphDecorator}. `text` is always the source
+   * of the argument expression; `literal` is set only when the argument is a
+   * string, number, or boolean literal the producer could resolve statically,
+   * so a consumer can use it without evaluating code.
+   */
+  export interface IArgument {
+    /** The argument expression's source text. */
+    text: string;
+
+    /** The statically-resolved literal value, when the argument is a literal. */
+    literal?: string | number | boolean;
+  }
+}

package/src/structures/ITtscGraphDiagnostic.ts

@@ -0,0 +1,34 @@
+/**
+ * A compiler or plugin diagnostic, fused onto the graph so an edit-triage query
+ * can name the owning symbol of an error.
+ *
+ * The TypeScript semantic pass contributes numeric-coded `tsc` diagnostics;
+ * `@ttsc/lint` rules and transform plugins (typia, nestia, …) contribute
+ * `plugin`/`lint` findings whose `code` is a string. `node` is set when the
+ * finding's position was attributed to a graph node.
+ */
+export interface ITtscGraphDiagnostic {
+  /** Project-relative path of the file the diagnostic is reported in. */
+  file: string;
+
+  /** 1-based line of the diagnostic. */
+  line: number;
+
+  /** 1-based column of the diagnostic, when known. */
+  column?: number;
+
+  /** Numeric `tsc` code, or string rule id for a lint/plugin finding. */
+  code: number | string;
+
+  /** The human-readable diagnostic message. */
+  message: string;
+
+  /** Severity, when the producer distinguishes it. */
+  severity?: "error" | "warning" | "info" | "hint";
+
+  /** Which lane produced the diagnostic. */
+  origin?: "tsc" | "plugin" | "lint";
+
+  /** Node id the diagnostic was fused onto, when resolved. */
+  node?: string;
+}

package/src/structures/ITtscGraphDump.ts

@@ -0,0 +1,35 @@
+import { ITtscGraphDiagnostic } from "./ITtscGraphDiagnostic";
+import { ITtscGraphEdge } from "./ITtscGraphEdge";
+import { ITtscGraphNode } from "./ITtscGraphNode";
+
+/**
+ * The whole-graph export `ttscgraph dump` writes and the MCP server loads — the
+ * wire contract between the Go fact-builder and the TypeScript graph engine.
+ *
+ * It is the complete graph with none of the per-response caps the MCP tools
+ * apply: every node and edge the build resolved. The server parses it once at
+ * startup (typia-validated) into an in-memory resident graph and answers every
+ * tool call from that warm model; the bundled 3D viewer reduces the same dump.
+ *
+ * Paths in `project` and `tsconfig` are absolute; `file` fields on nodes,
+ * edges, and diagnostics are project-relative.
+ */
+export interface ITtscGraphDump {
+  /** Absolute path of the project root the graph was built for. */
+  project: string;
+
+  /** The tsconfig the program was loaded from, relative to `project`. */
+  tsconfig: string;
+
+  /** Every node the build recorded. */
+  nodes: ITtscGraphNode[];
+
+  /** Every edge the build resolved. */
+  edges: ITtscGraphEdge[];
+
+  /**
+   * Fused compiler and plugin diagnostics, when diagnostics were collected.
+   * Absent when the dump was built without a diagnostics pass.
+   */
+  diagnostics?: ITtscGraphDiagnostic[];
+}

package/src/structures/ITtscGraphEdge.ts

@@ -0,0 +1,24 @@
+import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
+import { TtscGraphEdgeKind } from "./TtscGraphEdgeKind";
+
+/**
+ * A directed relationship from one {@link ITtscGraphNode} to another, both named
+ * by `id`. The triple `(from, to, kind)` is unique; a repeated relationship
+ * keeps the first source-order evidence.
+ *
+ * Every edge is resolved by the compiler, so there is no per-edge trust flag to
+ * carry — the whole graph is checker-resolved fact.
+ */
+export interface ITtscGraphEdge {
+  /** Node id the relationship originates from. */
+  from: string;
+
+  /** Node id the relationship points to. */
+  to: string;
+
+  /** The relationship kind. */
+  kind: TtscGraphEdgeKind;
+
+  /** The source expression that produced the edge, for display and expansion. */
+  evidence?: ITtscGraphEvidence;
+}

package/src/structures/ITtscGraphEvidence.ts

@@ -0,0 +1,29 @@
+/**
+ * A source location that grounds a node or edge in real code — the declaration
+ * span for a node, or the expression that produced an edge.
+ *
+ * Evidence is display and grounding only; it is never identity. A node's id is
+ * position-invariant (see {@link ITtscGraphNode}), so an edit that shifts a span
+ * does not re-key anything. `startLine`/`startCol` are 1-based. `text` is an
+ * optional short excerpt the producer may include so a consumer can show the
+ * evidence without a file read.
+ */
+export interface ITtscGraphEvidence {
+  /** Project-relative path of the file the span lives in. */
+  file: string;
+
+  /** 1-based line where the span starts. */
+  startLine: number;
+
+  /** 1-based column where the span starts, when known. */
+  startCol?: number;
+
+  /** 1-based line where the span ends, when it differs from `startLine`. */
+  endLine?: number;
+
+  /** 1-based column where the span ends, when known. */
+  endCol?: number;
+
+  /** A short source excerpt of the span, when the producer inlines one. */
+  text?: string;
+}

package/src/structures/ITtscGraphExpand.ts

@@ -0,0 +1,85 @@
+/**
+ * The resolved nodes the `graph_expand` tool returns for a set of handles —
+ * their declared shape (signature, and a container's members), and only on
+ * request their full source body.
+ */
+export interface ITtscGraphExpand {
+  nodes: ITtscGraphExpand.INode[];
+
+  /** Handles that resolved to no node, or that were ambiguous. */
+  unknown: string[];
+}
+export namespace ITtscGraphExpand {
+  /** Which handles to expand, and how much of each to return. */
+  export interface IProps {
+    /**
+     * Node ids from another tool, or dotted symbol handles such as
+     * `OrderService.create`. Pass every handle you need in one call.
+     */
+    handles: string[];
+
+    /**
+     * Also list each node's direct dependencies and dependents (the symbols it
+     * uses and the symbols that use it).
+     *
+     * @default false
+     */
+    neighbors?: boolean;
+
+    /**
+     * Return the full declaration source body too. Off by default: expand
+     * returns the declared shape — a symbol's signature, and a class/interface/
+     * namespace's member outline — which is what you usually need and a
+     * fraction of the tokens. Turn this on only for the few leaf functions or
+     * methods whose actual control-flow logic you must read.
+     *
+     * @default false
+     */
+    source?: boolean;
+  }
+
+  /** One expanded node: its declared shape, and on request its source. */
+  export interface INode {
+    id: string;
+    name: string;
+    kind: string;
+    file: string;
+    /** 1-based declaration line, when known. */
+    line?: number;
+    /** The declaration signature — its first line(s) up to the body. */
+    signature?: string;
+    /**
+     * For a class, interface, namespace, module, enum, or file: the symbols it
+     * contains, each with its own signature — the member outline a consumer
+     * reaches for, without the bodies.
+     */
+    members?: IMember[];
+    /** The full declaration source — only when `source` was requested. */
+    source?: string;
+    /** True when `source` was cut at the line cap. */
+    truncated?: boolean;
+    /** Symbols this node uses (outgoing dependency edges). */
+    dependsOn?: IReference[];
+    /** Symbols that use this node (incoming dependency edges). */
+    dependedOnBy?: IReference[];
+  }
+
+  /** One member of a container node, with its signature but not its body. */
+  export interface IMember {
+    name: string;
+    kind: string;
+    /** 1-based declaration line, when known. */
+    line?: number;
+    /** The member's declaration signature. */
+    signature?: string;
+  }
+
+  /** A dependency neighbor of an expanded node and the edge that links them. */
+  export interface IReference {
+    id: string;
+    name: string;
+    kind: string;
+    /** The edge kind connecting the two (`calls`, `type_ref`, …). */
+    relation: string;
+  }
+}

package/src/structures/ITtscGraphIndex.ts

@@ -0,0 +1,100 @@
+/** The compact source-free index returned by `graph_index` for a code question. */
+export interface ITtscGraphIndex {
+  /** The original query the index was built for. */
+  query: string;
+
+  /** Ranked symbols relevant to the query. */
+  hits: ITtscGraphIndex.IHit[];
+
+  /** Code handles written directly in the query, resolved when possible. */
+  mentions: ITtscGraphIndex.IMention[];
+
+  /** Direct dependency context for the resolved mentions and highest hits. */
+  neighborhood: ITtscGraphIndex.INeighborhood[];
+
+  /** Follow-up handles for deeper graph calls. */
+  next: ITtscGraphIndex.INext;
+
+  /** True when result caps hid additional seeds or references. */
+  truncated?: boolean;
+}
+
+export namespace ITtscGraphIndex {
+  /**
+   * Ask the graph for the first index an agent should read before opening
+   * source: ranked symbols, exact mentioned handles, and nearby dependency
+   * edges.
+   */
+  export interface IProps {
+    /**
+     * A natural code question or search phrase. Mix prose with code handles,
+     * for example `how Repository.find loads relations` or
+     * `SelectQueryBuilder.setFindOptions join aliases`.
+     */
+    query: string;
+
+    /**
+     * Maximum ranked hits to return.
+     *
+     * @default 8
+     */
+    limit?: number;
+
+    /**
+     * Maximum direct dependencies and dependents to return per indexed symbol.
+     *
+     * @default 4
+     */
+    neighbors?: number;
+  }
+
+  /** A compact symbol coordinate, optionally with its declaration signature. */
+  export interface INode {
+    id: string;
+    name: string;
+    kind: string;
+    file: string;
+    /** 1-based declaration line, when known. */
+    line?: number;
+    /** Declaration head, included only for indexed symbols. */
+    signature?: string;
+  }
+
+  /** One ranked search hit. */
+  export interface IHit extends INode {
+    /** Relative relevance; higher is a better match. */
+    score: number;
+  }
+
+  /** A code handle written in the query, with its resolution status. */
+  export interface IMention {
+    handle: string;
+    node?: INode;
+    candidates?: INode[];
+  }
+
+  /** Direct dependency context around one indexed symbol. */
+  export interface INeighborhood extends INode {
+    dependsOn: IReference[];
+    dependedOnBy: IReference[];
+  }
+
+  /** One neighboring symbol and the relationship leading to it. */
+  export interface IReference {
+    id: string;
+    name: string;
+    kind: string;
+    file: string;
+    /** 1-based declaration line, when known. */
+    line?: number;
+    relation: string;
+  }
+
+  /** Tool-call handles suggested by this first index. */
+  export interface INext {
+    /** Pass these ids to `graph_expand`, with `source: true` only when needed. */
+    expand: string[];
+    /** Pass these ids to `graph_trace` when following dependency flow. */
+    traceFrom: string[];
+  }
+}