GitHubivarvong
ply
main
1// The pack check: what a consumer who installs the packed tarball gets, with lifecycle scripts off.
2// `npm run check:pack` (CI job `pack`, once per supported Node major); test/pack-install.test.js runs the tarball
3// part in the suite.
4//
5// 1. a fresh export of the tracked files (no dist/, no node_modules) is packed with `npm pack` (its `prepare`
6// builds dist/ with the checkout's installed typescript);
7// 2. the tarball is installed with `npm install --ignore-scripts` into an empty project: exactly one package, `ply`;
8// 3. the root and every subpath in package.json "exports" are imported under the running Node;
9// 4. `require('ply')` is run under the running Node and compared with what README.md Install states for that version;
10// 5. (CLI only) the setup command examples/README.md documents is run in a second fresh export, then each example
11// is started without arguments: it must reach its own usage line (exit 2), not ERR_MODULE_NOT_FOUND.
12// `--out <dir>` keeps the tarball there (CI uploads it as a workflow artifact); `--tarball <file>` runs steps 2 to 4
13// on an existing tarball (CI: the same tarball under Node 20 and 24, where the dev tools are not installed).
14import { spawnSync } from 'node:child_process';
15import { mkdtempSync, mkdirSync, writeFileSync, copyFileSync, symlinkSync, rmSync, readFileSync, existsSync, readdirSync } from 'node:fs';
16import { tmpdir } from 'node:os';
17import { join, dirname, resolve } from 'node:path';
18import { fileURLToPath } from 'node:url';
20const REPO = join(dirname(fileURLToPath(import.meta.url)), '..');
21const pkg = JSON.parse(readFileSync(join(REPO, 'package.json'), 'utf8'));
22// 'ply', 'ply/edit', …: the names a consumer writes, from package.json exports
23export const SUBPATHS = Object.keys(pkg.exports).map(key => `ply${key.slice(1)}`);
24export const EXAMPLES = ['push-tree', 'checkout-tree', 'push-repo'];
26function sh(command, args, options) {
27 const run = spawnSync(command, args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, ...options });
28 return { status: run.status, out: `${run.stdout ?? ''}${run.stderr ?? ''}` };
29}
31// The tracked files of the working tree, copied to a new directory: what `git clone` gives, with this checkout's edits.
32export function freshExport() {
33 const dir = mkdtempSync(join(tmpdir(), 'ply-export-'));
34 const listed = sh('git', ['ls-files', '-z'], { cwd: REPO });
35 if (listed.status !== 0) throw new Error(`git ls-files failed: ${listed.out}`);
36 for (const file of listed.out.split('\0')) {
37 if (file === '' || !existsSync(join(REPO, file))) continue;
38 mkdirSync(dirname(join(dir, file)), { recursive: true });
39 copyFileSync(join(REPO, file), join(dir, file));
40 }
41 return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
42}
44// npm pack in a fresh export. The build tools are the checkout's installed devDependencies (a symlink); nothing is
45// written into the checkout. Returns the tarball path inside `out`.
46export function pack(out) {
47 const source = freshExport();
48 try {
49 symlinkSync(join(REPO, 'node_modules'), join(source.dir, 'node_modules'));
50 const run = sh('npm', ['pack', '--json', '--pack-destination', out], { cwd: source.dir });
51 if (run.status !== 0) throw new Error(`npm pack failed:\n${run.out}`);
52 const tarball = readdirSync(out).filter(name => name.endsWith('.tgz'));
53 if (tarball.length !== 1) throw new Error(`expected one tarball in ${out}, found ${tarball.join(', ')}`);
54 return join(out, String(tarball[0]));
55 } finally { source.cleanup(); }
56}
58// An empty project with the tarball installed, lifecycle scripts off, registry untouched (ply has no dependencies).
59export function installTarball(tarball) {
60 const dir = mkdtempSync(join(tmpdir(), 'ply-pack-consumer-'));
61 writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'consumer', private: true }));
62 const run = sh('npm', ['install', '--ignore-scripts', '--offline', '--no-audit', '--no-fund', tarball], { cwd: dir });
63 if (run.status !== 0) throw new Error(`npm install failed:\n${run.out}`);
64 const packages = readdirSync(join(dir, 'node_modules')).filter(name => !name.startsWith('.'));
65 return { dir, packages, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
66}
68// Import every subpath from inside the consumer under `node`. Returns { name: export count } or throws with Node's error.
69export function importAll(consumerDir, node = process.execPath) {
70 const code = `const out = {}; for (const name of ${JSON.stringify(SUBPATHS)}) out[name] = Object.keys(await import(name)).length; console.log(JSON.stringify(out));`;
71 const run = sh(node, ['--input-type=module', '-e', code], { cwd: consumerDir });
72 if (run.status !== 0) throw new Error(`import failed under ${node}:\n${run.out}`);
73 return JSON.parse(run.out);
74}
76// What `require('ply')` does from a CommonJS file under `node`: 'ok' or the error code Node throws.
77export function requireRoot(consumerDir, node = process.execPath) {
78 writeFileSync(join(consumerDir, 'req.cjs'), `try { require('ply'); console.log('ok'); } catch (error) { console.log(error.code); }\n`);
79 const run = sh(node, ['req.cjs'], { cwd: consumerDir, env: { ...process.env, NODE_NO_WARNINGS: '1' } });
80 return run.out.trim();
81}
83// What README Install states `require('ply')` does on a Node version: 'ok' where Node loads an ES module with require()
84// 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
85// CHANGELOG_V20.md, 20.19.0: "require(esm) is now enabled by default").
86export function requireExpected({ major, minor }) {
87 return major > 22 || (major === 22 && minor >= 12) || (major === 20 && minor >= 19) ? 'ok' : 'ERR_REQUIRE_ESM';
88}
90export function nodeVersion(node = process.execPath) {
91 const [major, minor] = sh(node, ['-p', 'process.versions.node']).out.trim().split('.').map(Number);
92 return { major: major ?? 0, minor: minor ?? 0 };
93}
95// The first command of the first ```sh block of examples/README.md: the one documented setup step.
96export function examplesSetupCommand(readme) {
97 const block = /```sh\n([^\n]*)\n/.exec(readme);
98 return block ? String(block[1]).split('#')[0].trim() : '';
99}
101// Run the documented setup in a fresh export, then start each example without arguments.
102export function examplesFromExport() {
103 const source = freshExport();
104 try {
105 const command = examplesSetupCommand(readFileSync(join(source.dir, 'examples', 'README.md'), 'utf8'));
106 if (!command.startsWith('npm ')) return { command, setup: 'examples/README.md documents no setup command before the example commands', runs: [] };
107 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' } });
108 const runs = EXAMPLES.map(name => {
109 const run = sh(process.execPath, [join('examples', `${name}.mjs`)], { cwd: source.dir });
110 return { name, status: run.status, first: run.out.split('\n').find(line => line.trim() !== '') ?? '' };
111 });
112 return { command, setup: setup.status === 0 ? 'ok' : `exit ${setup.status}:\n${setup.out.slice(-2000)}`, runs };
113 } finally { source.cleanup(); }
114}
116if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
117 const outFlag = process.argv.indexOf('--out');
118 const out = outFlag > 0 ? resolve(String(process.argv[outFlag + 1])) : mkdtempSync(join(tmpdir(), 'ply-pack-'));
119 mkdirSync(out, { recursive: true });
120 let failed = false;
121 const check = (ok, line) => { console.log(`pack-check ${ok ? 'ok ' : 'FAIL'} ${line}`); if (!ok) failed = true; };
122 // --tarball <file>: check an already packed tarball under the running Node (steps 2 to 4 only)
123 const given = process.argv.indexOf('--tarball');
124 const tarball = given > 0 ? resolve(String(process.argv[given + 1])) : pack(out);
125 const consumer = installTarball(tarball);
126 try {
127 check(consumer.packages.length === 1 && consumer.packages[0] === 'ply', `install --ignore-scripts: packages [${consumer.packages.join(', ')}]`);
128 const imported = importAll(consumer.dir);
129 check(Object.keys(imported).length === SUBPATHS.length, `node ${process.versions.node}: imported ${Object.keys(imported).length} of ${SUBPATHS.length} subpaths`);
130 const { major, minor } = nodeVersion();
131 const required = requireRoot(consumer.dir);
132 const expected = requireExpected({ major, minor });
133 check(required === expected, `node ${process.versions.node}: require('ply') -> ${required} (README states ${expected})`);
134 } finally { consumer.cleanup(); }
135 if (given < 0) {
136 const examples = examplesFromExport();
137 check(examples.setup === 'ok', `examples setup \`${examples.command}\` in a fresh export: ${examples.setup}`);
138 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}`);
139 }
140 console.log(`pack-check tarball ${tarball}`);
141 process.exit(failed ? 1 : 0);
142}
Diagnostics6 git calls · 210 ms
CallStatusSizeTime0210 ms
discover200191 B3 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=1 git.response.bytes=191 git.server.agent=git/github-9922ec520325-Linux git.server.object_format=sha1 git.server.caps=agent ls-refs fetch server-option object-format git.server.fetch=shallow wait-for-done filter git.protocol.version=2 git.pkt.frames=9 git.pkt.data=7 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=191 git.pkt.payload.max=36
ls-refs20012 KiB2 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=11990 git.response.cache=UPDATING git.response.duration_ms=2 git.protocol.version=2 git.pkt.frames=152 git.pkt.data=151 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=11990 git.pkt.payload.max=122 git.ls_refs.count=151 git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 102004.2 KiB · hit1 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=4 git.response.bytes=4347 git.response.cache=HIT git.response.duration_ms=1 git.fetch.filter=tree:0 git.fetch.wants=19912563f540228593df0c489082e5e2508e21e4 git.fetch.haves.count=0 git.fetch.deepen=10 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=7 git.pkt.data=5 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=4347 git.pkt.payload.max=4247 git.sideband.band1.bytes=4247 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=10 git.pack.bytes=4247 git.pack.ofs_delta=0 git.pack.ref_delta=0 git.pack.chain.max=0 git.pack.trailer=a6caf8e129bea82c9bae4cbc7c130c9205add400 git.pack.full=10Open pack map
fetchtree:0200919 B · hit4 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=3 git.response.bytes=919 git.response.cache=HIT git.response.duration_ms=4 git.fetch.filter=tree:0 git.fetch.wants=800d30ba8923860bfc460ca884b7f9ba22083588 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=919 git.pkt.payload.max=892 git.sideband.band1.bytes=892 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=892 git.pack.trailer=5323b9266eea5ded637285d1c5320699f12be76eOpen pack map
fetchtree:0200831 B · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=199 git.response.bytes=831 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=tree:0 git.fetch.wants=b9290e370bd091fd3272931655a175dd1a7af82d git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=831 git.pkt.payload.max=804 git.sideband.band1.bytes=804 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=804 git.pack.trailer=81ddc1f73214935b4ee953ad84f959db955ce0d1Open pack map
fetch2003.3 KiB199 ms
git.upload-pack fetch http.response.status_code=200 git.response.bytes=3402 git.response.cache=MISS git.response.duration_ms=199 git.fetch.wants=b3bd42551dc8e67e4612578bdb91896828d104e1 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=3402 git.pkt.payload.max=3375 git.sideband.band1.bytes=3375 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0
Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.
- Remote
- https://github.com/ivarvong/ply
- Ref
- refs/heads/main
- Commit
- 19912563f540228593df0c489082e5e2508e21e4
- cf-ray
- a5e0fc994f27332c
- Request
- 30d58ce9…
- Protocol
- v2 · sha1
- Agent
- git/github-9922ec520325-Linux
- Filter
- advertised
- Fetch
- shallow wait-for-done filter
- Capabilities
- agent ls-refs fetch server-option object-format