ttsc 0.32.0 → 0.32.1

package/src/launcher/internal/runTtsc.ts

@@ -35,8 +35,9 @@ import { resolveCacheDir } from "./resolveCacheDir";
 import { resolveSingleFileOutput } from "./resolveSingleFileOutput";
 import { resolveRuntimeCleanTargets } from "./runtime/resolveRuntimeCleanTargets";
 import { withRuntimeDirectoryLock } from "./runtime/withRuntimeDirectoryLock";
+import { AsyncWatchTopology } from "./watch/AsyncWatchTopology";
 import { type WatchInputChange } from "./watch/WatchInputChange";
-import { WatchTopology } from "./watch/WatchTopology";
+import { WatchSettlement } from "./watch/WatchSettlement";
 
 /**
  * CLI entry point for `ttsc`. Dispatches argv to the appropriate lane (build,
@@ -582,12 +583,26 @@ function printCacheHelp(): void {
  * full request retains cache, reporting and watch callbacks. Only the private
  * helper writes the selected public file. Success presentation follows that
  * completed copy and describes public emission, without private products or a
- * fabricated transform-site count. Watch supplies quiet true itself.
+ * fabricated transform-site count. Watch supplies quiet true itself. The async
+ * watch executor awaits input publication before building; ordinary CLI calls
+ * keep their synchronous return contract and share output planning.
  */
 function runSingleFile(
   options: ReturnType<typeof parseTtscBuildArgs> &
     Pick<TtscSingleFileEmitOptions, "onProjectInputs" | "onWatchInputs">,
-): number {
+): number;
+function runSingleFile(
+  options: ReturnType<typeof parseTtscBuildArgs> &
+    Pick<TtscSingleFileEmitOptions, "onProjectInputs" | "onWatchInputs">,
+  execute: typeof runSingleFileEmit.async,
+): Promise<number>;
+function runSingleFile(
+  options: ReturnType<typeof parseTtscBuildArgs> &
+    Pick<TtscSingleFileEmitOptions, "onProjectInputs" | "onWatchInputs">,
+  execute:
+    | typeof runSingleFileEmit
+    | typeof runSingleFileEmit.async = runSingleFileEmit,
+): number | Promise<number> {
   if (options.files.length !== 1) {
     throw new Error(
       "ttsc: single-file mode currently accepts exactly one input file",
@@ -610,20 +625,25 @@ function runSingleFile(
         project,
       )
     : undefined;
-  runSingleFileEmit({ ...options, cwd, file, out }, selection);
-  if (options.quiet === false) {
-    process.stdout.write(
-      `// ttsc: tsconfig=${project.path} cwd=${cwd} emit=${emit}\n`,
-    );
+  const result = execute({ ...options, cwd, file, out }, selection);
+  const report = (): number => {
+    if (options.quiet === false) {
+      process.stdout.write(
+        `// ttsc: tsconfig=${project.path} cwd=${cwd} emit=${emit}\n`,
+      );
+      if (out !== undefined) {
+        process.stdout.write(`// ttsc: emitted=1 files\n`);
+        process.stdout.write(`  + ${relativeToCwd(cwd, out) || out}\n`);
+      }
+    }
     if (out !== undefined) {
-      process.stdout.write(`// ttsc: emitted=1 files\n`);
-      process.stdout.write(`  + ${relativeToCwd(cwd, out) || out}\n`);
+      process.stdout.write(
+        `${relativeToCwd(cwd, out) || path.basename(out)}\n`,
+      );
     }
-  }
-  if (out !== undefined) {
-    process.stdout.write(`${relativeToCwd(cwd, out) || path.basename(out)}\n`);
-  }
-  return 0;
+    return 0;
+  };
+  return typeof result === "string" ? report() : result.then(report);
 }
 
 function runWatch(
@@ -631,7 +651,7 @@ function runWatch(
   checkOnly: boolean,
 ): number {
   const cwd = path.resolve(options.cwd ?? process.cwd());
-  let topology: WatchTopology | undefined;
+  let topology: AsyncWatchTopology | undefined;
   const invocation = {
     ...(checkOnly ? { ...options, emit: false } : options),
     cwd,
@@ -639,10 +659,10 @@ function runWatch(
       inputs: readonly string[],
       identities?: PluginContentIdentities.Store,
     ) => {
-      topology?.setExtraInputs(inputs, identities);
+      return topology?.setExtraInputs(inputs, identities);
     },
     onProjectInputs: (inputs: ITtscProjectInputSnapshot) => {
-      topology?.setProjectInputs(inputs);
+      return topology?.setProjectInputs(inputs);
     },
     quiet: true,
   };
@@ -653,6 +673,8 @@ function runWatch(
   let closing: Promise<void> | undefined;
   let rerun = false;
   let timer: NodeJS.Timeout | null = null;
+  const settlement = new WatchSettlement();
+  let completedBuilds = 0;
   const resident =
     invocation.files.length === 0 ? new ResidentCheckWatchSession() : undefined;
   const pendingChanges = new PendingResidentCheckWatchChanges();
@@ -664,6 +686,7 @@ function runWatch(
   const runOnce = async () => {
     if (closed) return;
     running = true;
+    settlement.changed();
     const change = pendingChanges.take();
     if (process.env.TTSC_WATCH_DEBUG_INPUTS)
       debugWatchInputs(`cycle ${JSON.stringify(change)}`);
@@ -682,14 +705,14 @@ function runWatch(
       // rebuild reports a clear failure and the watcher keeps running instead
       // of crashing the process with an uncaught exception.
       const status = await (invocation.files.length !== 0
-        ? Promise.resolve(runSingleFile(invocation))
+        ? runSingleFile(invocation, runSingleFileEmit.async)
         : (async () => {
             const buildOptions = checkOnly
               ? { ...invocation, emit: false }
               : invocation;
             const result =
               resident === undefined
-                ? runBuild(buildOptions)
+                ? await runBuild.async(buildOptions)
                 : await resident.run(buildOptions, change);
             // Watch output is one ordered stream. The diagnostics a build
             // produced and the "[ttsc] watch build …" marker that concludes
@@ -710,6 +733,7 @@ function runWatch(
       process.stdout.write(
         `[ttsc] ${status === 0 ? "watch build complete" : "watch build failed"}\n`,
       );
+      ++completedBuilds;
     } catch (error) {
       if (closed) return;
       // Same ordered-stream rule as the build path: the failure text goes on
@@ -719,30 +743,33 @@ function runWatch(
       lastStatus = lastStatus === 0 ? 2 : lastStatus;
       completedBuild = true;
       process.stdout.write(`[ttsc] watch build failed\n`);
+      ++completedBuilds;
     } finally {
-      running = false;
       if (completed && !closed) {
         try {
           // A filesystem event can arrive after the build reports completion
-          // but before this synchronous cleanup reaches its re-resolution.
+          // but before post-build reconciliation reaches its re-resolution.
           // Notify for a membership change here as well, otherwise that new
           // input is silently absorbed into the watch set without a rebuild.
-          topology?.refresh(true);
+          await topology?.refresh(true);
         } catch (error) {
           process.stderr.write(
             `[ttsc] watch error on ${watchMessagePath(cwd, root)}: ${formatError(error)}\n`,
           );
         }
       }
+      running = false;
     }
     if (rerun) {
       rerun = false;
       trigger();
     }
+    settlement.changed();
   };
   const trigger = (change?: WatchInputChange, reload = false) => {
     if (closed) return;
     pendingChanges.push(change, reload);
+    settlement.changed();
     if (running) {
       rerun = true;
       return;
@@ -758,33 +785,30 @@ function runWatch(
       activeSelected: active !== undefined,
     });
     closed = true;
+    settlement.changed();
     if (timer) clearTimeout(timer);
     timer = null;
     process.off("SIGINT", onInterrupt);
     process.off("SIGTERM", onTerminate);
     process.off("message", onMessage);
     process.off("disconnect", onDisconnect);
-    let topologyError: unknown;
-    try {
-      topology?.close();
-    } catch (error) {
-      topologyError = error;
-    }
+    const topologyClosing = topology?.close() ?? Promise.resolve();
     const residentClosing = resident?.close() ?? Promise.resolve();
     const activeClosing = active ?? Promise.resolve();
-    closing = Promise.allSettled([residentClosing, activeClosing]).then(
-      (results) => {
-        const errors = results.flatMap((result) =>
-          result.status === "rejected" ? [result.reason] : [],
+    closing = Promise.allSettled([
+      topologyClosing,
+      residentClosing,
+      activeClosing,
+    ]).then((results) => {
+      const errors = results.flatMap((result) =>
+        result.status === "rejected" ? [result.reason] : [],
+      );
+      if (errors.length !== 0)
+        throw new AggregateError(
+          errors,
+          `ttsc: watch shutdown failed: ${errors.map(formatError).join("; ")}`,
         );
-        if (topologyError !== undefined) errors.push(topologyError);
-        if (errors.length !== 0)
-          throw new AggregateError(
-            errors,
-            `ttsc: watch shutdown failed: ${errors.map(formatError).join("; ")}`,
-          );
-      },
-    );
+    });
     if (process.env.TTSC_E2E_TRACE) {
       // Observe the original promises without substituting their settlements.
       void residentClosing.then(
@@ -893,9 +917,48 @@ function runWatch(
       const id = message.id;
       E2ETrace.watchShutdown("ipc-stop-received", { stopId: id });
       void finish(id);
+    } else if (
+      typeof message === "object" &&
+      message !== null &&
+      "type" in message &&
+      message.type === "ttsc.watch.settle" &&
+      "id" in message &&
+      typeof message.id === "string" &&
+      message.id.length !== 0
+    ) {
+      const id = message.id;
+      // Build markers retain their exact text and one marker per cycle. IPC
+      // travels on another pipe, so its receipt carries the completed count:
+      // a caller must drain those stdout markers before using the boundary.
+      void settlement
+        .wait(
+          async () => {
+            await topology?.whenIdle();
+            if (closed) throw new Error("ttsc: watch closed before settling");
+            return !running && !rerun && timer === null;
+          },
+          async () => {
+            if (process.connected && process.send !== undefined)
+              await new Promise<void>((resolve, reject) => {
+                process.send!(
+                  { type: "ttsc.watch.settled", id, builds: completedBuilds },
+                  (error: Error | null) =>
+                    error === null ? resolve() : reject(error),
+                );
+              });
+          },
+        )
+        .catch((error: unknown) => {
+          if (!closed) {
+            process.stderr.write(`${formatError(error)}\n`);
+            lastStatus = lastStatus === 0 ? 2 : lastStatus;
+            void finish();
+          }
+        });
     }
   };
   const startRun = () => {
+    timer = null;
     active = runOnce();
     void active.catch((error: unknown) => {
       process.stderr.write(`${formatError(error)}\n`);
@@ -904,7 +967,13 @@ function runWatch(
     });
   };
 
-  topology = new WatchTopology(invocation, {
+  topology = new AsyncWatchTopology(invocation, {
+    onFailure: (error) => {
+      if (closed) return;
+      lastStatus = lastStatus === 0 ? 2 : lastStatus;
+      process.stderr.write(`${formatError(error)}\n`);
+      void finish();
+    },
     onError: (location, error) => {
       process.stderr.write(
         `[ttsc] watch error on ${watchMessagePath(cwd, location)}: ${formatError(error)}\n`,
@@ -934,16 +1003,25 @@ function runWatch(
     },
     onTopologyChange: () => trigger(undefined, true),
   });
+  const start = async (): Promise<void> => {
+    await topology!.refresh(false);
+    if (closed) return;
+    process.stdout.write(`[ttsc] watching ${watchMessagePath(cwd, root)}\n`);
+    startRun();
+  };
   try {
-    topology.refresh(false);
     process.on("SIGINT", onInterrupt);
     process.on("SIGTERM", onTerminate);
     if (process.connected) {
       process.on("message", onMessage);
       process.on("disconnect", onDisconnect);
     }
-    process.stdout.write(`[ttsc] watching ${watchMessagePath(cwd, root)}\n`);
-    startRun();
+    void start().catch((error: unknown) => {
+      if (closed) return;
+      lastStatus = lastStatus === 0 ? 2 : lastStatus;
+      process.stderr.write(`${formatError(error)}\n`);
+      void finish();
+    });
   } catch (error) {
     // Refresh may fail after acquiring only part of the watch set. Release that
     // partial ownership as well as setup's signal listeners before returning.

package/src/launcher/internal/runtime/CommonJsRuntimeSource.ts

@@ -71,16 +71,20 @@ export namespace CommonJsRuntimeSource {
   }
 
   /**
-   * Construct an owned require with local TypeScript extension advertisements.
+   * Construct an owned require sharing the original live extension registry.
    *
-   * @evidence contracts/common.md#principled-implementation createRequire loads through Node's shared CommonJS cache; copied public properties preserve cache/main access, while a copied registry advertises the already-supported source extensions without changing their actual loader.
+   * Node's loader and every native require share this registration object.
+   * Copying it hides later registrations, replacements and deletions from one
+   * side; source-extension advertisement belongs to runtime installation.
+   *
+   * @evidence contracts/common.md#principled-implementation createRequire loads through Node's shared CommonJS cache; copied public properties preserve cache/main access, and the original registry reference preserves the public extension-registration contract across later edits. Missing original metadata falls back to the native registry.
    * @evidence contracts/common.md#clear-and-simple-design The callable and resolve member share one filename anchor; source recovery remains in the configured policy.
-   * @evidence contracts/common.md#prohibited-implementation-shortcuts Extension entries belong to this new function, not Module._extensions or a foreign require; no private loader slot is assigned.
-   * @evidence contracts/common.md#meaningful-documentation Native prose identifies ownership and distinguishes advertisements from actual loading.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Construction assigns only the owned function's properties, adds no extension capability and replaces no foreign handler or private loader slot. Runtime installation separately advertises its supported CommonJS source extensions.
+   * @evidence contracts/common.md#meaningful-documentation Native prose explains why live registry identity is required and assigns advertisement to the installation owner.
    * @evidence contracts/portability.md#os-neutral-implementation The public createRequire API takes the native filename; no OS-name or path-string case heuristic is introduced.
-   * @evidence contracts/performance.md#efficient-algorithms Construction copies public require properties and E extension entries, including their property observations, and creates a native filename-anchored require. Calls delegate native resolution, module evaluation/cache work or the configured resolver; their cost is not bounded by construction or extension count.
+   * @evidence contracts/performance.md#efficient-algorithms Construction copies P public require properties and creates a native filename-anchored require without traversing or allocating another extension registry. Calls delegate native resolution, module evaluation/cache work or the configured resolver; their cost is not bounded by property count.
    * @evidence contracts/performance.md#reuse-equivalent-work Callable loading delegates to Node's CommonJS cache; the configured resolve policy remains a distinct per-call operation, not a cached result of constructing the function.
-   * @evidence contracts/performance.md#bound-retention-and-release-resources The evaluated module owns the returned function, captured filename/native require and copied extension registry. Captured cache/main references share Node or original-require state rather than copying all cached modules; the factory adds no historical module collection or native handle.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The evaluated module owns the returned function and captured filename/native require. Cache, main and extension-registry references share Node or original-require state; the factory adds no registry copy, historical module collection or native handle.
    */
   export function create(
     original: NodeJS.Require,
@@ -107,9 +111,7 @@ export namespace CommonJsRuntimeSource {
       )) as NodeJS.RequireResolve;
     owned.resolve.paths = native.resolve.paths;
     owned.cache = original.cache ?? native.cache;
-    owned.extensions = { ...(original.extensions ?? native.extensions) };
-    for (const extension of [".ts", ".tsx", ".cts", ".mts"])
-      owned.extensions[extension] = owned.extensions[".js"]!;
+    owned.extensions = original.extensions ?? native.extensions;
     return owned;
   }
 

package/src/launcher/internal/runtime/advertiseTypeScriptExtensions.ts

@@ -0,0 +1,25 @@
+/**
+ * Publish the CommonJS source extensions served by the installed runtime hooks.
+ *
+ * Tools such as tsconfig-paths enumerate the process registry before asking
+ * Node to resolve a file, and rechoir checks it before loading a typed config.
+ * A module-local copy cannot satisfy those checks. Add only missing entries
+ * using Node's JavaScript handler; registerHooks still owns source compilation
+ * and existing loader handlers keep their identity. Node probes these entries
+ * after its existing extensions, preserving JavaScript precedence.
+ *
+ * @evidence contracts/common.md#principled-implementation The public require.extensions registry advertises supported CommonJS source loading to consumers that inspect extensions before resolution; absent entries delegate to Node's existing JavaScript handler, which consumes the source supplied by registerHooks.
+ * @evidence contracts/common.md#clear-and-simple-design One installation operation publishes loader capability without adding a second compilation or resolution path.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Only missing public registry entries are added; no foreign handler or method is replaced and no consumer identity affects production behavior. The source suffixes describe the supported CommonJS contract rather than fixture-specific routes.
+ * @evidence contracts/common.md#meaningful-documentation The prose explains why process-wide advertisement is needed, who compiles the source, which handlers remain authoritative and how native precedence is preserved.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Registry updates use JavaScript property semantics without filesystem, path or process arguments; Node's loader owns native resolution.
+ * @evidence contracts/performance.md#efficient-algorithms A fixed set of three CommonJS source extensions requires constant time and space, without scanning modules or files.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This capability publication shares no computed compilation or resolution result.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The caller's process registry retains at most three added references to an existing Node handler for the installed hooks' process lifetime; no handle or task is acquired.
+ */
+export function advertiseTypeScriptExtensions(
+  extensions: NodeJS.RequireExtensions,
+): void {
+  for (const extension of [".ts", ".tsx", ".cts"])
+    extensions[extension] ??= extensions[".js"]!;
+}

package/src/launcher/internal/runtime/installRuntimeHooks.ts

@@ -43,6 +43,7 @@ import type { RuntimeManifest } from "./RuntimeManifest";
 import { RuntimeManifestRegistry } from "./RuntimeManifestRegistry";
 import { RuntimeModuleFormat } from "./RuntimeModuleFormat";
 import { RuntimeProjectOwnership } from "./RuntimeProjectOwnership";
+import { advertiseTypeScriptExtensions } from "./advertiseTypeScriptExtensions";
 import { checkNodeRuntimeSupport } from "./checkNodeRuntimeSupport";
 import { commonJsExportNames } from "./commonJsExportNames";
 import { commonJsImportFacade } from "./commonJsImportFacade";
@@ -94,8 +95,10 @@ import { selectRuntimePluginPolicy } from "./selectRuntimePluginPolicy";
  * reach the API lacks on some releases is `require.resolve`, which is probed
  * before installation. Served CommonJS bodies receive an owned require function
  * whose resolve member applies the same source policy on those releases. Its
- * copied extension registry advertises the supported source extensions; foreign
- * resolver methods and global extension registries are never replaced.
+ * shared extension registry preserves live registrations. Installation also
+ * advertises missing CommonJS source extensions in the process registry because
+ * ecosystem tools inspect it before resolution; existing handlers remain intact
+ * and foreign resolver methods are never replaced.
  *
  * Direct descriptor evaluation records user preloads after hook installation.
  * Only the generated CommonJS output sibling takes Node's native resolve/load
@@ -104,7 +107,7 @@ import { selectRuntimePluginPolicy } from "./selectRuntimePluginPolicy";
  *
  * @evidence contracts/common.md#principled-implementation Resolution preserves successful Node decisions, rescues source spellings only after documented resolution fails, and serves only outputs whose ownership index names the exact source. CommonJS facades delegate native evaluation and project detected own named exports under the selected namespace capability; an owned module-local require supplies source resolution when native require.resolve bypasses public hooks.
  * @evidence contracts/common.md#clear-and-simple-design One synchronous hook owner coordinates source selection, emission ownership and descriptor observation; the entry, owning-project and orphan lanes remain explicit because they have distinct compilation premises. Private helpers carry those policies without a second foreign-resolver layer.
- * @evidence contracts/common.md#prohibited-implementation-shortcuts Public registerHooks handles resolution and loading; installation mutates neither Module._resolveFilename nor require.extensions. Source-extension recovery implements emitted-to-source spelling under the runtime contract, and module-local require adaptation addresses the probed public-hook difference without replacing Node methods.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Public registerHooks handles resolution and loading; installation adds missing public extension entries with Node's own JavaScript handler while preserving every existing handler and resolver method. Source-extension recovery implements emitted-to-source spelling under the runtime contract, and module-local require adaptation addresses the probed public-hook difference without replacing Node methods.
  * @evidence contracts/common.md#meaningful-documentation Native paragraphs describe the three serving lanes, compile gates, source identity, capability-based local adaptation and extension-registry ownership; helper comments state ownership and failure effects with descriptive prose separated from tags.
  * @evidence contracts/portability.md#os-neutral-implementation Node URL conversion, native filesystem paths and physical resolution preserve OS spelling boundaries. Actual public-hook probes select runtime capabilities, native emit uses executable arguments without shell interpolation, and unresolved filesystem observation refuses reusable descriptor proof.
  * @evidence contracts/performance.md#efficient-algorithms Source ownership indexes replace repeated whole-emit scans with indexed source/native-identity queries. Export discovery processes source/emit bytes, reexport edges, native resolution and Set/name unions under traversal-local seen sets; separate roots can repeat traversal. Config-chain validation reads discovered inputs. Compiler identity brackets and streams executable bytes on valid lookups, refusing failed observations. Native build/name-scan/orphan paths add compilation, path/metadata/IO cost; recursive graphs remain subject to stack limits.
@@ -134,6 +137,7 @@ export function installRuntimeHooks(options: RuntimeHookOptions = {}): void {
     process.setSourceMapsEnabled(true);
   }
   registerHooks({ load, resolve });
+  advertiseTypeScriptExtensions(require.extensions);
   PluginDescriptorInputObservation.begin(true);
   installed = true;
 }