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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13575-automate-a-review-finding-as-a-lint-or-t → main 7 commits fork 3 threads · 3 unresolved
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 | ||
| 16 | 16 | takes layout space beside a button, tab or the top bar: the element carries `hintAttr(key)` (`data-hint`), which shows |
| 17 | 17 | 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, |
| 18 | 18 | 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). | |
| 19 | 22 | |
| 20 | 23 | - `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. |
| 21 | 24 | - `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 @@ | ||
| 1 | 1 | { |
| 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 | }, | |
| 2 | 92 | "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 | |
| 4 | 218 | }, |
| 5 | 219 | "src/web/style/components.ts": { |
| 6 | 220 | "caps": 4 |
scripts/design-lint.ts +11 −4
| @@ -323,13 +323,13 @@ export function compare(base: Baseline, now: Scan, design: string, areas: readon | ||
| 323 | 323 | /** |
| 324 | 324 | * The quiet-page rules a machine can check (#8775, from #8719): markup and style only, never prose. |
| 325 | 325 | */ |
| 326 | export type QuietRule = "label" | "caps" | "echo" | "inline-colour" | "keyhint" | "accent"; | |
| 326 | export type QuietRule = "label" | "caps" | "echo" | "inline-colour" | "keyhint" | "accent" | "pagehead"; | |
| 327 | 327 | 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"]; | |
| 329 | 329 | const STATUS_WORD = "open|closed|merged|draft|done|failed|passing|failing|pending|running|queued|shipped|blocked|active|ready"; |
| 330 | 330 | |
| 331 | 331 | /** 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[] { | |
| 333 | 333 | const code = blanked(text); |
| 334 | 334 | const at = (i: number) => code.slice(0, i).split("\n").length; |
| 335 | 335 | const out: QuietFinding[] = []; |
| @@ -361,6 +361,13 @@ export function quiet(text: string): QuietFinding[] { | ||
| 361 | 361 | for (const m of code.matchAll(/--accent(?!-fg\b)(?:[-_][a-z0-9_-]*|\d+)(?![\w-])/gi)) { |
| 362 | 362 | 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" }); |
| 363 | 363 | } |
| 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 |
||
| 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 | } | |
| 364 | 371 | // A colour name in an inline style="": the stylesheet scan reads css templates only. |
| 365 | 372 | for (const m of code.matchAll(/\bstyle="([^"]*)"/g)) { |
| 366 | 373 | const bad = m[1]!.match(NAMED_RE); |
| @@ -416,7 +423,7 @@ export function compareQuiet(debt: QuietDebt, files: Record<string, QuietFinding | ||
| 416 | 423 | export function scanQuiet(root: string): Record<string, QuietFinding[]> { |
| 417 | 424 | const out: Record<string, QuietFinding[]> = {}; |
| 418 | 425 | for (const f of sourceFiles(root)) { |
| 419 | const found = quiet(readFileSync(f, "utf8")); | |
| 426 | const found = quiet(readFileSync(f, "utf8"), relative(root, f)); | |
| 420 | 427 | if (found.length) out[relative(root, f)] = found; |
| 421 | 428 | } |
| 422 | 429 | return out; |
src/web/pages/template.ts +3 −4
| @@ -12,7 +12,7 @@ import { templateView } from "../../core/template_view.ts"; | ||
| 12 | 12 | import { notePhase, takeSessionTime, timePhase } from "../../core/route_timing.ts"; |
| 13 | 13 | import type { Ctx } from "../../http/context.ts"; |
| 14 | 14 | import { DEFAULT_TEMPLATE, TEMPLATES } from "../../spawn/templates.ts"; |
| 15 | import { notFoundPage } from "../chrome.ts"; | |
| 15 | import { notFoundPage, pageHead } from "../chrome.ts"; | |
| 16 | 16 | import { html } from "../html.ts"; |
| 17 | 17 | import { page } from "../layout.ts"; |
| 18 | 18 | import { statusRow } from "./security.ts"; |
| @@ -32,10 +32,9 @@ export async function templatePage(ctx: Ctx): Promise<Response> { | ||
| 32 | 32 | ctx, |
| 33 | 33 | title: view.title, |
| 34 | 34 | ...(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: |
||
| 36 | 36 | <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>`} | |
| 39 | 38 | ${built |
| 40 | 39 | ? null |
| 41 | 40 | : view.files.length === 0 |
test/design-lint.test.ts +21
| @@ -385,3 +385,24 @@ describe("design check: the layout rules (#12017)", () => { | ||
| 385 | 385 | expect(compareLayout(base.layout ?? {}, scanLayout("."))).toEqual([]); |
| 386 | 386 | }, SLOW); |
| 387 | 387 | }); |
| 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 | }); |
Principle 8 and doc integrity: this bullet is inserted in the middle of the
keyhintbullet. '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.