@ttsc/graph 0.16.4 → 0.16.5

package/src/structures/ITtscGraphNode.ts

@@ -0,0 +1,64 @@
+import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
+import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
+import { TtscGraphNodeKind } from "./TtscGraphNodeKind";
+import { TtscGraphNodeModifier } from "./TtscGraphNodeModifier";
+
+/**
+ * One node in the graph: a declared symbol or a structural container (file,
+ * package).
+ *
+ * The `id` is position-invariant: `path#qualifiedName:kind` (e.g.
+ * `src/order.ts#OrderService.create:method`), so inserting a line above a
+ * declaration does not re-key it. Line and span live in `evidence` and are
+ * never part of identity.
+ */
+export interface ITtscGraphNode {
+  /** Position-invariant identity (see the interface doc for the id grammar). */
+  id: string;
+
+  /** What this node represents. */
+  kind: TtscGraphNodeKind;
+
+  /** The simple, unqualified declared name (`create`, `OrderService`, `App`). */
+  name: string;
+
+  /**
+   * The owner-qualified name, when the node lives inside another declaration —
+   * `OrderService.create`, `Shopping.ISale`. Absent for a top-level
+   * declaration.
+   */
+  qualifiedName?: string;
+
+  /** Project-relative path of the file that declares this node. */
+  file: string;
+
+  /**
+   * True when the declaration lives outside the workspace (a dependency). The
+   * graph keeps the leaf as a named endpoint but does not expand its
+   * internals.
+   */
+  external: boolean;
+
+  /**
+   * True when `file` is git-ignored generated code (a Prisma client, a codegen
+   * output). Projections desurface these so generated nodes do not bury the
+   * authored graph.
+   */
+  ignored?: boolean;
+
+  /** True when the symbol is part of its module's export surface. */
+  exported?: boolean;
+
+  /** Declaration modifiers, when the declaration pass recorded any. */
+  modifiers?: TtscGraphNodeModifier[];
+
+  /**
+   * The decorators written on this declaration, in source order, when it has
+   * any — raw decorator facts (`@Controller`, `@Get`) a consumer can interpret
+   * without re-parsing source.
+   */
+  decorators?: ITtscGraphDecorator[];
+
+  /** The declaration span, for display and source expansion. */
+  evidence?: ITtscGraphEvidence;
+}

package/src/structures/ITtscGraphOverview.ts

@@ -0,0 +1,79 @@
+/**
+ * A compact, source-read-free architecture map of the project — the result of
+ * the `graph_overview` tool.
+ */
+export interface ITtscGraphOverview {
+  /** Absolute project root. */
+  project: string;
+
+  /** Size of the graph. */
+  counts: ITtscGraphOverview.ICounts;
+
+  /** Folder layering, largest first. */
+  layers?: ITtscGraphOverview.ILayer[];
+
+  /** Highest-dependency symbols, busiest first. */
+  hotspots?: ITtscGraphOverview.IHotspot[];
+
+  /** Exported API symbols, most-depended-on first. */
+  publicApi?: ITtscGraphOverview.IPublicApi[];
+}
+export namespace ITtscGraphOverview {
+  /** Which architecture facets `graph_overview` should return. */
+  export interface IProps {
+    /**
+     * The facet to project, or `all` for every facet. `layers` is the folder
+     * layering, `hotspots` the highest-dependency symbols, `publicApi` the
+     * exported API symbols ranked by how depended-on they are.
+     *
+     * @default "all"
+     */
+    aspect?: "all" | "layers" | "hotspots" | "publicApi";
+  }
+
+  /** Size of the graph by node/edge totals and per-kind node counts. */
+  export interface ICounts {
+    files: number;
+    nodes: number;
+    edges: number;
+    /** Node count per kind. */
+    byKind: Record<string, number>;
+  }
+
+  /** One folder layer: its source files and export surface. */
+  export interface ILayer {
+    /** Directory, project-relative. */
+    dir: string;
+    /** Distinct source files under it. */
+    files: number;
+    /** Exported symbols declared under it. */
+    exported: number;
+  }
+
+  /** A high-dependency symbol with its non-structural fan-in and fan-out. */
+  export interface IHotspot {
+    id: string;
+    name: string;
+    kind: string;
+    file: string;
+    /** Non-structural edges pointing at this symbol. */
+    fanIn: number;
+    /** Non-structural edges leaving this symbol. */
+    fanOut: number;
+  }
+
+  /**
+   * One symbol on the project's exported public API surface. The list is ranked
+   * by how depended-on the symbol is, with test, typings, and generated files
+   * excluded, so the names a consumer of the project would reach for surface
+   * first — not whichever file happens to declare the most exports.
+   */
+  export interface IPublicApi {
+    /** The exported symbol's name. */
+    name: string;
+    /** Its declaration kind (`class`, `interface`, `function`, …). */
+    kind: string;
+    /** Project-relative path of the file that declares it. */
+    file: string;
+  }
+}

package/src/structures/ITtscGraphQuery.ts

@@ -0,0 +1,49 @@
+/** The ranked hits the `graph_query` tool returns for a natural code query. */
+export interface ITtscGraphQuery {
+  hits: ITtscGraphQuery.IHit[];
+
+  /** Follow-up handles for source or member details. */
+  next: ITtscGraphQuery.INext;
+}
+export namespace ITtscGraphQuery {
+  /** Find the symbols and clusters most relevant to a natural code query. */
+  export interface IProps {
+    /**
+     * What to find, in natural language and code vocabulary mixed freely — a
+     * symbol name, a dotted member (`OrderService.create`), or a phrase
+     * (`shopping order create`, `repository find relations`). Exact names are
+     * not required; subword and CamelCase matches rank too.
+     */
+    query: string;
+
+    /**
+     * Maximum hits to return.
+     *
+     * @default 12
+     */
+    limit?: number;
+  }
+
+  /** One ranked hit with a handle to follow via `graph_expand` or `graph_trace`. */
+  export interface IHit {
+    id: string;
+    name: string;
+    kind: string;
+    file: string;
+    /** 1-based declaration line, when known. */
+    line?: number;
+    /**
+     * The hit's declaration signature, so you can often answer without
+     * expanding.
+     */
+    signature?: string;
+    /** Relative relevance; higher is a better match. */
+    score: number;
+  }
+
+  /** Tool-call handles suggested by this index result. */
+  export interface INext {
+    /** Pass these ids to `graph_expand`, with `source: true` only when needed. */
+    expand: string[];
+  }
+}

package/src/structures/ITtscGraphTrace.ts

@@ -0,0 +1,97 @@
+/**
+ * The ordered dependency flow the `graph_trace` tool returns from a start
+ * symbol.
+ */
+export interface ITtscGraphTrace {
+  /** The resolved start node, or undefined when `from` matched nothing. */
+  start?: ITtscGraphTrace.INode;
+
+  direction: string;
+
+  /** Edges traversed, in breadth-first order. */
+  hops: ITtscGraphTrace.IHop[];
+
+  /** Unique nodes reached (excluding the start), each with its depth and roles. */
+  reached: ITtscGraphTrace.INode[];
+
+  /** True when the trace hit maxNodes or maxDepth and more flow exists. */
+  truncated: boolean;
+
+  /** The resolved `to` target, when a path was requested. */
+  target?: ITtscGraphTrace.INode;
+
+  /**
+   * When `to` was given: the ordered dependency path from `from` to `to`
+   * (`from` first, `to` last), or empty when `to` is not reachable from
+   * `from`.
+   */
+  path?: ITtscGraphTrace.INode[];
+
+  /** When `from` was an ambiguous name, the matches to disambiguate with. */
+  candidates?: ITtscGraphTrace.INode[];
+}
+export namespace ITtscGraphTrace {
+  /** Where and how far to trace dependency flow. */
+  export interface IProps {
+    /**
+     * Where to start: a node id from another tool, a simple symbol name, or a
+     * dotted member name such as `OrderService.create`. An ambiguous name
+     * returns its candidates instead of a trace.
+     */
+    from: string;
+
+    /**
+     * A target symbol: node id, simple symbol name, or dotted member name. When
+     * given, the tool returns the dependency path from `from` to this target —
+     * the one-call answer for "how does A reach B" — instead of an open-ended
+     * trace.
+     */
+    to?: string;
+
+    /**
+     * `forward` follows what the start uses (callees, instantiations, renders);
+     * `reverse` follows what uses the start (callers); `impact` is a reverse
+     * trace that flags the public API and tests a change would reach.
+     *
+     * @default "forward"
+     */
+    direction?: "forward" | "reverse" | "impact";
+
+    /**
+     * How many hops deep to follow.
+     *
+     * @default 6
+     */
+    maxDepth?: number;
+
+    /**
+     * Cap on reached nodes; the trace stops and marks itself truncated past it.
+     *
+     * @default 60
+     */
+    maxNodes?: number;
+  }
+
+  /** One traversed edge, with its depth from the start. */
+  export interface IHop {
+    from: string;
+    to: string;
+    kind: string;
+    /** Hops from the start (1 = direct). */
+    depth: number;
+  }
+
+  /** A node on the trace: the start, a reached node, or a candidate. */
+  export interface INode {
+    id: string;
+    name: string;
+    kind: string;
+    file: string;
+    /** Hops from the start, on a reached node. */
+    depth?: number;
+    /** The node's signature — carried on path nodes so the path explains itself. */
+    signature?: string;
+    /** Why this node matters to an impact trace: `exported`, `test`. */
+    roles?: string[];
+  }
+}

package/src/structures/TtscGraphEdgeKind.ts

@@ -0,0 +1,23 @@
+/**
+ * The relationship a directed edge encodes between two {@link ITtscGraphNode}s.
+ *
+ * Structural edges (`contains`, `exports`, `imports`) come from the declaration
+ * pass. Value and type edges (`calls`, `accesses`, `instantiates`, `type_ref`,
+ * `extends`, `implements`, `overrides`, `renders`) are resolved by the checker
+ * — `renders` is a JSX component use. `decorates` carries a decorator fact and
+ * `tests` a test-to-subject relationship.
+ */
+export type TtscGraphEdgeKind =
+  | "contains"
+  | "exports"
+  | "imports"
+  | "calls"
+  | "accesses"
+  | "instantiates"
+  | "type_ref"
+  | "extends"
+  | "implements"
+  | "overrides"
+  | "decorates"
+  | "renders"
+  | "tests";

package/src/structures/TtscGraphNodeKind.ts

@@ -0,0 +1,26 @@
+/**
+ * What a graph node represents.
+ *
+ * The symbol kinds (`file` through `parameter`) are declarations the TypeScript
+ * program owns and the checker resolves. `external_symbol` is a
+ * dependency-boundary leaf the workspace references but does not declare — the
+ * graph keeps it as a named endpoint without expanding the dependency's
+ * internals.
+ *
+ * Used as the `kind` discriminant on {@link ITtscGraphNode}.
+ */
+export type TtscGraphNodeKind =
+  | "file"
+  | "package"
+  | "namespace"
+  | "module"
+  | "function"
+  | "class"
+  | "interface"
+  | "type"
+  | "enum"
+  | "variable"
+  | "method"
+  | "property"
+  | "parameter"
+  | "external_symbol";

package/src/structures/TtscGraphNodeModifier.ts

@@ -0,0 +1,19 @@
+/**
+ * A declaration modifier carried on a symbol {@link ITtscGraphNode}, when the
+ * declaration pass records it. Used by projections that reason about visibility
+ * and shape — e.g. a public-API overview filters on `export`, a class outline
+ * separates `static` members.
+ */
+export type TtscGraphNodeModifier =
+  | "export"
+  | "default"
+  | "declare"
+  | "abstract"
+  | "static"
+  | "readonly"
+  | "async"
+  | "const"
+  | "public"
+  | "private"
+  | "protected"
+  | "optional";

package/src/structures/index.ts

@@ -0,0 +1,21 @@
+// The canonical graph data model and tool I/O types: the wire contract
+// `ttscgraph dump` emits and the MCP server loads, plus the schemas typia
+// derives the tool surface from. Pure types so typia can build validators and
+// tool schemas at build time, and so the Go `dump.go` writer has one TypeScript
+// source of truth to mirror.
+
+export * from "./ITtscGraphApplication";
+export * from "./ITtscGraphDecorator";
+export * from "./ITtscGraphDiagnostic";
+export * from "./ITtscGraphDump";
+export * from "./ITtscGraphEdge";
+export * from "./ITtscGraphEvidence";
+export * from "./ITtscGraphExpand";
+export * from "./ITtscGraphIndex";
+export * from "./ITtscGraphNode";
+export * from "./ITtscGraphOverview";
+export * from "./ITtscGraphQuery";
+export * from "./ITtscGraphTrace";
+export * from "./TtscGraphEdgeKind";
+export * from "./TtscGraphNodeKind";
+export * from "./TtscGraphNodeModifier";

package/src/view.ts

@@ -0,0 +1,155 @@
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+
+import { type RawDump, reduce } from "./reduce";
+import { resolveGraphBinary } from "./resolveGraphBinary";
+
+interface ViewOptions {
+  cwd: string;
+  tsconfig: string;
+  port: number;
+  open: boolean;
+  maxNodes: number;
+}
+
+function parseViewArgs(argv: readonly string[]): ViewOptions {
+  const opts: ViewOptions = {
+    cwd: process.cwd(),
+    tsconfig: "tsconfig.json",
+    port: 0,
+    open: true,
+    maxNodes: 1200,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if (arg === "--cwd") opts.cwd = argv[++i] ?? opts.cwd;
+    else if (arg.startsWith("--cwd=")) opts.cwd = arg.slice("--cwd=".length);
+    else if (arg === "--tsconfig" || arg === "-p")
+      opts.tsconfig = argv[++i] ?? opts.tsconfig;
+    else if (arg.startsWith("--tsconfig="))
+      opts.tsconfig = arg.slice("--tsconfig=".length);
+    else if (arg === "--port") opts.port = Number(argv[++i]);
+    else if (arg.startsWith("--port="))
+      opts.port = Number(arg.slice("--port=".length));
+    else if (arg === "--no-open") opts.open = false;
+    else if (arg === "--max-nodes") opts.maxNodes = Number(argv[++i]);
+    else if (arg.startsWith("--max-nodes="))
+      opts.maxNodes = Number(arg.slice("--max-nodes=".length));
+  }
+  return opts;
+}
+
+/**
+ * `ttsc-graph view`: build the project's code graph, reduce it, and serve a
+ * self-contained 3D viewer on a localhost port, opening the browser. The native
+ * binary produces the graph (the same `dump` the docs document); everything
+ * else is local and offline. The process stays alive serving until Ctrl+C.
+ */
+export function runView(argv: readonly string[]): number | void {
+  const opts = parseViewArgs(argv);
+
+  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;
+  }
+
+  process.stderr.write(
+    `@ttsc/graph: building the graph for ${opts.cwd} (${opts.tsconfig})...\n`,
+  );
+  const dump = spawnSync(
+    binary,
+    ["dump", "--cwd", opts.cwd, "--tsconfig", opts.tsconfig],
+    { encoding: "utf8", maxBuffer: 1024 * 1024 * 1024 },
+  );
+  if (dump.error) {
+    process.stderr.write(`@ttsc/graph: ${dump.error.message}\n`);
+    return 1;
+  }
+  if (dump.status !== 0) {
+    process.stderr.write(dump.stderr || "@ttsc/graph: dump failed\n");
+    return dump.status ?? 1;
+  }
+
+  let raw: RawDump;
+  try {
+    raw = JSON.parse(dump.stdout) as RawDump;
+  } catch (err) {
+    process.stderr.write(
+      `@ttsc/graph: could not parse the graph dump: ${String(err)}\n`,
+    );
+    return 1;
+  }
+
+  const payload = reduce(raw, { maxNodes: opts.maxNodes });
+  payload.project = path.basename(path.resolve(opts.cwd));
+  const graphJson = JSON.stringify(payload);
+
+  const viewerDir = path.join(__dirname, "viewer");
+  let indexHtml: Buffer;
+  let viewerJs: Buffer;
+  try {
+    indexHtml = fs.readFileSync(path.join(viewerDir, "index.html"));
+    viewerJs = fs.readFileSync(path.join(viewerDir, "viewer.js"));
+  } catch (err) {
+    process.stderr.write(
+      `@ttsc/graph: the bundled viewer is missing (${String(err)}). ` +
+        "Reinstall @ttsc/graph.\n",
+    );
+    return 1;
+  }
+
+  const server = http.createServer((req, res) => {
+    const url = (req.url ?? "/").split("?")[0];
+    if (url === "/graph.json") {
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(graphJson);
+    } else if (url === "/viewer.js") {
+      res.writeHead(200, {
+        "content-type": "application/javascript; charset=utf-8",
+      });
+      res.end(viewerJs);
+    } else {
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      res.end(indexHtml);
+    }
+  });
+
+  server.listen(opts.port, "127.0.0.1", () => {
+    const address = server.address();
+    const port =
+      typeof address === "object" && address ? address.port : opts.port;
+    const url = `http://127.0.0.1:${port}/`;
+    const counts = payload.counts;
+    process.stderr.write(
+      `@ttsc/graph: ${counts.nodes.toLocaleString()} nodes / ${counts.links.toLocaleString()} edges` +
+        ` (from ${counts.rawNodes.toLocaleString()} / ${counts.rawEdges.toLocaleString()})\n`,
+    );
+    process.stderr.write(`@ttsc/graph: serving the 3D viewer at ${url}\n`);
+    process.stderr.write("@ttsc/graph: press Ctrl+C to stop.\n");
+    if (opts.open) openBrowser(url);
+  });
+  // No return: the listening server keeps the process alive until Ctrl+C.
+}
+
+/** Best-effort open the URL in the default browser; the URL is printed anyway. */
+function openBrowser(url: string): void {
+  try {
+    if (process.platform === "win32")
+      spawn("cmd", ["/c", "start", "", url], {
+        stdio: "ignore",
+        detached: true,
+      }).unref();
+    else if (process.platform === "darwin")
+      spawn("open", [url], { stdio: "ignore", detached: true }).unref();
+    else spawn("xdg-open", [url], { stdio: "ignore", detached: true }).unref();
+  } catch {
+    /* the URL is printed; opening is a convenience */
+  }
+}

package/src/viewer/index.html

@@ -0,0 +1,123 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>ttsc · code graph</title>
+    <style>
+      :root {
+        color-scheme: dark;
+      }
+      * {
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        margin: 0;
+        height: 100%;
+        background: #0a0c10;
+        color: #e6edf3;
+        font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+        overflow: hidden;
+      }
+      #app {
+        display: flex;
+        flex-direction: column;
+        height: 100vh;
+      }
+      header {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: baseline;
+        gap: 0 14px;
+        padding: 10px 16px;
+        border-bottom: 1px solid #222834;
+        background: linear-gradient(to bottom, #13171f, #0e1116);
+      }
+      header .brand {
+        font-size: 13px;
+        font-weight: 600;
+        color: #f5f5f5;
+      }
+      header .brand b {
+        color: #36e2ee;
+      }
+      header #project {
+        font-size: 12px;
+        color: #9ca3af;
+      }
+      header #counts {
+        margin-left: auto;
+        font-size: 11px;
+        color: #6b7280;
+      }
+      #graph {
+        position: relative;
+        flex: 1;
+        min-height: 0;
+      }
+      #graph .tooltip {
+        position: absolute;
+        display: none;
+        pointer-events: none;
+        z-index: 10;
+        max-width: 24rem;
+        padding: 4px 7px;
+        border-radius: 6px;
+        background: rgba(12, 14, 19, 0.93);
+        border: 1px solid #2a313e;
+        font-size: 11px;
+        line-height: 1.4;
+      }
+      #graph .tooltip .muted {
+        color: #8b97a8;
+      }
+      footer {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 6px 16px;
+        padding: 8px 16px;
+        border-top: 1px solid #222834;
+        font-size: 10px;
+        color: #6b7280;
+      }
+      footer .dot {
+        display: inline-flex;
+        align-items: center;
+        gap: 6px;
+      }
+      footer .swatch {
+        display: inline-block;
+        width: 16px;
+        height: 2px;
+        border-radius: 2px;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app">
+      <header>
+        <span class="brand"><b>ttsc</b> · code graph</span>
+        <span id="project"></span>
+        <span id="counts"></span>
+      </header>
+      <div id="graph"></div>
+      <footer>
+        <span class="dot"
+          ><span class="swatch" style="background: #3fb950"></span
+          >value-call</span
+        >
+        <span class="dot"
+          ><span class="swatch" style="background: #f5b042"></span
+          >type-ref</span
+        >
+        <span class="dot"
+          ><span class="swatch" style="background: #6ea8ff"></span
+          >heritage</span
+        >
+        <span>node size = connection count · color = declaration kind</span>
+      </footer>
+    </div>
+    <script src="viewer.js"></script>
+  </body>
+</html>