ts-node-pack 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-node-pack",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Pack a TypeScript package into a Node-compatible npm tarball without modifying the source tree",
   "keywords": [
     "cli",
@@ -26,13 +26,13 @@
   "exports": {
     ".": "./src/index.js"
   },
-  "engines": {
-    "node": ">=20"
-  },
-  "packageManager": "pnpm@10.33.0",
   "dependencies": {
     "npm-packlist": "^10.0.4",
     "ts-blank-space": "^0.8.0"
   },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@10.33.0",
   "types": "./src/index.d.ts"
 }

package/src/index.d.ts

@@ -9,46 +9,6 @@ export interface TsNodePackOptions {
  * Returns the path to the .tgz file (or the staging dir if --emit-only).
  */
 export declare function tsNodePack(packageDir: string, options?: TsNodePackOptions): Promise<string>;
-/**
- * Rewrite .ts/.tsx extensions to .js in relative import/export specifiers.
- *
- * Why regex is sound here:
- *
- *   The input is exclusively tsc-generated .d.ts files, not arbitrary source.
- *   tsc emits a highly constrained subset of syntax in declarations:
- *
- *   - Import/export specifiers are always single-line string literals.
- *   - Specifiers are always wrapped in matching quotes (' or ").
- *   - Relative paths always start with ./ or ../ (tsc never normalizes these).
- *   - No template literals, concatenation, or computed specifiers appear.
- *   - The only keywords introducing module specifiers are `from`, `import`,
- *     and `import()`.
- *
- *   Because the grammar of specifiers in .d.ts output is regular (a finite
- *   set of keyword prefixes + a quoted string literal), regex matches it
- *   exactly — no ambiguity, no context-sensitivity, no false positives.
- *
- *   If tsc ever adds native .d.ts rewriting (TypeScript#56556), this
- *   function becomes a no-op: the `if (rewritten !== original)` guard
- *   in rewriteDtsFiles means no file is touched.
- *
- * Handles:
- *  - Named/default/type imports:  import { x } from './foo.js'
- *  - Re-exports:                  export { x } from './foo.js'
- *  - Star re-exports:             export * from './foo.js'
- *  - Side-effect imports:         import './foo.js'
- *  - Dynamic imports:             import('./foo.js')
- *  - .tsx extensions:             import './component.js'
- *
- * Does NOT rewrite (by design):
- *  - Non-relative specifiers:     import 'lodash'
- *  - Already-.js specifiers:      import './foo.js'
- *  - import.meta.url:             not a module specifier
- *  - require():                   not valid in ESM .d.ts
- *  - Bare string literals:        const x = './foo.ts'
- */
-export declare const TS_SPECIFIER_PATTERNS: RegExp[];
-export declare function rewriteTsSpecifiers(content: any): any;
 /**
  * Resolve `workspace:` protocol specifiers in the package's dependency
  * fields to concrete versions, matching yarn-berry and pnpm behavior.

package/src/index.js

@@ -15,6 +15,7 @@ import { basename, dirname, join, relative, resolve } from "node:path";
 import { promisify } from "node:util";
 import packlist from "npm-packlist";
 import tsBlankSpace from "ts-blank-space";
+import { TS_SPECIFIER_PATTERNS, rewriteTsSpecifiers } from "./rewrite-specifiers.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -45,7 +46,7 @@ export async function tsNodePack(
   log(`Package: ${pkgJson.name}@${pkgJson.version}`);
 
   const tsconfigPath = resolveTsconfig(packageDir, tsconfig);
-  log(`Using tsconfig: ${tsconfigPath}`);
+  if (tsconfigPath) log(`Found tsconfig: ${tsconfigPath}`);
 
   // ── Phase 2: Create staging directory ─────────────────────────────────
   log("Phase 2: Creating staging directory...");
@@ -55,99 +56,94 @@ export async function tsNodePack(
   log(`Staging: ${stagingDir}`);
 
   try {
-    // ── Phase 3: Generate derived tsconfig ────────────────────────────────
-    // Written inside the temp dir — never touches the source tree.
-    // `extends` takes an absolute path; paths defined by the base tsconfig
-    // (include/files/exclude/rootDir/paths) resolve relative to the base
-    // config's own location, which is still inside packageDir, so globs
-    // continue to work.
-    log("Phase 3: Generating derived tsconfig...");
-    const emitConfigPath = join(tmpDir, "tsconfig.emit.json");
-
-    // Because the emit config lives outside packageDir, tsc's typeRoots
-    // walk-up (which starts at the config's directory) can't reach
-    // packageDir/node_modules/@types. Pin typeRoots explicitly when that
-    // directory exists so entries named in the base config's `types`
-    // field — e.g. `types: ["node"]` — can be resolved. TS 6.0 made this
-    // explicit opt-in (no more auto-inclusion of every @types package),
-    // which surfaces the missing resolution as a clear TS2688 error
-    // rather than silent "Cannot find module 'node:util'".
-    const atTypesDir = join(packageDir, "node_modules", "@types");
-    const hasAtTypes = existsSync(atTypesDir);
-
-    const emitConfig = {
-      extends: tsconfigPath,
-      compilerOptions: {
-        // Force rootDir so emit preserves the source layout — otherwise
-        // tsc infers the common ancestor and strips the `src/` prefix,
-        // breaking `main`/`exports` that reference `./src/...`.
-        rootDir: packageDir,
-        outDir: stagingDir,
-        declaration: true,
-        // ts-blank-space handles .js emit (Phase 6); tsc only emits .d.ts.
-        emitDeclarationOnly: true,
-        // Extract types from JS+JSDoc sources in mixed packages.
-        allowJs: true,
-        noEmit: false,
-        // Incremental/composite would try to write a .tsbuildinfo whose
-        // path tsc computes relative to the base config, producing
-        // garbled paths when our outDir crosses directory trees.
-        incremental: false,
-        composite: false,
-        tsBuildInfoFile: null,
-        ...(hasAtTypes ? { typeRoots: [atTypesDir] } : {}),
-      },
-    };
-    await writeFile(emitConfigPath, JSON.stringify(emitConfig, null, 2) + "\n");
-
-    // ── Phase 4: Copy the npm-packlist into staging ──────────────────────
+    // ── Phase 3: Copy the npm-packlist into staging ──────────────────────
     // `npm-packlist` is the same file-enumeration engine `npm pack` uses
     // internally. It applies `files`, `.npmignore`, the npm default
     // includes (package.json, README*, LICENSE*) and default excludes
     // (.git, node_modules, ...) — so the staging directory ends up as a
     // faithful mirror of whatever `npm pack` would have produced from
-    // the source tree, minus our downstream transforms (ts-blank-space,
-    // declaration emit, specifier rewrite).
-    log("Phase 4: Enumerating package files via npm-packlist...");
-    // npm-packlist's tree-based API (v7+) expects a node with `path` +
-    // parsed `package.json`. We fabricate a minimal tree rather than
-    // pulling in @npmcli/arborist — we don't need bundled-dependency
-    // resolution, workspace walking, or the rest of arborist's
-    // machinery, just the pack-file list.
+    // the source tree, minus our downstream transforms.
     //
-    // `isProjectRoot: true` sends npm-packlist down the
-    // "root package" branch of `gatherBundles`, which looks only at
-    // bundleDependencies (missing here, so no-op). Without this, it
-    // takes the "bundled dep of some other project" branch and tries
-    // to walk `edgesOut` — which doesn't exist on our hand-built tree.
+    // `isProjectRoot: true` sends npm-packlist down its "root package"
+    // branch — without it, it tries to walk `edgesOut` which doesn't
+    // exist on our hand-built tree (no @npmcli/arborist).
+    log("Phase 3: Enumerating package files via npm-packlist...");
     const packFiles = await packlist({
       path: packageDir,
       package: pkgJson,
       isProjectRoot: true,
     });
-    // Pre-create every parent directory serially (mkdir on the same
-    // path from multiple concurrent calls can race), then copy files
-    // in parallel.
-    const dirs = new Set        (
-      packFiles.map((rel) => dirname(join(stagingDir, rel))),
-    );
+    // Pre-create unique parent dirs serially (concurrent mkdir on the
+    // same path can race on some filesystems), then copy in parallel.
+    const dirs = new Set        (packFiles.map((rel) => dirname(join(stagingDir, rel))));
     for (const d of dirs) await mkdir(d, { recursive: true });
     await Promise.all(
-      packFiles.map((rel) =>
-        copyFile(join(packageDir, rel), join(stagingDir, rel)),
-      ),
+      packFiles.map((rel) => copyFile(join(packageDir, rel), join(stagingDir, rel))),
     );
     log(`Copied ${packFiles.length} file(s) into staging`);
 
-    // ── Phase 5: Emit declarations via tsc ──────────────────────────────
-    // tsc reads sources from packageDir (the base config's include
-    // resolves there) and writes .d.ts files into stagingDir via outDir.
-    // The copies from Phase 4 are left alone — tsc's outputs land
-    // alongside them. tsc may emit declarations for files outside the
-    // `files` array (e.g. test/); those won't make it into the final
-    // tarball because npm pack only ships what `files` references.
-    log("Phase 5: Emitting .d.ts files via tsc...");
-    await runTsc(emitConfigPath, packageDir, log);
+    // ── Phase 4: Decide whether to run tsc, generate config if so ────────
+    // Three conditions trigger declaration emit:
+    //   1. user passed --tsconfig (explicit opt-in)
+    //   2. tsconfig.build.json exists (agoric convention for opt-in)
+    //   3. any source contains .ts/.tsx/.mts (we'd be stripping them
+    //      anyway, and probably want their declarations)
+    // For pure JS+JSDoc packages with only `tsconfig.json` and no .ts
+    // sources, this skips tsc entirely — matching what `npm pack` would
+    // have done before ts-node-pack: ship .js files, no .d.ts.
+    const hasTsSources = packFiles.some(
+      (f) => /\.(ts|tsx|mts)$/.test(f) && !/\.d\.(ts|mts)$/.test(f),
+    );
+    const isExplicitOptIn =
+      tsconfigPath !== null &&
+      (tsconfig !== undefined || basename(tsconfigPath) === "tsconfig.build.json");
+    const shouldRunTsc = tsconfigPath !== null && (isExplicitOptIn || hasTsSources);
+
+    if (shouldRunTsc) {
+      log("Phase 4: Generating derived tsconfig...");
+      const emitConfigPath = join(tmpDir, "tsconfig.emit.json");
+      // tsc's typeRoots walk-up starts at the config's directory, so it
+      // can't reach packageDir/node_modules/@types from our temp-dir
+      // location. Pin typeRoots when that directory exists. (TS 6.0
+      // surfaces the missing resolution as TS2688 instead of the silent
+      // "Cannot find module 'node:util'" cascade of earlier versions.)
+      const atTypesDir = join(packageDir, "node_modules", "@types");
+      const hasAtTypes = existsSync(atTypesDir);
+      const emitConfig = {
+        extends: tsconfigPath,
+        compilerOptions: {
+          // Force rootDir so emit preserves the source layout —
+          // otherwise tsc infers the common ancestor and strips the
+          // `src/` prefix, breaking `main`/`exports` that reference
+          // `./src/...`.
+          rootDir: packageDir,
+          outDir: stagingDir,
+          declaration: true,
+          // ts-blank-space handles .js emit (Phase 6); tsc only emits .d.ts.
+          emitDeclarationOnly: true,
+          // Extract types from JS+JSDoc sources in mixed packages.
+          allowJs: true,
+          noEmit: false,
+          // Incremental/composite write a .tsbuildinfo whose path tsc
+          // computes relative to the base config, producing garbled
+          // paths when our outDir crosses directory trees.
+          incremental: false,
+          composite: false,
+          tsBuildInfoFile: null,
+          ...(hasAtTypes ? { typeRoots: [atTypesDir] } : {}),
+        },
+      };
+      await writeFile(emitConfigPath, JSON.stringify(emitConfig, null, 2) + "\n");
+
+      log("Phase 5: Emitting .d.ts files via tsc...");
+      await runTsc(emitConfigPath, packageDir, log);
+    } else {
+      log(
+        tsconfigPath === null
+          ? "Phase 4-5: Skipping tsc (no tsconfig found; pure-JS package)"
+          : "Phase 4-5: Skipping tsc (no .ts sources and no tsconfig.build.json opt-in)",
+      );
+    }
 
     // ── Phase 6: Strip types and rewrite specifiers ─────────────────────
     // Single-pass transform of every staging file that could contain a
@@ -157,10 +153,7 @@ export async function tsNodePack(
     // ts-blank-space preserves line and column positions, so no
     // sourcemaps are needed for debugging.
     log("Phase 6: Stripping types and rewriting specifiers...");
-    const { strippedCount, rewrittenCount } = await processStagingFiles(
-      stagingDir,
-      log,
-    );
+    const { strippedCount, rewrittenCount } = await processStagingFiles(stagingDir, log);
     log(
       `Stripped ${strippedCount} type-annotated file(s); rewrote ${rewrittenCount} other file(s)`,
     );
@@ -173,16 +166,9 @@ export async function tsNodePack(
     // packages to publish), then flip entry paths and strip dev-only
     // fields.
     log("Phase 7: Rewriting package.json...");
-    const resolvedPkg = await resolveWorkspaceDependencies(
-      pkgJson,
-      packageDir,
-      log,
-    );
+    const resolvedPkg = await resolveWorkspaceDependencies(pkgJson, packageDir, log);
     const rewrittenPkg = rewritePackageJson(resolvedPkg);
-    await writeFile(
-      join(stagingDir, "package.json"),
-      JSON.stringify(rewrittenPkg, null, 2) + "\n",
-    );
+    await writeFile(join(stagingDir, "package.json"), JSON.stringify(rewrittenPkg, null, 2) + "\n");
 
     // ── Phase 8: Validate ─────────────────────────────────────────────────
     log("Phase 8: Validating...");
@@ -191,7 +177,7 @@ export async function tsNodePack(
     // ── Phase 9: Pack ─────────────────────────────────────────────────────
     if (!emitOnly) {
       log("Phase 9: Packing...");
-      const tgzPath = await pack(stagingDir, log);
+      const tgzPath = await pack(stagingDir);
       const tgzName = basename(tgzPath);
       const dest = join(process.cwd(), tgzName);
       await copyFile(tgzPath, dest);
@@ -214,7 +200,12 @@ export async function tsNodePack(
 
 // ── Phase helpers ──────────────────────────────────────────────────────────
 
-function resolveTsconfig(packageDir, tsconfigOption) {
+/**
+ * Find the tsconfig to extend, or null if the package has no TypeScript
+ * config at all (pure JS package). The `--tsconfig` flag is the one
+ * explicit case where missing-config is fatal.
+ */
+function resolveTsconfig(packageDir, tsconfigOption)                {
   if (tsconfigOption) {
     const p = resolve(packageDir, tsconfigOption);
     if (!existsSync(p)) {
@@ -222,14 +213,11 @@ function resolveTsconfig(packageDir, tsconfigOption) {
     }
     return p;
   }
-
   const buildConfig = join(packageDir, "tsconfig.build.json");
   if (existsSync(buildConfig)) return buildConfig;
-
   const defaultConfig = join(packageDir, "tsconfig.json");
   if (existsSync(defaultConfig)) return defaultConfig;
-
-  throw new Error(`No tsconfig found in ${packageDir}. Provide one with --tsconfig.`);
+  return null;
 }
 
 /**
@@ -314,18 +302,14 @@ async function processStagingFiles(stagingDir, log) {
       });
       if (errors.length > 0) {
         throw new Error(
-          "ts-blank-space rejected non-erasable TypeScript:\n  " +
-            errors.join("\n  "),
+          "ts-blank-space rejected non-erasable TypeScript:\n  " + errors.join("\n  "),
         );
       }
     }
     content = rewriteTsSpecifiers(content);
 
     if (isTs || isMts) {
-      const destPath = srcPath.replace(
-        isMts ? /\.mts$/ : /\.ts$/,
-        isMts ? ".mjs" : ".js",
-      );
+      const destPath = srcPath.replace(isMts ? /\.mts$/ : /\.ts$/, isMts ? ".mjs" : ".js");
       await writeFile(destPath, content);
       await unlink(srcPath);
       strippedCount++;
@@ -339,70 +323,6 @@ async function processStagingFiles(stagingDir, log) {
   return { strippedCount, rewrittenCount };
 }
 
-/**
- * Rewrite .ts/.tsx extensions to .js in relative import/export specifiers.
- *
- * Why regex is sound here:
- *
- *   The input is exclusively tsc-generated .d.ts files, not arbitrary source.
- *   tsc emits a highly constrained subset of syntax in declarations:
- *
- *   - Import/export specifiers are always single-line string literals.
- *   - Specifiers are always wrapped in matching quotes (' or ").
- *   - Relative paths always start with ./ or ../ (tsc never normalizes these).
- *   - No template literals, concatenation, or computed specifiers appear.
- *   - The only keywords introducing module specifiers are `from`, `import`,
- *     and `import()`.
- *
- *   Because the grammar of specifiers in .d.ts output is regular (a finite
- *   set of keyword prefixes + a quoted string literal), regex matches it
- *   exactly — no ambiguity, no context-sensitivity, no false positives.
- *
- *   If tsc ever adds native .d.ts rewriting (TypeScript#56556), this
- *   function becomes a no-op: the `if (rewritten !== original)` guard
- *   in rewriteDtsFiles means no file is touched.
- *
- * Handles:
- *  - Named/default/type imports:  import { x } from './foo.js'
- *  - Re-exports:                  export { x } from './foo.js'
- *  - Star re-exports:             export * from './foo.js'
- *  - Side-effect imports:         import './foo.js'
- *  - Dynamic imports:             import('./foo.js')
- *  - .tsx extensions:             import './component.js'
- *
- * Does NOT rewrite (by design):
- *  - Non-relative specifiers:     import 'lodash'
- *  - Already-.js specifiers:      import './foo.js'
- *  - import.meta.url:             not a module specifier
- *  - require():                   not valid in ESM .d.ts
- *  - Bare string literals:        const x = './foo.ts'
- */
-// Three shapes for a relative TypeScript specifier in a string literal:
-//   1. `from './foo.js'`         — named/default/type imports, re-exports
-//   2. `import './foo.js'`       — bare side-effect imports
-//   3. `import('./foo.js')`      — dynamic imports
-//
-// The extension capture group matches `ts`, `tsx`, or `mts`. Rewriting
-// turns `.ts`/`.tsx` into `.js` and `.mts` into `.mjs`, matching the
-// output extensions ts-blank-space produces in Phase 6.
-//
-// Used both to rewrite specifiers and (in the validator) to detect any
-// specifier that slipped through. Must stay in sync with each other.
-export const TS_SPECIFIER_PATTERNS = [
-  /(from\s*['"])(\.\.?\/[^'"]*?)\.(tsx?|mts)(['"])/g,
-  /(import\s+['"])(\.\.?\/[^'"]*?)\.(tsx?|mts)(['"])/g,
-  /(import\s*\(\s*['"])(\.\.?\/[^'"]*?)\.(tsx?|mts)(['"]\s*\))/g,
-];
-
-export function rewriteTsSpecifiers(content) {
-  for (const pattern of TS_SPECIFIER_PATTERNS) {
-    content = content.replace(pattern, (_m, pre, path, ext, post) =>
-      pre + path + (ext === "mts" ? ".mjs" : ".js") + post,
-    );
-  }
-  return content;
-}
-
 const DEP_FIELDS_WITH_WORKSPACE = [
   "dependencies",
   "peerDependencies",
@@ -481,9 +401,7 @@ async function findWorkspaceRoot(startDir) {
   let dir = startDir;
   while (true) {
     try {
-      const pkg = JSON.parse(
-        await readFile(join(dir, "package.json"), "utf8"),
-      );
+      const pkg = JSON.parse(await readFile(join(dir, "package.json"), "utf8"));
       if (pkg.workspaces) return dir;
     } catch {
       // Missing or unreadable package.json — not the root, keep going.
@@ -495,9 +413,7 @@ async function findWorkspaceRoot(startDir) {
 }
 
 async function buildWorkspaceVersionMap(workspaceRoot) {
-  const rootPkg = JSON.parse(
-    await readFile(join(workspaceRoot, "package.json"), "utf8"),
-  );
+  const rootPkg = JSON.parse(await readFile(join(workspaceRoot, "package.json"), "utf8"));
   const patterns           = Array.isArray(rootPkg.workspaces)
     ? rootPkg.workspaces
     : rootPkg.workspaces?.packages || [];
@@ -507,9 +423,7 @@ async function buildWorkspaceVersionMap(workspaceRoot) {
     const dirs = await expandWorkspacePattern(workspaceRoot, pattern);
     for (const d of dirs) {
       try {
-        const pkg = JSON.parse(
-          await readFile(join(d, "package.json"), "utf8"),
-        );
+        const pkg = JSON.parse(await readFile(join(d, "package.json"), "utf8"));
         if (pkg.name && pkg.version) map.set(pkg.name, pkg.version);
       } catch {
         // Missing or malformed sibling package.json — skip.
@@ -546,9 +460,7 @@ async function expandWorkspacePattern(workspaceRoot, pattern) {
         }
       } else if (part.includes("*")) {
         const regex = new RegExp(
-          "^" +
-            part.replace(/[.+^$()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") +
-            "$",
+          "^" + part.replace(/[.+^$()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$",
         );
         try {
           const entries = await readdir(base, { withFileTypes: true });
@@ -673,9 +585,7 @@ async function validate(stagingDir, pkg, log) {
     // false positives. Comment stripping here is intentionally coarse
     // (doesn't understand strings-containing-comment-markers) — good enough
     // for tsc-emitted output, where comments are well-behaved.
-    const content = raw
-      .replace(/\/\*[\s\S]*?\*\//g, "")
-      .replace(/(^|[^:])\/\/.*$/gm, "$1");
+    const content = raw.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1");
     const relPath = relative(stagingDir, filePath);
 
     for (const pattern of TS_SPECIFIER_PATTERNS) {
@@ -751,7 +661,7 @@ function collectExportsRefs(value, refs) {
   }
 }
 
-async function pack(stagingDir, log) {
+async function pack(stagingDir) {
   const { stdout } = await execFileAsync("npm", ["pack"], {
     cwd: stagingDir,
   });

package/src/rewrite-specifiers.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @file Rewrite relative TypeScript specifiers to JavaScript ones.
+ *
+ * The input grammar is intentionally narrow: a relative path (`./` or
+ * `../`) ending in `.ts`, `.tsx`, or `.mts`, embedded in one of six
+ * specific syntactic contexts. The output replaces the extension with
+ * `.js` (for `.ts`/`.tsx`) or `.mjs` (for `.mts`), matching what
+ * `ts-blank-space` produces in the strip phase.
+ *
+ * Why regex is sound here:
+ *
+ *   The inputs are tsc-emitted `.d.ts` declaration files and JS sources
+ *   stripped of types — both highly constrained subsets of JavaScript:
+ *
+ *   - Import/export specifiers are always single-line string literals.
+ *   - Specifiers are always wrapped in matching quotes (' or ").
+ *   - Relative paths always start with `./` or `../`.
+ *   - No template literals, concatenation, or computed specifiers appear.
+ *
+ *   Because the grammar of relative specifiers in this input is regular
+ *   (a finite set of keyword prefixes + a quoted string literal), regex
+ *   matches it exactly with no false positives — provided the patterns
+ *   below stay in sync with each other and the validator that uses them.
+ */
+export declare const TS_SPECIFIER_PATTERNS: RegExp[];
+/**
+ * Apply every pattern in TS_SPECIFIER_PATTERNS to `content`, rewriting
+ * each matched relative TypeScript specifier to its corresponding
+ * JavaScript form. Returns the transformed string; the input is not
+ * mutated.
+ */
+export declare function rewriteTsSpecifiers(content: string): string;

package/src/rewrite-specifiers.js

@@ -0,0 +1,67 @@
+/**
+ * @file Rewrite relative TypeScript specifiers to JavaScript ones.
+ *
+ * The input grammar is intentionally narrow: a relative path (`./` or
+ * `../`) ending in `.ts`, `.tsx`, or `.mts`, embedded in one of six
+ * specific syntactic contexts. The output replaces the extension with
+ * `.js` (for `.ts`/`.tsx`) or `.mjs` (for `.mts`), matching what
+ * `ts-blank-space` produces in the strip phase.
+ *
+ * Why regex is sound here:
+ *
+ *   The inputs are tsc-emitted `.d.ts` declaration files and JS sources
+ *   stripped of types — both highly constrained subsets of JavaScript:
+ *
+ *   - Import/export specifiers are always single-line string literals.
+ *   - Specifiers are always wrapped in matching quotes (' or ").
+ *   - Relative paths always start with `./` or `../`.
+ *   - No template literals, concatenation, or computed specifiers appear.
+ *
+ *   Because the grammar of relative specifiers in this input is regular
+ *   (a finite set of keyword prefixes + a quoted string literal), regex
+ *   matches it exactly with no false positives — provided the patterns
+ *   below stay in sync with each other and the validator that uses them.
+ */
+
+// Six shapes for a relative TypeScript specifier in a string literal:
+//   1. `from './foo.js'`                — named/default/type imports, re-exports
+//   2. `import './foo.js'`              — bare side-effect imports
+//   3. `import('./foo.js')`             — dynamic imports
+//   4. `require('./foo.js')`            — CJS requires (in .cjs / .d.cts)
+//   5. `declare module './foo.js' {…}`  — TypeScript ambient declarations
+//   6. `/// <reference path="./foo.js"/>` — triple-slash directives
+//
+// The extension capture group matches `ts`, `tsx`, or `mts`. The
+// negative lookbehind `(?<!\.d)` prevents the regex from matching
+// `./foo.d.ts` (and `.d.mts`/`.d.cts`/`.d.tsx`), which are pure
+// declaration files that must keep their original specifiers.
+//
+// Word-boundary anchors (`\b`) on the keyword-leading patterns prevent
+// false positives on identifiers like `myfrom` or `customRequire`.
+//
+// Used both to rewrite specifiers and (in the validator) to detect any
+// specifier that slipped through. Patterns must stay in sync.
+export const TS_SPECIFIER_PATTERNS = [
+  /(\bfrom\s*['"])(\.\.?\/[^'"]*?)(?<!\.d)\.(tsx?|mts)(['"])/g,
+  /(\bimport\s+['"])(\.\.?\/[^'"]*?)(?<!\.d)\.(tsx?|mts)(['"])/g,
+  /(\bimport\s*\(\s*['"])(\.\.?\/[^'"]*?)(?<!\.d)\.(tsx?|mts)(['"]\s*\))/g,
+  /(\brequire\s*\(\s*['"])(\.\.?\/[^'"]*?)(?<!\.d)\.(tsx?|mts)(['"]\s*\))/g,
+  /(\bdeclare\s+module\s*['"])(\.\.?\/[^'"]*?)(?<!\.d)\.(tsx?|mts)(['"])/g,
+  /(<reference\s+path\s*=\s*['"])(\.\.?\/[^'"]*?)(?<!\.d)\.(tsx?|mts)(['"])/g,
+];
+
+/**
+ * Apply every pattern in TS_SPECIFIER_PATTERNS to `content`, rewriting
+ * each matched relative TypeScript specifier to its corresponding
+ * JavaScript form. Returns the transformed string; the input is not
+ * mutated.
+ */
+export function rewriteTsSpecifiers(content        )         {
+  for (const pattern of TS_SPECIFIER_PATTERNS) {
+    content = content.replace(
+      pattern,
+      (_m, pre, path, ext, post) => pre + path + (ext === "mts" ? ".mjs" : ".js") + post,
+    );
+  }
+  return content;
+}