@ttsc/graph 0.23.0 → 0.25.0

package/src/server/runTrace.ts

@@ -29,11 +29,7 @@ const MAX_STEPS = 12;
 const DISPATCH_KINDS = new Set<string>(["overrides", "implements"]);
 // A declaration whose kind is a type surface never carries a body, and an
 // external leaf carries one the graph deliberately does not hold.
-const BODYLESS_KINDS = new Set<string>([
-  "interface",
-  "type",
-  "external_symbol",
-]);
+const BODYLESS_KINDS = new Set<string>(["interface", "type"]);
 // `abstract` and `declare` are the two keywords that take the body away from a
 // declaration that would otherwise have to have one.
 const BODYLESS_MODIFIERS = new Set<string>(["abstract", "declare"]);
@@ -48,11 +44,10 @@ const BODYLESS_MODIFIERS = new Set<string>(["abstract", "declare"]);
 const DISPATCH_HUB = 12;
 
 /**
- * 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.
+ * Breadth-first trace along the dependency graph. Structural (contains/exports)
+ * 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,
@@ -946,7 +941,7 @@ function traversable(
   kind: string,
   focus: ITtscGraphTrace.IRequest["focus"],
 ): boolean {
-  if (kind === "contains" || kind === "exports" || kind === "imports") {
+  if (kind === "contains" || kind === "exports") {
     return false;
   }
   if (kind === "dispatches") return focus !== "types";
@@ -963,8 +958,7 @@ function traversable(
       kind === "type_ref" ||
       kind === "extends" ||
       kind === "implements" ||
-      kind === "overrides" ||
-      kind === "decorates"
+      kind === "overrides"
     );
   }
   return true;
@@ -985,16 +979,13 @@ function edgeKindRank(kind: string): number {
       return 2;
     case "accesses":
       return 3;
-    case "tests":
-      return 4;
     case "overrides":
-    case "decorates":
-      return 5;
+      return 4;
     case "extends":
     case "implements":
-      return 6;
+      return 5;
     case "type_ref":
-      return 7;
+      return 6;
     default:
       return 10;
   }

package/src/structures/ITtscGraphDump.ts

@@ -1,6 +1,8 @@
 import { ITtscGraphEdge } from "./ITtscGraphEdge";
 import { ITtscGraphNode } from "./ITtscGraphNode";
 import { ITtscGraphSpan } from "./ITtscGraphSpan";
+import { TtscGraphDumpEdgeKind } from "./TtscGraphDumpEdgeKind";
+import { TtscGraphDumpNodeKind } from "./TtscGraphDumpNodeKind";
 
 /**
  * The whole-graph export `ttscgraph dump` writes and the MCP server loads — the
@@ -229,8 +231,11 @@ export namespace ITtscGraphDump {
    */
   export interface INode extends Omit<
     ITtscGraphNode,
-    "evidence" | "implementation"
+    "evidence" | "implementation" | "kind"
   > {
+    /** Declaration kind written by the native producer. */
+    kind: TtscGraphDumpNodeKind;
+
     /** Declaration span; its file is this node's `file`. */
     evidence?: ITtscGraphSpan;
 
@@ -246,7 +251,10 @@ export namespace ITtscGraphDump {
    * names — the id is `path#Qualified.Name:kind` — so the path rode the wire a
    * second time on every edge, and edges outnumber nodes several times over.
    */
-  export interface IEdge extends Omit<ITtscGraphEdge, "evidence"> {
+  export interface IEdge extends Omit<ITtscGraphEdge, "evidence" | "kind"> {
+    /** Relationship kind written by the native producer. */
+    kind: TtscGraphDumpEdgeKind;
+
     /** Expression span; its file is the one embedded in `from`. */
     evidence?: ITtscGraphSpan;
   }

package/src/structures/ITtscGraphNode.ts

@@ -4,8 +4,7 @@ import { TtscGraphNodeKind } from "./TtscGraphNodeKind";
 import { TtscGraphNodeModifier } from "./TtscGraphNodeModifier";
 
 /**
- * One node in the graph: a declared symbol or a structural container (file,
- * package).
+ * One node in the graph: a declared symbol or a synthesized file container.
  *
  * The `id` is position-invariant: `path#qualifiedName:kind` (e.g.
  * `src/order.ts#OrderService.create:method`), so inserting a line above a

package/src/structures/ITtscGraphSnapshot.ts

@@ -44,11 +44,52 @@ export interface ITtscGraphSnapshot {
   /** The snapshot, present exactly when `changed` is true. */
   dump?: ITtscGraphDump;
 
+  /** Native graph-shard transaction, present for an opted-in changed request. */
+  snapshot?: ITtscGraphSnapshot.ITransaction;
+
   /** Set when the request produced no snapshot; `mode` is then `"error"`. */
   error?: string;
 }
 
 export namespace ITtscGraphSnapshot {
+  /** Versioned content-addressed transaction emitted by `ttscgraph serve`. */
+  export interface ITransaction {
+    protocolVersion: number;
+    schemaVersion: number;
+    project: string;
+    tsconfig: string;
+    producer: ITtscGraphDump.IProducer;
+    capabilities: string[];
+    universe: ITtscGraphDump.IUniverse;
+    sequence: number;
+    generation: string;
+    baseSequence?: number;
+    baseGeneration?: string;
+    upserts: IShardUpsert[];
+    deletes: string[];
+    manifest: IShardReference[];
+  }
+
+  export interface IShardUpsert {
+    digest: string;
+    shard: IShard;
+  }
+
+  export interface IShardReference {
+    key: string;
+    digest: string;
+  }
+
+  /** One source/config or metadata-owned raw compiler fact shard. */
+  export interface IShard {
+    key: string;
+    source?: ITtscGraphDump.ISourceDigest;
+    config?: ITtscGraphDump.IFileDigest;
+    nodes: ITtscGraphDump.INode[];
+    edges: ITtscGraphDump.IEdge[];
+    diagnostics: ITtscGraphDump.IDiagnostic[];
+  }
+
   /**
    * The computation modes the producer reports, plus the transport's `error`.
    *
@@ -56,7 +97,7 @@ export namespace ITtscGraphSnapshot {
    * - `reload`: the build universe moved, so the program was reloaded whole.
    * - `unchanged`: nothing moved; no dump rides it and the last one still holds.
    * - `incremental`: edits applied onto the reused resident program.
-   * - `rebuild`: edits applied, but the program could not be reused.
+   * - `rebuild`: edits applied, but graph projection required a complete build.
    * - `error`: no snapshot was produced.
    */
   export type Mode =

package/src/structures/TtscGraphDumpEdgeKind.ts

@@ -0,0 +1,11 @@
+/** Relationship kinds the native Go dump producer can write. */
+export type TtscGraphDumpEdgeKind =
+  | "exports"
+  | "calls"
+  | "accesses"
+  | "instantiates"
+  | "type_ref"
+  | "extends"
+  | "implements"
+  | "overrides"
+  | "renders";

package/src/structures/TtscGraphDumpNodeKind.ts

@@ -0,0 +1,10 @@
+/** Declaration kinds the native Go dump producer can write. */
+export type TtscGraphDumpNodeKind =
+  | "module"
+  | "function"
+  | "class"
+  | "interface"
+  | "type"
+  | "enum"
+  | "variable"
+  | "method";

package/src/structures/TtscGraphEdgeKind.ts

@@ -1,22 +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`,
+ * Structural `exports` edges come from the native declaration pass, while the
+ * TypeScript memory layer synthesizes `contains` ownership. 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.
+ * — `renders` is a JSX component use. Decorators are facts on their target node,
+ * not edges.
  *
  * `dispatches` is the runtime counterpart of `overrides`/`implements`: the
  * checker resolves a call to the declaration it names, and where that
  * declaration is abstract or an interface member, the code that runs is its
  * implementation. It carries the implementation's declaration span, and a
- * traversal that follows what executes emits it in place of the dead end.
+ * traversal that follows what executes emits it in place of the dead end. It is
+ * trace-only and never appears in a native dump.
  */
 export type TtscGraphEdgeKind =
   | "contains"
   | "exports"
-  | "imports"
   | "calls"
   | "accesses"
   | "instantiates"
@@ -25,6 +26,4 @@ export type TtscGraphEdgeKind =
   | "implements"
   | "overrides"
   | "dispatches"
-  | "decorates"
-  | "renders"
-  | "tests";
+  | "renders";

package/src/structures/TtscGraphNodeKind.ts

@@ -1,19 +1,15 @@
 /**
  * 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 walking into the dependency's
- * internals.
+ * The native builder emits declaration kinds from `module` through `method`.
+ * The TypeScript memory layer replaces each module with a `file` container and
+ * refines class/interface member variables to `property`. An external boundary
+ * leaf keeps its real declaration kind and sets `external: true`.
  *
  * Used as the `kind` discriminant on {@link ITtscGraphNode}.
  */
 export type TtscGraphNodeKind =
   | "file"
-  | "package"
-  | "namespace"
-  | "module"
   | "function"
   | "class"
   | "interface"
@@ -21,6 +17,4 @@ export type TtscGraphNodeKind =
   | "enum"
   | "variable"
   | "method"
-  | "property"
-  | "parameter"
-  | "external_symbol";
+  | "property";

package/src/structures/TtscGraphNodeModifier.ts

@@ -15,5 +15,4 @@ export type TtscGraphNodeModifier =
   | "const"
   | "public"
   | "private"
-  | "protected"
-  | "optional";
+  | "protected";

package/src/structures/index.ts

@@ -21,5 +21,7 @@ export * from "./ITtscGraphSnapshot";
 export * from "./ITtscGraphSpan";
 export * from "./ITtscGraphTour";
 export * from "./TtscGraphEdgeKind";
+export * from "./TtscGraphDumpEdgeKind";
+export * from "./TtscGraphDumpNodeKind";
 export * from "./TtscGraphNodeKind";
 export * from "./TtscGraphNodeModifier";

package/src/view.ts

@@ -10,7 +10,7 @@ import {
   projectOptions,
 } from "./launcherArgs";
 import { parseDump } from "./model/loadGraph";
-import { ensureExecutable } from "./nativeExecutable";
+import { captureProcessOutput, ensureExecutable } from "./nativeExecutable";
 import { reduce } from "./reduce";
 import { resolveGraphBinary } from "./resolveGraphBinary";
 
@@ -70,11 +70,25 @@ export function runView(argv: readonly string[]): number | void {
   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 },
-  );
+  // The dump goes to a file rather than a pipe, so no output ceiling applies.
+  const capture = captureProcessOutput();
+  let dump;
+  let dumpStdout: string;
+  let dumpStderr: string;
+  try {
+    dump = spawnSync(
+      binary,
+      ["dump", "--cwd", opts.cwd, "--tsconfig", opts.tsconfig],
+      {
+        stdio: ["ignore", capture.stdoutFd, capture.stderrFd],
+        windowsHide: true,
+      },
+    );
+    dumpStdout = capture.read("stdout");
+    dumpStderr = capture.read("stderr");
+  } finally {
+    capture.dispose();
+  }
   if (dump.error) {
     process.stderr.write(`@ttsc/graph: ${dump.error.message}\n`);
     return 1;
@@ -86,7 +100,7 @@ export function runView(argv: readonly string[]): number | void {
 
   let raw: ReturnType<typeof parseDump>;
   try {
-    raw = parseDump(dump.stdout);
+    raw = parseDump(dumpStdout);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     process.stderr.write(