ts-node-pack 0.1.3 → 0.2.1

package/README.md

@@ -25,18 +25,19 @@ Requires Node ≥ 20 and TypeScript ≥ 5.7 available in the package being packe
 ## Usage
 
 ```sh
-ts-node-pack <packageDir> [--tsconfig <path>] [--emit-only] [--keep-temp] [--verbose]
+ts-node-pack <packageDir> [--tsconfig <path>] [--stage-to <dir>] [--skip-pack] [--force] [--verbose]
 ```
 
 | Flag                | Description                                                                                  |
 | ------------------- | -------------------------------------------------------------------------------------------- |
 | `--tsconfig <path>` | tsconfig to extend. Defaults to `tsconfig.build.json` if present, otherwise `tsconfig.json`. |
-| `--emit-only`       | Run emit + rewrites + validation, but skip `npm pack`. Prints the staging directory.         |
-| `--keep-temp`       | Do not delete the temporary staging directory on exit.                                       |
+| `--stage-to <dir>`  | Stage into `<dir>` instead of an auto-created temp dir. Caller owns its lifecycle.           |
+| `--skip-pack`       | Skip the final `npm pack` step. Requires `--stage-to`.                                       |
+| `--force`           | With `--stage-to`, clear `<dir>` if it already has contents.                                 |
 | `-v`, `--verbose`   | Log each pipeline phase to stderr.                                                           |
 | `-h`, `--help`      | Show help.                                                                                   |
 
-The resulting `<name>-<version>.tgz` is written to the current working directory.
+The resulting `<name>-<version>.tgz` is written to the current working directory (unless `--skip-pack` is set).
 
 ### Example
 
@@ -46,20 +47,35 @@ ts-node-pack ./packages/core --verbose
 npm install ./my-core-1.2.3.tgz
 ```
 
+### `--stage-to` and `--skip-pack`
+
+By default `ts-node-pack` stages into an auto-created `mkdtemp()` directory, runs `npm pack` against it, copies the resulting `.tgz` to the current working directory, and removes the temp dir.
+
+Pass `--stage-to <dir>` when you want to keep the staged contents — for example, to let another tool pack from that directory instead (`lerna publish --contents <dir>`, an alternate tarball builder, etc.). `<dir>` must either not exist, be empty, or be opted-in for clearing via `--force`.
+
+Combine with `--skip-pack` to stop after staging and never run `npm pack` at all. `--skip-pack` is only valid with `--stage-to` (otherwise the staged contents would have no accessible location).
+
+| Invocation                                        | Behavior                                                            |
+| ------------------------------------------------- | ------------------------------------------------------------------- |
+| `ts-node-pack <pkg>`                              | Stage to temp dir, pack, copy `.tgz` to CWD, delete temp dir.       |
+| `ts-node-pack <pkg> --stage-to <dir>`             | Stage to `<dir>`, pack, copy `.tgz` to CWD, leave `<dir>` in place. |
+| `ts-node-pack <pkg> --stage-to <dir> --skip-pack` | Stage to `<dir>`, skip pack, leave `<dir>` in place.                |
+| `ts-node-pack <pkg> --skip-pack`                  | Error: `skipPack requires stageTo`.                                 |
+
 ## Pipeline
 
 1. **Resolve package** — read `package.json`, pick tsconfig.
-2. **Stage** — create `mkdtemp()/package/`.
-3. **Derived tsconfig** — write `tsconfig.emit.json` _inside the temp dir_ that `extends` the chosen tsconfig (by absolute path) and forces `outDir`, `declaration`, `rewriteRelativeImportExtensions: true`, `noEmit: false`. If the base tsconfig enables `sourceMap`, `inlineSourceMap`, or `declarationMap`, `inlineSources: true` is also set so debuggers get full source-level fidelity without any `.ts` files in the tarball.
+2. **Stage** — use `--stage-to <dir>` if given, otherwise create `mkdtemp()/package/`. A small separate `mkdtemp()` work dir always holds auxiliary files (e.g. the derived tsconfig) so they never land in the packed contents.
+3. **Derived tsconfig** — write `tsconfig.emit.json` _inside the work dir_ that `extends` the chosen tsconfig (by absolute path) and forces `outDir`, `declaration`, `rewriteRelativeImportExtensions: true`, `noEmit: false`. If the base tsconfig enables `sourceMap`, `inlineSourceMap`, or `declarationMap`, `inlineSources: true` is also set so debuggers get full source-level fidelity without any `.ts` files in the tarball.
 4. **Emit** — run `tsc -p` against the derived config.
 5. **Rewrite `.d.ts`** — for each emitted `.d.ts`, rewrite `./foo.ts` → `./foo.js` in `import` / `export from` / dynamic `import()` specifiers. Non-relative specifiers are left alone.
 6. **Rewrite `package.json`** — rewrite `.ts` → `.js` (and → `.d.ts` under `types` conditions) in `main`, `module`, `types`, `typings`, `bin`, `exports`, and the `files` array. Strip `devDependencies` and `scripts`.
 7. **Copy assets** — `README*`, `LICENSE*`, `CHANGELOG*`, `NOTICE*`. Source `.ts` files are never copied.
 8. **Validate** — fail if any `.ts` specifier remains in emitted `.js` / `.d.ts` / `package.json`, or if a referenced entry point does not exist.
-9. **Pack** — `npm pack` in the staging directory; move the tarball to the original CWD.
-10. **Cleanup** — remove `.ts-node-pack/` and the temp directory (unless `--keep-temp`).
+9. **Pack** — unless `--skip-pack`: `npm pack` in the staging directory and move the tarball to the original CWD.
+10. **Cleanup** — always remove the work dir. In default mode this also removes the staging dir (which is nested inside). In `--stage-to` mode the staging dir is the caller's, and survives.
 
-The source tree is never mutated. All intermediate artifacts (derived tsconfig, staging dir, tarball) live under a single `mkdtemp()` directory that is removed on exit.
+The source tree is never mutated.
 
 ### Sourcemaps
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-node-pack",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Pack a TypeScript package into a Node-compatible npm tarball without modifying the source tree",
   "keywords": [
     "cli",

package/src/cli.js

@@ -8,8 +8,9 @@ const { values, positionals } = parseArgs({
   allowPositionals: true,
   options: {
     tsconfig: { type: "string" },
-    "emit-only": { type: "boolean", default: false },
-    "keep-temp": { type: "boolean", default: false },
+    "skip-pack": { type: "boolean", default: false },
+    "stage-to": { type: "string" },
+    force: { type: "boolean", default: false },
     verbose: { type: "boolean", short: "v", default: false },
     help: { type: "boolean", short: "h", default: false },
   },
@@ -20,10 +21,12 @@ if (values.help || positionals.length === 0) {
 
 Options:
   --tsconfig <path>   Path to tsconfig (default: tsconfig.build.json or tsconfig.json)
-  --emit-only         Emit compiled files without packing
-  --keep-temp         Keep temporary staging directory
-  -v, --verbose       Verbose output
-  -h, --help          Show this help message
+  --stage-to <dir>    Stage into <dir> instead of an auto-created temp dir.
+                      Caller owns cleanup. Errors if <dir> is non-empty unless --force.
+  --skip-pack         Skip the final \`npm pack\` step. Requires --stage-to.
+  --force             With --stage-to, clear <dir> if it already has contents.
+  -v, --verbose       Log each pipeline phase to stderr.
+  -h, --help          Show this help message.
 `);
   process.exit(values.help ? 0 : 1);
 }
@@ -33,8 +36,9 @@ const packageDir = resolve(positionals[0]);
 try {
   const result = await tsNodePack(packageDir, {
     tsconfig: values.tsconfig,
-    emitOnly: values["emit-only"],
-    keepTemp: values["keep-temp"],
+    skipPack: values["skip-pack"],
+    stageTo: values["stage-to"],
+    force: values.force,
     verbose: values.verbose,
   });
   console.log(result);

package/src/index.d.ts

@@ -1,12 +1,24 @@
 export interface TsNodePackOptions {
     tsconfig?: string;
-    emitOnly?: boolean;
-    keepTemp?: boolean;
+    /**
+     * Skip the final `npm pack` step. Requires `stageTo` (otherwise there
+     * is no way for the caller to access the staged contents).
+     */
+    skipPack?: boolean;
+    /**
+     * Stage directly into this directory instead of an auto-created temp
+     * dir. Caller owns cleanup. Errors if the directory already has
+     * contents, unless `force` is set.
+     */
+    stageTo?: string;
+    /** With `stageTo`, clear the target directory if it already has contents. */
+    force?: boolean;
     verbose?: boolean;
 }
 /**
  * Main pipeline: pack a TypeScript package into a Node-compatible tarball.
- * Returns the path to the .tgz file (or the staging dir if --emit-only).
+ * Returns the path to the .tgz file, or the staging directory when
+ * `skipPack` is set.
  */
 export declare function tsNodePack(packageDir: string, options?: TsNodePackOptions): Promise<string>;
 /**

package/src/index.js

@@ -15,28 +15,47 @@ 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";
+import { rewriteTsSpecifiers } from "./rewrite-specifiers.js";
+import { validate } from "./validation.js";
 
 const execFileAsync = promisify(execFile);
 
                                     
                     
+     
+                                                                        
+                                                             
+     
                      
-                     
+     
+                                                                       
+                                                                  
+                                     
+     
+                   
+                                                                               
+                  
                     
  
 
 /**
  * Main pipeline: pack a TypeScript package into a Node-compatible tarball.
- * Returns the path to the .tgz file (or the staging dir if --emit-only).
+ * Returns the path to the .tgz file, or the staging directory when
+ * `skipPack` is set.
  */
 export async function tsNodePack(
   packageDir        ,
   options                    = {},
 )                  {
-  const { tsconfig, emitOnly, keepTemp, verbose } = options;
+  const { tsconfig, skipPack, stageTo, force, verbose } = options;
   const log = verbose ? (...args           ) => console.error("[ts-node-pack]", ...args) : () => {};
 
+  if (skipPack && !stageTo) {
+    throw new Error(
+      "skipPack requires stageTo: caller must specify where to put the staged contents",
+    );
+  }
+
   packageDir = resolve(packageDir);
 
   // ── Phase 1: Resolve package ──────────────────────────────────────────
@@ -48,11 +67,34 @@ export async function tsNodePack(
   const tsconfigPath = resolveTsconfig(packageDir, tsconfig);
   if (tsconfigPath) log(`Found tsconfig: ${tsconfigPath}`);
 
-  // ── Phase 2: Create staging directory ─────────────────────────────────
-  log("Phase 2: Creating staging directory...");
-  const tmpDir = await mkdtemp(join(tmpdir(), "ts-node-pack-"));
-  const stagingDir = join(tmpDir, "package");
-  await mkdir(stagingDir, { recursive: true });
+  // ── Phase 2: Create work and staging directories ─────────────────────
+  // We always need a private work dir for auxiliary files (e.g.
+  // tsconfig.emit.json) that MUST NOT land inside the packed contents.
+  // In default mode the staging dir is nested inside the work dir, so
+  // cleaning up the work dir cleans up everything. In stageTo mode the
+  // staging dir is the caller's directory — we still create a small
+  // separate work dir for auxiliary files and rm only that in Phase 10.
+  log("Phase 2: Creating work and staging directories...");
+  const workDir = await mkdtemp(join(tmpdir(), "ts-node-pack-"));
+  let stagingDir        ;
+  if (stageTo) {
+    stagingDir = resolve(stageTo);
+    if (existsSync(stagingDir)) {
+      const entries = await readdir(stagingDir);
+      if (entries.length > 0) {
+        if (!force) {
+          throw new Error(
+            `stageTo directory is not empty: ${stagingDir}. Pass force: true to clear it.`,
+          );
+        }
+        await rm(stagingDir, { recursive: true, force: true });
+      }
+    }
+    await mkdir(stagingDir, { recursive: true });
+  } else {
+    stagingDir = join(workDir, "package");
+    await mkdir(stagingDir, { recursive: true });
+  }
   log(`Staging: ${stagingDir}`);
 
   try {
@@ -100,7 +142,7 @@ export async function tsNodePack(
 
     if (shouldRunTsc) {
       log("Phase 4: Generating derived tsconfig...");
-      const emitConfigPath = join(tmpDir, "tsconfig.emit.json");
+      const emitConfigPath = join(workDir, "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
@@ -187,26 +229,31 @@ export async function tsNodePack(
     await validate(stagingDir, rewrittenPkg, log);
 
     // ── Phase 9: Pack ─────────────────────────────────────────────────────
-    if (!emitOnly) {
+    if (!skipPack) {
       log("Phase 9: Packing...");
       const tgzPath = await pack(stagingDir);
       const tgzName = basename(tgzPath);
       const dest = join(process.cwd(), tgzName);
       await copyFile(tgzPath, dest);
+      // In stageTo mode the whole staging dir survives into the caller's
+      // filesystem, so the intermediate .tgz that `npm pack` wrote in
+      // there would stick around as visible clutter. Remove it. (In
+      // default mode the entire workDir is rm'd in Phase 10, so this
+      // unlink is redundant but harmless.)
+      if (stageTo) await unlink(tgzPath);
       log(`Created: ${dest}`);
       return dest;
     }
 
-    log(`Emit-only mode. Staging directory: ${stagingDir}`);
+    log(`Skip-pack mode. Staging directory: ${stagingDir}`);
     return stagingDir;
   } finally {
     // ── Phase 10: Cleanup ───────────────────────────────────────────────
-    if (!emitOnly && !keepTemp) {
-      log("Phase 10: Cleaning up temp directory...");
-      await rm(tmpDir, { recursive: true, force: true });
-    } else if (keepTemp) {
-      log(`Keeping temp directory: ${tmpDir}`);
-    }
+    // Always rm the work dir. In default mode this also removes the
+    // staging dir (nested inside). In stageTo mode the staging dir is
+    // the caller's directory and survives.
+    log("Phase 10: Cleaning up work directory...");
+    await rm(workDir, { recursive: true, force: true });
   }
 }
 
@@ -549,7 +596,7 @@ export function rewritePackageJson(pkg) {
   } else if (result.typings) {
     result.typings = rewriteTsToDts(result.typings);
   } else if (mainWasTs) {
-    result.types = result.main.replace(/\.js$/, ".d.ts");
+    result.types = rewriteTsToDts(originalMain);
   }
 
   // Rewrite bin
@@ -571,7 +618,7 @@ export function rewritePackageJson(pkg) {
   // Rewrite files array
   if (Array.isArray(result.files)) {
     result.files = result.files.flatMap((f) => {
-      if (typeof f === "string" && /\.tsx?$/.test(f)) {
+      if (typeof f === "string" && TS_SOURCE_EXT_RE.test(f)) {
         return [rewriteTsToJs(f), rewriteTsToDts(f)];
       }
       return [f];
@@ -581,14 +628,22 @@ export function rewritePackageJson(pkg) {
   return result;
 }
 
+// `.ts`/`.tsx` → `.js`; `.mts` → `.mjs`. Matches what `ts-blank-space`
+// writes in Phase 6 and the specifier-rewrite pass in rewrite-specifiers.ts.
 function rewriteTsToJs(p) {
-  return typeof p === "string" ? p.replace(/\.tsx?$/, ".js") : p;
+  if (typeof p !== "string") return p;
+  return p.replace(/\.mts$/, ".mjs").replace(/\.tsx?$/, ".js");
 }
 
+// `.ts`/`.tsx` → `.d.ts`; `.mts` → `.d.mts`. Matches the declaration files
+// tsc emits from an .mts source.
 function rewriteTsToDts(p) {
-  return typeof p === "string" ? p.replace(/\.tsx?$/, ".d.ts") : p;
+  if (typeof p !== "string") return p;
+  return p.replace(/\.mts$/, ".d.mts").replace(/\.tsx?$/, ".d.ts");
 }
 
+const TS_SOURCE_EXT_RE = /\.(tsx?|mts)$/;
+
 function rewriteExportsValue(value, isTypesKey) {
   if (typeof value === "string") {
     return isTypesKey ? rewriteTsToDts(value) : rewriteTsToJs(value);
@@ -606,98 +661,6 @@ function rewriteExportsValue(value, isTypesKey) {
   return value;
 }
 
-async function validate(stagingDir, pkg, log) {
-  const errors = [];
-
-  // Check .js and .d.ts files for remaining .ts specifiers
-  const allFiles = await findFiles(
-    stagingDir,
-    (name) => name.endsWith(".js") || name.endsWith(".d.ts"),
-  );
-
-  for (const filePath of allFiles) {
-    const raw = await readFile(filePath, "utf8");
-    // Strip block and line comments before scanning so JSDoc examples that
-    // literally contain strings like `import './foo.js'` don't register as
-    // 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 relPath = relative(stagingDir, filePath);
-
-    for (const pattern of TS_SPECIFIER_PATTERNS) {
-      for (const m of content.matchAll(pattern)) {
-        errors.push(`${relPath}: remaining .ts specifier: ${m[0]}`);
-      }
-    }
-  }
-
-  // Check package.json for .ts references in entry points
-  const entryFields = ["main", "module", "types", "typings"];
-  for (const field of entryFields) {
-    if (typeof pkg[field] === "string" && /(?<!\.d)\.tsx?$/.test(pkg[field])) {
-      errors.push(`package.json "${field}" still references .ts: ${pkg[field]}`);
-    }
-  }
-
-  // Non-fatal: yarn/npm tolerate `bin`/`main` pointing at missing
-  // files. Real transformation bugs are caught by the specifier
-  // checks above.
-  const referencedFiles = collectReferencedFiles(pkg);
-  for (const ref of referencedFiles) {
-    if (!existsSync(join(stagingDir, ref))) {
-      log(`  Warning: referenced file missing from tarball: ${ref}`);
-    }
-  }
-
-  if (errors.length > 0) {
-    const msg = "Validation failed:\n  " + errors.join("\n  ");
-    throw new Error(msg);
-  }
-
-  log(`Validated ${allFiles.length} file(s), no issues found`);
-}
-
-function collectReferencedFiles(pkg) {
-  const refs = new Set        ();
-
-  for (const field of ["main", "module", "types", "typings"]) {
-    if (typeof pkg[field] === "string") {
-      refs.add(pkg[field].replace(/^\.\//, ""));
-    }
-  }
-
-  if (typeof pkg.bin === "string") {
-    refs.add(pkg.bin.replace(/^\.\//, ""));
-  } else if (typeof pkg.bin === "object" && pkg.bin !== null) {
-    for (const v of Object.values(pkg.bin)) {
-      if (typeof v === "string") refs.add(v.replace(/^\.\//, ""));
-    }
-  }
-
-  if (pkg.exports) {
-    collectExportsRefs(pkg.exports, refs);
-  }
-
-  return refs;
-}
-
-function collectExportsRefs(value, refs) {
-  if (typeof value === "string") {
-    refs.add(value.replace(/^\.\//, ""));
-    return;
-  }
-  if (Array.isArray(value)) {
-    for (const v of value) collectExportsRefs(v, refs);
-    return;
-  }
-  if (typeof value === "object" && value !== null) {
-    for (const v of Object.values(value)) {
-      collectExportsRefs(v, refs);
-    }
-  }
-}
-
 async function pack(stagingDir) {
   const { stdout } = await execFileAsync("npm", ["pack"], {
     cwd: stagingDir,

package/src/validation.d.ts

@@ -0,0 +1,21 @@
+export declare function validate(stagingDir: any, pkg: any, log?: (...args: unknown[]) => void): Promise<void>;
+/**
+ * Collect the relative file paths referenced by path-bearing fields of a
+ * package.json manifest, partitioned by how strictly a missing target
+ * should be treated.
+ *
+ * - `strict`: `main`, `module`, `types`, `typings`, and every leaf of
+ *   `exports`. A missing target here is a bug in the tarball we produced —
+ *   Node's module resolution will fail and `npm publish` warns on
+ *   dangling `types`.
+ * - `lenient`: `bin` entries. yarn and npm both tolerate a `bin` pointing
+ *   at a missing file (see the `bin-missing` fixture, which mirrors
+ *   agoric/portfolio-api's intentional shape).
+ *
+ * Exported for direct unit-testing of the policy; the only runtime caller
+ * is `validate()` above.
+ */
+export declare function collectReferencedFiles(pkg: any): {
+    strict: Set<string>;
+    lenient: Set<string>;
+};

package/src/validation.js

@@ -0,0 +1,146 @@
+/**
+ * Post-rewrite validation of a staged package. `validate()` is the one
+ * caller of `collectReferencedFiles`; both live here because the
+ * strict-vs-lenient partition is a policy decision owned by validation.
+ */
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { TS_SPECIFIER_PATTERNS } from "./rewrite-specifiers.js";
+
+export async function validate(
+  stagingDir,
+  pkg,
+  log                               = () => {},
+) {
+  const errors = [];
+
+  // Check .js/.mjs and .d.ts/.d.mts files for remaining .ts specifiers
+  const allFiles = await findFiles(
+    stagingDir,
+    (name) =>
+      name.endsWith(".js") ||
+      name.endsWith(".mjs") ||
+      name.endsWith(".d.ts") ||
+      name.endsWith(".d.mts"),
+  );
+
+  for (const filePath of allFiles) {
+    const raw = await readFile(filePath, "utf8");
+    // Strip block and line comments before scanning so JSDoc examples that
+    // literally contain strings like `import './foo.js'` don't register as
+    // 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 relPath = relative(stagingDir, filePath);
+
+    for (const pattern of TS_SPECIFIER_PATTERNS) {
+      for (const m of content.matchAll(pattern)) {
+        errors.push(`${relPath}: remaining .ts specifier: ${m[0]}`);
+      }
+    }
+  }
+
+  // Check package.json for .ts references in entry points
+  const entryFields = ["main", "module", "types", "typings"];
+  for (const field of entryFields) {
+    if (typeof pkg[field] === "string" && /(?<!\.d)\.(tsx?|mts)$/.test(pkg[field])) {
+      errors.push(`package.json "${field}" still references .ts: ${pkg[field]}`);
+    }
+  }
+
+  // main/module/types/typings/exports must resolve to a file that is
+  // actually in the staging dir. This catches rewrite bugs that specifier
+  // scanning can't — e.g. the @endo/ses-ava regression where a synthesized
+  // `types: ./index.d.ts` pointed at a .d.ts ts-node-pack never emitted.
+  // `bin` is deliberately excluded: yarn/npm both tolerate a missing bin
+  // target (see the bin-missing fixture — agoric/portfolio-api ships that
+  // way intentionally), so we only warn.
+  const { strict: strictRefs, lenient: lenientRefs } = collectReferencedFiles(pkg);
+  for (const ref of strictRefs) {
+    if (!existsSync(join(stagingDir, ref))) {
+      errors.push(`referenced file missing from tarball: ${ref}`);
+    }
+  }
+  for (const ref of lenientRefs) {
+    if (!existsSync(join(stagingDir, ref))) {
+      log(`  Warning: referenced file missing from tarball: ${ref}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    const msg = "Validation failed:\n  " + errors.join("\n  ");
+    throw new Error(msg);
+  }
+
+  log(`Validated ${allFiles.length} file(s), no issues found`);
+}
+
+/**
+ * Collect the relative file paths referenced by path-bearing fields of a
+ * package.json manifest, partitioned by how strictly a missing target
+ * should be treated.
+ *
+ * - `strict`: `main`, `module`, `types`, `typings`, and every leaf of
+ *   `exports`. A missing target here is a bug in the tarball we produced —
+ *   Node's module resolution will fail and `npm publish` warns on
+ *   dangling `types`.
+ * - `lenient`: `bin` entries. yarn and npm both tolerate a `bin` pointing
+ *   at a missing file (see the `bin-missing` fixture, which mirrors
+ *   agoric/portfolio-api's intentional shape).
+ *
+ * Exported for direct unit-testing of the policy; the only runtime caller
+ * is `validate()` above.
+ */
+export function collectReferencedFiles(pkg) {
+  const strict = new Set        ();
+  const lenient = new Set        ();
+  const addStrict = (p) => strict.add(stripDotSlash(p));
+  const addLenient = (p) => lenient.add(stripDotSlash(p));
+
+  for (const field of ["main", "module", "types", "typings"]) {
+    if (typeof pkg[field] === "string") addStrict(pkg[field]);
+  }
+
+  if (typeof pkg.bin === "string") {
+    addLenient(pkg.bin);
+  } else if (typeof pkg.bin === "object" && pkg.bin !== null) {
+    for (const v of Object.values(pkg.bin)) {
+      if (typeof v === "string") addLenient(v);
+    }
+  }
+
+  if (pkg.exports) collectExportsRefs(pkg.exports, strict);
+
+  return { strict, lenient };
+}
+
+function collectExportsRefs(value, refs) {
+  if (typeof value === "string") {
+    refs.add(stripDotSlash(value));
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const v of value) collectExportsRefs(v, refs);
+    return;
+  }
+  if (typeof value === "object" && value !== null) {
+    for (const v of Object.values(value)) collectExportsRefs(v, refs);
+  }
+}
+
+function stripDotSlash(p) {
+  return p.replace(/^\.\//, "");
+}
+
+async function findFiles(dir, test) {
+  const results = [];
+  const entries = await readdir(dir, { withFileTypes: true, recursive: true });
+  for (const entry of entries) {
+    if (entry.isFile() && test(entry.name)) {
+      results.push(join(entry.parentPath, entry.name));
+    }
+  }
+  return results;
+}