@ttsc/graph 0.23.0 → 0.25.0

package/src/model/TtscGraphShardStore.ts

@@ -0,0 +1,371 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+
+import { ITtscGraphDump } from "../structures/ITtscGraphDump";
+import { ITtscGraphSnapshot } from "../structures/ITtscGraphSnapshot";
+import { DUMP_SCHEMA_VERSION } from "./loadGraph";
+
+/** Atomic validator and assembler for native `ttscgraph` shard transactions. */
+export class TtscGraphShardStore {
+  static readonly PROTOCOL_VERSION = 1;
+
+  private sequence: number | undefined;
+  private generation: string | undefined;
+  private project: string | undefined;
+  private tsconfig: string | undefined;
+  private shards = new Map<
+    string,
+    { digest: string; shard: ITtscGraphSnapshot.IShard }
+  >();
+
+  /** Validate and atomically commit one complete or base-generation delta. */
+  apply(transaction: ITtscGraphSnapshot.ITransaction): ITtscGraphDump {
+    this.assertCoordinates(transaction);
+    const next = new Map(this.shards);
+    const touched = new Set<string>();
+    for (const key of transaction.deletes) {
+      assertShardKey(key);
+      if (touched.has(key)) {
+        throw new Error(`@ttsc/graph: native transaction repeats shard ${key}`);
+      }
+      touched.add(key);
+      if (!next.delete(key)) {
+        throw new Error(
+          `@ttsc/graph: native transaction deletes unknown shard ${key}`,
+        );
+      }
+    }
+    for (const upsert of transaction.upserts) {
+      assertShardKey(upsert.shard.key);
+      if (touched.has(upsert.shard.key)) {
+        throw new Error(
+          `@ttsc/graph: native transaction touches shard ${upsert.shard.key} more than once`,
+        );
+      }
+      touched.add(upsert.shard.key);
+      const digest = TtscGraphShardStore.shardDigest(upsert.shard);
+      if (digest !== upsert.digest) {
+        throw new Error(
+          `@ttsc/graph: native shard ${upsert.shard.key} digest ${upsert.digest} does not match ${digest}`,
+        );
+      }
+      next.set(upsert.shard.key, { digest, shard: upsert.shard });
+    }
+
+    const manifest = [...transaction.manifest];
+    for (let index = 0; index < manifest.length; index++) {
+      const reference = manifest[index]!;
+      if (
+        index !== 0 &&
+        compareText(manifest[index - 1]!.key, reference.key) >= 0
+      ) {
+        throw new Error(
+          "@ttsc/graph: native shard manifest must be strictly key-sorted",
+        );
+      }
+    }
+    if (manifest.length !== next.size) {
+      throw new Error(
+        "@ttsc/graph: native shard manifest does not describe the reconstructed generation",
+      );
+    }
+    for (const reference of manifest) {
+      assertShardKey(reference.key);
+      const committed = next.get(reference.key);
+      if (committed === undefined || committed.digest !== reference.digest) {
+        throw new Error(
+          `@ttsc/graph: native shard manifest disagrees at ${reference.key}`,
+        );
+      }
+    }
+    const generation = digest({
+      tsconfig: transaction.tsconfig,
+      producer: transaction.producer,
+      capabilities: transaction.capabilities,
+      universe: transaction.universe,
+      manifest,
+    });
+    if (generation !== transaction.generation) {
+      throw new Error(
+        `@ttsc/graph: native generation ${transaction.generation} does not match ${generation}`,
+      );
+    }
+
+    const dump = assemble(transaction, next);
+    this.sequence = transaction.sequence;
+    this.generation = transaction.generation;
+    this.project = transaction.project;
+    this.tsconfig = transaction.tsconfig;
+    this.shards = next;
+    return dump;
+  }
+
+  /** SHA-256 over the producer's deterministic Go JSON encoding. */
+  static shardDigest(shard: ITtscGraphSnapshot.IShard): string {
+    return digest(shard);
+  }
+
+  private assertCoordinates(
+    transaction: ITtscGraphSnapshot.ITransaction,
+  ): void {
+    if (transaction.protocolVersion !== TtscGraphShardStore.PROTOCOL_VERSION) {
+      throw new Error(
+        `@ttsc/graph: ttscgraph sends graph snapshot protocol v${String(transaction.protocolVersion)}, this client reads v${String(TtscGraphShardStore.PROTOCOL_VERSION)}`,
+      );
+    }
+    if (transaction.schemaVersion !== DUMP_SCHEMA_VERSION) {
+      throw new Error(
+        `@ttsc/graph: ttscgraph sends dump schema v${String(transaction.schemaVersion)}, this client reads v${String(DUMP_SCHEMA_VERSION)}`,
+      );
+    }
+    if (
+      !Number.isSafeInteger(transaction.sequence) ||
+      transaction.sequence < 1
+    ) {
+      throw new Error("@ttsc/graph: native transaction sequence is invalid");
+    }
+    if (transaction.generation === "") {
+      throw new Error("@ttsc/graph: native transaction generation is empty");
+    }
+    if (this.sequence === undefined || this.generation === undefined) {
+      if (
+        transaction.sequence !== 1 ||
+        transaction.baseSequence !== undefined ||
+        transaction.baseGeneration !== undefined ||
+        transaction.deletes.length !== 0
+      ) {
+        throw new Error(
+          "@ttsc/graph: initial native transaction is not a complete generation",
+        );
+      }
+      return;
+    }
+    if (
+      transaction.sequence !== this.sequence + 1 ||
+      transaction.baseSequence !== this.sequence ||
+      transaction.baseGeneration !== this.generation
+    ) {
+      throw new Error(
+        `@ttsc/graph: native transaction has stale base ${String(transaction.baseSequence)}/${String(transaction.baseGeneration)}`,
+      );
+    }
+    if (
+      transaction.project !== this.project ||
+      transaction.tsconfig !== this.tsconfig
+    ) {
+      throw new Error(
+        "@ttsc/graph: native transaction changed its resident project coordinates",
+      );
+    }
+  }
+}
+
+function assemble(
+  transaction: ITtscGraphSnapshot.ITransaction,
+  committed: ReadonlyMap<
+    string,
+    { digest: string; shard: ITtscGraphSnapshot.IShard }
+  >,
+): ITtscGraphDump {
+  const nodes: ITtscGraphDump.INode[] = [];
+  const edges: ITtscGraphDump.IEdge[] = [];
+  const diagnostics: ITtscGraphDump.IDiagnostic[] = [];
+  const sources: ITtscGraphDump.ISourceDigest[] = [];
+  const nodeOwners = new Map<string, string>();
+  const sourceFiles = new Set<string>();
+  const configInputs = new Map<string, string>();
+  for (const [key, value] of committed) {
+    const shard = value.shard;
+    if (shard.key !== key) {
+      throw new Error(`@ttsc/graph: native shard key disagrees at ${key}`);
+    }
+    if (shard.source !== undefined && shard.config !== undefined) {
+      throw new Error(
+        `@ttsc/graph: native shard ${key} claims both source and config input`,
+      );
+    }
+    if (
+      shard.config !== undefined &&
+      (shard.nodes.length !== 0 || shard.edges.length !== 0)
+    ) {
+      throw new Error(
+        `@ttsc/graph: native config shard ${key} unexpectedly owns facts`,
+      );
+    }
+    if (shard.config !== undefined) {
+      if (configInputs.has(shard.config.file)) {
+        throw new Error(
+          `@ttsc/graph: native config ${shard.config.file} has more than one shard`,
+        );
+      }
+      configInputs.set(shard.config.file, shard.config.digest);
+    }
+    if (shard.source !== undefined) {
+      if (sourceFiles.has(shard.source.file)) {
+        throw new Error(
+          `@ttsc/graph: native source ${shard.source.file} has more than one shard`,
+        );
+      }
+      sourceFiles.add(shard.source.file);
+      sources.push({ ...shard.source });
+    }
+    assertShardContents(key, shard);
+    for (const node of shard.nodes) {
+      const owner = nodeOwners.get(node.id);
+      if (owner !== undefined) {
+        throw new Error(
+          `@ttsc/graph: native node ${node.id} is owned by both ${owner} and ${key}`,
+        );
+      }
+      nodeOwners.set(node.id, key);
+      nodes.push(node);
+    }
+    edges.push(...shard.edges);
+    diagnostics.push(...shard.diagnostics);
+  }
+  for (const [key, value] of committed) {
+    for (const edge of value.shard.edges) {
+      if (nodeOwners.get(edge.from) !== key) {
+        throw new Error(
+          `@ttsc/graph: native shard ${key} does not own edge source ${edge.from}`,
+        );
+      }
+      if (!nodeOwners.has(edge.to)) {
+        throw new Error(
+          `@ttsc/graph: native edge target is absent from the generation: ${edge.to}`,
+        );
+      }
+    }
+  }
+  const unmatchedConfigs = new Map(configInputs);
+  for (const config of transaction.universe.configs) {
+    if (
+      unmatchedConfigs.get(config.file) !== config.digest ||
+      !unmatchedConfigs.delete(config.file)
+    ) {
+      throw new Error(
+        `@ttsc/graph: native config shard disagrees with universe input ${config.file}`,
+      );
+    }
+  }
+  if (unmatchedConfigs.size !== 0) {
+    throw new Error(
+      "@ttsc/graph: native config shards do not cover the build universe",
+    );
+  }
+  nodes.sort((left, right) => compareText(left.id, right.id));
+  edges.sort(
+    (left, right) =>
+      compareText(left.from, right.from) ||
+      compareText(left.to, right.to) ||
+      compareText(left.kind, right.kind),
+  );
+  diagnostics.sort(
+    (left, right) =>
+      compareText(left.file, right.file) ||
+      left.line - right.line ||
+      left.column - right.column ||
+      left.code - right.code,
+  );
+  sources.sort((left, right) => compareText(left.file, right.file));
+  return {
+    project: transaction.project,
+    tsconfig: transaction.tsconfig,
+    provenance: {
+      schemaVersion: transaction.schemaVersion,
+      capabilities: [...transaction.capabilities],
+      producer: { ...transaction.producer },
+      universe: {
+        configs: transaction.universe.configs.map((config) => ({ ...config })),
+        roots: transaction.universe.roots.map((root) => ({ ...root })),
+      },
+      sources,
+    },
+    diagnostics,
+    nodes,
+    edges,
+  };
+}
+
+function assertShardContents(
+  key: string,
+  shard: ITtscGraphSnapshot.IShard,
+): void {
+  if (shard.source !== undefined) {
+    for (const node of shard.nodes) {
+      if (node.external || node.file !== shard.source.file) {
+        throw new Error(
+          `@ttsc/graph: native source shard ${key} owns node ${node.id} from ${node.file}`,
+        );
+      }
+    }
+    for (const diagnostic of shard.diagnostics) {
+      if (diagnostic.file !== shard.source.file) {
+        throw new Error(
+          `@ttsc/graph: native source shard ${key} owns diagnostic from ${diagnostic.file}`,
+        );
+      }
+    }
+    return;
+  }
+  if (shard.edges.length !== 0) {
+    throw new Error(
+      `@ttsc/graph: native non-source shard ${key} unexpectedly owns edges`,
+    );
+  }
+  if (shard.config !== undefined) {
+    for (const diagnostic of shard.diagnostics) {
+      if (diagnostic.file !== shard.config.file) {
+        throw new Error(
+          `@ttsc/graph: native config shard ${key} owns diagnostic from ${diagnostic.file}`,
+        );
+      }
+    }
+    return;
+  }
+  for (const node of shard.nodes) {
+    if (!node.external) {
+      throw new Error(
+        `@ttsc/graph: native metadata shard ${key} owns authored node ${node.id}`,
+      );
+    }
+  }
+  for (const diagnostic of shard.diagnostics) {
+    if (diagnostic.file !== "") {
+      throw new Error(
+        `@ttsc/graph: native metadata shard ${key} owns diagnostic from ${diagnostic.file}`,
+      );
+    }
+  }
+}
+
+function assertShardKey(key: string): void {
+  if (key === "" || key.includes("\0")) {
+    throw new Error(`@ttsc/graph: native shard key is invalid: ${key}`);
+  }
+}
+
+function compareText(left: string, right: string): number {
+  return Buffer.compare(Buffer.from(left, "utf8"), Buffer.from(right, "utf8"));
+}
+
+function goJSON(value: unknown): string {
+  return JSON.stringify(value).replace(/[<>&\u2028\u2029]/gu, (character) => {
+    switch (character) {
+      case "<":
+        return "\\u003c";
+      case ">":
+        return "\\u003e";
+      case "&":
+        return "\\u0026";
+      case "\u2028":
+        return "\\u2028";
+      default:
+        return "\\u2029";
+    }
+  });
+}
+
+function digest(value: unknown): string {
+  return createHash("sha256").update(goJSON(value)).digest("hex");
+}

package/src/model/loadGraph.ts

@@ -1,16 +1,11 @@
 import { spawnSync } from "node:child_process";
 import typia from "typia";
 
-import { ensureExecutable } from "../nativeExecutable";
+import { captureProcessOutput, ensureExecutable } from "../nativeExecutable";
 import { resolveGraphBinary } from "../resolveGraphBinary";
 import { ITtscGraphDump } from "../structures/ITtscGraphDump";
 import { TtscGraphMemory } from "./TtscGraphMemory";
 
-// A full-project dump is the whole fact graph as one JSON document; a large
-// monorepo runs to many megabytes, well past spawnSync's 1 MiB default, so the
-// buffer is raised to a ceiling no real graph reaches.
-const MAX_DUMP_BYTES = 1024 * 1024 * 1024;
-
 /**
  * The dump schema version this client reads.
  *
@@ -64,11 +59,23 @@ export function loadGraph(
   }
   ensureExecutable(binary);
 
-  const result = spawnSync(
-    binary,
-    ["dump", "--cwd", cwd, "--tsconfig", tsconfig],
-    { encoding: "utf8", maxBuffer: MAX_DUMP_BYTES, windowsHide: true },
-  );
+  // The dump goes to a file rather than a pipe, so no output ceiling applies:
+  // a graph is as large as the repository is, and any limit named here would be
+  // a guess about someone else's monorepo. See `captureProcessOutput`.
+  const capture = captureProcessOutput();
+  let result;
+  let stdout: string;
+  let stderr: string;
+  try {
+    result = spawnSync(binary, ["dump", "--cwd", cwd, "--tsconfig", tsconfig], {
+      stdio: ["ignore", capture.stdoutFd, capture.stderrFd],
+      windowsHide: true,
+    });
+    stdout = capture.read("stdout");
+    stderr = capture.read("stderr");
+  } finally {
+    capture.dispose();
+  }
   if (result.error) {
     throw new Error(
       `@ttsc/graph: ttscgraph dump failed: ${result.error.message}`,
@@ -76,11 +83,11 @@ export function loadGraph(
   }
   if (result.status !== 0) {
     throw new Error(
-      `@ttsc/graph: ttscgraph dump exited with ${result.status}: ${(result.stderr ?? "").trim()}`,
+      `@ttsc/graph: ttscgraph dump exited with ${result.status}: ${stderr.trim()}`,
     );
   }
 
-  return TtscGraphMemory.from(parseDump(result.stdout));
+  return TtscGraphMemory.from(parseDump(stdout));
 }
 
 /**

package/src/nativeExecutable.ts

@@ -1,4 +1,6 @@
 import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 
 /**
  * Ensure a resolved native binary can be executed on POSIX installs.
@@ -22,3 +24,84 @@ export function ensureExecutable(binary: string): void {
     }
   }
 }
+
+export interface CapturedProcessOutput {
+  /** Close the descriptors and remove the backing files. */
+  dispose(): void;
+  /** Read one stream's text. */
+  read(stream: "stdout" | "stderr"): string;
+  stderrFd: number;
+  stdoutFd: number;
+}
+
+/**
+ * A pair of temporary files standing in for a child process's pipes.
+ *
+ * `spawnSync` holds a _piped_ stream in this process's memory and refuses to
+ * keep more than `maxBuffer` bytes, so any piped capture has to name a ceiling
+ * — and a ceiling is a number nobody chose for this machine, deciding that a
+ * large but legitimate graph said too much. Handing the child a file descriptor
+ * instead means the bytes never pass through this heap on their way out of the
+ * child: how much a process may write is the filesystem's business, and that is
+ * the same answer everywhere. Reading the result back still materializes a
+ * string, so V8's own maximum string length remains the outer bound — a
+ * property of the runtime rather than a budget chosen here.
+ */
+export function captureProcessOutput(): CapturedProcessOutput {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), "ttscgraph-spawn-"));
+  const stdoutPath = path.join(directory, "stdout");
+  const stderrPath = path.join(directory, "stderr");
+  const stdoutFd = fs.openSync(stdoutPath, "w+");
+  let stderrFd: number;
+  try {
+    stderrFd = fs.openSync(stderrPath, "w+");
+  } catch (error) {
+    // The first descriptor and the directory are already live, and no caller
+    // ever received a handle to dispose of them.
+    closeQuietly(stdoutFd);
+    removeQuietly(directory);
+    throw error;
+  }
+  return {
+    dispose(): void {
+      closeQuietly(stdoutFd);
+      closeQuietly(stderrFd);
+      removeQuietly(directory);
+    },
+    read(stream): string {
+      const location = stream === "stdout" ? stdoutPath : stderrPath;
+      try {
+        return fs.readFileSync(location, "utf8");
+      } catch {
+        // A spawn that never launched leaves nothing behind.
+        return "";
+      }
+    },
+    stderrFd,
+    stdoutFd,
+  };
+}
+
+/** Close a descriptor, ignoring one that is already closed. */
+function closeQuietly(fd: number): void {
+  try {
+    fs.closeSync(fd);
+  } catch {
+    // Already closed; removing the directory is what reclaims the space.
+  }
+}
+
+/**
+ * Remove the capture directory without letting cleanup replace a result.
+ *
+ * `dispose` runs from a `finally`, so a throw here would surface instead of the
+ * spawn's own outcome — and on Windows a grandchild that inherited the handle
+ * can hold the file long enough to make removal fail.
+ */
+function removeQuietly(directory: string): void {
+  try {
+    fs.rmSync(directory, { force: true, recursive: true });
+  } catch {
+    // Best effort.
+  }
+}

package/src/server/runDetails.ts

@@ -24,13 +24,11 @@ const MAX_NEIGHBORS = 3;
 const DEFAULT_DEPENDENCIES = 2;
 const MAX_DEPENDENCIES = 4;
 // Structural relationships are navigation, not the dependency picture details is for.
-const STRUCTURAL_KINDS = new Set<string>(["contains", "exports", "imports"]);
+const STRUCTURAL_KINDS = new Set<string>(["contains", "exports"]);
 // Kinds whose value is their member outline, not implementation text.
-const CONTAINER_KINDS = new Set<string>([
+const CONTAINER_KINDS = new Set<ITtscGraphNode["kind"]>([
   "class",
   "interface",
-  "namespace",
-  "module",
   "enum",
   "file",
 ]);
@@ -464,16 +462,13 @@ function edgeKindRank(kind: string): number {
     case "accesses":
     case "renders":
       return 2;
-    case "tests":
-      return 3;
     case "overrides":
-    case "decorates":
-      return 4;
+      return 3;
     case "extends":
     case "implements":
-      return 5;
+      return 4;
     case "type_ref":
-      return 6;
+      return 5;
     default:
       return 10;
   }

package/src/server/runEntrypoints.ts

@@ -12,7 +12,7 @@ const MAX_LIMIT = 8;
 const DEFAULT_NEIGHBORS = 0;
 const MAX_NEIGHBORS = 2;
 const MAX_SEEDS = 3;
-const STRUCTURAL_KINDS = new Set<string>(["contains", "exports", "imports"]);
+const STRUCTURAL_KINDS = new Set<string>(["contains", "exports"]);
 
 /**
  * Build the first source-free entrypoints list for a code question. The result
@@ -198,16 +198,13 @@ function edgeKindRank(kind: string): number {
     case "accesses":
     case "renders":
       return 2;
-    case "tests":
-      return 3;
     case "overrides":
-    case "decorates":
-      return 4;
+      return 3;
     case "extends":
     case "implements":
-      return 5;
+      return 4;
     case "type_ref":
-      return 6;
+      return 5;
     default:
       return 10;
   }

package/src/server/runLookup.ts

@@ -260,7 +260,7 @@ function degree(graph: TtscGraphMemory, id: string): number {
 }
 
 function isStructural(kind: string): boolean {
-  return kind === "contains" || kind === "exports" || kind === "imports";
+  return kind === "contains" || kind === "exports";
 }
 
 function isTestFile(file: string): boolean {

package/src/server/runOverview.ts

@@ -5,7 +5,7 @@ import { isPublicApiNoisePath, isSupportPath } from "./pathPolicy";
 import { IRunnerOutput, resultNext } from "./resultNext";
 
 /** Edges that express nesting/packaging, not code dependency. */
-const STRUCTURAL_KINDS = new Set<string>(["contains", "exports", "imports"]);
+const STRUCTURAL_KINDS = new Set<string>(["contains", "exports"]);
 
 /**
  * Project a compact, source-read-free architecture map: counts by kind, folder
@@ -83,8 +83,8 @@ function layers(graph: TtscGraphMemory): ITtscGraphOverview.ILayer[] {
 
 /**
  * The symbols at the center of the dependency graph, ranked by real fan-in and
- * fan-out. Structural `contains`/`exports`/`imports` edges are excluded so the
- * ranking reflects code dependency, not nesting.
+ * fan-out. Structural `contains`/`exports` edges are excluded so the ranking
+ * reflects code dependency, not nesting.
  */
 function hotspots(graph: TtscGraphMemory): ITtscGraphOverview.IHotspot[] {
   const real = (id: string, side: "in" | "out"): number => {

package/src/server/runTour.ts

@@ -49,21 +49,19 @@ const MAX_READ_NEXT = 14;
 const FLOW_OVERLAP = 0.6;
 const TOUR_TRACE_MAX_DEPTH = 6;
 const TOUR_TRACE_MAX_NODES = 18;
-const STRUCTURAL_KINDS = new Set<string>(["contains", "exports", "imports"]);
+const STRUCTURAL_KINDS = new Set<string>(["contains", "exports"]);
 const EXECUTION_KINDS = new Set<string>([
   "calls",
   "instantiates",
   "accesses",
   "renders",
 ]);
-const TOUR_SEED_KINDS = new Set<string>([
+const TOUR_SEED_KINDS = new Set<ITtscGraphNode["kind"]>([
   "class",
   "function",
   "method",
   "property",
   "variable",
-  "module",
-  "namespace",
   "enum",
 ]);
 
@@ -845,11 +843,11 @@ function isTourHop(graph: TtscGraphMemory, hop: ITtscGraphTrace.IHop): boolean {
 // floor makes it a no-op on small graphs that have no genuine hub. The `out <= 1`
 // guard keeps thin pass-throughs out but never prunes a real branching step.
 //
-// The fan-in counted is EXECUTION fan-in. `realDegree` also counts `type_ref`,
-// `extends`, `decorates`, and `tests`, and a widely referenced type or a
-// widely decorated symbol is not a call hub: a `Config` class named in twelve
-// parameter positions and constructed once was read as a hub and cut out of the
-// flow that constructs it. Popularity as a name is not popularity as a call.
+// The fan-in counted is EXECUTION fan-in. `realDegree` also counts `type_ref`
+// and `extends`, and a widely referenced type is not a call hub: a `Config`
+// class named in twelve parameter positions and constructed once was read as a
+// hub and cut out of the flow that constructs it. Popularity as a name is not
+// popularity as a call.
 function isSharedUtility(graph: TtscGraphMemory, id: string): boolean {
   const execution = executionDegree(graph, id);
   return execution.in >= 12 && execution.out <= 1;
@@ -932,11 +930,7 @@ function ownerOf(graph: TtscGraphMemory, id: string): string | undefined {
   for (const edge of graph.incoming(id)) {
     if (edge.kind !== "contains") continue;
     const owner = graph.node(edge.from);
-    if (
-      owner !== undefined &&
-      owner.kind !== "file" &&
-      owner.kind !== "module"
-    ) {
+    if (owner !== undefined && owner.kind !== "file") {
       return owner.id;
     }
   }