ttsc 0.30.4 → 0.31.1

package/src/launcher/internal/buildSingleRootProject.ts

@@ -0,0 +1,303 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { runBuild } from "../../compiler/internal/build/runBuild";
+import { readProjectConfig } from "../../compiler/internal/project/readProjectConfig";
+import { readEffectiveCompilerOptions } from "../../compiler/internal/readEffectiveCompilerOptions";
+import { createFilesystemPathIdentityContext } from "../../internal/pathIdentity/createFilesystemPathIdentityContext";
+import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
+import type { TtscCommonOptions } from "../../structures/internal/TtscCommonOptions";
+import { DependencyBuildGeneration } from "./runtime/DependencyBuildGeneration";
+import { runtimeCompilerArgs } from "./runtimeCompilerArgs";
+import { runtimeEmitProfile } from "./runtimeEmitProfile";
+import { singleRootProjectConfig } from "./singleRootProjectConfig";
+
+/**
+ * Compile one TypeScript root that its owning project's file set does not
+ * contain, with every compiler option of that project.
+ *
+ * `ttsc` selects a _file set_: a project whose `include` is `src` must emit
+ * only `src` into `outDir`, and a `clear.ts`, a `build/release.ts`, or a
+ * `lint.config.ts` beside the tsconfig has no business in `lib`. `ttsx` needs
+ * that project's compiler options for a file it runs, not its file list. Those
+ * two requirements are not in conflict, but the whole-project build cannot
+ * satisfy the second, so such a root is compiled here through a project that
+ * inherits every option and declares only the root. Two lanes need it: the
+ * launcher's entry when the project build did not emit it, and a TypeScript
+ * file the running program reaches that no build compiled.
+ *
+ * Where the synthesized tsconfig lives depends on what the build reads from its
+ * location. `extends` with an absolute path resolves from anywhere, and every
+ * relative option resolves against the config that declares it, but
+ * `${configDir}` is substituted with the directory of the config tsgo was
+ * given, and the default `typeRoots` and each `types` entry are looked up from
+ * there. A checked build needs all of them exactly as the user's config sees
+ * them, so its tsconfig is written beside the real one, and a directory that
+ * refuses the write is reported by name. TypeScript-Go's command line cannot
+ * combine a project with a file list, and ttsc ships no host that replaces a
+ * project's roots in memory, so no other placement is faithful. An emit-only
+ * build ignores diagnostics, and none of those lookups changes what it emits,
+ * with one exception: `${configDir}` inside `paths` or `baseUrl` decides which
+ * module an import resolves to, and so whether a re-exported name is elided as
+ * a type. Unless its config chain uses `${configDir}`, an emit-only build's
+ * tsconfig is written beside `emitDir` instead, because such a build runs while
+ * the program is running, for an installed package whose directory may be
+ * read-only or for a plugin descriptor whose inputs are fingerprinted by their
+ * directory's metadata, and a file created and removed in the user's tree would
+ * disturb both. The overlay is created exclusively: an occupied name is refused
+ * without writing or removing that entry. After acquisition, closing its
+ * descriptor and removing the overlay are attempted on success or failure;
+ * native cleanup failures may leave the overlay behind.
+ *
+ * `rootDir` is the root of the source's volume. The layout of this emit is
+ * private, so `rootDir` decides nothing here but whether a file of the program
+ * fits under it, and every narrower choice fails some program: the inherited
+ * `rootDir` (`src`) does not contain the root, and a root that imports a
+ * sibling package's source reaches outside any ancestor it shares with the
+ * project. A file outside `rootDir` is TS6059 in a checked build and, in an
+ * emit-only one, an output written beside the user's `.ts`. The caller finds
+ * the output through `EmitOwnershipIndex` against the returned `rootDir`, so
+ * the width costs nothing in precision. A `--rootDir` forwarded on the command
+ * line still wins, as it does in every build, and the returned `rootDir` is
+ * then that one.
+ *
+ * `composite` is switched off. It exists for `tsc -b`, whose project graph
+ * needs every file listed, and inherited here it would reject each import of
+ * the root with TS6307, since only the root is listed. Declarations go with it:
+ * nothing at run time reads them, and an inherited `declarationMap` would
+ * otherwise fail with TS5069 once `composite` no longer implies `declaration`.
+ * An emit-only build also switches `noEmitOnError` off, since it fails only on
+ * an empty output and an inherited `noEmitOnError` would turn any diagnostic
+ * into one.
+ *
+ * @returns The project, effective `rootDir` and compiler-owned source
+ *   provenance for actual written outputs. Missing provenance is not
+ *   synthesized from maps.
+ * @throws When the build fails. A checked build fails on any diagnostic; an
+ *   emit-only build fails only when it produced no JavaScript at all.
+ * @evidence contracts/common.md#principled-implementation A transient extends overlay changes only roots and runtime output constraints, while preserving configDir-sensitive anchors; effective rootDir is returned for output ownership rather than inferred from emitted filenames.
+ * @evidence contracts/common.md#clear-and-simple-design This boundary owns single-root overlay construction and cleanup, delegates project parsing/building, and isolates writable-directory diagnostics in a private helper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Private emit layout, disabled declaration/composite products and checked versus installed-package diagnostics are runtime contract distinctions, not source patches or tests-only compiler modes.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain overlay placement, wide rootDir, diagnostics and cleanup, while separately documented input members preserve their ownership facts.
+ * @evidence contracts/portability.md#os-neutral-implementation Shared filesystem identity selects the source volume from resolved native identity when available and retained spelling otherwise; overlay JSON converts only native separators, preserving literal POSIX backslashes. Public exclusive creation refuses an occupied overlay name without overwriting it; explicit compiler paths avoid shell interpolation and blanket case folding.
+ * @evidence contracts/performance.md#efficient-algorithms Emit-only placement parses the config chain and scans its text for configDir anchors; checked placement skips that scan. Native identity resolution, overlay serialization/write, effective-options preparation and delegated compilation contribute path/input/output byte costs; this boundary performs no source-directory mirror or second whole-project compilation.
+ * @evidence contracts/performance.md#reuse-equivalent-work One effective-options reader for this overlay and exact forwarded tokens is shared by runtime lowering, emit classification and rootDir selection, avoiding duplicate response-file compiler queries. Callers own sharing of completed build generations.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Exclusive open establishes ownership of one transient tsconfig and descriptor. The descriptor is closed before parsing; finally attempts any remaining close and removal after write, close, parse or build failure, without removing a failed-acquisition entry. Native cleanup failures may retain the overlay; caller owns emit storage and delegated build lifetimes.
+ */
+export function buildSingleRootProject(props: {
+  /** The root, in the physical spelling the runtime loads it by. */
+  source: string;
+
+  /** The owning `tsconfig.json`, whose options the root inherits. */
+  tsconfig: string;
+
+  /** Directory the build runs in. */
+  projectRoot: string;
+
+  /** Directory-safe token, unique per concurrent build of one tsconfig. */
+  key: string;
+
+  /** Where the JavaScript goes. The directory must be private to this build. */
+  emitDir: string;
+
+  /**
+   * Whether diagnostics stop the build. A root of the user's program is
+   * checked; a root inside an installed package is emit-only, matching the
+   * policy for every other file of that package.
+   */
+  checked: boolean;
+
+  /** Names the root in a failure: `entry` for the launcher's own entry. */
+  role: "entry" | "root";
+
+  /** Build options forwarded to `runBuild`. */
+  options?: TtscCommonOptions & { cacheDir?: string };
+}): {
+  /** Parsed overlay project whose compiler options governed this build. */
+  project: ReturnType<typeof readProjectConfig>;
+
+  /** Effective native layout root, including any forwarded rootDir override. */
+  rootDir: string;
+
+  /** Actual written output to compile-time source ledger; absent means unknown. */
+  emittedSources?: TtscBuildResult["emittedSources"];
+
+  /** Actual output-specific proof refusal context, independent of diagnostics. */
+  emittedSourceProofFailures?: TtscBuildResult["emittedSourceProofFailures"];
+} {
+  const options = props.options ?? {};
+  // `source` already carries the one spelling the runtime decided on. tsgo
+  // compares it against `rootDir` textually — `GetCommonSourceDirectory` takes
+  // `rootDir` verbatim and `ContainsPath` is lexical — so a mismatch here is
+  // not a near miss: the file counts as outside `rootDir`, and tsgo emits it to
+  // its own source path with the extension changed instead of under `outDir`,
+  // writing a `.js` and its map beside the user's `.ts` where nothing cleans
+  // them up.
+  const volumeRoot = path.parse(
+    createFilesystemPathIdentityContext({
+      throwOnRealpathError: false,
+    }).resolve(props.source).path,
+  ).root;
+  const beside =
+    props.checked ||
+    readProjectConfig({ tsconfig: props.tsconfig }).configPaths.some((file) =>
+      fs.readFileSync(file, "utf8").includes("${configDir}"),
+    );
+  const tsconfig = path.join(
+    beside ? path.dirname(props.tsconfig) : path.dirname(props.emitDir),
+    `.ttsx-${props.role}.${props.key}.tsconfig.json`,
+  );
+  fs.mkdirSync(path.dirname(tsconfig), { recursive: true });
+  let configDescriptor: number | undefined;
+  let ownsConfig = false;
+  try {
+    try {
+      configDescriptor = fs.openSync(tsconfig, "wx");
+      ownsConfig = true;
+      fs.writeFileSync(
+        configDescriptor,
+        JSON.stringify(
+          singleRootProjectConfig({
+            tsconfig: props.tsconfig,
+            source: props.source,
+            volumeRoot,
+            checked: props.checked,
+          }),
+          null,
+          2,
+        ),
+        "utf8",
+      );
+      fs.closeSync(configDescriptor);
+      configDescriptor = undefined;
+    } catch (error) {
+      throw unwritableConfigDirectory(error, props, path.dirname(tsconfig));
+    }
+    const project = readProjectConfig({
+      cwd: props.projectRoot,
+      // A tsconfig outside the project would otherwise make its own private
+      // directory the project root.
+      projectRoot:
+        options.projectRoot ?? (beside ? undefined : props.projectRoot),
+      tsconfig,
+    });
+    fs.mkdirSync(props.emitDir, { recursive: true });
+    const effectiveOptions = readEffectiveCompilerOptions(
+      project,
+      options.passthrough,
+      options.binary,
+    );
+    const result = runBuild({
+      binary: options.binary,
+      checkers: options.checkers,
+      cwd: props.projectRoot,
+      emit: true,
+      env: options.env,
+      cacheDir: options.cacheDir,
+      outDir: props.emitDir,
+      // Every output this build writes stays in ttsx's private directory: a
+      // declared `declarationDir`, `tsBuildInfoFile`, or `outFile`, and any
+      // output location forwarded on the command line, would otherwise land in
+      // the user's tree.
+      isolateOutputsTo: props.emitDir,
+      passthrough: runtimeCompilerArgs(
+        project,
+        options.passthrough,
+        options.binary,
+        effectiveOptions,
+      ),
+      // A source map on the transient emit lets the serve path inline it under
+      // the source URL; a project that configures its own keeps it.
+      forceRuntimeSourceMap: runtimeEmitProfile(
+        project,
+        options.passthrough,
+        options.binary,
+        effectiveOptions,
+      ).forceRuntimeSourceMap,
+      forceEmitProvenance: true,
+      // Native plugins discover their config files from the tsconfig's
+      // directory, which for a private tsconfig is ttsx's cache; anchor them
+      // at the real one, as a bundler adapter's temporary overlay does.
+      pluginConfigDir:
+        options.pluginConfigDir ??
+        (beside ? undefined : path.dirname(props.tsconfig)),
+      plugins: options.plugins,
+      quiet: true,
+      resolvedProject: project,
+      singleThreaded: options.singleThreaded,
+      skipDiagnosticsCheck: !props.checked,
+      tsconfig,
+    });
+    // An emit-only build reports its diagnostics through the exit status even
+    // though it wrote the JavaScript, so only an empty output fails it — the
+    // same rule the dependency lane applies to the package's other files.
+    const failed = props.checked
+      ? result.status !== 0
+      : !DependencyBuildGeneration.emittedAnything(props.emitDir);
+    if (failed) {
+      throw new Error(
+        [
+          props.checked
+            ? `ttsx: ${props.role} check failed for ${props.source}`
+            : `ttsx: ${props.role} build produced no output for ${props.source}`,
+          result.stderr || result.stdout,
+        ]
+          .filter((line) => line.trim().length !== 0)
+          .join("\n"),
+      );
+    }
+    // The root the compiler actually laid the outputs against: the one written
+    // above unless the command line forwarded another.
+    const effective = effectiveOptions?.("rootDir");
+    return {
+      emittedSources: result.emittedSources,
+      emittedSourceProofFailures: result.emittedSourceProofFailures,
+      project,
+      rootDir:
+        typeof effective === "string"
+          ? path.resolve(project.root, effective)
+          : volumeRoot,
+    };
+  } finally {
+    if (configDescriptor !== undefined) {
+      try {
+        fs.closeSync(configDescriptor);
+      } catch {
+        // Preserve the write or close failure that reached this cleanup.
+      }
+    }
+    if (ownsConfig) {
+      try {
+        fs.rmSync(tsconfig, { force: true });
+      } catch {
+        // Best effort: native cleanup failure can leave this overlay behind.
+      }
+    }
+  }
+}
+
+/**
+ * The error for a synthesized tsconfig the filesystem refused, naming the
+ * directory and what to do instead of surfacing a bare `EPERM`. Any other
+ * failure is returned unchanged.
+ *
+ * TypeScript-Go's command line cannot combine a project with a file list, so a
+ * build that must read the anchors of a tsconfig from its own directory needs a
+ * tsconfig in that directory. A read-only checkout, mount, or volume refuses
+ * it.
+ */
+function unwritableConfigDirectory(
+  error: unknown,
+  props: { source: string; tsconfig: string },
+  directory: string,
+): unknown {
+  const code = (error as NodeJS.ErrnoException | null)?.code;
+  if (code !== "EACCES" && code !== "EPERM" && code !== "EROFS") return error;
+  return new Error(
+    [
+      `ttsx: cannot compile ${props.source} with the options of ${props.tsconfig}: ${directory} is not writable (${code}).`,
+      "The file is outside that project's file set, and ttsx compiles it through a temporary tsconfig placed beside the project's own for the length of the build.",
+      `Make the directory writable, or add the file to the project's "include" or "files".`,
+    ].join("\n"),
+  );
+}

package/src/launcher/internal/getCompilerVersionText.ts

@@ -1,18 +1,33 @@
 import fs from "node:fs";
 import path from "node:path";
 
+import { outputText } from "../../compiler/internal/outputText";
 import { resolveTsgo } from "../../compiler/internal/resolveTsgo";
-import { outputText, spawnNative } from "../../compiler/internal/spawnNative";
+import { SidecarEnvironment } from "../../compiler/internal/sharedHost/SidecarEnvironment";
+import { spawnNative } from "../../compiler/internal/spawnNative";
 import type { TtscCommonOptions } from "../../structures/internal/TtscCommonOptions";
 
-/** Format the CLI version banner from the wrapper package and resolved tsc. */
+/**
+ * Format the CLI version banner from the wrapper package and resolved tsc. A
+ * failed native version request throws; unreadable wrapper metadata uses
+ * 0.0.0.
+ *
+ * @evidence contracts/common.md#principled-implementation The selected compiler's version command supplies reported banner text, not a content or ABI identity certificate, while package-local metadata supplies wrapper identity with a documented fallback.
+ * @evidence contracts/common.md#clear-and-simple-design Native invocation and wrapper metadata reading have separate failure policies; the private reader owns only the package-relative lookup.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The fallback is an explicit unknown wrapper version, not a fabricated compiler version or a suppressed failed native command.
+ * @evidence contracts/common.md#meaningful-documentation Native prose documents the distinct native-command failure and metadata fallback, and the helper explains the compiled-layout anchor.
+ * @evidence contracts/portability.md#os-neutral-implementation resolveTsgo and spawnNative own executable selection and invocation; shared environment merging preserves Windows alias identity and caller precedence while POSIX names remain exact. Node paths anchor package metadata without a shell or filesystem case folding.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Delegated synchronous spawn/capture owns process/output-file lifetime and cleanup attempts, without a descendant-join or certified native release guarantee here. Captured output and package metadata are call-local; returned banner text belongs to the caller and this helper stores no history.
+ * @evidence contracts/performance.md#efficient-algorithms Compiler selection, environment merging and delegated spawn/capture/recovery add native lookup, argv/environment and process costs. Full output decoding/trim/formatting and package JSON reading/parsing scale with their bytes; no local timeout or output-byte cap bounds them.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This helper queries the current selected compiler and package metadata each call rather than retaining its banner; delegated runtime capability/cache policies are owned by their helpers.
+ */
 export function getCompilerVersionText(
   options: TtscCommonOptions = {},
 ): string {
   const tsgo = resolveTsgo(options);
   const res = spawnNative(tsgo.binary, ["--version"], {
     cwd: options.cwd,
-    env: { ...process.env, ...options.env },
+    env: SidecarEnvironment.merge(process.env, options.env),
   });
   if (res.error || res.status !== 0) {
     throw new Error(
@@ -23,7 +38,7 @@ export function getCompilerVersionText(
 }
 
 /**
- * Read the `version` field from the `@ttsc/ttsc` package.json that sits three
+ * Read the `version` field from the `ttsc` package.json that sits three
  * directories above the compiled launcher output (`lib/launcher/internal/`).
  * Returns `"0.0.0"` on any I/O or parse failure so the banner is always safe to
  * display.
@@ -34,7 +49,7 @@ function readOwnPackageVersion(): string {
     const pkg = JSON.parse(fs.readFileSync(file, "utf8")) as {
       version?: string;
     };
-    return pkg.version ?? "0.0.0";
+    return typeof pkg?.version === "string" ? pkg.version : "0.0.0";
   } catch {
     return "0.0.0";
   }

package/src/launcher/internal/inlineServedSourceMap.ts

@@ -0,0 +1,294 @@
+import { tokTypes, tokenizer } from "acorn";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Rewrite a recognized trailing source-map line comment to inline metadata,
+ * anchoring native source paths to file URLs while preserving qualified URLs. A
+ * supplied single-source anchor overrides its map entry; this is lexical
+ * attribution rather than a check that the referenced source exists.
+ *
+ * Ttsx runs tsgo-built JavaScript under the ORIGINAL `.ts` source URL. When the
+ * owning tsconfig emits external maps, their relative URL belongs to the emit
+ * directory rather than the served source URL. Reading and embedding metadata
+ * avoids that relative lookup after temporary emits are removed. Actual Node,
+ * coverage-tool, debugger and editor interpretation remains their boundary.
+ *
+ * Re-inlining supported normalized string-source maps under the same source
+ * anchor preserves the rewritten bytes. This adapter does not validate every
+ * source-map semantic shape or authenticate a cross-process cache population.
+ *
+ * Reuse requires unchanged served text, source anchor and actual map bytes. The
+ * module cache retains at most 128 recent entries; individual map sizes are not
+ * capped. Only actual trailing line comments are rewritten. Strings, templates
+ * and regular-expression contents cannot supply a directive; unsupported
+ * lexical input is left for the runtime loader to diagnose.
+ *
+ * @param source - The emitted JavaScript text served under the source URL.
+ * @param emittedFile - On-disk path of the emitted `.js`, beside its `.map`.
+ * @param sourceFile - Real path of the `.ts` source the emit was built from.
+ * @evidence contracts/common.md#principled-implementation Acorn comment boundaries distinguish a real trailing directive from literal contents. Metadata uses supplied lexical anchors; parse failures, non-object maps, invalid index sections and unsupported lexical input retain the source. This is not complete source-map schema validation.
+ * @evidence contracts/common.md#clear-and-simple-design The serve boundary coordinates input-equivalent reuse, while helpers separate URL decoding, file reading and source anchoring; external map validity is checked before returning cached JavaScript.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Canonical sibling-map fallback follows compiler emit layout and missing-map removal addresses a dangling reference; no cached filename alone substitutes for current source or map contents.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain source-URL execution, idempotence, cache equivalence and retention limits; parameters distinguish emitted and original-source paths.
+ * @evidence contracts/portability.md#os-neutral-implementation Node path resolution reads native emitted files and pathToFileURL encodes source paths; already-qualified map URLs remain protocol identifiers rather than being case-folded as filesystem paths.
+ * @evidence contracts/performance.md#efficient-algorithms Work includes regex matching, optional full-source Acorn lexing, native map reads, JSON/base64 conversion and recursive section/source normalization with path-text costs. No universal linear-time or depth bound is asserted. An equal-source entry at the same emitted key reuses lexical recognition; a fully matching entry avoids rewrite processing after current map-data validation.
+ * @evidence contracts/performance.md#reuse-equivalent-work Absolute native locations capture cwd-sensitive emitted/source anchors, while exact source text shares lexical recognition and freshly read map JSON validates the rewrite; changed bytes or anchors rebuild rather than serving an old generation.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The module owns a 128-entry insertion-ordered LRU and evicts its oldest entry after a miss; retained bytes still depend on individual source/map sizes, and process exit releases the remaining cache.
+ */
+export function inlineServedSourceMap(
+  source: string,
+  emittedFile: string | undefined,
+  sourceFile: string | undefined,
+): string {
+  if (emittedFile === undefined) {
+    return source;
+  }
+  const emittedPath = path.resolve(emittedFile);
+  const sourcePath =
+    sourceFile === undefined ? undefined : path.resolve(sourceFile);
+  const cached = inlineCache.get(emittedPath);
+  const match =
+    cached?.source === source ? cached.match : trailingSourceMapComment(source);
+  const url = match?.[1]?.trim();
+  const json = url ? readMapJson(url, emittedPath) : null;
+  if (
+    cached !== undefined &&
+    cached.source === source &&
+    cached.sourceFile === sourcePath &&
+    cached.json === json
+  ) {
+    inlineCache.delete(emittedPath);
+    inlineCache.set(emittedPath, cached);
+    return cached.rewritten;
+  }
+  const rewritten = rewrite(source, emittedPath, sourcePath, match, json);
+  inlineCache.delete(emittedPath);
+  inlineCache.set(emittedPath, {
+    source,
+    sourceFile: sourcePath,
+    match,
+    json,
+    rewritten,
+  });
+  if (inlineCache.size > 128) {
+    inlineCache.delete(inlineCache.keys().next().value!);
+  }
+  return rewritten;
+}
+
+/** Most recently used rewrites; map bytes are re-read before sharing a result. */
+const inlineCache = new Map<
+  string,
+  {
+    source: string;
+    sourceFile: string | undefined;
+    match: RegExpExecArray | null;
+    json: string | null;
+    rewritten: string;
+  }
+>();
+
+/**
+ * Trailing `//# sourceMappingURL=<url>` (or legacy `//@`) magic comment.
+ * Anchored at end of text through any trailing whitespace, so it matches the
+ * last comment whether tsgo emitted it with a newline, none, or a CRLF line
+ * ending.
+ */
+const SOURCE_MAPPING_URL = /\/\/[#@] sourceMappingURL=([^\r\n]*)[ \t\r\n]*$/;
+
+/**
+ * Locate a real trailing line comment without treating string/regex text as
+ * code.
+ */
+function trailingSourceMapComment(source: string): RegExpExecArray | null {
+  const candidate = SOURCE_MAPPING_URL.exec(source);
+  if (candidate === null) return null;
+  let recognized = false;
+  try {
+    const lexer = tokenizer(source, {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      onComment(block, _text, start) {
+        if (!block && start === candidate.index) recognized = true;
+      },
+    });
+    while (lexer.getToken().type !== tokTypes.eof) {
+      // Lexing supplies comment boundaries without allocating an AST.
+    }
+  } catch {
+    // Optional mapping cannot replace the actual loader's syntax diagnostics.
+    return null;
+  }
+  return recognized ? candidate : null;
+}
+function rewrite(
+  source: string,
+  emittedFile: string,
+  sourceFile: string | undefined,
+  match: RegExpExecArray | null,
+  json: string | null,
+): string {
+  if (match === null) {
+    return source;
+  }
+  const url = match[1]!.trim();
+  if (url.length === 0) {
+    return source;
+  }
+  if (json === null) {
+    // The referenced map cannot be read (an external ref whose sibling is
+    // missing). Strip the dangling comment so Node does not cache the script
+    // with `data: null` and misattribute coverage; leave an already-inline
+    // `data:` map untouched since it is self-contained.
+    return url.startsWith("data:")
+      ? source
+      : source.slice(0, match.index).replace(/\r?\n$/, "");
+  }
+  const inlined = inlineComment(json, emittedFile, sourceFile);
+  if (inlined === null) {
+    return source;
+  }
+  return source.slice(0, match.index) + inlined;
+}
+
+/** Read the raw map JSON from a `data:` URI or a sibling map file. */
+function readMapJson(url: string, emittedFile: string): string | null {
+  if (url.startsWith("data:")) {
+    return decodeDataUri(url);
+  }
+  const direct = path.resolve(path.dirname(emittedFile), url);
+  const fromRef = readFileOrNull(direct);
+  if (fromRef !== null) {
+    return fromRef;
+  }
+  // tsgo names the comment after the emit basename; fall back to the canonical
+  // sibling path when the comment's relative form does not resolve on disk.
+  return readFileOrNull(`${emittedFile}.map`);
+}
+
+/** Decode a `data:application/json[;base64],...` source-map URI to its JSON. */
+function decodeDataUri(url: string): string | null {
+  const comma = url.indexOf(",");
+  if (comma === -1) {
+    return null;
+  }
+  const meta = url.slice(0, comma);
+  if (!meta.includes("application/json")) {
+    return null;
+  }
+  const payload = url.slice(comma + 1);
+  try {
+    return meta.includes(";base64")
+      ? Buffer.from(payload, "base64").toString("utf8")
+      : decodeURIComponent(payload);
+  } catch {
+    return null;
+  }
+}
+
+/** Parse the map, absolutize its `sources`, and re-encode it as a `data:` URI. */
+function inlineComment(
+  json: string,
+  emittedFile: string,
+  sourceFile: string | undefined,
+): string | null {
+  let map: {
+    sources?: unknown;
+    sourceRoot?: unknown;
+    [key: string]: unknown;
+  };
+  try {
+    map = JSON.parse(json) as typeof map;
+  } catch {
+    return null;
+  }
+  if (map === null || typeof map !== "object" || Array.isArray(map)) {
+    return null;
+  }
+  try {
+    absolutizeMap(map, path.dirname(emittedFile), sourceFile);
+  } catch {
+    // A URL root that cannot resolve its relative entries must retain the
+    // original metadata rather than silently become a native path.
+    return null;
+  }
+  const encoded = Buffer.from(JSON.stringify(map), "utf8").toString("base64");
+  return `//# sourceMappingURL=data:application/json;charset=utf-8;base64,${encoded}`;
+}
+
+/**
+ * Normalize each embedded map without inventing root-level sources for an
+ * index.
+ */
+function absolutizeMap(
+  map: { sources?: unknown; sourceRoot?: unknown; [key: string]: unknown },
+  mapDir: string,
+  sourceFile: string | undefined,
+): void {
+  if (Array.isArray(map.sections)) {
+    for (const section of map.sections) {
+      const child: unknown = section?.map;
+      if (child === null || typeof child !== "object" || Array.isArray(child))
+        throw new Error("unsupported external source-map section");
+      // Sections can describe different originals; use each map's own anchor.
+      absolutizeMap(child as typeof map, mapDir, undefined);
+    }
+  } else {
+    map.sources = absolutizeSources(map, mapDir, sourceFile);
+    // Absolute source URLs no longer use their former relative root.
+    delete map.sourceRoot;
+  }
+}
+
+/**
+ * Map each entry of the source map's `sources` to an absolute `file://` URL.
+ *
+ * Tsgo's per-file emit is 1:1, so a single source is the served file itself and
+ * resolves to the real on-disk `sourceFile` the serve path already knows — the
+ * most reliable anchor. A map that somehow carries several sources (or is
+ * consumed without a known source file) has each relative entry resolved
+ * against the map's own directory and `sourceRoot`, exactly where tsgo computed
+ * them from; entries that are already absolute URLs pass through unchanged.
+ */
+function absolutizeSources(
+  map: { sources?: unknown; sourceRoot?: unknown },
+  mapDir: string,
+  sourceFile: string | undefined,
+): string[] {
+  const sources = Array.isArray(map.sources) ? map.sources : [];
+  if (sources.length === 1 && sourceFile !== undefined) {
+    return [pathToFileURL(sourceFile).href];
+  }
+  const sourceRoot = typeof map.sourceRoot === "string" ? map.sourceRoot : "";
+  return sources.map((entry) => {
+    if (typeof entry !== "string") {
+      return String(entry);
+    }
+    if (path.isAbsolute(entry)) {
+      return pathToFileURL(entry).href;
+    }
+    if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(entry)) {
+      return entry;
+    }
+    if (
+      !path.isAbsolute(sourceRoot) &&
+      /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(sourceRoot)
+    ) {
+      return new URL(
+        entry,
+        sourceRoot.endsWith("/") ? sourceRoot : `${sourceRoot}/`,
+      ).href;
+    }
+    return pathToFileURL(path.resolve(mapDir, sourceRoot, entry)).href;
+  });
+}
+
+function readFileOrNull(file: string): string | null {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}