main
1// Ratchet for JavaScript absence spellings. The boundary module (src/absent.ts) is the
2// only exempt file. Everywhere else, the four needles below may only decrease.
3//
4// Needles are built from pieces so this file does not itself contain them. Comments
5// and string literals count: the gate is a grep, not a parser. A checked-in baseline
6// must match the scan exactly, and on a pull request each count must be <= the base.
8import { execFileSync } from "node:child_process";
9import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
10import { join, relative, sep } from "node:path";
11import { fileURLToPath, pathToFileURL } from "node:url";
13export const BOUNDARY = "src/absent.ts";
14export const BASELINE_PATH = "scripts/absence-baseline.json";
16const EXEMPT = new Set([BOUNDARY]);
17const ROOTS = ["src", "scripts", "test", "cloudflare.config.ts", "vite.config.ts"];
18const SKIP_DIRS = new Set(["node_modules", ".cloudflare", "dist", "coverage", ".git"]);
19const EXTENSIONS = new Set([".ts", ".tsx", ".js", ".mjs", ".cjs"]);
21const NEEDLES = {
22 word: `\\b${"un"}${"defined"}\\b`,
23 optional: `\\${"?"}:`,
24 chain: `\\${"?"}\\${"."}`,
25 nullish: `\\${"?"}\\${"?"}`,
26} as const;
28const KEYS = ["word", "optional", "chain", "nullish", "total"] as const;
30const LABEL: Readonly<Record<(typeof KEYS)[number], string>> = {
31 word: "absence-word",
32 optional: "optional-member",
33 chain: "optional-chain",
34 nullish: "nullish",
35 total: "total",
36};
38export type AbsenceCounts = {
39 readonly word: number;
40 readonly optional: number;
41 readonly chain: number;
42 readonly nullish: number;
43 readonly total: number;
44};
46export type AbsenceBaseline = {
47 readonly boundary: typeof BOUNDARY;
48 readonly counts: AbsenceCounts;
49 readonly files: Readonly<Record<string, AbsenceCounts>>;
50};
52type Part = {
53 word: number;
54 optional: number;
55 chain: number;
56 nullish: number;
57};
59export function repoRoot(): string {
60 return fileURLToPath(new URL("..", import.meta.url));
61}
63export function scanSource(text: string): AbsenceCounts {
64 return withTotal(tally(text));
65}
67export function scanRepo(root: string): AbsenceBaseline {
68 const paths: string[] = [];
69 for (const entry of ROOTS) collect(root, entry, paths);
70 paths.sort();
71 const files: Record<string, AbsenceCounts> = {};
72 const sum: Part = { word: 0, optional: 0, chain: 0, nullish: 0 };
73 for (const path of paths) {
74 const rel = normalize(relative(root, path));
75 if (EXEMPT.has(rel)) continue;
76 const counts = scanSource(readFileSync(path, "utf8"));
77 if (counts.total === 0) continue;
78 files[rel] = counts;
79 sum.word += counts.word;
80 sum.optional += counts.optional;
81 sum.chain += counts.chain;
82 sum.nullish += counts.nullish;
83 }
84 return { boundary: BOUNDARY, counts: withTotal(sum), files };
85}
87export function riseReasons(next: AbsenceCounts, previous: AbsenceCounts): readonly string[] {
88 const reasons: string[] = [];
89 for (const key of KEYS) {
90 if (next[key] > previous[key]) reasons.push(`${LABEL[key]} rose from ${previous[key]} to ${next[key]}`);
91 }
92 return reasons;
93}
95export function drift(scan: AbsenceBaseline, baseline: AbsenceBaseline): readonly string[] {
96 const lines: string[] = [];
97 if (baseline.boundary !== BOUNDARY) lines.push("baseline boundary is not the gate boundary");
98 for (const key of KEYS) {
99 if (scan.counts[key] !== baseline.counts[key]) {
100 lines.push(`${LABEL[key]}: scan ${scan.counts[key]}, baseline ${baseline.counts[key]}`);
101 }
102 }
103 const paths = [...new Set([...Object.keys(scan.files), ...Object.keys(baseline.files)])].sort();
104 for (const path of paths) {
105 const left = scan.files[path];
106 const right = baseline.files[path];
107 if (!left || !right) {
108 lines.push(left ? `${path}: missing from the baseline` : `${path}: baseline lists a clean file`);
109 continue;
110 }
111 for (const key of KEYS) {
112 if (left[key] !== right[key]) lines.push(`${path} ${LABEL[key]}: scan ${left[key]}, baseline ${right[key]}`);
113 }
114 }
115 return lines;
116}
118export function parseBaseline(text: string): AbsenceBaseline {
119 const raw: unknown = JSON.parse(text);
120 if (!isRecord(raw)) throw new Error("absence baseline is not an object");
121 if (raw.boundary !== BOUNDARY) throw new Error("absence baseline boundary does not match the gate");
122 const counts = parseCounts(raw.counts, "counts");
123 if (!isRecord(raw.files)) throw new Error("absence baseline files is not an object");
124 const files: Record<string, AbsenceCounts> = {};
125 for (const path of Object.keys(raw.files).sort()) {
126 files[path] = parseCounts(raw.files[path], path);
127 }
128 return { boundary: BOUNDARY, counts, files };
129}
131export function renderBaseline(baseline: AbsenceBaseline): string {
132 return `${JSON.stringify(baseline, null, 2)}\n`;
133}
135export function formatCounts(counts: AbsenceCounts): string {
136 return KEYS.map((key) => `${LABEL[key]} ${counts[key]}`).join(", ");
137}
139function main(argv: readonly string[]): number {
140 assertGateIsClean();
141 if (EXEMPT.size !== 1 || !EXEMPT.has(BOUNDARY)) {
142 console.error("absence gate: the exempt set must be the one boundary module");
143 return 1;
144 }
145 const root = repoRoot();
146 const scan = scanRepo(root);
147 const parsed = parseArgs(argv);
148 if (parsed.tag === "error") {
149 console.error(parsed.message);
150 return 2;
151 }
152 const write = parsed.tag === "write";
154 const baselineFile = join(root, BASELINE_PATH);
155 if (write) {
156 if (existsSync(baselineFile)) {
157 const previous = parseBaseline(readFileSync(baselineFile, "utf8"));
158 const reasons = riseReasons(scan.counts, previous.counts);
159 if (reasons.length > 0) {
160 console.error("absence gate: --write refused, the baseline may only decrease");
161 for (const reason of reasons) console.error(` ${reason}`);
162 return 1;
163 }
164 }
165 writeFileSync(baselineFile, renderBaseline(scan));
166 console.log(`absence gate: wrote ${BASELINE_PATH} (${formatCounts(scan.counts)})`);
167 return 0;
168 }
170 if (!existsSync(baselineFile)) {
171 console.error(`absence gate: missing ${BASELINE_PATH}; run with --write to create it`);
172 return 1;
173 }
174 const baseline = parseBaseline(readFileSync(baselineFile, "utf8"));
175 const lines = drift(scan, baseline);
176 if (lines.length > 0) {
177 console.error(`absence gate: scan does not match ${BASELINE_PATH}`);
178 for (const line of lines) console.error(` ${line}`);
179 console.error("Update a decrease with --write. A rise has to be removed.");
180 return 1;
181 }
182 console.log(`absence gate: ok (${formatCounts(scan.counts)})`);
184 if (parsed.tag !== "against") return 0;
185 const ref = parsed.ref;
186 const previous = readBaselineAt(ref, root);
187 if (previous === null) {
188 console.log(`absence gate: ${ref} has no baseline yet; decrease check skipped`);
189 return 0;
190 }
191 const reasons = riseReasons(scan.counts, previous.counts);
192 if (reasons.length > 0) {
193 console.error(`absence gate: baseline rose relative to ${ref}`);
194 for (const reason of reasons) console.error(` ${reason}`);
195 return 1;
196 }
197 console.log(`absence gate: did not rise relative to ${ref} (${formatCounts(previous.counts)})`);
198 return 0;
199}
201type CliArgs =
202 | { readonly tag: "check" }
203 | { readonly tag: "write" }
204 | { readonly tag: "against"; readonly ref: string }
205 | { readonly tag: "error"; readonly message: string };
207function parseArgs(argv: readonly string[]): CliArgs {
208 if (argv.length === 0) return { tag: "check" };
209 const head = argv[0];
210 if (argv.length === 1 && head === "--write") return { tag: "write" };
211 if (argv.length === 2 && head === "--against") {
212 const ref = argv[1];
213 if (typeof ref !== "string" || !validRef(ref)) return { tag: "error", message: "absence gate: --against needs a git ref" };
214 return { tag: "against", ref };
215 }
216 return { tag: "error", message: "absence gate: pass no arguments, --write, or --against <ref>" };
217}
219function readBaselineAt(ref: string, cwd: string): AbsenceBaseline | null {
220 try {
221 const text = execFileSync("git", ["show", `${ref}:${BASELINE_PATH}`], {
222 cwd,
223 encoding: "utf8",
224 stdio: ["ignore", "pipe", "pipe"],
225 });
226 return parseBaseline(text);
227 } catch (error: unknown) {
228 if (missingBaseline(error)) return null;
229 const message = error instanceof Error ? error.message : "git show failed";
230 throw new Error(`absence gate could not read ${ref}:${BASELINE_PATH}: ${message}`);
231 }
232}
234function missingBaseline(error: unknown): boolean {
235 if (typeof error !== "object" || error === null) return false;
236 let stderr = "";
237 if ("stderr" in error && typeof error.stderr === "string") stderr = error.stderr;
238 const message = error instanceof Error ? error.message : "";
239 const text = `${message}\n${stderr}`;
240 return text.includes("does not exist") || text.includes("exists on disk, but not in");
241}
243function validRef(ref: string): boolean {
244 return ref.length > 0 && !ref.startsWith("-") && !ref.includes(":") && !ref.includes("..");
245}
247function collect(root: string, entry: string, out: string[]): void {
248 const abs = join(root, entry);
249 if (!existsSync(abs)) return;
250 const stat = statSync(abs);
251 if (stat.isDirectory()) {
252 const parts = entry.split(sep);
253 const name = parts[parts.length - 1];
254 if (typeof name === "string" && SKIP_DIRS.has(name)) return;
255 for (const child of readdirSync(abs)) collect(root, join(entry, child), out);
256 return;
257 }
258 if (stat.isFile() && isCode(entry)) out.push(abs);
259}
261function isCode(path: string): boolean {
262 const dot = path.lastIndexOf(".");
263 if (dot < 0) return false;
264 return EXTENSIONS.has(path.slice(dot));
265}
267function tally(text: string): Part {
268 return {
269 word: count(text, NEEDLES.word),
270 optional: count(text, NEEDLES.optional),
271 chain: count(text, NEEDLES.chain),
272 nullish: count(text, NEEDLES.nullish),
273 };
274}
276function count(text: string, source: string): number {
277 return [...text.matchAll(new RegExp(source, "g"))].length;
278}
280function withTotal(part: Part): AbsenceCounts {
281 return {
282 word: part.word,
283 optional: part.optional,
284 chain: part.chain,
285 nullish: part.nullish,
286 total: part.word + part.optional + part.chain + part.nullish,
287 };
288}
290function parseCounts(value: unknown, where: string): AbsenceCounts {
291 if (!isRecord(value)) throw new Error(`absence baseline ${where} is not an object`);
292 const part: Part = {
293 word: integer(value.word, `${where}.word`),
294 optional: integer(value.optional, `${where}.optional`),
295 chain: integer(value.chain, `${where}.chain`),
296 nullish: integer(value.nullish, `${where}.nullish`),
297 };
298 const total = integer(value.total, `${where}.total`);
299 const counts = withTotal(part);
300 if (counts.total !== total) throw new Error(`absence baseline ${where}.total does not add up`);
301 return counts;
302}
304function integer(value: unknown, where: string): number {
305 if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
306 throw new Error(`absence baseline ${where} is not a non-negative integer`);
307 }
308 return value;
309}
311function isRecord(value: unknown): value is Record<string, unknown> {
312 return typeof value === "object" && value !== null && !Array.isArray(value);
313}
315function normalize(path: string): string {
316 return path.split(sep).join("/");
317}
319function assertGateIsClean(): void {
320 const text = readFileSync(fileURLToPath(import.meta.url), "utf8");
321 const counts = scanSource(text);
322 if (counts.total === 0) return;
323 const lines: number[] = [];
324 for (const source of Object.values(NEEDLES)) {
325 const re = new RegExp(source, "g");
326 for (const match of text.matchAll(re)) {
327 const index = typeof match.index === "number" ? match.index : 0;
328 lines.push(text.slice(0, index).split("\n").length);
329 }
330 }
331 throw new Error(`absence gate matched its own source at lines ${lines.join(", ")} (${formatCounts(counts)})`);
332}
334assertGateIsClean();
336const invoked = process.argv[1];
337if (typeof invoked === "string" && import.meta.url === pathToFileURL(invoked).href) {
338 process.exit(main(process.argv.slice(2)));
339}
Diagnostics4 git calls · 376 ms
CallStatusSizeTime0376 ms
discover200152 B4 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=4 git.response.bytes=152 git.server.agent=gitty/1.0 git.server.object_format=sha1 git.server.caps=agent ls-refs fetch object-format git.server.fetch=shallow filter sideband-all git.protocol.version=2 git.pkt.frames=8 git.pkt.data=6 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=152 git.pkt.payload.max=34
ls-refs200145 B4 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=145 git.response.cache=UPDATING git.response.duration_ms=4 git.protocol.version=2 git.pkt.frames=3 git.pkt.data=2 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=145 git.pkt.payload.max=76 git.ls_refs.count=2 git.ls_refs.head=refs/heads/main
fetchblob:none · deepen 1020042 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=42585 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=blob:none git.fetch.filter.requested=tree:0 git.fetch.filter.fallback=blob:none git.fetch.filter.learned=false git.fetch.wants=262b639aa1b258fc1777c3a66ba8f811df3a3da2 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=6 git.pkt.data=4 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=42585 git.pkt.payload.max=42490 git.sideband.band1.bytes=42489 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=61 git.pack.bytes=42489 git.pack.ofs_delta=0 git.pack.ref_delta=0 git.pack.chain.max=0 git.pack.trailer=7dbf576d97429022615f79aa46b440d9da603496 git.pack.full=61Open pack map
fetch2003.7 KiB369 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=369 git.response.bytes=3750 git.response.cache=MISS git.response.duration_ms=369 git.fetch.wants=521e1e52934045b8972bb867418fe7f6f9e9c21b 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=3 git.pkt.data=2 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=3750 git.pkt.payload.max=3729 git.sideband.band1.bytes=3728 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://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/ply-web.git
- Ref
- refs/heads/main
- Commit
- 262b639aa1b258fc1777c3a66ba8f811df3a3da2
- cf-ray
- a5e1cd561fc7c6f8
- Request
- ae7714a0…
- Protocol
- v2 · sha1
- Agent
- gitty/1.0
- Filter
- advertised
- Fetch
- shallow filter sideband-all
- Capabilities
- agent ls-refs fetch object-format