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

Automate a review finding as a lint or test: **Design system.** The page departs from docs/DESIGN.md (see line comments for p #13577

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/13575-automate-a-review-finding-as-a-lint-or-t → main 7 commits fork 3 threads · 3 unresolved

  • Merged. scout/13575-automate-a-review-finding-as-a-lint-or-t was merged into main as f760ce8.

Review

Sign in to review this change.
5 files changed +253 −9
docs/design/areas/quiet.md +3
@@ -16,6 +16,9 @@ markup and style, never in a paragraph's words. What already breaks one on main
1616 takes layout space beside a button, tab or the top bar: the element carries `hintAttr(key)` (`data-hint`), which shows
outdated

Principle 8 and doc integrity: this bullet is inserted in the middle of the keyhint bullet. 'A shortcut never' (line 15) now ends at your text, and 'takes layout space beside a button…' (line 17) is orphaned. Move it to after the keyhint bullet's last line, and wrap it at the file's width like the rest.

1717 as a tooltip on hover or focus and as an overlay while Option is held, and never on touch. Only a menu or palette row,
1818 which has a column for it, draws the `<kbd>`.
19 - `pagehead` — a hand-rolled element with the `page-head` class outside `pageHead()` in `src/web/chrome.ts`. The head
20 says in one plain sentence what the page is for (`sub`), which a bare div has no place for (principles 1 and 8;
21 asked for in four reviews, #13575).
1922
2023 - `banner` (#10699) — `role="alert"`, a `.banner` or a `.notice-danger` in the home and board builders (`board.ts`, `boards-view.ts`, `studio/home*.ts`, `alarm_lines.ts`), zero allowed. A setting that is off is one line on its own page and the system page; only a transient flash (its tag carries `data-flash`) may alert.
2124 - `test/calm-banners.test.ts` renders `/` and `/board` for an admin on a healthy forge and with egress in report mode: neither carries an alert; the fault is one line on Capacity and System.
docs/design/quiet-debt.json +215 −1
@@ -1,6 +1,220 @@
11 {
2 "src/web/failed_page.ts": {
3 "pagehead": 1
4 },
5 "src/web/pages/access.ts": {
6 "pagehead": 1
7 },
8 "src/web/pages/account.ts": {
9 "pagehead": 2
10 },
11 "src/web/pages/accounts.ts": {
12 "pagehead": 1
13 },
14 "src/web/pages/admin-limits.ts": {
15 "pagehead": 1
16 },
17 "src/web/pages/api.ts": {
18 "pagehead": 2
19 },
20 "src/web/pages/app_templates.ts": {
21 "pagehead": 2
22 },
23 "src/web/pages/audit.ts": {
24 "pagehead": 1
25 },
26 "src/web/pages/backups.ts": {
27 "pagehead": 1
28 },
29 "src/web/pages/billing.ts": {
30 "pagehead": 2
31 },
32 "src/web/pages/boards-view.ts": {
33 "pagehead": 1
34 },
35 "src/web/pages/bring.ts": {
36 "pagehead": 4
37 },
38 "src/web/pages/browse.ts": {
39 "pagehead": 3
40 },
41 "src/web/pages/cloud.ts": {
42 "pagehead": 2
43 },
44 "src/web/pages/confirms.ts": {
45 "pagehead": 1
46 },
47 "src/web/pages/contribute.ts": {
48 "pagehead": 1
49 },
50 "src/web/pages/cost.ts": {
51 "pagehead": 1
52 },
53 "src/web/pages/crew.ts": {
54 "pagehead": 1
55 },
56 "src/web/pages/display.ts": {
57 "pagehead": 1
58 },
59 "src/web/pages/economics.ts": {
60 "pagehead": 1
61 },
62 "src/web/pages/features.ts": {
63 "pagehead": 1
64 },
65 "src/web/pages/flags.ts": {
66 "pagehead": 2
67 },
68 "src/web/pages/fleet-graph.ts": {
69 "pagehead": 1
70 },
71 "src/web/pages/fleet-ops.ts": {
72 "pagehead": 1
73 },
74 "src/web/pages/fleet.ts": {
75 "pagehead": 1
76 },
77 "src/web/pages/gate.ts": {
78 "pagehead": 1
79 },
80 "src/web/pages/hosted-forges.ts": {
81 "pagehead": 1
82 },
83 "src/web/pages/issues.ts": {
84 "pagehead": 1
85 },
86 "src/web/pages/iterations.ts": {
87 "pagehead": 1
88 },
89 "src/web/pages/maintenance.ts": {
90 "pagehead": 1
91 },
292 "src/web/pages/map.ts": {
3 "caps": 1
93 "caps": 1,
94 "pagehead": 2
95 },
96 "src/web/pages/milestones.ts": {
97 "pagehead": 1
98 },
99 "src/web/pages/model.ts": {
100 "pagehead": 1
101 },
102 "src/web/pages/my-repos.ts": {
103 "pagehead": 1
104 },
105 "src/web/pages/notes.ts": {
106 "pagehead": 1
107 },
108 "src/web/pages/now.ts": {
109 "pagehead": 1
110 },
111 "src/web/pages/org.ts": {
112 "pagehead": 1
113 },
114 "src/web/pages/origin-flow.ts": {
115 "pagehead": 2
116 },
117 "src/web/pages/origin-repos.ts": {
118 "pagehead": 1
119 },
120 "src/web/pages/origins.ts": {
121 "pagehead": 1
122 },
123 "src/web/pages/passkeys.ts": {
124 "pagehead": 8
125 },
126 "src/web/pages/payments.ts": {
127 "pagehead": 1
128 },
129 "src/web/pages/people.ts": {
130 "pagehead": 1
131 },
132 "src/web/pages/pinned.ts": {
133 "pagehead": 1
134 },
135 "src/web/pages/pipeline.ts": {
136 "pagehead": 1
137 },
138 "src/web/pages/privacy.ts": {
139 "pagehead": 1
140 },
141 "src/web/pages/releases.ts": {
142 "pagehead": 1
143 },
144 "src/web/pages/repo.ts": {
145 "pagehead": 1
146 },
147 "src/web/pages/resilience.ts": {
148 "pagehead": 2
149 },
150 "src/web/pages/scrapes.ts": {
151 "pagehead": 1
152 },
153 "src/web/pages/secrets.ts": {
154 "pagehead": 1
155 },
156 "src/web/pages/security.ts": {
157 "pagehead": 1
158 },
159 "src/web/pages/security_controls.ts": {
160 "pagehead": 1
161 },
162 "src/web/pages/security_public.ts": {
163 "pagehead": 1
164 },
165 "src/web/pages/site.ts": {
166 "pagehead": 2
167 },
168 "src/web/pages/sources.ts": {
169 "pagehead": 1
170 },
171 "src/web/pages/status.ts": {
172 "pagehead": 1
173 },
174 "src/web/pages/subscriptions.ts": {
175 "pagehead": 1
176 },
177 "src/web/pages/system.ts": {
178 "pagehead": 1
179 },
180 "src/web/pages/teams.ts": {
181 "pagehead": 2
182 },
183 "src/web/pages/terms.ts": {
184 "pagehead": 1
185 },
186 "src/web/pages/traffic.ts": {
187 "pagehead": 1
188 },
189 "src/web/pages/trusted.ts": {
190 "pagehead": 1
191 },
192 "src/web/pages/usage-tabs.ts": {
193 "pagehead": 1
194 },
195 "src/web/pages/usage.ts": {
196 "pagehead": 1
197 },
198 "src/web/pages/week.ts": {
199 "pagehead": 1
200 },
201 "src/web/pinned.ts": {
202 "pagehead": 1
203 },
204 "src/web/settings/devices.ts": {
205 "pagehead": 1
206 },
207 "src/web/studio/change.ts": {
208 "pagehead": 1
209 },
210 "src/web/studio/previews.ts": {
211 "pagehead": 1
212 },
213 "src/web/studio/run.ts": {
214 "pagehead": 1
215 },
216 "src/web/studio/tell.ts": {
217 "pagehead": 1
4218 },
5219 "src/web/style/components.ts": {
6220 "caps": 4
scripts/design-lint.ts +11 −4
@@ -323,13 +323,13 @@ export function compare(base: Baseline, now: Scan, design: string, areas: readon
323323 /**
324324 * The quiet-page rules a machine can check (#8775, from #8719): markup and style only, never prose.
325325 */
326 export type QuietRule = "label" | "caps" | "echo" | "inline-colour" | "keyhint" | "accent";
326 export type QuietRule = "label" | "caps" | "echo" | "inline-colour" | "keyhint" | "accent" | "pagehead";
327327 export type QuietFinding = { line: number; rule: QuietRule; text: string; use: string };
328 export const QUIET_RULES: readonly QuietRule[] = ["label", "caps", "echo", "inline-colour", "keyhint", "accent"];
328 export const QUIET_RULES: readonly QuietRule[] = ["label", "caps", "echo", "inline-colour", "keyhint", "accent", "pagehead"];
329329 const STATUS_WORD = "open|closed|merged|draft|done|failed|passing|failing|pending|running|queued|shipped|blocked|active|ready";
330330
331331 /** Where `text` breaks a quiet-page rule: file line, the offence, and what to use instead. */
332 export function quiet(text: string): QuietFinding[] {
332 export function quiet(text: string, file = ""): QuietFinding[] {
333333 const code = blanked(text);
334334 const at = (i: number) => code.slice(0, i).split("\n").length;
335335 const out: QuietFinding[] = [];
@@ -361,6 +361,13 @@ export function quiet(text: string): QuietFinding[] {
361361 for (const m of code.matchAll(/--accent(?!-fg\b)(?:[-_][a-z0-9_-]*|\d+)(?![\w-])/gi)) {
362362 out.push({ line: at(m.index!), rule: "accent", text: m[0], use: "var(--accent) for interaction alone, and var(--fg) or var(--muted-fg) for emphasis; one accent per page" });
363363 }
364 // A page's head is `pageHead(title, { sub, actions })`, whose one sentence says what the page is
365 // for (principles 1 and 8); a hand-rolled element with the `page-head` class has no place for it.
366 if (file !== "src/web/chrome.ts") {
outdated

The check is a pattern that fits only <div class="page-head" …> with double quotes and the class first. <div class="x page-head">, class='page-head' and <header class="page-head"> all pass, so the next reviewer will still have to say it. Widen the match to any element whose class list contains page-head. Also, the exemption is any file containing the string export function pageHead(, which is broader than 'the helper'. Scope it to src/web/chrome.ts.

367 for (const m of code.matchAll(/<[a-z][\w-]*\s[^>]*?\bclass\s*=\s*(["'])(?:[^"'>]*\s)?page-head(?:\s[^"'>]*)?\1/gi)) {
368 out.push({ line: at(m.index!), rule: "pagehead", text: m[0], use: 'pageHead(title, { sub: "one plain sentence on what the page is for", actions }) from src/web/chrome.ts (principles 1 and 8)' });
369 }
370 }
364371 // A colour name in an inline style="": the stylesheet scan reads css templates only.
365372 for (const m of code.matchAll(/\bstyle="([^"]*)"/g)) {
366373 const bad = m[1]!.match(NAMED_RE);
@@ -416,7 +423,7 @@ export function compareQuiet(debt: QuietDebt, files: Record<string, QuietFinding
416423 export function scanQuiet(root: string): Record<string, QuietFinding[]> {
417424 const out: Record<string, QuietFinding[]> = {};
418425 for (const f of sourceFiles(root)) {
419 const found = quiet(readFileSync(f, "utf8"));
426 const found = quiet(readFileSync(f, "utf8"), relative(root, f));
420427 if (found.length) out[relative(root, f)] = found;
421428 }
422429 return out;
src/web/pages/template.ts +3 −4
@@ -12,7 +12,7 @@ import { templateView } from "../../core/template_view.ts";
1212 import { notePhase, takeSessionTime, timePhase } from "../../core/route_timing.ts";
1313 import type { Ctx } from "../../http/context.ts";
1414 import { DEFAULT_TEMPLATE, TEMPLATES } from "../../spawn/templates.ts";
15 import { notFoundPage } from "../chrome.ts";
15 import { notFoundPage, pageHead } from "../chrome.ts";
1616 import { html } from "../html.ts";
1717 import { page } from "../layout.ts";
1818 import { statusRow } from "./security.ts";
@@ -32,10 +32,9 @@ export async function templatePage(ctx: Ctx): Promise<Response> {
3232 ctx,
3333 title: view.title,
3434 ...(built ? { description: view.about } : {}),
35 body: html`<div class="page-head"><h1>${view.title}</h1></div>
35 body: html`${pageHead(view.title, { sub: view.about !== "" ? view.about : "The files a forge starts with." })}
outdated

Principle 1: pageHead(view.title) passes no sub. The rule you wrote says a head carries one plain sentence on what the page is for, and view.about is right there. Use pageHead(view.title, { sub: view.about }) and drop the duplicate <p> below if it repeats it (nothing should explain itself twice). The converted page should show the rule met, not only the lint's pattern avoided.

3636 <section>
37 <p>${built ? view.about : "A forge started from this template begins with these files."}</p>
38 ${!built && view.about !== "" ? html`<p class="muted">${view.about}</p>` : null}
37 ${built ? null : html`<p>A forge started from this template begins with these files.</p>`}
3938 ${built
4039 ? null
4140 : view.files.length === 0
test/design-lint.test.ts +21
@@ -385,3 +385,24 @@ describe("design check: the layout rules (#12017)", () => {
385385 expect(compareLayout(base.layout ?? {}, scanLayout("."))).toEqual([]);
386386 }, SLOW);
387387 });
388
389 describe("design lint: a hand-rolled page head (principles 1 and 8)", () => {
390 test("a bare page-head div fails, naming the rule and pageHead", async () => {
391 const { quiet } = await import("../scripts/design-lint.ts");
392 const f = quiet('export const x = html`<div class="page-head"><h1>Data</h1></div>`;');
393 expect(f.map((x) => x.rule)).toEqual(["pagehead"]);
394 expect(f[0]!.use).toContain("pageHead(");
395 });
396 test("any element with page-head among its classes is found, either quote", async () => {
397 const { quiet } = await import("../scripts/design-lint.ts");
398 for (const h of ['<div class="x page-head">', "<div class='page-head'>", '<header class="page-head wide">'])
399 expect(quiet("const a = html`" + h + "</div>`;").map((x) => x.rule)).toEqual(["pagehead"]);
400 expect(quiet('const a = html`<div class="page-head-sub">`;')).toEqual([]);
401 });
402 test("the pageHead helper itself and its callers pass", async () => {
403 const { quiet } = await import("../scripts/design-lint.ts");
404 expect(quiet('export function pageHead(t) { return html`<div class="page-head"><h1>${t}</h1></div>`; }', "src/web/chrome.ts")).toEqual([]);
405 expect(quiet('export function pageHead(t) { return html`<div class="page-head"></div>`; }', "src/web/x.ts").length).toBe(1);
406 expect(quiet('const h = pageHead("Data", { sub: "Every table." });')).toEqual([]);
407 });
408 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs