GitHubivarvong

ply

main
ply6 git calls121 ms20 KiB3 cachedprotocol v2
121 lines6.6 KiBRaw
1// Absence ratchet. Outside src/absent.ts, counts of the platform missing value (the `undefined` identifier or type
2// keyword, `void <literal>`), optional members and parameters (`a?: T`, `m?(): T`, a mapped `?:`, an optional tuple
3// member), optional chaining (`?.`), and nullish coalescing (`??`, `??=`) must match scripts/absence-baseline.json
4// exactly. A rise fails. A drop fails until this change lowers the baseline, so the count only moves down on purpose.
5//
6// It counts syntax, not text: each file is parsed (@babel/parser with its typescript plugin, the parser scripts/decision-points.mjs uses) and the nodes are counted, so `(?:` in a
7// regex literal, `??` in a string or template text, and `undefined` in a comment are nothing, and `a? : T` or `void 0`
8// are what they are however they are spaced. (The textual count once failed a regex's non-capturing group and the
9// "fix" loosened a wire parser; a gate must not change parser behaviour for no reason.)
10//
11// node scripts/absence-ratchet.mjs compare, exit 1 on any difference
12// node scripts/absence-ratchet.mjs --write rewrite the baseline when the count fell (a rise is refused)
13import { readFileSync, writeFileSync, readdirSync, existsSync } from 'node:fs';
14import { join } from 'node:path';
15import { pathToFileURL } from 'node:url';
16import { createRequire } from 'node:module';
18export const BOUNDARY = 'src/absent.ts';
19const BASELINE_PATH = 'scripts/absence-baseline.json';
20const KEYS = ['undefined', 'optional', 'chain', 'coalesce'];
22const { parse } = createRequire(import.meta.url)('@babel/parser');
23const LITERALS = new Set(['NumericLiteral', 'BigIntLiteral', 'StringLiteral', 'NullLiteral', 'BooleanLiteral']);
24const CHAIN = new Set(['OptionalMemberExpression', 'OptionalCallExpression', 'MemberExpression', 'CallExpression']);
25const NOT_SYNTAX = new Set(['loc', 'leadingComments', 'trailingComments', 'innerComments', 'comments', 'tokens', 'errors', 'extra']);
26// One count per syntax node. Exported for the test: (file name, source text) -> counts. A file that does not parse
27// throws: it is never counted as empty.
28export function tally(file, text) {
29 const counts = { undefined: 0, optional: 0, chain: 0, coalesce: 0 };
30 const visit = node => {
31 const t = node.type;
32 // the missing value: the identifier (an expression, a shorthand member, a binding), the type keyword, `void 0`
33 if (t === 'TSUndefinedKeyword' || (t === 'Identifier' && node.name === 'undefined')) counts.undefined += 1;
34 else if (t === 'UnaryExpression' && node.operator === 'void' && LITERALS.has(node.argument.type)) counts.undefined += 1;
35 // `?.`: the link that carries the token (the rest of the chain has optional: false)
36 if (CHAIN.has(t)) { if (node.optional === true) counts.chain += 1; }
37 // an optional member, method, parameter, mapped member (`?:` or `+?:`; `-?:` removes optionality) or tuple member
38 else if (t === 'TSOptionalType' || node.optional === true || node.optional === '+') counts.optional += 1;
39 if ((t === 'LogicalExpression' && node.operator === '??') || (t === 'AssignmentExpression' && node.operator === '??=')) counts.coalesce += 1;
40 for (const key of Object.keys(node)) {
41 if (NOT_SYNTAX.has(key)) continue;
42 const child = node[key];
43 if (Array.isArray(child)) { for (const c of child) if (c !== null && typeof c === 'object' && typeof c.type === 'string') visit(c); }
44 else if (child !== null && typeof child === 'object' && typeof child.type === 'string') visit(child);
45 }
46 };
47 visit(parse(text, { sourceType: 'module', errorRecovery: false, plugins: file.endsWith('.ts') ? ['typescript'] : [] }).program);
48 return counts;
51const walk = dir => readdirSync(dir, { withFileTypes: true }).flatMap(entry => {
52 const path = join(dir, entry.name).split('\\').join('/');
53 if (entry.isDirectory()) return walk(path);
54 return /\.(?:ts|js|mjs|cjs)$/.test(entry.name) ? [path] : [];
55});
57export function countTree() {
58 const totals = { boundary: BOUNDARY, undefined: 0, optional: 0, chain: 0, coalesce: 0 };
59 const files = [];
60 for (const file of walk('src')) {
61 if (file === BOUNDARY) continue;
62 const counts = tally(file, readFileSync(file, 'utf8'));
63 const n = KEYS.reduce((sum, key) => sum + counts[key], 0);
64 if (n) files.push({ file, ...counts, n });
65 for (const key of KEYS) totals[key] += counts[key];
66 }
67 files.sort((a, b) => b.n - a.n || a.file.localeCompare(b.file));
68 return { totals, files };
71export function compareCounts(actual, baseline) {
72 const problems = [];
73 if (actual.boundary !== baseline.boundary) problems.push(`boundary is ${actual.boundary}, baseline says ${baseline.boundary}`);
74 for (const key of KEYS) {
75 const got = actual[key];
76 const want = baseline[key];
77 if (typeof want !== 'number') problems.push(`${key} is ${got}, baseline has no number`);
78 else if (got > want) problems.push(`${key} rose ${want} -> ${got}; absence outside ${actual.boundary} may only fall`);
79 else if (got < want) problems.push(`${key} fell ${want} -> ${got}; lower ${BASELINE_PATH} in this change`);
80 }
81 return problems;
84function main() {
85 if (!existsSync(BOUNDARY)) {
86 console.error(`absence-ratchet: ${BOUNDARY} is missing; it is the only file that may name platform absence`);
87 process.exit(1);
88 }
89 const { totals, files } = countTree();
90 const write = process.argv.includes('--write');
91 let baseline = null;
92 if (existsSync(BASELINE_PATH)) baseline = JSON.parse(readFileSync(BASELINE_PATH, 'utf8'));
93 if (!baseline) {
94 if (!write) {
95 console.error(`absence-ratchet: no ${BASELINE_PATH}; run with --write to create it`);
96 process.exit(1);
97 }
98 writeFileSync(BASELINE_PATH, `${JSON.stringify(totals, null, 2)}\n`);
99 console.log(`absence-ratchet: wrote ${BASELINE_PATH}`);
100 process.exit(0);
101 }
102 const problems = compareCounts(totals, baseline);
103 if (write) {
104 const rose = problems.filter(line => line.includes('rose'));
105 if (rose.length) {
106 console.error(`absence-ratchet:\n ${rose.join('\n ')}`);
107 process.exit(1);
108 }
109 writeFileSync(BASELINE_PATH, `${JSON.stringify(totals, null, 2)}\n`);
110 console.log(`absence-ratchet: wrote ${BASELINE_PATH}`);
111 process.exit(0);
112 }
113 if (problems.length) {
114 const detail = files.map(row => ` ${row.file}: undefined ${row.undefined}, optional ${row.optional}, chain ${row.chain}, coalesce ${row.coalesce}`).join('\n');
115 console.error(`absence-ratchet:\n ${problems.join('\n ')}\n${detail}`);
116 process.exit(1);
117 }
118 console.log(`absence-ratchet: undefined ${totals.undefined}, optional ${totals.optional}, chain ${totals.chain}, coalesce ${totals.coalesce} (boundary ${BOUNDARY})`);
121if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();
Diagnostics6 git calls · 121 ms
CallStatusSizeTime0121 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 KiB3 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=UPDATING
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=10
Open pack map
fetchtree:0200919 B · hit1 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=1
git.response.bytes=919
git.response.cache=HIT
git.response.duration_ms=1
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=5323b9266eea5ded637285d1c5320699f12be76e
Open 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=3
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=81ddc1f73214935b4ee953ad84f959db955ce0d1
Open pack map
fetch2002.6 KiB111 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=111
git.response.bytes=2646
git.response.cache=MISS
git.response.duration_ms=111
git.fetch.wants=59412d7a5e3cc7d29a1bcef060cb8569368bf802
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=2646
git.pkt.payload.max=2619
git.sideband.band1.bytes=2619
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
a5e1cbfe2d0ec6f8
Request
a42cc5c5…
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