@ttsc/graph 0.22.0 → 0.24.0

package/src/model/loadGraph.ts

@@ -96,7 +96,7 @@ export function loadGraph(
  * on disk may be from any build — so the version is the first question to ask
  * of it.
  */
-function parseDump(json: string): ITtscGraphDump {
+export function parseDump(json: string): ITtscGraphDump {
   let value: unknown;
   try {
     value = JSON.parse(json);
@@ -121,5 +121,14 @@ function parseDump(json: string): ITtscGraphDump {
         "project, or from TTSC_GRAPH_BINARY).",
     );
   }
-  return typia.assert<ITtscGraphDump>(value);
+  try {
+    return typia.assert<ITtscGraphDump>(value);
+  } catch (error) {
+    throw new Error(
+      `@ttsc/graph: dump output does not match schema v${String(
+        DUMP_SCHEMA_VERSION,
+      )}: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
 }

package/src/reduce.ts

@@ -62,11 +62,6 @@ function isAbsolute(p: string): boolean {
   return /^(?:[A-Za-z]:)?\//.test(posix(p));
 }
 
-function isWindowsPath(p: string): boolean {
-  const normalized = posix(p);
-  return /^[A-Za-z]:(?:\/|$)/.test(normalized) || normalized.startsWith("//");
-}
-
 function directoryOf(file: string): string {
   const normalized = posix(file).replace(/\/+$/, "");
   const slash = normalized.lastIndexOf("/");
@@ -77,16 +72,13 @@ function directoryOf(file: string): string {
 function commonRoot(directories: string[]): string {
   if (directories.length === 0) return "";
   let parts = posix(directories[0]!).split("/");
-  const caseInsensitive = directories.every(isWindowsPath);
   for (const directory of directories.slice(1)) {
     const other = posix(directory).split("/");
     let i = 0;
     while (
       i < parts.length &&
       i < other.length &&
-      (caseInsensitive
-        ? parts[i]!.toLowerCase() === other[i]!.toLowerCase()
-        : parts[i] === other[i])
+      legacyPathSegmentsEqual(parts, other, i)
     )
       i++;
     parts = parts.slice(0, i);
@@ -95,6 +87,41 @@ function commonRoot(directories: string[]): string {
   return parts.join("/");
 }
 
+function legacyPathSegmentsEqual(
+  left: readonly string[],
+  right: readonly string[],
+  index: number,
+): boolean {
+  const leftVolume = windowsVolumeSegmentCount(left);
+  const rightVolume = windowsVolumeSegmentCount(right);
+  return leftVolume !== 0 && leftVolume === rightVolume && index < leftVolume
+    ? left[index]!.toLowerCase() === right[index]!.toLowerCase()
+    : left[index] === right[index];
+}
+
+function windowsVolumeSegmentCount(parts: readonly string[]): number {
+  if (/^[A-Za-z]:$/.test(parts[0] ?? "")) return 1;
+  return parts[0] === "" &&
+    parts[1] === "" &&
+    parts[2] !== undefined &&
+    parts[2] !== "" &&
+    parts[3] !== undefined &&
+    parts[3] !== ""
+    ? 4
+    : 0;
+}
+
+function legacyPathIsWithin(candidate: string, root: string): boolean {
+  const candidateParts = posix(candidate).split("/");
+  const rootParts = posix(root).split("/");
+  return (
+    rootParts.length <= candidateParts.length &&
+    rootParts.every((_, index) =>
+      legacyPathSegmentsEqual(rootParts, candidateParts, index),
+    )
+  );
+}
+
 // A null root means the dump's paths are already project-relative (the current
 // `ttscgraph dump` contract); they pass through structure-intact.
 function relativize(abs: string, root: string | null): string {
@@ -102,15 +129,7 @@ function relativize(abs: string, root: string | null): string {
   if (root === null) return a;
   const normalizedRoot = posix(root);
   const r = normalizedRoot === "/" ? "/" : normalizedRoot.replace(/\/+$/, "");
-  const caseInsensitive = isWindowsPath(a) && isWindowsPath(r);
-  const comparedPath = caseInsensitive ? a.toLowerCase() : a;
-  const comparedRoot = caseInsensitive ? r.toLowerCase() : r;
-  if (
-    comparedRoot &&
-    (comparedRoot === "/" ||
-      comparedPath === comparedRoot ||
-      comparedPath.startsWith(comparedRoot + "/"))
-  )
+  if (r && (r === "/" || legacyPathIsWithin(a, r)))
     return a.slice(r.length).replace(/^\/+/, "");
   const nm = a.lastIndexOf("node_modules/");
   // A package tail is a deliberate normalization: the same dependency reached

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;
     }
   }

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

@@ -9,8 +9,9 @@ import {
   positiveIntegerOption,
   projectOptions,
 } from "./launcherArgs";
+import { parseDump } from "./model/loadGraph";
 import { ensureExecutable } from "./nativeExecutable";
-import { type RawDump, reduce } from "./reduce";
+import { reduce } from "./reduce";
 import { resolveGraphBinary } from "./resolveGraphBinary";
 
 interface ViewOptions {
@@ -83,12 +84,15 @@ export function runView(argv: readonly string[]): number | void {
     return dump.status ?? 1;
   }
 
-  let raw: RawDump;
+  let raw: ReturnType<typeof parseDump>;
   try {
-    raw = JSON.parse(dump.stdout) as RawDump;
-  } catch (err) {
+    raw = parseDump(dump.stdout);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
     process.stderr.write(
-      `@ttsc/graph: could not parse the graph dump: ${String(err)}\n`,
+      message.startsWith("@ttsc/graph:")
+        ? `${message}\n`
+        : `@ttsc/graph: could not validate the graph dump: ${message}\n`,
     );
     return 1;
   }
@@ -127,10 +131,30 @@ export function runView(argv: readonly string[]): number | void {
     }
   });
 
+  let endpoint = `127.0.0.1:${opts.port}`;
+  let failed = false;
+  server.on("error", (error: NodeJS.ErrnoException) => {
+    if (failed) return;
+    failed = true;
+    const detail =
+      typeof error.code === "string"
+        ? `${error.code}: ${error.message}`
+        : error.message;
+    process.stderr.write(
+      `@ttsc/graph: could not serve the 3D viewer at ${endpoint} (${detail}).\n`,
+    );
+    process.exitCode = 1;
+    if (server.listening) {
+      server.close();
+      server.closeAllConnections?.();
+    }
+  });
   server.listen(opts.port, "127.0.0.1", () => {
+    if (failed) return;
     const address = server.address();
     const port =
       typeof address === "object" && address ? address.port : opts.port;
+    endpoint = `127.0.0.1:${port}`;
     const url = `http://127.0.0.1:${port}/`;
     const counts = payload.counts;
     process.stderr.write(