GitHubivarvong
ply
main
1// The dist check: what a consumer of the built package gets. `npm run check:dist` and the last step of `npm run check`
2// (CI: "dist is what consumers import"); test/dist-types.test.js runs the same compiles in the suite.
3//
4// dist is built into a scratch directory and never into this tree's dist/: a contributor's dist/ may be linked into
5// another project or hold a build under comparison, and a check must not rewrite it. `npm run build` is still what
6// writes dist/.
7//
8// Load: the build is installed as <scratch>/load/node_modules/ply and `import('ply')` runs there, through
9// package.json's exports map; it must export Tracer and RETRY.
10//
11// Types: dist is built once (never into the checkout's dist/), copied into one scratch consumer project per variant,
12// and a file importing every subpath export plus a file using the signer and pack-cache types with the consumer's own
13// platform values is compiled by tsc with skipLibCheck false:
14// node20, node22, node24 — lib ES2022 + @types/node of that major, all subpaths (a Node service: no DOM or WebWorker
15// lib). 20 is the engines floor, 22 is CI's Node, 24 is the repo's own @types/node.
16// dom — lib ES2022 + DOM, no @types, every subpath but the *-node ones (a browser bundle)
17// workers — lib ES2022 + @cloudflare/workers-types, every subpath but the *-node ones (a Worker)
18// tsc is the judge: the declarations may name only types every one of these environments declares. The type packages
19// are exact-pinned devDependencies (types-node-20 and types-node-22 are npm aliases of @types/node, named outside
20// @types so no tsconfig picks them up by accident). No variant can be skipped: a missing package is an error.
21import { spawnSync } from 'node:child_process';
22import { mkdtempSync, mkdirSync, writeFileSync, copyFileSync, cpSync, symlinkSync, rmSync, readFileSync, existsSync } from 'node:fs';
23import { tmpdir } from 'node:os';
24import { join, dirname, resolve } from 'node:path';
25import { fileURLToPath } from 'node:url';
27const REPO = join(dirname(fileURLToPath(import.meta.url)), '..');
28const TSC = join(REPO, 'node_modules', '.bin', 'tsc');
29const pkg = JSON.parse(readFileSync(join(REPO, 'package.json'), 'utf8'));
30// 'ply', 'ply/edit', …: the names a consumer writes, from package.json exports
31export const SUBPATHS = Object.keys(pkg.exports).map(key => `ply${key.slice(1)}`);
32const NODE_ONLY = name => name.endsWith('-node');
33const WEB = SUBPATHS.filter(name => !NODE_ONLY(name));
35// A consumer's own code against the declarations: its platform key goes into SignerKey, a generated key goes back
36// into the platform's crypto.subtle.sign and out as the platform's key type, and neither the key nor a cache miss has
37// degraded to `any`.
38const IS_ANY = 'type IsAny<T> = 0 extends 1 & T ? true : false;\n';
39const useTypes = (preamble, keyType) => `${IS_ANY}${preamble}import { ed25519Signer, generateSigner, type SignerKey } from 'ply/sign';
40import type { PackCache } from 'ply/packcache';
41declare const own: ${keyType};
42export const key: SignerKey = { privateKey: own, publicKeyRaw: new Uint8Array(32) };
43export const signer = ed25519Signer(key);
44export const keyNotAny: IsAny<SignerKey['privateKey']> = false;
45export async function roundTrip(): Promise<${keyType}> {
46 const generated = await generateSigner();
47 await crypto.subtle.sign('Ed25519', generated.keyPair.privateKey, new Uint8Array(1));
48 return generated.keyPair.publicKey;
49}
50export const missNotAny: IsAny<Awaited<ReturnType<PackCache['match']>>> = false;
51export async function miss(cache: PackCache): Promise<number> { const hit = await cache.match('k'); return hit === undefined ? 0 : hit.status; }
52`;
53const NODE_USE = useTypes(`import type { webcrypto } from 'node:crypto';\n`, 'webcrypto.CryptoKey');
54const WEB_USE = useTypes('', 'CryptoKey');
56// provides: the type package the consumer installs, as { its name in the consumer: its directory in this repo's
57// node_modules }.
58const nodeVariant = (major, source) => ({ name: `node${major}`, lib: ['es2022'], types: ['node'], provides: { '@types/node': source }, subpaths: SUBPATHS, use: NODE_USE });
59export const VARIANTS = [
60 nodeVariant(20, 'types-node-20'),
61 nodeVariant(22, 'types-node-22'),
62 nodeVariant(24, '@types/node'),
63 { name: 'dom', lib: ['es2022', 'dom'], types: [], provides: {}, subpaths: WEB, use: WEB_USE },
64 { name: 'workers', lib: ['es2022'], types: ['@cloudflare/workers-types'], provides: { '@cloudflare/workers-types': '@cloudflare/workers-types' }, subpaths: WEB, use: WEB_USE },
65];
67// ply as the tarball lays it out ({package.json,dist}), built once; each variant gets its own copy.
68export function buildConsumer() {
69 const dir = mkdtempSync(join(tmpdir(), 'ply-dist-check-'));
70 const ply = join(dir, 'ply');
71 mkdirSync(ply);
72 copyFileSync(join(REPO, 'package.json'), join(ply, 'package.json'));
73 const built = spawnSync(TSC, ['-p', join(REPO, 'tsconfig.json'), '--outDir', join(ply, 'dist')], { cwd: REPO, encoding: 'utf8' });
74 if (built.status !== 0) throw new Error(`build failed:\n${built.stdout}${built.stderr}`);
75 return { dir, ply, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
76}
78const LOAD = "const m = await import('ply'); if (!m.Tracer || !m.RETRY) { console.error('dist-check: the built ply does not export Tracer and RETRY'); process.exit(1); }";
80// Import the build the way a consumer does. Returns the exit status (0 when both exports are there).
81export function loadConsumer(consumer) {
82 const dir = join(consumer.dir, 'load');
83 rmSync(dir, { recursive: true, force: true });
84 mkdirSync(join(dir, 'node_modules'), { recursive: true });
85 cpSync(consumer.ply, join(dir, 'node_modules', 'ply'), { recursive: true });
86 // NODE_OPTIONS may carry a hook path relative to this tree; the load runs in the scratch directory.
87 return spawnSync(process.execPath, ['--input-type=module', '-e', LOAD], { cwd: dir, stdio: 'inherit', env: { ...process.env, NODE_OPTIONS: '' } }).status ?? 1;
88}
90// Compile one variant in its own consumer project: node_modules/ply plus the variant's type package and nothing else.
91// Returns { errors, provided }: errors are tsc's `error TS` lines (empty when it compiles), or the one line naming a
92// type package that is not installed; provided maps each type package to the version the compile ran against.
93export function compileVariant(consumer, variant) {
94 const dir = join(consumer.dir, variant.name);
95 const modules = join(dir, 'node_modules');
96 rmSync(dir, { recursive: true, force: true });
97 mkdirSync(modules, { recursive: true });
98 cpSync(consumer.ply, join(modules, 'ply'), { recursive: true });
99 const provided = {};
100 for (const [name, source] of Object.entries(variant.provides)) {
101 const from = join(REPO, 'node_modules', source);
102 if (!existsSync(join(from, 'package.json'))) return { errors: [`${variant.name}: node_modules/${source} is not installed (run npm ci); this variant is never skipped`], provided };
103 provided[name] = JSON.parse(readFileSync(join(from, 'package.json'), 'utf8')).version;
104 mkdirSync(dirname(join(modules, name)), { recursive: true });
105 symlinkSync(from, join(modules, name));
106 }
107 const all = variant.subpaths.map((name, index) => `import * as m${index} from '${name}';`).join('\n')
108 + `\nexport const all = [${variant.subpaths.map((_, index) => `m${index}`).join(', ')}];\n`;
109 writeFileSync(join(dir, 'all.ts'), all);
110 writeFileSync(join(dir, 'use.ts'), variant.use);
111 const config = {
112 compilerOptions: {
113 noEmit: true, strict: true, exactOptionalPropertyTypes: true, noUncheckedIndexedAccess: true, skipLibCheck: false,
114 target: 'es2022', module: 'nodenext', moduleResolution: 'nodenext', lib: variant.lib, types: variant.types,
115 },
116 files: ['all.ts', 'use.ts'],
117 };
118 writeFileSync(join(dir, 'tsconfig.json'), JSON.stringify(config));
119 writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'consumer', private: true, type: 'module' }));
120 const run = spawnSync(TSC, ['-p', 'tsconfig.json', '--pretty', 'false'], { cwd: dir, encoding: 'utf8' });
121 const errors = `${run.stdout}${run.stderr}`.split('\n').filter(line => line.includes('error TS'));
122 if (run.status !== 0 && errors.length === 0) errors.push(`tsc exited ${run.status}: ${run.stdout}${run.stderr}`);
123 return { errors, provided };
124}
126if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
127 const consumer = buildConsumer();
128 let failed = false;
129 try {
130 const loaded = loadConsumer(consumer);
131 console.log(`dist-check load: ${loaded === 0 ? 'ok' : `failed (exit ${loaded})`}`);
132 if (loaded !== 0) failed = true;
133 for (const variant of VARIANTS) {
134 const { errors, provided } = compileVariant(consumer, variant);
135 const against = Object.entries(provided).map(([name, version]) => ` (${name} ${version})`).join('');
136 console.log(`dist-check types ${variant.name}${against}: ${errors.length} errors over ${variant.subpaths.length} subpaths`);
137 for (const line of errors) console.log(` ${line}`);
138 if (errors.length > 0) failed = true;
139 }
140 } finally { consumer.cleanup(); }
141 process.exit(failed ? 1 : 0);
142}
Diagnostics6 git calls · 129 ms
CallStatusSizeTime0129 ms
discover200191 B2 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 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 KiB · hit3 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=3 git.response.bytes=11990 git.response.cache=HIT git.response.duration_ms=3 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 · hit3 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=4347 git.response.cache=HIT git.response.duration_ms=3 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 · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=919 git.response.cache=HIT git.response.duration_ms=2 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 · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=831 git.response.cache=HIT git.response.duration_ms=2 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.5 KiB119 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=119 git.response.bytes=3571 git.response.cache=MISS git.response.duration_ms=119 git.fetch.wants=81fbd26b2a978c45c6e0565345a788e0b11f7718 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=3571 git.pkt.payload.max=3544 git.sideband.band1.bytes=3544 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
- a5e183d6195f3014
- Request
- 01297a9c…
- 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