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
scout/forge:scout/5881-drift-gate-a-page-may-not-define-a-one-o → main 4 commits fork 2 threads · 2 unresolved
5 files
changed +146
−4
docs/design/baseline.json +2 −1
| @@ -1,3 +1,4 @@ | ||
| 1 | 1 | { |
| 2 | "files": {} | |
| 2 | "files": {}, | |
| 3 | "drift": 1 | |
| 3 | 4 | } |
forge.json +5
| @@ -15,8 +15,13 @@ | ||
| 15 | 15 | } |
| 16 | 16 | }, |
| 17 | 17 | "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 | ======= | |
| 18 | 22 | "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\"", |
| 19 | 23 | "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 | |
| 20 | 25 | "timeout": 7200, |
| 21 | 26 | "limits": { |
| 22 | 27 | "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))) | |
| 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 @@ | ||
| 48 | 48 | * takes the baseline, a scan and the text of DESIGN.md with its sections. |
| 49 | 49 | */ |
| 50 | 50 | |
| 51 | import { readdirSync, readFileSync, writeFileSync } from "node:fs"; | |
| 51 | import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs"; | |
| 52 | 52 | import { join, relative } from "node:path"; |
| 53 | 53 | |
| 54 | 54 | /** The type scale in docs/DESIGN.md §3, in px. */ |
| @@ -74,7 +74,7 @@ const WEB_MESSAGE: Record<(typeof WEB_KEYS)[number], string> = { | ||
| 74 | 74 | input: "form input under 16px, which zooms iOS (specification.website, input size)", |
| 75 | 75 | target: "interactive target under 24x24 CSS px, WCAG 2.5.8 (specification.website, target size)", |
| 76 | 76 | }; |
| 77 | export type Baseline = { files: Record<string, Counts> }; | |
| 77 | export type Baseline = { files: Record<string, Counts>; drift?: number }; | |
| 78 | 78 | /** One offence, where it is and what the system offers instead. */ |
| 79 | 79 | export type Finding = { line: number; kind: "colour" | "size"; text: string; use: string }; |
| 80 | 80 | export type Scan = Baseline & { classes: string[]; found?: Record<string, Finding[]> }; |
| @@ -317,7 +317,10 @@ if (import.meta.main) { | ||
| 317 | 317 | const root = process.cwd(); |
| 318 | 318 | const now = scan(root); |
| 319 | 319 | 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 }; | |
| 321 | 324 | writeFileSync(join(root, BASELINE), JSON.stringify(baseline, null, 2) + "\n"); |
| 322 | 325 | console.log(`wrote ${BASELINE}`); |
| 323 | 326 | } 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 | }); |
new above
offline
Pluralise: '1 one-off classes' reads wrong.