// The pack check: what a consumer who installs the packed tarball gets, with lifecycle scripts off.
// `npm run check:pack` (CI job `pack`, once per supported Node major); test/pack-install.test.js runs the tarball
// part in the suite.
//
// 1. a fresh export of the tracked files (no dist/, no node_modules) is packed with `npm pack` (its `prepare`
// builds dist/ with the checkout's installed typescript);
// 2. the tarball is installed with `npm install --ignore-scripts` into an empty project: exactly one package, `ply`;
// 3. the root and every subpath in package.json "exports" are imported under the running Node;
// 4. `require('ply')` is run under the running Node and compared with what README.md Install states for that version;
// 5. (CLI only) the setup command examples/README.md documents is run in a second fresh export, then each example
// is started without arguments: it must reach its own usage line (exit 2), not ERR_MODULE_NOT_FOUND.
// `--out
` keeps the tarball there (CI uploads it as a workflow artifact); `--tarball ` runs steps 2 to 4
// on an existing tarball (CI: the same tarball under Node 20 and 24, where the dev tools are not installed).
import { spawnSync } from 'node:child_process';
import { mkdtempSync, mkdirSync, writeFileSync, copyFileSync, symlinkSync, rmSync, readFileSync, existsSync, readdirSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
const REPO = join(dirname(fileURLToPath(import.meta.url)), '..');
const pkg = JSON.parse(readFileSync(join(REPO, 'package.json'), 'utf8'));
// 'ply', 'ply/edit', …: the names a consumer writes, from package.json exports
export const SUBPATHS = Object.keys(pkg.exports).map(key => `ply${key.slice(1)}`);
export const EXAMPLES = ['push-tree', 'checkout-tree', 'push-repo'];
function sh(command, args, options) {
const run = spawnSync(command, args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, ...options });
return { status: run.status, out: `${run.stdout ?? ''}${run.stderr ?? ''}` };
}
// The tracked files of the working tree, copied to a new directory: what `git clone` gives, with this checkout's edits.
export function freshExport() {
const dir = mkdtempSync(join(tmpdir(), 'ply-export-'));
const listed = sh('git', ['ls-files', '-z'], { cwd: REPO });
if (listed.status !== 0) throw new Error(`git ls-files failed: ${listed.out}`);
for (const file of listed.out.split('\0')) {
if (file === '' || !existsSync(join(REPO, file))) continue;
mkdirSync(dirname(join(dir, file)), { recursive: true });
copyFileSync(join(REPO, file), join(dir, file));
}
return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
}
// npm pack in a fresh export. The build tools are the checkout's installed devDependencies (a symlink); nothing is
// written into the checkout. Returns the tarball path inside `out`.
export function pack(out) {
const source = freshExport();
try {
symlinkSync(join(REPO, 'node_modules'), join(source.dir, 'node_modules'));
const run = sh('npm', ['pack', '--json', '--pack-destination', out], { cwd: source.dir });
if (run.status !== 0) throw new Error(`npm pack failed:\n${run.out}`);
const tarball = readdirSync(out).filter(name => name.endsWith('.tgz'));
if (tarball.length !== 1) throw new Error(`expected one tarball in ${out}, found ${tarball.join(', ')}`);
return join(out, String(tarball[0]));
} finally { source.cleanup(); }
}
// An empty project with the tarball installed, lifecycle scripts off, registry untouched (ply has no dependencies).
export function installTarball(tarball) {
const dir = mkdtempSync(join(tmpdir(), 'ply-pack-consumer-'));
writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'consumer', private: true }));
const run = sh('npm', ['install', '--ignore-scripts', '--offline', '--no-audit', '--no-fund', tarball], { cwd: dir });
if (run.status !== 0) throw new Error(`npm install failed:\n${run.out}`);
const packages = readdirSync(join(dir, 'node_modules')).filter(name => !name.startsWith('.'));
return { dir, packages, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
}
// Import every subpath from inside the consumer under `node`. Returns { name: export count } or throws with Node's error.
export function importAll(consumerDir, node = process.execPath) {
const code = `const out = {}; for (const name of ${JSON.stringify(SUBPATHS)}) out[name] = Object.keys(await import(name)).length; console.log(JSON.stringify(out));`;
const run = sh(node, ['--input-type=module', '-e', code], { cwd: consumerDir });
if (run.status !== 0) throw new Error(`import failed under ${node}:\n${run.out}`);
return JSON.parse(run.out);
}
// What `require('ply')` does from a CommonJS file under `node`: 'ok' or the error code Node throws.
export function requireRoot(consumerDir, node = process.execPath) {
writeFileSync(join(consumerDir, 'req.cjs'), `try { require('ply'); console.log('ok'); } catch (error) { console.log(error.code); }\n`);
const run = sh(node, ['req.cjs'], { cwd: consumerDir, env: { ...process.env, NODE_NO_WARNINGS: '1' } });
return run.out.trim();
}
// What README Install states `require('ply')` does on a Node version: 'ok' where Node loads an ES module with require()
// by default, 'ERR_REQUIRE_ESM' before that. That is 22.12.0 and later, and on the 20 line 20.19.0 and later (Node's
// CHANGELOG_V20.md, 20.19.0: "require(esm) is now enabled by default").
export function requireExpected({ major, minor }) {
return major > 22 || (major === 22 && minor >= 12) || (major === 20 && minor >= 19) ? 'ok' : 'ERR_REQUIRE_ESM';
}
export function nodeVersion(node = process.execPath) {
const [major, minor] = sh(node, ['-p', 'process.versions.node']).out.trim().split('.').map(Number);
return { major: major ?? 0, minor: minor ?? 0 };
}
// The first command of the first ```sh block of examples/README.md: the one documented setup step.
export function examplesSetupCommand(readme) {
const block = /```sh\n([^\n]*)\n/.exec(readme);
return block ? String(block[1]).split('#')[0].trim() : '';
}
// Run the documented setup in a fresh export, then start each example without arguments.
export function examplesFromExport() {
const source = freshExport();
try {
const command = examplesSetupCommand(readFileSync(join(source.dir, 'examples', 'README.md'), 'utf8'));
if (!command.startsWith('npm ')) return { command, setup: 'examples/README.md documents no setup command before the example commands', runs: [] };
const setup = sh('sh', ['-c', command], { cwd: source.dir, env: { ...process.env, npm_config_audit: 'false', npm_config_fund: 'false', npm_config_prefer_offline: 'true' } });
const runs = EXAMPLES.map(name => {
const run = sh(process.execPath, [join('examples', `${name}.mjs`)], { cwd: source.dir });
return { name, status: run.status, first: run.out.split('\n').find(line => line.trim() !== '') ?? '' };
});
return { command, setup: setup.status === 0 ? 'ok' : `exit ${setup.status}:\n${setup.out.slice(-2000)}`, runs };
} finally { source.cleanup(); }
}
if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
const outFlag = process.argv.indexOf('--out');
const out = outFlag > 0 ? resolve(String(process.argv[outFlag + 1])) : mkdtempSync(join(tmpdir(), 'ply-pack-'));
mkdirSync(out, { recursive: true });
let failed = false;
const check = (ok, line) => { console.log(`pack-check ${ok ? 'ok ' : 'FAIL'} ${line}`); if (!ok) failed = true; };
// --tarball : check an already packed tarball under the running Node (steps 2 to 4 only)
const given = process.argv.indexOf('--tarball');
const tarball = given > 0 ? resolve(String(process.argv[given + 1])) : pack(out);
const consumer = installTarball(tarball);
try {
check(consumer.packages.length === 1 && consumer.packages[0] === 'ply', `install --ignore-scripts: packages [${consumer.packages.join(', ')}]`);
const imported = importAll(consumer.dir);
check(Object.keys(imported).length === SUBPATHS.length, `node ${process.versions.node}: imported ${Object.keys(imported).length} of ${SUBPATHS.length} subpaths`);
const { major, minor } = nodeVersion();
const required = requireRoot(consumer.dir);
const expected = requireExpected({ major, minor });
check(required === expected, `node ${process.versions.node}: require('ply') -> ${required} (README states ${expected})`);
} finally { consumer.cleanup(); }
if (given < 0) {
const examples = examplesFromExport();
check(examples.setup === 'ok', `examples setup \`${examples.command}\` in a fresh export: ${examples.setup}`);
for (const run of examples.runs) check(run.status === 2 && run.first.startsWith('usage: '), `examples/${run.name}.mjs without arguments: exit ${run.status}, ${run.first}`);
}
console.log(`pack-check tarball ${tarball}`);
process.exit(failed ? 1 : 0);
}