@ttsc/graph 0.31.4 → 0.32.0

package/src/model/loadGraph.ts

@@ -1,6 +1,7 @@
 import typia from "typia";
 
 import { GraphProcessTrace } from "../internal/GraphProcessTrace";
+import { InstalledGraphBinary } from "../internal/InstalledGraphBinary";
 import { captureProcessOutput, ensureExecutable } from "../nativeExecutable";
 import { resolveGraphBinary } from "../resolveGraphBinary";
 import { ITtscGraphDump } from "../structures/ITtscGraphDump";
@@ -34,7 +35,7 @@ export const DUMP_SCHEMA_VERSION = 8;
  * @evidence contracts/common.md#clear-and-simple-design One-shot process execution, capture ownership and parse validation have separate helpers; the resident MCP path remains a different lifetime owner.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed resolution or native execution throws rather than returning an invented empty graph.
  * @evidence contracts/common.md#meaningful-documentation Native paragraphs state direct/viewer usage, project/binary defaults and every externally visible failure boundary.
- * @evidence contracts/portability.md#os-neutral-implementation Native argv carries cwd, tsconfig and artifact paths without a shell; project-anchored binary resolution and permission repair account for host execution differences.
+ * @evidence contracts/portability.md#os-neutral-implementation Native argv carries cwd, tsconfig and artifact paths without a shell; installation-anchored binary resolution and permission repair account for host execution differences.
  * @evidence contracts/performance.md#efficient-algorithms One native dump is followed by linear JSON parsing/validation and model indexing; output is file-backed rather than constrained by a guessed pipe budget.
  * @evidence contracts/performance.md#reuse-equivalent-work Direct loads intentionally build the requested current project anew; callers needing repeated equivalent snapshots use TtscGraphSession's resident producer and model.
  * @evidence contracts/performance.md#bound-retention-and-release-resources The operation owns two capture descriptors until the finally block disposes them; returned graph ownership transfers to the caller, while artifact storage remains process/project scoped.
@@ -49,24 +50,18 @@ export function loadGraph(
 
     /**
      * Absolute path to the `ttscgraph` binary. Defaults to the per-platform
-     * binary resolved from the project's installed `ttsc`; pass it explicitly
-     * to point at a custom build.
+     * binary installed with `@ttsc/graph`; pass it explicitly to point at a
+     * custom build.
      */
     binary?: string;
   } = {},
 ): TtscGraphMemory {
   const cwd = options.cwd ?? process.cwd();
   const tsconfig = options.tsconfig ?? "tsconfig.json";
-  // Resolve the platform binary from the selected project cwd, not the caller's
-  // process directory, so a one-shot load names its own installation.
-  const binary = options.binary ?? resolveGraphBinary(process.env, cwd);
-  if (binary === null) {
-    throw new Error(
-      "@ttsc/graph: could not resolve the ttscgraph binary. " +
-        "Install `ttsc` so its platform package is present, " +
-        "or set TTSC_GRAPH_BINARY to an absolute path.",
-    );
-  }
+  // The producer belongs to this package's installation, so the selected
+  // project only becomes the native process's --cwd.
+  const binary = options.binary ?? resolveGraphBinary(process.env);
+  if (binary === null) throw new Error(InstalledGraphBinary.missingMessage());
   ensureExecutable(binary);
 
   // The dump goes to a file rather than a pipe, so no output ceiling applies:
@@ -159,8 +154,7 @@ export function parseDump(json: string): ITtscGraphDump {
       `@ttsc/graph: ttscgraph dump is schema ${
         version === undefined ? "unknown" : `v${String(version)}`
       }, this client reads v${String(DUMP_SCHEMA_VERSION)}. ` +
-        "Install a matching `ttsc` (the binary resolves from the target " +
-        "project, or from TTSC_GRAPH_BINARY).",
+        InstalledGraphBinary.MISMATCH_REMEDY,
     );
   }
   try {

package/src/resolveGraphBinary.ts

@@ -1,60 +1,41 @@
-import { createRequire } from "node:module";
-import path from "node:path";
+import { InstalledGraphBinary } from "./internal/InstalledGraphBinary";
 
 /**
- * Resolve the per-platform `ttscgraph` binary, or `null` when it cannot be
- * located.
+ * Resolve the `ttscgraph` binary this `@ttsc/graph` release spawns, or `null`
+ * when it cannot be located.
  *
- * `ttsc` is a peer dependency pinned to this package's own version, installed
- * alongside `@ttsc/graph` in the user's project rather than nested under this
- * launcher, so resolution starts from the user's project, not from this
- * package's own tree.
- *
- * The pin is what keeps the two halves of the graph in step. `literals` and the
- * rest of the node facts are resolved by the Go builder and ride the dump, so a
- * newer `@ttsc/graph` reading an older `ttscgraph` would find those fields
- * simply absent and answer from a graph missing facts it believes are there.
+ * The binary ships in `@ttsc/graph-<platform>-<arch>`, which `@ttsc/graph`
+ * lists as an exact-version optional dependency, so it is resolved from this
+ * package's own installation. The JavaScript client and the native producer
+ * therefore always come from one release, wherever the launcher was started.
+ * That pairing matters because node facts such as `literals` are resolved by
+ * the producer and ride the dump: a client reading an older producer would find
+ * those fields absent and answer from a graph missing facts it believes are
+ * there.
  *
  * Resolution order:
  *
  * 1. `TTSC_GRAPH_BINARY` env var, when set to an absolute path.
- * 2. The per-platform npm package `@ttsc/<platform>-<arch>/bin/ttscgraph[.exe]`.
- *    That package carries `ttsc`, `ttscserver`, and `ttscgraph` together and is
- *    an `optionalDependency` of `ttsc`, so it is resolved from `ttsc`'s
- *    location — found from `cwd`, the project the caller selected (via `--cwd`
- *    or an API `cwd` option), defaulting to `process.cwd()` when no project was
- *    named. A launcher started from an unrelated directory still resolves the
- *    `ttsc` installed under the target project it was asked to graph.
+ * 2. `@ttsc/graph-<platform>-<arch>/bin/ttscgraph[.exe]`, resolved from the
+ *    installed `@ttsc/graph` package.
+ *
+ * `cwd` is still accepted so existing callers keep compiling. It no longer
+ * affects resolution: the binary used to come from the target project's `ttsc`
+ * platform package, and now belongs to `@ttsc/graph` itself.
  *
- * @evidence contracts/common.md#principled-implementation Project-anchored module resolution locates the peer ttsc and then its platform binary; an explicit absolute override has precedence.
- * @evidence contracts/common.md#clear-and-simple-design One resolver owns override and peer-package lookup for all graph launchers.
- * @evidence contracts/common.md#prohibited-implementation-shortcuts Resolution uses installed package contracts rather than guessing binary paths from repository layouts.
- * @evidence contracts/common.md#meaningful-documentation Native paragraphs and the ordered list explain peer placement, override precedence and target-project anchoring.
- * @evidence contracts/portability.md#os-neutral-implementation Native path checks and module resolution select the platform/architecture package; only Windows's required executable suffix differs explicitly.
+ * @evidence contracts/common.md#principled-implementation The installed-package resolver locates the exact-version platform dependency from this module's own location; an explicit absolute override has precedence.
+ * @evidence contracts/common.md#clear-and-simple-design The public function delegates to the one resolver every launcher, loader and session uses, anchored at this package's installation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Resolution uses the installed package contract rather than repository layouts or the target project's packages.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs and the ordered list explain package ownership, override precedence and the retained but ignored cwd argument.
+ * @evidence contracts/portability.md#os-neutral-implementation The delegated resolver selects the platform/architecture package through Node module resolution; only Windows's executable suffix differs.
  * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a path string and opens no handle.
- * @evidenceExclude contracts/performance.md#efficient-algorithms performs a constant number of module resolutions (ttsc, then its platform package).
+ * @evidenceExclude contracts/performance.md#efficient-algorithms performs at most one module resolution.
  * @evidenceExclude contracts/performance.md#reuse-equivalent-work resolves on every call and caches nothing, so a reinstall between calls is honored.
  */
 export function resolveGraphBinary(
   env: NodeJS.ProcessEnv = process.env,
-  cwd: string = process.cwd(),
+  cwd?: string,
 ): string | null {
-  if (env.TTSC_GRAPH_BINARY && path.isAbsolute(env.TTSC_GRAPH_BINARY)) {
-    return env.TTSC_GRAPH_BINARY;
-  }
-  const exe = process.platform === "win32" ? "ttscgraph.exe" : "ttscgraph";
-  try {
-    // Anchor package lookup at the absolute project root so a relative `--cwd`
-    // resolves the same way the native process interprets it.
-    const fromProject = createRequire(
-      path.join(path.resolve(cwd), "package.json"),
-    );
-    const ttscPackageJson = fromProject.resolve("ttsc/package.json");
-    const fromTtsc = createRequire(ttscPackageJson);
-    return fromTtsc.resolve(
-      `@ttsc/${process.platform}-${process.arch}/bin/${exe}`,
-    );
-  } catch {
-    return null;
-  }
+  void cwd;
+  return InstalledGraphBinary.resolve(env, __filename);
 }

package/src/runGraph.ts

@@ -25,7 +25,7 @@ const VERSION: string = (require("../package.json") as { version: string })
  * @evidence contracts/common.md#clear-and-simple-design The launcher owns lane dispatch while viewer, server and native dump helpers own their respective execution boundaries.
  * @evidence contracts/common.md#prohibited-implementation-shortcuts A missing dump binary exposes only an explicitly qualified help summary; execution failures retain nonzero outcomes instead of fake graph answers.
  * @evidence contracts/common.md#meaningful-documentation Native lane bullets explain observable CLI behavior and resident refresh ownership with a blank line before tags.
- * @evidence contracts/portability.md#os-neutral-implementation Native lanes resolve the selected project's platform package and pass argv directly; stdio MCP uses Node transport APIs without shell path construction.
+ * @evidence contracts/portability.md#os-neutral-implementation Native lanes resolve this package's installed platform binary and pass argv directly; stdio MCP uses Node transport APIs without shell path construction.
  * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources starts the stdio server (owned by startServer), runs a synchronous dump child to completion or hands over to runView, and keeps no handle itself.
  * @evidenceExclude contracts/performance.md#efficient-algorithms dispatches on the first argv token to one lane and the lanes own the work.
  * @evidenceExclude contracts/performance.md#reuse-equivalent-work runs one launcher lane per process invocation, so there is nothing to share.
@@ -52,11 +52,11 @@ export function runGraph(
  * on this process's stdout. Returns the child's exit code.
  */
 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.
+  // The producer belongs to this package's installation; `--cwd` only selects
+  // the project the native process graphs.
   const { cwd, tsconfig, artifactsSpecified } =
     TtscGraphLauncherArguments.dump(argv);
-  const binary = resolveGraphBinary(process.env, cwd);
+  const binary = resolveGraphBinary(process.env);
   if (binary === null) {
     // `ttscgraph` owns the flag contract, so a resolvable binary always answers
     // `--help` itself and stays the single source of truth. It cannot answer

package/src/view.ts

@@ -6,6 +6,7 @@ import path from "node:path";
 import { TtscGraphLauncherArguments } from "./TtscGraphLauncherArguments";
 import { TtscGraphViewSnapshot } from "./TtscGraphViewSnapshot";
 import { GraphProcessTrace } from "./internal/GraphProcessTrace";
+import { InstalledGraphBinary } from "./internal/InstalledGraphBinary";
 import { publishArtifacts } from "./model/publishedArtifacts";
 import { captureProcessOutput, ensureExecutable } from "./nativeExecutable";
 import { reduce } from "./reduce";
@@ -29,15 +30,11 @@ import { resolveGraphBinary } from "./resolveGraphBinary";
 export function runView(argv: readonly string[]): number | void {
   const opts = TtscGraphLauncherArguments.view(argv);
 
-  // Anchor binary resolution at the project selected by `--cwd`, so `view` from
-  // an unrelated directory still finds the `ttsc` installed under the target.
-  const binary = resolveGraphBinary(process.env, opts.cwd);
+  // The producer belongs to this package's installation; `--cwd` only selects
+  // the project the native process graphs.
+  const binary = resolveGraphBinary(process.env);
   if (binary === null) {
-    process.stderr.write(
-      "@ttsc/graph: could not resolve the ttscgraph binary. " +
-        "Install `ttsc` so its platform package is present, " +
-        "or set TTSC_GRAPH_BINARY to an absolute path.\n",
-    );
+    process.stderr.write(`${InstalledGraphBinary.missingMessage()}\n`);
     return 1;
   }
   ensureExecutable(binary);