GitHubivarvong
ply
main
1// The hole computation shared by the gates (test/space/registry.test.js, test/space/failsites.test.js), the ratchet
2// writer and SPACES.md (scripts/spaces.mjs). A hole is one id in one category:
3//
4// decisions a decision point of the inventory (scripts/decision-points.mjs) that no registry rule names gate a
5// git a git-manifest entry (test/space/git-manifest.json) neither covered nor excluded gate b
6// failsites a fail site (fail / failHere / wrapper call) no recorded stack passed through, unless excluded gate c
7// claims a fail site the registry assigns to a space whose runners ran and did not reach it (merged or
8// pending: a space whose runners are in the run is judged, whatever its status says) gate c
9// linux a runner of a merged CI space with no record from a Linux run. Judged only on records from Linux (CI);
10// a macOS pass does not count: the filesystem there hides cells (a non-UTF-8 ref name cannot be a file)
11// stale a registry rule that matches nothing (the decision it named is gone or renamed)
12//
13// Ratchet (test/space/ratchet.json): per category, the ids that are holes today. A category stored with 0 holes is in
14// ENFORCE mode: any hole fails. Otherwise REPORT mode: the holes are printed and the gate passes, unless a hole is not
15// in the stored list (a new hole: the count can only go down, and a fixed hole cannot be traded for a new one). A fixed
16// hole is reported until the ratchet is rewritten (`npm run spaces -- --ratchet`), which never adds an id.
17import { readFileSync, readdirSync, existsSync } from 'node:fs';
18import { join, dirname } from 'node:path';
19import { fileURLToPath } from 'node:url';
20import { inventory, decisionPoints } from '../../scripts/decision-points.mjs';
21import { SPACES, DECISIONS, GIT, SAMPLED } from './registry.js';
23const HERE = dirname(fileURLToPath(import.meta.url));
24export const ROOT = join(HERE, '../..');
25export const RATCHET = join(HERE, 'ratchet.json');
26export const CATEGORIES = ['decisions', 'git', 'failsites', 'claims', 'linux', 'stale'];
27export const manifest = () => JSON.parse(readFileSync(join(HERE, 'git-manifest.json'), 'utf8'));
28export const ratchet = () => JSON.parse(readFileSync(RATCHET, 'utf8'));
29export const spaceByName = new Map(SPACES.map(s => [s.name, s]));
30export const isSite = p => p.kind === 'fail' || p.kind === 'failHere' || p.kind === 'wrapper';
32const glob = pattern => new RegExp(`^${pattern.split('*').map(s => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`);
33// Resolve every id against a rule list: an exact rule wins over a glob; among globs, the first in source order.
34export function resolve(ids, rules) {
35 const exact = new Map(), globs = [];
36 rules.forEach((r, i) => (r.match.includes('*') ? globs.push({ r, i, re: glob(r.match) }) : exact.set(r.match, { r, i })));
37 const used = new Set(), by = new Map();
38 for (const id of ids) {
39 // a decode is never swept in by a function glob: its mode is a decision of its own, named explicitly
40 const e = exact.get(id) ?? globs.find(g => g.re.test(id) && (!id.includes(':decode:') || g.r.match.includes(':decode:')));
41 if (e) { by.set(id, e.r); used.add(e.i); }
42 }
43 return { by, unused: rules.filter((_, i) => !used.has(i)) };
44}
46// Structural problems in the registry itself (always fatal: a rule naming a space or axis that does not exist is a typo,
47// not a hole).
48export function registryProblems(spaces = SPACES) {
49 const bad = [];
50 const names = new Set();
51 for (const s of spaces) {
52 if (names.has(s.name)) bad.push(`space ${s.name} registered twice`);
53 names.add(s.name);
54 if (!['main', 'pending'].includes(s.status)) bad.push(`space ${s.name}: status must be main or pending`);
55 if (s.status === 'pending' && !/^#\d+$/.test(s.pending ?? '')) bad.push(`space ${s.name}: a pending space names its PR (pending: '#NN')`);
56 if (!['enumerated', 'curated', 'random'].includes(s.kind)) bad.push(`space ${s.name}: kind must be enumerated, curated or random`);
57 if (!['ci', 'ci-step', 'nightly', 'local', 'manual'].includes(s.run)) bad.push(`space ${s.name}: run must be ci, ci-step, nightly, local or manual`);
58 if (s.osDependent !== undefined && (typeof s.osDependent !== 'string' || s.osDependent.length < 12)) bad.push(`space ${s.name}: osDependent says why`);
59 if (!s.oracle) bad.push(`space ${s.name}: no oracle`);
60 if (!s.axes?.length) bad.push(`space ${s.name}: no axes`);
61 if (s.status === 'main') for (const r of s.runners ?? []) if (!existsSync(join(ROOT, r))) bad.push(`space ${s.name}: runner ${r} does not exist`);
62 // a pending space is one whose runners are not in this tree yet. Once they all are, it is merged: left pending,
63 // its sites would be claimed (gate a green) by a space the Linux gate and SPACES.md treat as not there
64 if (s.status === 'pending' && s.runners?.length && s.runners.every(r => existsSync(join(ROOT, r)))) bad.push(`space ${s.name}: pending (${s.pending}) but every runner is in the tree; it is merged: status: 'main'`);
65 }
66 for (const [list, rules] of [['DECISIONS', DECISIONS], ['GIT', GIT]]) for (const r of rules) {
67 if (typeof r.match !== 'string' || !r.match) { bad.push(`${list}: a rule without match`); continue; }
68 if ('excluded' in r) { if (typeof r.excluded !== 'string' || r.excluded.length < 12) bad.push(`${list} ${r.match}: an exclusion needs a reason`); continue; }
69 const s = spaceByName.get(r.space);
70 if (!s) { bad.push(`${list} ${r.match}: unknown space ${r.space}`); continue; }
71 if (!s.axes.some(a => a.tag === r.axisTag)) bad.push(`${list} ${r.match}: space ${r.space} has no axis ${r.axisTag} (axes: ${s.axes.map(a => a.tag).join(', ')})`);
72 }
73 return bad;
74}
76// Fail-site records written by test/space/failsite-hook.mjs: frame -> Set(runner).
77export function readRecords(dir) {
78 const frames = new Map();
79 const runners = new Set();
80 const platforms = new Map(); // runner -> Set(platform)
81 // frame -> Set(runner) for the errors a test read; null when no record carries the field (records of an older
82 // recorder): then `observed` is not judged, which is not the same as nothing observed
83 let observed = null;
84 if (!dir || !existsSync(dir)) return null;
85 for (const f of readdirSync(dir).filter(x => x.endsWith('.json'))) {
86 const rec = JSON.parse(readFileSync(join(dir, f), 'utf8'));
87 runners.add(rec.runner);
88 if (!platforms.has(rec.runner)) platforms.set(rec.runner, new Set());
89 platforms.get(rec.runner).add(rec.platform ?? 'unknown');
90 for (const k of Object.keys(rec.frames)) { if (!frames.has(k)) frames.set(k, new Set()); frames.get(k).add(rec.runner); }
91 if (Array.isArray(rec.observed)) {
92 observed ??= new Map();
93 for (const k of rec.observed) { if (!observed.has(k)) observed.set(k, new Set()); observed.get(k).add(rec.runner); }
94 }
95 }
96 return { frames, runners, platforms, observed };
97}
98export const frameOf = p => `${p.file}:${p.callLine}:${p.col}`;
100// Everything the gates and SPACES.md need, computed once.
101export function compute({ records = null, spaces = SPACES, decisions = DECISIONS } = {}) {
102 const byName = spaces === SPACES ? spaceByName : new Map(spaces.map(s => [s.name, s]));
103 const inv = inventory();
104 const points = decisionPoints(inv);
105 const man = manifest();
106 const dec = resolve(points.map(p => p.id), decisions);
107 const git = resolve(man.entries.map(e => e.id), GIT);
108 const holes = { decisions: [], git: [], failsites: null, claims: null, observed: null, linux: null, stale: [] };
109 for (const p of points) if (!dec.by.has(p.id)) holes.decisions.push(p.id);
110 for (const e of man.entries) if (!git.by.has(e.id)) holes.git.push(e.id);
111 for (const r of dec.unused) holes.stale.push(`DECISIONS ${r.match}`);
112 for (const r of git.unused) holes.stale.push(`GIT ${r.match}`);
113 const sites = points.filter(isSite);
114 let reachedBy = null;
115 if (records) {
116 reachedBy = new Map(sites.map(p => [p.id, records.frames.get(frameOf(p)) ?? new Set()]));
117 const sampled = new Set(SAMPLED.map(s => s.id));
118 // a site the registry excludes (with its reason) is not a hole for gate c either
119 const excluded = p => { const r = dec.by.get(p.id); return !!r && 'excluded' in r; };
120 holes.failsites = sites.filter(p => !reachedBy.get(p.id).size && !sampled.has(p.id) && !excluded(p)).map(p => p.id);
121 // reached is not judged: a site whose error code no test read (see failsite-hook.mjs) would pass
122 // gate c with a wrong code, message or outcome. Reported by failsites.test.js; not in CATEGORIES (no ratchet
123 // baseline yet: that needs one recorded run of the whole suite)
124 if (records.observed) holes.observed = sites.filter(p => reachedBy.get(p.id).size && !records.observed.get(frameOf(p))?.size && !sampled.has(p.id) && !excluded(p)).map(p => p.id);
125 holes.claims = [];
126 for (const p of sites) {
127 const r = dec.by.get(p.id);
128 const s = r && !('excluded' in r) ? byName.get(r.space) : null;
129 if (!s || !s.runners?.length || sampled.has(p.id)) continue;
130 // a claim is checked only when its space's runners were part of this run. The space's status is not asked: a
131 // pending space whose runner ran is judged like a merged one (a glob claims every new site in its file)
132 if (!s.runners.some(x => records.runners.has(x))) continue;
133 if (!s.runners.some(x => reachedBy.get(p.id).has(x))) holes.claims.push(`${p.id} -> ${s.name}`);
134 }
135 }
136 // the Linux gate: only a run that has Linux records can judge it (null otherwise: not judged, not passed)
137 if (records && [...(records.platforms?.values() ?? [])].some(p => p.has('linux'))) {
138 holes.linux = [];
139 for (const s of spaces) if (s.status === 'main' && s.run === 'ci') for (const r of s.runners ?? []) if (!records.platforms.get(r)?.has('linux')) holes.linux.push(`${s.name}: ${r}`);
140 }
141 return { inv, points, sites, man, dec, git, holes, reachedBy };
142}
144// Gate verdict for one category against the ratchet: { mode, problems, fixed }.
145export function judge(category, ids, stored = ratchet().categories[category]) {
146 const known = new Set(stored?.ids ?? []);
147 const mode = (stored?.count ?? 0) === 0 ? 'ENFORCE' : 'REPORT';
148 const fresh = ids.filter(id => !known.has(id));
149 const fixed = [...known].filter(id => !ids.includes(id));
150 return { mode, problems: mode === 'ENFORCE' ? ids : fresh, fixed, count: ids.length, stored: stored?.count ?? 0 };
151}
153// ---- severity: what a hole costs if git and ply disagree there ----
154// 1: a strict or replacement decode of bytes git passes through raw (unless the registry says display-only);
155// a check on untrusted input (anything a server, a repository or the wire decides: objects, packs, pkt-lines,
156// reports, advertisements), on either side (a git check with no space, or a ply parser site no cell reached)
157// 2: a decision that claims an outcome: landed, rejected, conflict, ambiguous, not fast-forward
158// 3: the rest (caller input validation, limits, local I/O)
159const UNTRUSTED_CODES = new Set(['pack_corrupt', 'protocol', 'not_git', 'remote_error']);
160const OUTCOME_CODES = new Set(['cas_conflict', 'push_rejected', 'ambiguous', 'merge_conflict', 'not_fast_forward', 'not_linear', 'unrelated_histories', 'match_count']);
161const UNTRUSTED_GIT_KINDS = new Set(['fsck-msg', 'tree-mode', 'reject', 'ng', 'err-pkt', 'capability', 'refname-rule']);
162const CLIENT_SIDE_PARSERS = new Set(['pkt-line.c', 'sideband.c', 'connect.c', 'send-pack.c']);
163export function severityOfPoint(p) {
164 if (p.kind === 'decode') return p.mode === 'lossless' ? 3 : 1;
165 if (UNTRUSTED_CODES.has(p.code)) return 1;
166 if (OUTCOME_CODES.has(p.code)) return 2;
167 if (p.kind === 'export' && /^(parse|decode)/.test(p.fn)) return 1;
168 if (p.kind === 'export' && /^(decide|classify)/.test(p.fn)) return 2;
169 return 3;
170}
171export function severityOfGit(e) {
172 if (UNTRUSTED_GIT_KINDS.has(e.kind)) return e.kind === 'fsck-msg' && e.severity === 'IGNORE' ? 3 : 1;
173 if ((e.kind === 'die' || e.kind === 'error') && CLIENT_SIDE_PARSERS.has(e.file)) return 1;
174 return 3;
175}
Diagnostics7 git calls · 101 ms
CallStatusSizeTime0101 ms
discover200191 B3 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=3 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 · hit4 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=4 git.response.bytes=11990 git.response.cache=HIT git.response.duration_ms=4 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 · 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=4347 git.response.cache=HIT git.response.duration_ms=2 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:02005.6 KiB · 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=5724 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=58fabb6768b3f737ee9cd8bac647bdc27405fb4d 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=5724 git.pkt.payload.max=5697 git.sideband.band1.bytes=5697 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=5697 git.pack.trailer=be7e0453974a5fe832f9065a33bb7e3434c10e9bOpen pack map
fetchtree:02001.4 KiB · 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=1428 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=74d7bb09987bbe78a9c0ea8f43a1b5a4e079f538 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=1428 git.pkt.payload.max=1401 git.sideband.band1.bytes=1401 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=1401 git.pack.trailer=65ea1a3aeef333a80a2dfa3f441e629d90497e8eOpen pack map
fetch2004.5 KiB89 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=89 git.response.bytes=4589 git.response.cache=MISS git.response.duration_ms=89 git.fetch.wants=c849bbb613955eab32eacb56f9b703ee019f1474 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=4589 git.pkt.payload.max=4562 git.sideband.band1.bytes=4562 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
- a5e2f0063ab4fda9
- Request
- a0e39a1e…
- 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