@ttsc/graph 0.19.2 → 0.20.0

package/lib/structures/ITtscGraphDump.d.ts

@@ -12,18 +12,18 @@ 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. */
     provenance: ITtscGraphDump.IProvenance;
@@ -126,14 +126,14 @@ export declare namespace ITtscGraphDump {
     }
     /** A root file attributed to the config that named it. */
     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. */
     interface IFileDigest {
-        /** Project-relative. */
+        /** In the dump's path vocabulary. */
         file: string;
         /** Hex-encoded SHA-256. */
         digest: string;
@@ -148,7 +148,7 @@ export declare namespace ITtscGraphDump {
      * on every build.
      */
     interface ISourceDigest {
-        /** Project-relative. */
+        /** In the dump's path vocabulary. */
         file: string;
         /**
          * Hex-encoded SHA-256 of the text the checker resolved against — the ground
@@ -175,7 +175,7 @@ export declare namespace ITtscGraphDump {
     }
     /** One compiler diagnostic from the generation that produced the facts. */
     interface IDiagnostic {
-        /** Project-relative. */
+        /** In the dump's path vocabulary. */
         file: string;
         /** 1-based line. */
         line: number;

package/lib/structures/ITtscGraphNode.d.ts

@@ -52,11 +52,58 @@ export interface ITtscGraphNode {
     closure?: boolean;
     /** 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;
     /**
@@ -65,3 +112,27 @@ export interface ITtscGraphNode {
      */
     implementation?: ITtscGraphEvidence;
 }
+export declare namespace ITtscGraphNode {
+    /** One member of an enum: the name a caller writes and the value it carries. */
+    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. */
+    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/lib/structures/ITtscGraphTour.d.ts

@@ -56,7 +56,7 @@ export declare 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/lib/structures/ITtscGraphTrace.d.ts

@@ -11,7 +11,7 @@ export interface ITtscGraphTrace {
     hops: ITtscGraphTrace.IHop[];
     /** 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. */
     target?: ITtscGraphTrace.INode;

package/lib/view.js

@@ -8,39 +8,29 @@ const node_child_process_1 = require("node:child_process");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_http_1 = __importDefault(require("node:http"));
 const node_path_1 = __importDefault(require("node:path"));
+const launcherArgs_1 = require("./launcherArgs");
 const nativeExecutable_1 = require("./nativeExecutable");
 const reduce_1 = require("./reduce");
 const resolveGraphBinary_1 = require("./resolveGraphBinary");
 function parseViewArgs(argv) {
-    const opts = {
-        cwd: process.cwd(),
-        tsconfig: "tsconfig.json",
-        port: 0,
-        open: true,
-        maxNodes: 1200,
+    const values = (0, launcherArgs_1.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 = (0, launcherArgs_1.projectOptions)(values);
+    return {
+        ...project,
+        port: values.has("port") === true
+            ? (0, launcherArgs_1.nonNegativeIntegerOption)(values, "port", 65535)
+            : 0,
+        open: values.get("open") !== true,
+        maxNodes: values.has("max_nodes") === true
+            ? (0, launcherArgs_1.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;
 }
 /**
  * `ttsc-graph view`: build the project's code graph, reduce it, and serve a

package/lib/view.js.map

@@ -1 +1 @@
-{"version":3,"file":"view.js","sourceRoot":"","sources":["../src/view.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"view.js","sourceRoot":"","sources":["../src/view.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/graph",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "description": "Checker-resolved architecture graph over MCP for coding agents, backed by ttsc's in-process TypeScript-Go compiler.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -16,8 +16,11 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@typia/mcp": "13.1.0",
-    "typia": "13.1.0"
+    "@typia/mcp": "13.2.0",
+    "typia": "13.2.0"
+  },
+  "peerDependencies": {
+    "ttsc": "^0.20.0"
   },
   "keywords": [
     "ttsc",
@@ -39,7 +42,7 @@
     "three": "^0.184.0",
     "three-forcegraph": "^1.43.4",
     "typescript": "^7.0.2",
-    "ttsc": "0.19.2"
+    "ttsc": "0.20.0"
   },
   "repository": {
     "type": "git",

package/src/TtscGraphApplication.ts

@@ -1,6 +1,8 @@
 import { TtscGraphMemory } from "./model/TtscGraphMemory";
 import {
   RESULT_AUDIT,
+  RESULT_AUDIT_DETAILS,
+  RESULT_AUDIT_DETAILS_CAPPED,
   RESULT_AUDIT_ESCAPE,
   RESULT_AUDIT_SELECTION,
 } from "./server/resultAudit";
@@ -90,9 +92,14 @@ export class TtscGraphApplication implements ITtscGraphApplication {
         };
       }
       case "details": {
+        // details' identity is complete and its fan-out is a slice, which is
+        // not the walk-bounded-and-marked shape RESULT_AUDIT states.
         const r = runDetails(graph, props.request);
         return {
-          audit: RESULT_AUDIT,
+          audit:
+            r.membersCapped === true
+              ? RESULT_AUDIT_DETAILS_CAPPED
+              : RESULT_AUDIT_DETAILS,
           next: r.next,
           result: r.result,
         };

package/src/bin.ts

@@ -1,8 +1,18 @@
 #!/usr/bin/env node
 
 import { runGraph } from "./index";
+import { GraphArgumentError } from "./launcherArgs";
 
-const code = runGraph(process.argv.slice(2));
-if (typeof code === "number") {
-  process.exitCode = code;
+try {
+  const code = runGraph(process.argv.slice(2));
+  if (typeof code === "number") {
+    process.exitCode = code;
+  }
+} catch (error) {
+  if (error instanceof GraphArgumentError) {
+    process.stderr.write(`@ttsc/graph: ${error.message}\n`);
+    process.exitCode = 2;
+  } else {
+    throw error;
+  }
 }

package/src/index.ts

@@ -1,6 +1,10 @@
 import { spawnSync } from "node:child_process";
-import path from "node:path";
 
+import {
+  PROJECT_OPTIONS,
+  parseLauncherOptions,
+  projectOptions,
+} from "./launcherArgs";
 import { ensureExecutable } from "./nativeExecutable";
 import { resolveGraphBinary } from "./resolveGraphBinary";
 import { startServer } from "./server/startServer";
@@ -9,6 +13,8 @@ import { runView } from "./view";
 /** What a graph result says about where its facts came from. */
 export {
   RESULT_AUDIT,
+  RESULT_AUDIT_DETAILS,
+  RESULT_AUDIT_DETAILS_CAPPED,
   RESULT_AUDIT_ESCAPE,
   RESULT_AUDIT_SELECTION,
 } from "./server/resultAudit";
@@ -18,34 +24,34 @@ export {
 // project other than its own process directory names it once and the binary is
 // found under that project's installed `ttsc`.
 export { resolveGraphBinary } from "./resolveGraphBinary";
+/**
+ * The viewer reduction the `view` command runs before serving a payload.
+ *
+ * Exported because it is one of three copies of the same pure transform — the
+ * website's uploaded-dump viewer and the benchmark viewer hold the others — and
+ * a shared policy that cannot be measured from outside the package drifts. It
+ * already did: two of them filtered git-ignored generated code and this one did
+ * not.
+ */
+export { reduce } from "./reduce";
+export type { RawDump, RawEdge, RawNode, ViewerPayload } from "./reduce";
 export { loadGraph } from "./model/loadGraph";
-export { TtscGraphSession } from "./model/TtscGraphSession";
+export {
+  TtscGraphSession,
+  type TtscGraphRequestOptions,
+  type TtscGraphSessionOptions,
+} from "./model/TtscGraphSession";
 
 // The server version reported in the MCP handshake; read from this package.
 const VERSION: string = (require("../package.json") as { version: string })
   .version;
 
-/**
- * The project root and tsconfig to build the graph for, from the `--cwd` /
- * `--tsconfig` flags (the same ones `ttscgraph dump` accepts). Defaults are the
- * process working directory and `tsconfig.json`.
- */
-function parseProjectArgs(argv: readonly string[]): {
-  cwd: string;
-  tsconfig: string;
-} {
-  let cwd = process.cwd();
-  let tsconfig = "tsconfig.json";
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i]!;
-    if (arg === "--cwd" && i + 1 < argv.length) cwd = argv[++i]!;
-    else if (arg.startsWith("--cwd=")) cwd = arg.slice("--cwd=".length);
-    else if (arg === "--tsconfig" && i + 1 < argv.length) tsconfig = argv[++i]!;
-    else if (arg.startsWith("--tsconfig="))
-      tsconfig = arg.slice("--tsconfig=".length);
-  }
-  return { cwd: path.resolve(cwd), tsconfig };
-}
+const DUMP_OPTIONS = [
+  { key: "cwd", flags: ["--cwd", "-cwd"], kind: "value" },
+  { key: "tsconfig", flags: ["--tsconfig", "-tsconfig"], kind: "value" },
+  { key: "pretty", flags: ["--pretty", "-pretty"], kind: "boolean" },
+  { key: "help", flags: ["--help", "-help", "-h"], kind: "flag" },
+] as const;
 
 /**
  * Run the `@ttsc/graph` launcher.
@@ -62,9 +68,11 @@ export function runGraph(
   argv: readonly string[] = process.argv.slice(2),
 ): number | void {
   if (argv[0] === "view") return runView(argv.slice(1));
-  if (argv[0] === "dump") return runDump(argv);
+  if (argv[0] === "dump") return runDump(argv.slice(1));
 
-  const { cwd, tsconfig } = parseProjectArgs(argv);
+  const { cwd, tsconfig } = projectOptions(
+    parseLauncherOptions(argv, PROJECT_OPTIONS),
+  );
   void startServer({ cwd, tsconfig, version: VERSION }).catch(
     (error: unknown) => {
       process.stderr.write(
@@ -82,7 +90,7 @@ export function runGraph(
 function runDump(argv: readonly string[]): number {
   // Resolve the native binary from the target project the caller named with
   // `--cwd`, not from wherever the launcher process happened to start.
-  const { cwd } = parseProjectArgs(argv);
+  const { cwd } = projectOptions(parseLauncherOptions(argv, DUMP_OPTIONS));
   const binary = resolveGraphBinary(process.env, cwd);
   if (binary === null) {
     process.stderr.write(
@@ -93,7 +101,7 @@ function runDump(argv: readonly string[]): number {
     return 1;
   }
   ensureExecutable(binary);
-  const result = spawnSync(binary, [...argv], {
+  const result = spawnSync(binary, ["dump", ...argv], {
     stdio: "inherit",
     windowsHide: true,
   });

package/src/launcherArgs.ts

@@ -0,0 +1,168 @@
+import path from "node:path";
+
+export class GraphArgumentError extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = "GraphArgumentError";
+  }
+}
+
+type OptionKind = "value" | "flag" | "boolean";
+
+export interface ILauncherOption {
+  key: string;
+  flags: readonly string[];
+  kind: OptionKind;
+}
+
+export type ParsedLauncherOptions = ReadonlyMap<string, string | boolean>;
+
+export interface IProjectOptions {
+  cwd: string;
+  tsconfig: string;
+}
+
+export const PROJECT_OPTIONS: readonly ILauncherOption[] = [
+  { key: "cwd", flags: ["--cwd"], kind: "value" },
+  { key: "tsconfig", flags: ["--tsconfig"], kind: "value" },
+];
+
+/** Parse one complete launcher argument vector and reject every unknown token. */
+export function parseLauncherOptions(
+  argv: readonly string[],
+  definitions: readonly ILauncherOption[],
+): ParsedLauncherOptions {
+  const flags = new Map<string, ILauncherOption>();
+  for (const definition of definitions) {
+    for (const flag of definition.flags) flags.set(flag, definition);
+  }
+
+  const parsed = new Map<string, string | boolean>();
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    const exact = flags.get(arg);
+    if (exact !== undefined) {
+      if (exact.kind === "value") {
+        const value = argv[++i];
+        if (value === undefined || value.startsWith("-")) {
+          throw new GraphArgumentError(`${arg} requires a non-empty value`);
+        }
+        parsed.set(exact.key, requireValue(arg, value));
+      } else {
+        parsed.set(exact.key, true);
+      }
+      continue;
+    }
+
+    const equals = findEqualsOption(arg, flags);
+    if (equals === undefined) {
+      throw new GraphArgumentError(`unknown option ${arg}`);
+    }
+    const { definition, flag, value } = equals;
+    if (definition.kind === "flag") {
+      throw new GraphArgumentError(`${flag} does not take a value`);
+    }
+    if (definition.kind === "boolean") {
+      parsed.set(definition.key, parseBoolean(flag, value));
+    } else {
+      parsed.set(definition.key, requireValue(flag, value));
+    }
+  }
+  return parsed;
+}
+
+/** Resolve the two project-selection values shared by every launcher lane. */
+export function projectOptions(values: ParsedLauncherOptions): IProjectOptions {
+  return {
+    cwd: path.resolve(stringValue(values, "cwd") ?? process.cwd()),
+    tsconfig: stringValue(values, "tsconfig") ?? "tsconfig.json",
+  };
+}
+
+/** Read a bounded non-negative integer option without JavaScript coercion. */
+export function nonNegativeIntegerOption(
+  values: ParsedLauncherOptions,
+  key: string,
+  maximum: number,
+): number {
+  const value = stringValue(values, key);
+  if (value === undefined) {
+    throw new Error(`Missing required parsed option ${key}`);
+  }
+  if (!/^\d+$/.test(value)) {
+    throw new GraphArgumentError(`${optionName(key)} must be an integer`);
+  }
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number > maximum) {
+    throw new GraphArgumentError(
+      `${optionName(key)} must be between 0 and ${maximum}`,
+    );
+  }
+  return number;
+}
+
+/** Read a bounded positive integer option without JavaScript coercion. */
+export function positiveIntegerOption(
+  values: ParsedLauncherOptions,
+  key: string,
+  maximum: number,
+): number {
+  const value = nonNegativeIntegerOption(values, key, maximum);
+  if (value === 0) {
+    throw new GraphArgumentError(`${optionName(key)} must be greater than 0`);
+  }
+  return value;
+}
+
+function findEqualsOption(
+  arg: string,
+  flags: ReadonlyMap<string, ILauncherOption>,
+): { definition: ILauncherOption; flag: string; value: string } | undefined {
+  for (const [flag, definition] of flags) {
+    const prefix = `${flag}=`;
+    if (arg.startsWith(prefix)) {
+      return { definition, flag, value: arg.slice(prefix.length) };
+    }
+  }
+  return undefined;
+}
+
+function requireValue(flag: string, value: string): string {
+  if (value.trim() === "") {
+    throw new GraphArgumentError(`${flag} requires a non-empty value`);
+  }
+  return value;
+}
+
+function parseBoolean(flag: string, value: string): boolean {
+  switch (value) {
+    case "1":
+    case "t":
+    case "T":
+    case "TRUE":
+    case "true":
+    case "True":
+      return true;
+    case "0":
+    case "f":
+    case "F":
+    case "FALSE":
+    case "false":
+    case "False":
+      return false;
+    default:
+      throw new GraphArgumentError(`${flag} requires a boolean value`);
+  }
+}
+
+function stringValue(
+  values: ParsedLauncherOptions,
+  key: string,
+): string | undefined {
+  const value = values.get(key);
+  return typeof value === "string" ? value : undefined;
+}
+
+function optionName(key: string): string {
+  return `--${key.replaceAll("_", "-")}`;
+}