@ttsc/graph 0.19.2 → 0.20.0

package/src/structures/ITtscGraphDump.ts

@@ -13,19 +13,19 @@ import { ITtscGraphSpan } from "./ITtscGraphSpan";
  * warm model while project inputs stay unchanged; the bundled 3D viewer reduces
  * the same dump.
  *
- * `project` is absolute. Every other path is relative to it — `tsconfig`, and
- * the `file` fields on nodes, edges, diagnostics, and the provenance manifest.
- *
- * Two kinds of path fall outside the project and so cannot be relative to it: a
- * dependency keeps its `node_modules/`-relative tail, which is what makes a
- * dependency leaf readable, and anything else the compiler loaded keeps the
- * identity the compiler gave it — a virtual lib stays `bundled:///…`.
+ * `project` is the producer-local absolute locator. Every identity-bearing path
+ * uses one schema-v6 coordinate relative to it: project files are ordinary
+ * relative paths; same-filesystem siblings use `../` segments; package files
+ * keep their full resolution context (including version/peer-store segments);
+ * and a virtual compiler source stays `bundled:///…`. Raw absolute identities
+ * are never emitted. A source on another drive or UNC share makes the producer
+ * fail unless a future contract supplies a logical root for it.
  */
 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`. */
+  /** The tsconfig the program was loaded from, in the dump's path vocabulary. */
   tsconfig: string;
 
   /** Evidence about the one program that produced everything below. */
@@ -143,16 +143,16 @@ export namespace ITtscGraphDump {
 
   /** A root file attributed to the config that named it. */
   export interface IRootFile {
-    /** The tsconfig that named this root, project-relative. */
+    /** The tsconfig that named this root, in the dump's path vocabulary. */
     config: string;
 
-    /** The root file, project-relative. */
+    /** The root file, in the dump's path vocabulary. */
     file: string;
   }
 
   /** A file and the hex-encoded SHA-256 of its on-disk bytes. */
   export interface IFileDigest {
-    /** Project-relative. */
+    /** In the dump's path vocabulary. */
     file: string;
 
     /** Hex-encoded SHA-256. */
@@ -169,7 +169,7 @@ export namespace ITtscGraphDump {
    * on every build.
    */
   export interface ISourceDigest {
-    /** Project-relative. */
+    /** In the dump's path vocabulary. */
     file: string;
 
     /**
@@ -199,7 +199,7 @@ export namespace ITtscGraphDump {
 
   /** One compiler diagnostic from the generation that produced the facts. */
   export interface IDiagnostic {
-    /** Project-relative. */
+    /** In the dump's path vocabulary. */
     file: string;
 
     /** 1-based line. */

package/src/structures/ITtscGraphNode.ts

@@ -63,12 +63,63 @@ export interface ITtscGraphNode {
   /** Declaration modifiers, when the declaration pass recorded any. */
   modifiers?: TtscGraphNodeModifier[];
 
+  /**
+   * The complete value set of a type alias or enum whose declared type the
+   * checker resolved to literals, each in TypeScript source form (`"a"`, `1`,
+   * `true`, `null`).
+   *
+   * Present only when every constituent is enumerable, so the list is the whole
+   * type and never a sample of it: `type T = Kind | string` admits values no
+   * list can name and carries none. It is resolved from the type, not read off
+   * the declaration, so indirection (`type I = Kind | 'f'`) is followed and the
+   * answer does not depend on how the declaration is wrapped.
+   */
+  literals?: string[];
+
+  /**
+   * What an enum declares, in checker order: the name a caller writes and the
+   * value it carries. Absent on every other kind.
+   *
+   * `literals` says which values the enum admits, which is what a serializer
+   * asks. The code says `Colors.Red`, so the names are the other half, and
+   * without them a caller that had already named the enum still had to open the
+   * file to learn what to type. The members are not nodes — `Colors.Red` is a
+   * string a grep finds exactly — so this fills in the node the graph already
+   * holds instead of minting one per member.
+   */
+  enumMembers?: ITtscGraphNode.IEnumMember[];
+
+  /**
+   * Direct, statically named members when this variable is initialized with an
+   * object literal, in declaration order.
+   *
+   * The native builder takes identity from the compiler AST and renders the
+   * compact signature from the same Program-owned source snapshot. A spread or
+   * dynamic computed name has no declaration name it can report soundly, so it
+   * contributes no fabricated member.
+   */
+  objectMembers?: ITtscGraphNode.IObjectMember[];
+
   /**
    * Decorators written on this declaration, in source order: raw facts
    * (`@Controller`, `@Get`) a consumer interprets without re-parsing source.
    */
   decorators?: ITtscGraphDecorator[];
 
+  /**
+   * The declaration head, cut by the producer where the compiler says the body
+   * opens.
+   *
+   * Absent when the producer could not bound the head, in which case a consumer
+   * falls back to reading the declaration span. That fallback is a line scan,
+   * and a physical line is not a declaration boundary: it leaks implementation
+   * text when a declaration shares its line with its body, and it stops early
+   * when the head itself contains a brace — a type-literal parameter, an object
+   * return type, a destructured parameter. Prefer this field wherever it is
+   * present.
+   */
+  signature?: string;
+
   /** The declaration span, for display and signatures. */
   evidence?: ITtscGraphEvidence;
 
@@ -78,3 +129,32 @@ export interface ITtscGraphNode {
    */
   implementation?: ITtscGraphEvidence;
 }
+export namespace ITtscGraphNode {
+  /** One member of an enum: the name a caller writes and the value it carries. */
+  export interface IEnumMember {
+    /** The member's own name, unqualified (`Red` on `Colors.Red`). */
+    name: string;
+
+    /**
+     * The value it carries, in TypeScript source form (`"red"`, `1`). Absent
+     * for a computed member the checker could not fold to a constant; the name
+     * still stands.
+     */
+    value?: string;
+  }
+
+  /** One direct, statically named member of an object-literal variable. */
+  export interface IObjectMember {
+    /** The source-visible static property name. */
+    name: string;
+
+    /** Whether the declaration is a data property or callable/accessor member. */
+    kind: "property" | "method";
+
+    /** 1-based declaration line in the node's file, when source was available. */
+    line?: number;
+
+    /** Compact declaration outline rendered from the compiler source snapshot. */
+    signature?: string;
+  }
+}

package/src/structures/ITtscGraphTour.ts

@@ -66,7 +66,7 @@ export namespace ITtscGraphTour {
      * Central entrypoints to seed the tour. Raise only when the question names
      * several public paths that must all appear in one answer.
      *
-     * @default 4
+     * @default 5
      */
     limit?: number;
 

package/src/structures/ITtscGraphTrace.ts

@@ -17,7 +17,7 @@ export interface ITtscGraphTrace {
   /** Unique nodes reached (excluding the start), each with its depth and roles. */
   reached: ITtscGraphTrace.INode[];
 
-  /** True when the trace hit its node or depth cap; the returned flow stands. */
+  /** In an open trace, true when a bound omitted an eligible node or hop. */
   truncated: boolean;
 
   /** The resolved `to` target, when a path was requested. */

package/src/view.ts

@@ -3,6 +3,12 @@ import fs from "node:fs";
 import http from "node:http";
 import path from "node:path";
 
+import {
+  nonNegativeIntegerOption,
+  parseLauncherOptions,
+  positiveIntegerOption,
+  projectOptions,
+} from "./launcherArgs";
 import { ensureExecutable } from "./nativeExecutable";
 import { type RawDump, reduce } from "./reduce";
 import { resolveGraphBinary } from "./resolveGraphBinary";
@@ -16,30 +22,26 @@ interface ViewOptions {
 }
 
 function parseViewArgs(argv: readonly string[]): ViewOptions {
-  const opts: ViewOptions = {
-    cwd: process.cwd(),
-    tsconfig: "tsconfig.json",
-    port: 0,
-    open: true,
-    maxNodes: 1200,
+  const values = parseLauncherOptions(argv, [
+    { key: "cwd", flags: ["--cwd"], kind: "value" },
+    { key: "tsconfig", flags: ["--tsconfig", "-p"], kind: "value" },
+    { key: "port", flags: ["--port"], kind: "value" },
+    { key: "open", flags: ["--no-open"], kind: "flag" },
+    { key: "max_nodes", flags: ["--max-nodes"], kind: "value" },
+  ]);
+  const project = projectOptions(values);
+  return {
+    ...project,
+    port:
+      values.has("port") === true
+        ? nonNegativeIntegerOption(values, "port", 65_535)
+        : 0,
+    open: values.get("open") !== true,
+    maxNodes:
+      values.has("max_nodes") === true
+        ? positiveIntegerOption(values, "max_nodes", Number.MAX_SAFE_INTEGER)
+        : 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;
 }
 
 /**