Public: anyone can read this; the crew can change it.

Drift gate: a page may not define a one-off class for what a ui.ts part already does (warn with a count) #5893

Parked opened this
Closed without merging

scout/forge:scout/5881-drift-gate-a-page-may-not-define-a-one-o → main 4 commits fork 2 threads · 2 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
5 files changed +146 −4
docs/design/baseline.json +2 −1
@@ -1,3 +1,4 @@
11 {
2 "files": {}
2 "files": {},
3 "drift": 1
34 }
forge.json +5
@@ -15,8 +15,13 @@
1515 }
1616 },
1717 "check": {
18 <<<<<<< HEAD
19 "fast": "bun scripts/gate.ts && bun scripts/design-drift.ts && mkdir -p .forge-cache && GOMEMLIMIT=2GiB ./node_modules/typescript/bin/tsc --noEmit --incremental --tsBuildInfoFile .forge-cache/tsc.tsbuildinfo && FORGE_REQUIRE_CELLS=1 bun scripts/test-shards.ts --timeout 60000 --tier fast --diff $FORGE_CHECK_BASE..HEAD --learned \"$FORGE_CHECK_LEARNED\"",
20 "run": "bun scripts/gate.ts && bun scripts/design-drift.ts && mkdir -p .forge-cache && GOMEMLIMIT=2GiB ./node_modules/typescript/bin/tsc --noEmit --incremental --tsBuildInfoFile .forge-cache/tsc.tsbuildinfo && FORGE_REQUIRE_CELLS=1 bun scripts/test-shards.ts --timeout 60000 --gate --impact",
21 =======
1822 "fast": "bun scripts/gate.ts && mkdir -p .forge-cache && GOMEMLIMIT=2GiB ./node_modules/typescript/bin/tsc --noEmit --incremental --tsBuildInfoFile .forge-cache/tsc.tsbuildinfo && bun scripts/test-shards.ts --timeout 60000 --tier fast --diff $FORGE_CHECK_BASE..HEAD --learned \"$FORGE_CHECK_LEARNED\"",
1923 "run": "bun scripts/gate.ts && mkdir -p .forge-cache && GOMEMLIMIT=2GiB ./node_modules/typescript/bin/tsc --noEmit --incremental --tsBuildInfoFile .forge-cache/tsc.tsbuildinfo && bun scripts/test-shards.ts --timeout 60000 --gate --impact",
24 >>>>>>> origin/main
2025 "timeout": 7200,
2126 "limits": {
2227 "memory": 8192,
scripts/design-drift.ts added +92
@@ -0,0 +1,92 @@
1 /**
2 * The drift gate (#5881): a page module may not define a one-off class for
3 * what a `ui.ts` part already does. `design-lint.ts` ratchets new classes
4 * against DESIGN.md §5; this counts duplication — a `/* css *\/` rule in a
5 * page whose class is a home-made list, row, button, empty state or picker.
6 *
7 * A class is a duplicate when one of its words (`x-list`, `row-x`,
8 * `x-btn`) names a part: list/rows → `.list`/`.row`, btn/button → `.btn`,
9 * empty → `.empty`, picker → the search picker. Each class counts once per
10 * file, at the line of its first rule. The shared stylesheet (`src/web/style/`)
11 * and `ui.ts` are where the parts live and are not scanned.
12 *
13 * It is a warning: it prints `drift: N one-off classes duplicate a part` with
14 * file:line for each and exits 0. `--update` writes N to the `drift` key of
15 * docs/design/baseline.json, which `design-lint.ts --update` keeps.
16 */
17
18 import { existsSync, readFileSync, writeFileSync } from "node:fs";
19 import { join, relative } from "node:path";
20 import { sourceFiles } from "./design-lint.ts";
21
22 export type Duplicate = { file: string; line: number; cls: string; part: string };
23
24 /** The word in a class name → the part it re-makes. */
25 const PARTS: Record<string, string> = {
26 list: ".list/.row", lists: ".list/.row", row: ".list/.row", rows: ".list/.row",
27 btn: ".btn", button: ".btn", buttons: ".btn",
28 empty: ".empty", picker: "the search picker",
29 };
30
31 /** The part a class name re-makes, or undefined. */
32 export function partOf(cls: string): string | undefined {
33 for (const w of cls.split("-")) if (PARTS[w]) return PARTS[w];
34 return undefined;
35 }
36
37 const SHARED = /(^|\/)(style\/|ui\.ts$)/;
38
39 /** The css templates: tagged `/* css *\/ \`…\``, or the `const CSS = \`…\`` a page keeps beside its markup. */
40 const CSS_BLOCK = /(?:\/\* css \*\/|\b(?:const|let) [A-Za-z_]*CSS\s*=)\s*`((?:[^`\\]|\\.)*)`/g;
41
42 /** The one-off classes in one file's css templates, the first rule's line each. */
43 export function duplicatesIn(file: string, text: string): Duplicate[] {
44 const seen = new Set<string>();
45 const out: Duplicate[] = [];
46 for (const m of text.matchAll(CSS_BLOCK)) {
47 const css = m[1]!;
48 const from = m.index! + m[0].length - 1 - css.length;
49 // Selectors only: what precedes a `{`, comments blanked (newlines kept).
50 const bare = css.replace(/\/\*[\s\S]*?\*\//g, (c) => c.replace(/[^\n]/g, " "));
51 for (const sel of bare.matchAll(/([^{};]+)\{/g)) {
52 for (const c of sel[1]!.matchAll(/(?:^|[\s,>+~(\]:)])\.([a-z][a-z0-9_-]*)/gi)) {
53 const cls = c[1]!, part = partOf(cls);
54 if (!part || seen.has(cls)) continue;
55 seen.add(cls);
56 const at = from + sel.index! + sel[1]!.indexOf("." + cls, c.index!);
57 out.push({ file, line: text.slice(0, at).split("\n").length, cls, part });
58 }
59 }
60 }
61 return out.sort((a, b) => a.line - b.line);
62 }
63
64 /** The page modules: every src/web file but the ones that hold the parts. */
65 export function drift(root: string): Duplicate[] {
66 const files = sourceFiles(root);
67 const rel = (f: string) => relative(join(root, "src/web"), f);
68 // A class the shared stylesheet defines is the part itself, not a copy of it.
69 const shared = new Set(files.filter((f) => SHARED.test(rel(f))).flatMap((f) => duplicatesIn(f, readFileSync(f, "utf8")).map((d) => d.cls)));
70 return files
71 .filter((f) => !SHARED.test(rel(f)))

Pluralise: '1 one-off classes' reads wrong.

72 .flatMap((f) => duplicatesIn(relative(root, f), readFileSync(f, "utf8")))
73 .filter((d) => !shared.has(d.cls));
74 }
75
76 export function report(found: readonly Duplicate[]): string {
77 return [`drift: ${found.length} one-off ${found.length === 1 ? "class duplicates" : "classes duplicate"} a part`, ...found.map((d) => ` ${d.file}:${d.line} .${d.cls} → use ${d.part} from ui.ts`)].join("\n");
78 }
79
80 if (import.meta.main) {
81 const root = process.cwd();
82 const found = drift(root);
83 console.log(report(found));
84 const path = join(root, "docs/design/baseline.json");
85 const file = existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : { files: {} }; // a corrupt file throws
86 const base = file.drift;
87 if (typeof base === "number" && found.length > base) console.log(`warning: ${found.length - base} more than the baseline of ${base}; use the part, or run --update`);
88 if (process.argv.includes("--update")) {
89 writeFileSync(path, JSON.stringify({ ...file, drift: found.length }, null, 2) + "\n");
90 console.log("wrote docs/design/baseline.json");
91 }
92 }
scripts/design-lint.ts +6 −3
@@ -48,7 +48,7 @@
4848 * takes the baseline, a scan and the text of DESIGN.md with its sections.
4949 */
5050
51 import { readdirSync, readFileSync, writeFileSync } from "node:fs";
51 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
5252 import { join, relative } from "node:path";
5353
5454 /** The type scale in docs/DESIGN.md §3, in px. */
@@ -74,7 +74,7 @@ const WEB_MESSAGE: Record<(typeof WEB_KEYS)[number], string> = {
7474 input: "form input under 16px, which zooms iOS (specification.website, input size)",
7575 target: "interactive target under 24x24 CSS px, WCAG 2.5.8 (specification.website, target size)",
7676 };
77 export type Baseline = { files: Record<string, Counts> };
77 export type Baseline = { files: Record<string, Counts>; drift?: number };
7878 /** One offence, where it is and what the system offers instead. */
7979 export type Finding = { line: number; kind: "colour" | "size"; text: string; use: string };
8080 export type Scan = Baseline & { classes: string[]; found?: Record<string, Finding[]> };
@@ -317,7 +317,10 @@ if (import.meta.main) {
317317 const root = process.cwd();
318318 const now = scan(root);
319319 if (process.argv.includes("--update")) {
320 const baseline: Baseline = { files: now.files };
320 // Keep the keys this script does not own (`drift`, written by design-drift.ts).
321 let kept = {};
322 if (existsSync(join(root, BASELINE))) kept = JSON.parse(readFileSync(join(root, BASELINE), "utf8")); // a corrupt file throws
323 const baseline: Baseline = { ...kept, files: now.files };
321324 writeFileSync(join(root, BASELINE), JSON.stringify(baseline, null, 2) + "\n");
322325 console.log(`wrote ${BASELINE}`);
323326 } else {
test/design-drift.test.ts added +41
@@ -0,0 +1,41 @@
1 import { describe, expect, test } from "bun:test";
2 import { readFileSync } from "node:fs";
3 import { drift, duplicatesIn, partOf, report } from "../scripts/design-drift.ts";
4
5 const PAGE = [
6 "export const page = 1;",
7 "const CSS = `",
8 ".todo-list { display: grid; gap: 8px; }",
9 ".todo-list li { padding: 4px; }",
10 ".todo-card { padding: 8px; }",
11 "`;",
12 "const other = /* css */ `",
13 "/* .commented-btn { } */",
14 ".save-btn, .x:hover { color: var(--fg); }",
15 ".nothing-here-empty { margin: 0 }",
16 "`;",
17 ].join("\n");
18
19 describe("drift gate: one-off classes that duplicate a part (#5881)", () => {
20 test("a fixture page with a home-made list class is counted, once, at its first rule", () => {
21 const found = duplicatesIn("src/web/pages/fixture.ts", PAGE);
22 expect(found.map((d) => [d.cls, d.line])).toEqual([["todo-list", 3], ["save-btn", 9], ["nothing-here-empty", 10]]);
23 expect(report(found)).toContain("drift: 3 one-off classes duplicate a part");
24 expect(report(found)).toContain("src/web/pages/fixture.ts:3 .todo-list");
25 });
26
27 test("a single class reads in the singular", () => {
28 expect(report(duplicatesIn("p.ts", "const CSS = `.a-list { gap: 1px }`;"))).toContain("drift: 1 one-off class duplicates a part");
29 });
30
31 test("a page with no home-made part is clean", () => {
32 expect(duplicatesIn("p.ts", "const c = /* css */ `.todo-card { gap: 4px }`;")).toEqual([]);
33 expect(partOf("card")).toBeUndefined();
34 expect(partOf("rs-list")).toBe(".list/.row");
outdated

This turns the warning into a failing test for any count change, up or down. Assert drift(...).length <= base.drift instead, or remove it.

35 });
36
37 test("the tree is no worse than baseline.json (a ratchet: improving needs no update)", () => {
38 const base = JSON.parse(readFileSync("docs/design/baseline.json", "utf8"));
39 expect(drift(".").length).toBeLessThanOrEqual(base.drift);
40 }, 60_000);
41 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs