ttsc 0.30.4 → 0.31.1

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

@@ -0,0 +1,309 @@
+import fs from "node:fs";
+
+import { EmitOwnershipIndex } from "../../../compiler/internal/EmitOwnershipIndex";
+import { RuntimeEmitProvenance } from "./RuntimeEmitProvenance";
+import type { RuntimeManifest } from "./RuntimeManifest";
+import { realPath } from "./realPath";
+
+/**
+ * Every checked entry emit this runtime may serve from, and the lookup that
+ * decides which of them owns a source file.
+ *
+ * A direct ttsx child inherits one manifest through `TTSX_RUNTIME_MANIFEST`;
+ * `ttsc/register` adds one per root it prepares. The inherited manifest is read
+ * lazily within this registry module instance. Successful or ordinary absent
+ * decoding is memoized; recognizable invalid-provenance errors are not cached
+ * and a later call repeats the read.
+ *
+ * An inherited manifest without actual emit provenance cannot be recovered from
+ * this process's unknown preparation inputs and is rejected explicitly.
+ * Registered callback results are copied on admission; caller mutation cannot
+ * replace the build metadata associated with an already-created ownership
+ * index.
+ *
+ * @evidence contracts/common.md#principled-implementation Inherited and registered manifests preserve preparation order; ownership indexes use actual compiler output-to-source observations, and an inherited build without valid provenance is rejected instead of inventing ownership from filenames.
+ * @evidence contracts/common.md#clear-and-simple-design One registry owns admission snapshots, environment decoding and build-to-source lookup; each manifest delegates output identity to EmitOwnershipIndex instead of duplicating reverse mapping in hooks.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Ownership follows recorded builds and filesystem identity, not basename guesses or a fallback to unchecked source execution.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain inherited versus discovered roots, caller-independent admission, lookup precedence and immutable-build index reuse; members remain separately documented without property tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Native fs reads and the shared real-path resolver feed EmitOwnershipIndex's filesystem identity boundary; protocol output separators remain manifest data rather than native case assumptions.
+ * @evidence contracts/performance.md#efficient-algorithms Admission copies and validates output/provenance/refusal entries and path text; inherited decoding reads uncapped JSON bytes and snapshots metadata. Lookup scans M manifests and delegates first-use index construction and native query work. Successful/ordinary absent environment decoding is memoized, while invalid-provenance throws can repeat those costs.
+ * @evidence contracts/performance.md#reuse-equivalent-work Each admitted build has an owned frozen metadata snapshot and one WeakMap index; the ordered manifest view is shared until another admission invalidates it, while newly prepared roots receive distinct snapshots and indexes.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources This registry instance retains its inherited snapshot, every registered root and ordered view without eviction; metadata/provenance/refusal bytes and index state grow with preparations while the instance remains reachable. It owns no directory handle or artifact deletion policy.
+ */
+export namespace RuntimeManifestRegistry {
+  let environmentManifestCache: RuntimeManifest | null | undefined;
+
+  /**
+   * Manifests of the roots this process prepared itself, in preparation order.
+   * Only registerManifest appends owned snapshots; nothing removes from it.
+   */
+  const registeredManifests: RuntimeManifest[] = [];
+
+  let manifestView: readonly RuntimeManifest[] | undefined;
+
+  /**
+   * Admit one checked preparation in order, detached from its caller's object.
+   * The registry copies and freezes the metadata, output names and source
+   * associations without freezing the caller's values. Later caller mutation
+   * cannot change the build served by an existing ownership index.
+   *
+   * Invalid metadata throws before admission; this function neither builds the
+   * project nor proves that its producer's source observations are
+   * trustworthy.
+   *
+   * @evidence contracts/common.md#principled-implementation Admission validates the manifest grammar and captures all serving metadata, output names, format options and source arrays as owned frozen values, so a cached index cannot be paired with a later caller replacement.
+   * @evidence contracts/common.md#clear-and-simple-design One explicit admission operation owns the transfer from a callback result to stable registry metadata; index construction and actual producer observation remain with their existing owners.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Only owned copies are frozen; neither a foreign object mutation nor a filename-based fallback supplies missing build provenance.
+   * @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain copying, order, caller mutation, validation failure and the distinction between representation and trustworthy producer observations.
+   * @evidence contracts/portability.md#os-neutral-implementation Admission preserves validated native path strings exactly; absolute filename grammar is delegated to RuntimeEmitProvenance without case folding or separator conversion.
+   * @evidence contracts/performance.md#efficient-algorithms Snapshot copying and validation visit output, provenance/source and refusal entries, with path/text processing and temporary entry-pair/array allocations. One snapshot is appended without rescanning older builds; fixed top-level field count does not bound association bytes.
+   * @evidence contracts/performance.md#reuse-equivalent-work An admitted snapshot supplies one stable identity to every ownership lookup; admission invalidates only the combined manifest view, and never reuses a previous build's callback result as a new preparation.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources This registry instance retains one owned metadata snapshot per preparation without eviction, growing with output/provenance/refusal entries and text while reachable. Supported caller arrays are copied rather than retained, and no native handle is acquired.
+   */
+  export function registerManifest(manifest: RuntimeManifest): void {
+    const captured = snapshotManifest(manifest);
+    if (
+      !isRuntimeManifestShape(captured) ||
+      !RuntimeEmitProvenance.isRecord(captured.emittedSources)
+    ) {
+      throw new Error(
+        "ttsx: checked preparation has invalid runtime manifest metadata",
+      );
+    }
+    registeredManifests.push(captured);
+    manifestView = undefined;
+  }
+
+  function environmentManifest(): RuntimeManifest | null {
+    if (environmentManifestCache !== undefined) {
+      return environmentManifestCache;
+    }
+    const file = process.env.TTSX_RUNTIME_MANIFEST;
+    if (file === undefined || file.length === 0) {
+      environmentManifestCache = null;
+      return environmentManifestCache;
+    }
+    let value: unknown;
+    try {
+      value = JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch {
+      environmentManifestCache = null;
+      return environmentManifestCache;
+    }
+    if (!isRuntimeManifestShape(value)) {
+      environmentManifestCache = null;
+    } else if (!RuntimeEmitProvenance.isRecord(value.emittedSources)) {
+      throw new Error(
+        "ttsx: inherited runtime manifest has no valid compiler emit provenance; prepare the entry again with this ttsc version",
+      );
+    } else {
+      environmentManifestCache = snapshotManifest(value as RuntimeManifest);
+    }
+    return environmentManifestCache;
+  }
+
+  /**
+   * Every checked entry emit available to this runtime, in ownership order. An
+   * unreadable or malformed inherited manifest contributes no entry.
+   *
+   * A recognizable build manifest without valid emit provenance throws an
+   * unsupported-manifest error rather than silently changing its serving lane.
+   * The returned view and build metadata are owned frozen snapshots, shared
+   * until a later registration adds another checked preparation.
+   *
+   * @evidence contracts/common.md#principled-implementation The inherited checked build precedes roots prepared here; malformed JSON contributes no manifest, while a recognizable build without actual emit provenance fails explicitly because its original preparation inputs are unavailable.
+   * @evidence contracts/common.md#clear-and-simple-design The accessor assembles and shares one ordered view of owned manifest snapshots without exposing its mutable registration array or lazy environment decoding.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The accessor supplies only the supported inherited and registered lanes and does not invent an unchecked fallback manifest.
+   * @evidence contracts/common.md#meaningful-documentation Native prose defines ordering, unreadable/malformed absence, explicit missing-provenance failure and frozen-view lifetime rather than merely repeating the return type.
+   * @evidence contracts/portability.md#os-neutral-implementation The inherited path is read through Node fs; returned manifests retain native build paths and protocol output spelling without separator or case conversion here.
+   * @evidence contracts/performance.md#efficient-algorithms View construction copies M manifest references on first access or after registration invalidates it. First inherited decoding also reads uncapped JSON and validates/copies entry/path text; successful or ordinary absent decoding is memoized, but recognizable invalid-provenance throws repeat the read on later calls.
+   * @evidence contracts/performance.md#reuse-equivalent-work Lazy decoding shares successful or ordinary absent inherited state within this module instance, not a process-wide registry singleton. Registration invalidates the ordered view without changing earlier snapshots; rejected provenance is not memoized.
+   *
+   * @evidence contracts/performance.md#bound-retention-and-release-resources First access acquires the instance-owned inherited snapshot/absence and frozen ordered view; registration replaces the view while callers may retain older returned arrays. Current metadata stays registry-owned without eviction, and this accessor opens no retained descriptor or running task.
+   */
+  export function runtimeManifests(): readonly RuntimeManifest[] {
+    const inherited = environmentManifest();
+    manifestView ??= Object.freeze(
+      inherited === null
+        ? [...registeredManifests]
+        : [inherited, ...registeredManifests],
+    );
+    return manifestView;
+  }
+
+  /**
+   * Find the manifest whose checked build emitted `real`, and that emit.
+   *
+   * A manifest's prepared root is matched first, by its recorded source, so a
+   * root keeps precedence over other preparations. Every match, including that
+   * root, requires the ownership index's actual compiler output-to-source
+   * observations and physical source identity. A file no manifest compiled gets
+   * `null` and belongs to another lane, however many emitted files share its
+   * name. Producer observations and immutable emit are trusted preparation
+   * premises, not authenticated current contents; unavailable or ambiguous
+   * provenance and native identity failures can throw rather than return null.
+   *
+   * @evidence contracts/common.md#principled-implementation A prepared entry gets first ownership lookup, but every match must come from actual emitted-source observations in its build index; neither recorded entry filenames nor matching output stems prove source membership.
+   * @evidence contracts/common.md#clear-and-simple-design Two explicit passes separate entry precedence from general build ownership, with one index helper owning memoized reverse mapping.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No basename fallback or unchecked-file substitution stands in for proof that a selected manifest compiled the requested source.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states prepared-entry precedence, trusted preparation premises, null lane selection and possible provenance/native identity exceptions without certifying current contents.
+   * @evidence contracts/portability.md#os-neutral-implementation realPath selects prepared-entry precedence and EmitOwnershipIndex establishes native source identity from the compiler observation; filename existence and OS-name case folding cannot certify ownership.
+   * @evidence contracts/performance.md#efficient-algorithms Two manifest passes enforce precedence without sorting, adding entry realpath and native source-query/text work. First use constructs each index from output/provenance/refusal entries with native output identity observations; inherited read/snapshot costs also apply before the passes. Later queries reuse that association index, not its native alias observations.
+   * @evidence contracts/performance.md#reuse-equivalent-work Immutable prepared emit permits one preindexed association record per manifest across import specifiers; query aliases remain fresh and a newly prepared build supplies a distinct manifest identity.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources WeakMap indexes follow retained manifest objects; this registry instance keeps registered snapshots and their association/refusal text without eviction while reachable. Current alias observations are call-local rather than a queried-spelling history; artifact storage and immutable-retention policy belong to preparation owners.
+   */
+  export function findEntryEmit(real: string): {
+    /** Proven owning output; a later missing file remains an output read error. */
+    emittedFile: string;
+
+    /** Checked build whose recorded associations established this ownership. */
+    manifest: RuntimeManifest;
+  } | null {
+    const manifests = runtimeManifests();
+    for (const candidate of manifests) {
+      if (
+        candidate.entrySource !== undefined &&
+        candidate.entryFile !== undefined &&
+        realPath(candidate.entrySource) === real
+      ) {
+        const emitted = ownershipIndex(candidate).find(real);
+        if (emitted !== null) {
+          return { emittedFile: emitted, manifest: candidate };
+        }
+      }
+    }
+    for (const candidate of manifests) {
+      const emitted = ownershipIndex(candidate).find(real);
+      if (emitted !== null) {
+        return { emittedFile: emitted, manifest: candidate };
+      }
+    }
+    return null;
+  }
+
+  /**
+   * The ownership index of one manifest's build, created on first use. The
+   * association record and immutable emit are trusted preparation premises, so
+   * one index can serve multiple import specifiers; this cache does not
+   * authenticate external artifact mutation. Query aliases are still resolved
+   * afresh by the index.
+   */
+  function ownershipIndex(manifest: RuntimeManifest): EmitOwnershipIndex {
+    let index = ownershipIndexes.get(manifest);
+    if (index === undefined) {
+      index = new EmitOwnershipIndex({
+        emitDir: manifest.emitDir,
+        outputs: manifest.outputs,
+        emittedSources: manifest.emittedSources,
+        emittedSourceProofFailures: manifest.emittedSourceProofFailures,
+        rootDir: manifest.rootDir,
+      });
+      ownershipIndexes.set(manifest, index);
+    }
+    return index;
+  }
+
+  const ownershipIndexes = new WeakMap<RuntimeManifest, EmitOwnershipIndex>();
+
+  /** Capture only owned arrays/records; callers retain their mutable originals. */
+  function snapshotManifest(manifest: RuntimeManifest): RuntimeManifest {
+    const {
+      outputs,
+      moduleOptions,
+      emittedSources,
+      emittedSourceProofFailures,
+      ...metadata
+    } = manifest;
+    return Object.freeze({
+      ...metadata,
+      ...(emittedSourceProofFailures !== null &&
+      typeof emittedSourceProofFailures === "object" &&
+      !Array.isArray(emittedSourceProofFailures)
+        ? {
+            emittedSourceProofFailures: Object.freeze(
+              Object.fromEntries(
+                Object.entries(emittedSourceProofFailures).filter(
+                  ([, reason]) => typeof reason === "string",
+                ),
+              ),
+            ),
+          }
+        : {}),
+      ...(outputs === undefined
+        ? {}
+        : {
+            outputs: Array.isArray(outputs)
+              ? Object.freeze([...outputs])
+              : outputs,
+          }),
+      ...(moduleOptions === undefined
+        ? {}
+        : {
+            moduleOptions:
+              moduleOptions !== null &&
+              typeof moduleOptions === "object" &&
+              !Array.isArray(moduleOptions)
+                ? Object.freeze({ ...moduleOptions })
+                : moduleOptions,
+          }),
+      emittedSources:
+        emittedSources !== null &&
+        typeof emittedSources === "object" &&
+        !Array.isArray(emittedSources)
+          ? Object.freeze(
+              Object.fromEntries(
+                Object.entries(emittedSources).map(([output, sources]) => [
+                  output,
+                  Array.isArray(sources)
+                    ? Object.freeze([...sources])
+                    : sources,
+                ]),
+              ),
+            )
+          : emittedSources,
+    });
+  }
+
+  function isRuntimeManifestShape(value: unknown): value is Omit<
+    RuntimeManifest,
+    "emittedSources"
+  > & {
+    emittedSources?: unknown;
+  } {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      return false;
+    }
+    const manifest = value as Record<string, unknown>;
+    for (const key of ["projectRoot", "rootDir", "emitDir", "depCacheDir"]) {
+      if (typeof manifest[key] !== "string") return false;
+    }
+    for (const key of ["entrySource", "entryFile", "orphanCacheDir"]) {
+      if (manifest[key] !== undefined && typeof manifest[key] !== "string") {
+        return false;
+      }
+    }
+    if (
+      manifest.outputs !== undefined &&
+      (!Array.isArray(manifest.outputs) ||
+        !manifest.outputs.every((output) => typeof output === "string"))
+    ) {
+      return false;
+    }
+    if (manifest.moduleOptions !== undefined) {
+      if (
+        manifest.moduleOptions === null ||
+        typeof manifest.moduleOptions !== "object" ||
+        Array.isArray(manifest.moduleOptions)
+      ) {
+        return false;
+      }
+      const options = manifest.moduleOptions as Record<string, unknown>;
+      for (const key of ["module", "target"]) {
+        if (options[key] !== undefined && typeof options[key] !== "string") {
+          return false;
+        }
+      }
+    }
+    return manifest.plugins === undefined || manifest.plugins === false;
+  }
+}

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

@@ -0,0 +1,275 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import type { OwningModuleOptions } from "./OwningModuleOptions";
+import { RuntimeFilesystem } from "./RuntimeFilesystem";
+
+/**
+ * The runtime's module format (ES module or CommonJS) for a TypeScript file.
+ * For supported checked-project settings, classification follows the pinned
+ * TypeScript-Go emit precedence; unowned sources use this runtime's nearest
+ * package-scope policy, not a full Node loader validation or syntax detector.
+ *
+ * The runtime serves compiled JavaScript under the `.ts` URL, and Node must be
+ * told the format of that JavaScript. Guessing from the text would disagree
+ * with the emit whenever a file's syntax and its configuration differ, so the
+ * answer comes from the extension, the owning project's options, and the
+ * package `type`, in the supported emit order. Unreadable or malformed present
+ * manifests use CommonJS/no-declaration here rather than reporting a package
+ * parse error; cached scope observations are not invalidated by later
+ * mutation.
+ *
+ * @evidence contracts/common.md#principled-implementation Extension, dependency package declaration and effective module/target determine supported checked-emit format in pinned upstream order; unowned sources use the runtime's nearest-scope CommonJS fallback policy without claiming full Node loader equivalence.
+ * @evidence contracts/common.md#clear-and-simple-design One classifier owns format policy with private option normalization and package-scope lookup helpers, keeping hooks from independently guessing authored syntax.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Documented compiler precedence replaces source-text sniffing; node_modules is the upstream package-metadata boundary rather than a hardcoded consumer exception.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain supported emit precedence, unowned-source and malformed-manifest policy, package override scope and cache invalidation limits.
+ * @evidence contracts/portability.md#os-neutral-implementation Native path.dirname/fs select package scopes; node_modules matching is upstream's exact protocol segment rather than a guessed filesystem case policy.
+ * @evidence contracts/performance.md#efficient-algorithms Classification processes filename/option text; uncached scope lookup walks ancestor paths with native stat/read and uncapped JSON-byte costs, then fills visited directory keys. Cached scope map access avoids new native reads but still processes path keys; no fixed wrapper count bounds native latency.
+ * @evidence contracts/performance.md#reuse-equivalent-work This module instance shares its first scope observation across default and explicit-declaration decisions. No watcher or invalidation revisits a changed manifest, so reuse relies on the caller's stable package-scope premise rather than tracking Node's independent loader state.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources packageTypeCache retains directory-key text and shared scope answers without eviction while this module instance remains reachable, growing with observed scopes. Native reads retain no descriptor, and this cache does not own loaded modules or their release.
+ */
+export namespace RuntimeModuleFormat {
+  /**
+   * Classify supported checked emit from configuration and package scope, never
+   * by sniffing emitted text or validating the full Node loader contract.
+   *
+   * The file extension is authoritative first (`.mts`/`.mjs` → module,
+   * `.cts`/`.cjs` → commonjs): tsgo records these in
+   * `GetImpliedNodeFormatForFile`, then its emit worker consumes that metadata
+   * or preserves the explicit extension for non-node module kinds.
+   *
+   * After that the decision belongs to the project that emitted the file, so
+   * `options` is the whole compiler-option pair tsgo consults, not just
+   * `module`: an absent `module` is NOT "ask Node", it is "derive the kind from
+   * `target`" (tsgo's `getEmitModuleKind`), and TypeScript 7 defaults `target`
+   * to the latest standard, which means ES modules. A source-shipping
+   * dependency under `node_modules` can override this with an explicit package
+   * `type` for every module kind. Otherwise only the `node*` family defers to
+   * the nearest package `type`.
+   *
+   * `options` is `null` when the caller has no recorded checked preparation for
+   * the file, as in the orphan-source lane. The runtime's package-scope policy
+   * applies: supported `type` decides, otherwise CommonJS is returned,
+   * including a present unreadable/malformed manifest.
+   *
+   * @evidence contracts/common.md#principled-implementation Authoritative extension wins, then a node_modules package's explicit declaration, then the owning compiler's effective kind and node-family scope rule; this preserves the format of checked emit instead of treating absent module as an unowned file.
+   * @evidence contracts/common.md#clear-and-simple-design The ordered classifier delegates package lookup and option defaulting to focused private helpers while keeping precedence visible in one function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No source sniffing or project-specific exception supplies a format; package overrides are constrained by the actual upstream source metadata boundary.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain supported extension/options precedence, dependency overrides and null ownership, including the runtime's CommonJS malformed-manifest fallback rather than certifying all Node loader behavior.
+   * @evidence contracts/portability.md#os-neutral-implementation Native ancestor traversal locates manifests; exact extension and node_modules protocol spelling are distinguished from filesystem case sensitivity.
+   * @evidence contracts/performance.md#efficient-algorithms Filename suffix/segment and option normalization process their text; at most one uncached ancestor scope walk adds native stat/read, manifest bytes and visited path-key storage. Both scope questions share the map answer, avoiding repeat native reads without making path work or latency constant.
+   * @evidence contracts/performance.md#reuse-equivalent-work Explicit-declaration and default consumers share the instance's first nearest-scope observation under stable package metadata; later filesystem mutation does not invalidate that answer, and owning project options still classify independently.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Native reads leave no retained handle; the namespace retains observed directory keys and scope answers without eviction while its instance remains reachable. Per-walk ancestor chains and decoded manifest data are temporary; this operation does not own emitted artifact storage.
+   */
+  export function moduleFormat(
+    filename: string,
+    options: OwningModuleOptions | null,
+  ): string {
+    if (filename.endsWith(".mts") || filename.endsWith(".mjs")) {
+      return "module";
+    }
+    if (filename.endsWith(".cts") || filename.endsWith(".cjs")) {
+      return "commonjs";
+    }
+    if (options === null) {
+      return nearestPackageType(filename);
+    }
+    // A package that states its `type` outright decides for the files inside it
+    // whatever the module kind is. This is where a source-shipping dependency's
+    // own declaration overrides the compiling project's `module`; see
+    // `declaredNodeModulesPackageType` for why `node_modules` bounds it.
+    const declared = declaredNodeModulesPackageType(filename);
+    if (declared !== null) {
+      return declared;
+    }
+    const kind = effectiveModuleKind(options);
+    if (
+      kind === "node16" ||
+      kind === "node18" ||
+      kind === "node20" ||
+      kind === "nodenext"
+    ) {
+      return nearestPackageType(filename);
+    }
+    if (kind === "commonjs") {
+      return "commonjs";
+    }
+    // Everything that remains (es2015 … esnext, and `preserve`, which keeps the
+    // authored ESM syntax verbatim) classifies as ECMAScript modules for
+    // supported project settings. This helper does not validate unsupported
+    // module values or certify that such a project reached successful emit.
+    return "module";
+  }
+
+  /**
+   * The `"type"` a `node_modules` package states for `filename`, or `null`.
+   *
+   * Tsgo's `GetImpliedNodeFormatForEmitWorker` consults a file's
+   * `packageJsonType` for **every** module kind, not just the `node*` family.
+   * So a source-shipping dependency that declares `"type": "commonjs"` is
+   * emitted as CommonJS even while the compiling project asks for `esnext`, and
+   * the mirror has to honour the same override or Node is handed the wrong
+   * format.
+   *
+   * Outside `node_modules` that field is empty for every module kind this
+   * override can change. `loadSourceFileMetaData` does fill it elsewhere — for
+   * a file whose extension does not itself state the format (anything but
+   * `.mts`, `.cts`, `.mjs`, `.cjs`) whose project sets `moduleResolution` to
+   * the `node16`…`nodenext` family — but `program.go` rejects that resolution
+   * unless `module` is in the same family, and for a `node*` `module` the
+   * package `type` is already the whole answer, which the caller's own `node*`
+   * branch produces. So answering from a manifest outside `node_modules` could
+   * only override the project's own `module` option, the very confusion this
+   * classifier exists to end.
+   */
+  function declaredNodeModulesPackageType(
+    filename: string,
+  ): "module" | "commonjs" | null {
+    if (!pathHasNodeModulesSegment(filename)) {
+      return null;
+    }
+    return declaredPackageType(filename);
+  }
+
+  /**
+   * Whether any path segment of `filename` is literally `node_modules`.
+   *
+   * Case-sensitive on every platform, because the upstream test this mirrors is
+   * a case-sensitive substring search and Node's own resolver recognises only
+   * the exact spelling. A directory named `Node_Modules` is a package store to
+   * neither of them, and must not become one here.
+   */
+  function pathHasNodeModulesSegment(filename: string): boolean {
+    return filename.split(/[\\/]/).includes("node_modules");
+  }
+
+  /**
+   * The `module` kind tsgo actually emits with, mirroring `getEmitModuleKind`:
+   * the declared `module` when there is one, and otherwise the kind implied by
+   * `target`. `"none"` is the spelling of an unset `module`, so it derives the
+   * same way.
+   */
+  function effectiveModuleKind(options: OwningModuleOptions): string {
+    const declared = (options.module ?? "").toLowerCase();
+    if (declared !== "" && declared !== "none") {
+      return declared;
+    }
+    const target = (options.target ?? "").toLowerCase();
+    if (target === "esnext") {
+      return "esnext";
+    }
+    const year = scriptTargetYear(target);
+    if (year === null) {
+      // An unset `target` is `ScriptTargetLatestStandard` upstream, well above the
+      // ES2022 boundary. Every other spelling lands here too: TypeScript 7 removed
+      // `ES5` and dropped `ES3` entirely, and its only remaining targets are
+      // year-numbered ones, so nothing that reaches emit derives CommonJS.
+      return "es2022";
+    }
+    if (year >= 2022) return "es2022";
+    if (year >= 2020) return "es2020";
+    return "es2015";
+  }
+
+  /**
+   * Year of an `ES<year>` script target, with `es6` normalized to its `es2015`
+   * synonym. Returns `null` when the spelling is not a year-numbered target,
+   * which the caller resolves to the modern default.
+   */
+  function scriptTargetYear(target: string): number | null {
+    if (target === "es6") {
+      return 2015;
+    }
+    const match = /^es(\d{4})$/.exec(target);
+    return match === null ? null : Number(match[1]);
+  }
+
+  /**
+   * One nearest package-scope observation for both format decisions. Values
+   * remain cached within this module instance without filesystem invalidation.
+   */
+  interface PackageScope {
+    /** Node's format when this scope owns an otherwise unclassified file. */
+    nodeType: "module" | "commonjs";
+
+    /** Explicit supported type declaration, or absence/invalidity. */
+    declaredType: "module" | "commonjs" | null;
+  }
+
+  const packageTypeCache = new Map<string, PackageScope>();
+
+  function nearestPackageType(filename: string): "module" | "commonjs" {
+    return packageScope(filename).nodeType;
+  }
+
+  function packageScope(filename: string): PackageScope {
+    let directory = path.dirname(filename);
+    const chain: string[] = [];
+    while (true) {
+      const cached = packageTypeCache.get(directory);
+      if (cached !== undefined) {
+        return rememberPackageType(chain, cached);
+      }
+      chain.push(directory);
+      const scope = readPackageType(directory);
+      if (scope !== null) {
+        return rememberPackageType(chain, scope);
+      }
+      const parent = path.dirname(directory);
+      if (parent === directory) {
+        return rememberPackageType(chain, {
+          nodeType: "commonjs",
+          declaredType: null,
+        });
+      }
+      directory = parent;
+    }
+  }
+
+  function rememberPackageType(
+    directories: readonly string[],
+    scope: PackageScope,
+  ): PackageScope {
+    for (const directory of directories) {
+      packageTypeCache.set(directory, scope);
+    }
+    return scope;
+  }
+
+  /** Read a present package scope; null means no regular manifest was found. */
+  function readPackageType(directory: string): PackageScope | null {
+    const manifestPath = path.join(directory, "package.json");
+    if (!RuntimeFilesystem.isFile(manifestPath)) {
+      return null;
+    }
+    try {
+      const parsed = JSON.parse(fs.readFileSync(manifestPath, "utf8")) as {
+        type?: unknown;
+      };
+      const declaredType =
+        parsed.type === "module" || parsed.type === "commonjs"
+          ? parsed.type
+          : null;
+      return {
+        nodeType: declaredType ?? "commonjs",
+        declaredType,
+      };
+    } catch {
+      return { nodeType: "commonjs", declaredType: null };
+    }
+  }
+
+  /**
+   * The `"type"` the nearest `package.json` states outright, or `null` when the
+   * nearest manifest omits it (or there is none).
+   *
+   * `nearestPackageType` applies the runtime's CommonJS default to a silent or
+   * unreadable/malformed manifest. This answers the narrower question "did a
+   * package actually say", which is what an override has to be built on: a
+   * manifest that says nothing must not out-vote the compiling project's own
+   * `module` option.
+   */
+  function declaredPackageType(filename: string): "module" | "commonjs" | null {
+    return packageScope(filename).declaredType;
+  }
+}