From 39b06e22afeabe25d73f5b7617427cc3f7dc2b68 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Mon, 26 Oct 2026 10:13:33 -0700 Subject: [PATCH 1/6] v1.91.250.0 fix(tests): remove three free-tier fixture races (GSTA-107 daily flaky pass) (#3474) * fix(tests): remove three free-tier fixture races: atomic result files in dotenv-isolation and claude-code-runner, per-fixture Git repo in cso-git-hardening (GSTA-107) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix: pre-landing review fixes The new dotenv-isolation test spawns Bun with emptyBunConfig() instead of a literal --config=/dev/null, which the Windows lane cannot open; the runner's timeout case asserts the descendant published a pid before asking whether it is running, so a missed readiness window names itself. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(tests): cso-git-hardening fixtures turn git auto-maintenance off seedRepo commits with fixtureGit's replacement env, which never sees the shard backstop, so each commit started a detached git maintenance run that creates and deletes .git/objects/maintenance.lock under the tests' own .git reads and the afterEach rmSync (docs/TESTING_INTERNALS.md, Free-suite flake rules). Found by /ship's documentation audit; git 2.55.0 trace2 shows the maintenance spawn with the keys unset and none with them set. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --------- Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- CHANGELOG.md | 9 +++++++++ VERSION | 2 +- agents-digest/gstack-AGENTS.md | 2 +- browse/test/dotenv-isolation.test.ts | 27 +++++++++++++++++++++++++-- package.json | 2 +- test/claude-code-runner.test.ts | 20 ++++++++++++++++---- test/cso-git-hardening.test.ts | 28 +++++++++++++++++++--------- 7 files changed, 72 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9511718df..9070248f6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## [1.91.250.0] - 2026-10-26 + +**Three free-tier fixtures stop racing themselves (GSTA-107 daily flaky pass).** Two tests polled for a result file's existence while its writer created it with a plain `writeFileSync`, so a poll between create and write read an empty file; a third copied a shared template repository with `fs.cpSync` and threw once inside the directory walk. + +### Fixed +- **`browse/test/dotenv-isolation.test.ts`** (Free Tests 39902683183 and 40322888041, shard 2, "JSON Parse error: Unexpected EOF" at the `agent-env.json` read): the probe writes its result to a temp file and renames it into place, and `waitForFile` waits for content, not only for the file. A new test feeds the old race (an empty file filled 150 ms later) and runs the probe source itself. +- **`test/claude-code-runner.test.ts`** (Free Tests 39694715116, shard 13, `running(pid)` false at the timeout case): the descendant publishes `descendant.pid` by rename, and the test polls `publishedPid()`, a positive integer, instead of the file's existence, so an empty read can no longer become pid 0. +- **`test/cso-git-hardening.test.ts`** (Free Tests 40288142343, shard 17, `fs.cpSync` threw in `fixture()` with an empty message and passed on the serial retry): every fixture builds its own repository with Git instead of copying a shared template, with auto-maintenance off (`maintenance.auto=false`, `gc.auto=0`) so the detached `git maintenance run` a commit starts no longer touches `.git` while a test walks or removes it; the `beforeAll` still pays the cold macOS Git spawns once, on a throwaway repository. No timeout changed. + ## [1.91.249.0] - 2026-10-26 **Five paid-case flakes from the 2026-10-26 train gates, repaired at their causes (GSTA-107 daily flaky pass).** The "ship-docsync family" was three distinct slips, not one shared cause: a mistyped `--help` path the detector refused although the usage had already been read, an undeclared refusal of gstack's own state directory as an artifact location, and a fixture that did not install the shared preamble a generated skill requires. tpa-present's consent question paraphrased "defer" as "wait for now", and qa-functional-webhook-fix ran the probe's `--help` bare before its first capture. diff --git a/VERSION b/VERSION index 0e85b1976..e5e5d840f 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.91.249.0 +1.91.250.0 diff --git a/agents-digest/gstack-AGENTS.md b/agents-digest/gstack-AGENTS.md index 4fce7a04d..9c7adff2e 100644 --- a/agents-digest/gstack-AGENTS.md +++ b/agents-digest/gstack-AGENTS.md @@ -1,4 +1,4 @@ -# gstack digest v1.91.249.0 — regenerate/re-copy after upgrading gstack +# gstack digest v1.91.250.0 — regenerate/re-copy after upgrading gstack Behavioral rules from gstack (https://github.com/garrytan/gstack), compressed for agent hosts without a full skill install. The full skills add workflows, diff --git a/browse/test/dotenv-isolation.test.ts b/browse/test/dotenv-isolation.test.ts index c1bb710c9..f08d70c4f 100644 --- a/browse/test/dotenv-isolation.test.ts +++ b/browse/test/dotenv-isolation.test.ts @@ -7,6 +7,7 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test'; import * as fs from 'node:fs'; import * as os from 'node:os'; import * as path from 'node:path'; +import { emptyBunConfig } from '../src/bun-child-config'; import { spawnTerminalAgent } from '../src/terminal-agent-control'; const ROOT = path.resolve(import.meta.dir, '..', '..'); @@ -22,13 +23,22 @@ function seedHostileProject(dir: string): void { fs.writeFileSync(path.join(dir, 'bunfig.toml'), 'preload = ["./preload.ts"]\n'); } +// The probe publishes its result by rename, so a poller never sees the file +// half-written (Free Tests 39902683183 and 40322888041: a 50 ms poll read the +// empty file writeFileSync had just created, "JSON Parse error: Unexpected EOF"). function probeSource(out: string): string { - return `require('node:fs').writeFileSync(${JSON.stringify(out)}, JSON.stringify({ sandbox: process.env.GSTACK_CHROMIUM_NO_SANDBOX ?? null }));\n`; + return `const fs = require('node:fs'); const tmp = ${JSON.stringify(out)} + '.tmp'; fs.writeFileSync(tmp, JSON.stringify({ sandbox: process.env.GSTACK_CHROMIUM_NO_SANDBOX ?? null })); fs.renameSync(tmp, ${JSON.stringify(out)});\n`; } +/** The probe's complete result: waits for the file to exist and to hold content, not only to exist. */ async function waitForFile(file: string): Promise { const deadline = Date.now() + 20_000; - while (!fs.existsSync(file) && Date.now() < deadline) await Bun.sleep(50); + let content = ''; + while (Date.now() < deadline) { + try { content = fs.readFileSync(file, 'utf-8'); } catch {} + if (content) return content; + await Bun.sleep(50); + } return fs.readFileSync(file, 'utf-8'); } @@ -44,6 +54,19 @@ afterEach(() => { }); describe('D0: project .env and bunfig.toml are ignored', () => { + test('waitForFile returns a result that is still being written only once it holds content', async () => { + const out = path.join(path.dirname(project), 'late.json'); + fs.writeFileSync(out, ''); + setTimeout(() => fs.writeFileSync(out, '{"sandbox":null}'), 150); + expect(JSON.parse(await waitForFile(out))).toEqual({ sandbox: null }); + const atomic = path.join(path.dirname(project), 'atomic.json'); + fs.writeFileSync(path.join(path.dirname(project), 'atomic-probe.ts'), probeSource(atomic)); + const run = Bun.spawnSync([process.execPath, '--no-env-file', `--config=${emptyBunConfig()}`, path.join(path.dirname(project), 'atomic-probe.ts')], { cwd: project, env: { PATH: process.env.PATH ?? '' }, stdout: 'pipe', stderr: 'pipe', timeout: 30_000 }); + expect(run.exitCode, run.stderr.toString()).toBe(0); + expect(JSON.parse(fs.readFileSync(atomic, 'utf-8'))).toEqual({ sandbox: null }); + expect(fs.existsSync(atomic + '.tmp')).toBe(false); + }); + test('every compiled binary in scripts/build.sh turns dotenv and bunfig autoload off, and the flags work', () => { const lines = fs.readFileSync(path.join(ROOT, 'scripts', 'build.sh'), 'utf-8').split('\n').filter(l => /build --compile/.test(l)); expect(lines.length).toBeGreaterThanOrEqual(5); diff --git a/package.json b/package.json index 5d4b9ab65..7bc2bfa10 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "gstack", - "version": "1.91.249", + "version": "1.91.250", "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.", "license": "MIT", "type": "module", diff --git a/test/claude-code-runner.test.ts b/test/claude-code-runner.test.ts index 8b4254afc..a665d9906 100644 --- a/test/claude-code-runner.test.ts +++ b/test/claude-code-runner.test.ts @@ -18,8 +18,10 @@ const RESOLVED_DIR = realpathSync(DIR); // Publish readiness only after the grandchild has initialized and flushed both // inherited pipes; a PID returned by spawn alone does not establish that state. +// The pid lands by rename, so a poller that sees the file sees the whole pid +// (Free Tests 39694715116: an existence poll read the empty file as pid 0). writeFileSync(DESCENDANT, ` -import { appendFileSync, writeFileSync } from 'node:fs'; +import { appendFileSync, renameSync, writeFileSync } from 'node:fs'; const record = stage => { if (process.env.FAKE_MODE === 'timeout') { try { appendFileSync(${JSON.stringify(DESCENDANT_STAGES)}, JSON.stringify({ stage, atUnixMs: Date.now(), processNs: process.hrtime.bigint().toString(), pid: process.pid }) + '\\n'); } catch {} @@ -32,7 +34,8 @@ await new Promise(resolve => process.stdout.write(' ', resolve)); record('stdout_flushed'); await new Promise(resolve => process.stderr.write(' ', resolve)); record('stderr_flushed'); -writeFileSync(process.env.PID_FILE!, String(process.pid)); +writeFileSync(process.env.PID_FILE! + '.tmp', String(process.pid)); +renameSync(process.env.PID_FILE! + '.tmp', process.env.PID_FILE!); record('pid_published'); `); @@ -136,6 +139,13 @@ function running(pid: number): boolean { } catch { return false; } } +/** The descendant's published pid: a positive integer in the pid file, or undefined while unpublished. */ +function publishedPid(): number | undefined { + let text: string; + try { text = readFileSync(PID, 'utf8'); } catch { return undefined; } + return /^[1-9]\d*$/.test(text) ? Number(text) : undefined; +} + async function expectDescendantDead() { const pid = Number(readFileSync(PID, 'utf8')); try { @@ -295,8 +305,10 @@ describe('Claude Code restricted execution', () => { try { expect(fireTimeout).toBeDefined(); const readyBy = Date.now() + 2000; - while (!existsSync(PID) && Date.now() < readyBy) await Bun.sleep(5); - expect(running(Number(readFileSync(PID, 'utf8')))).toBe(true); + while (publishedPid() === undefined && Date.now() < readyBy) await Bun.sleep(5); + const descendantPid = publishedPid(); + expect(descendantPid, 'descendant never published its pid within the readiness window').toBeDefined(); + expect(running(descendantPid!)).toBe(true); const start = Date.now(); const expire = fireTimeout!; fireTimeout = undefined; diff --git a/test/cso-git-hardening.test.ts b/test/cso-git-hardening.test.ts index cbea74b7a..7c6d3eb96 100644 --- a/test/cso-git-hardening.test.ts +++ b/test/cso-git-hardening.test.ts @@ -1,4 +1,4 @@ -import { afterAll, afterEach, beforeAll, describe, expect, spyOn, test } from 'bun:test'; +import { afterEach, beforeAll, describe, expect, spyOn, test } from 'bun:test'; import * as fs from 'node:fs'; import * as os from 'node:os'; import * as path from 'node:path'; @@ -10,20 +10,30 @@ const roots:string[]=[]; afterEach(()=>{for(const root of roots.splice(0))fs.rmSync(root,{recursive:true,force:true});}); const fixtureGit=(repo:string,home:string)=>(...args:string[])=>{const result=spawnSync('/usr/bin/git',['-C',repo,...args],{encoding:'utf8',env:{HOME:home,PATH:'/usr/bin:/bin'},timeout:30_000});if(result.status)throw new Error(result.stderr);return result.stdout;}; -let template=''; +// Each fixture builds its own repository from Git; nothing is copied from a shared +// template (Free Tests 40288142343 shard 17: fs.cpSync of the template threw inside +// its directory walk once and passed on the serial retry). Auto-maintenance is off +// because `git commit` otherwise starts a detached `git maintenance run --auto` that +// creates and deletes .git/objects/maintenance.lock after the commit returns, under +// the tests' own .git reads and the afterEach rmSync (docs/TESTING_INTERNALS.md, +// Free-suite flake rules); fixtureGit's replacement env never sees the shard backstop. +function seedRepo(repo:string,home:string){ + const git=fixtureGit(repo,home);fs.mkdirSync(repo); + git('init','-q');git('config','user.email','fixture@example.test');git('config','user.name','Fixture'); + git('config','maintenance.auto','false');git('config','gc.auto','0'); + fs.writeFileSync(path.join(repo,'tracked.ts'),'export const tracked = true\n');git('add','tracked.ts');git('commit','-qm','base'); + return git; +} // The first /usr/bin/git spawns on a cold macOS runner can eat a test's whole 5 s budget before the code under test runs; pay them once here. beforeAll(()=>{ - template=fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(),'cso-git-hardening-template-'))); - const repo=path.join(template,'repo'),git=fixtureGit(repo,template);fs.mkdirSync(repo); - git('init','-q');git('config','user.email','fixture@example.test');git('config','user.name','Fixture'); - fs.writeFileSync(path.join(repo,'tracked.ts'),'export const tracked = true\n');git('add','tracked.ts');git('commit','-qm','base'); + const warm=fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(),'cso-git-hardening-warm-'))); + try{seedRepo(path.join(warm,'repo'),warm);}finally{fs.rmSync(warm,{recursive:true,force:true});} },{timeout:30_000}); -afterAll(()=>fs.rmSync(template,{recursive:true,force:true})); function fixture(){ const root=fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(),'cso-git-hardening-'))),repo=path.join(root,'repo'),runDir=path.join(root,'state','run'); - roots.push(root);fs.cpSync(path.join(template,'repo'),repo,{recursive:true});fs.mkdirSync(runDir,{recursive:true,mode:0o700}); - return{root,repo,runDir,git:fixtureGit(repo,root)}; + roots.push(root);const git=seedRepo(repo,root);fs.mkdirSync(runDir,{recursive:true,mode:0o700}); + return{root,repo,runDir,git}; } function replaceWithSymlinkAfterLstat(target:string,replacement:string,occurrence=1){ From fa3a2400b5a21a7881c6d9ecf9c400c282a3ddc3 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Mon, 26 Oct 2026 10:35:04 -0700 Subject: [PATCH 2/6] v1.91.251.0 feat(design-lint): bundled free design lint (bin/gstack-design-lint + lib/design-lint/), hallmark sloplint port (#3459) * feat(design-lint): core of the bundled free design lint (parsers, colour, tokens, reporter, waivers, CLI) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * docs(design-lint): CHANGELOG entry, NOTICE and MIT-hallmark licence, module-size ratchet entries Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * feat(design-lint): port the colour and type rule families from sloplint rules/color.ts: gates 2a 2b 7a 7b 22 23 29 48 65 74 (check2, check7, check22, check23, check29Glow, check48, check65, check65Tailwind). rules/type.ts: gates 1 25 37 38i 38ii 38iii 55a 55b 64 67 (check1, check25, check37, check38a, check38c, check55, check64, check67, check67Html). Thresholds and heuristics are hallmark's; evidence and fixes are rewritten in gstack's voice; the stamp, genre and posture guards are gone, so every check runs in its strict form. The clean fixture carried two real tells hallmark's own sloplint also flags: an oklch literal on .button:hover (48) and the cream paper + Fraunces + clay accent look (65). The hover colour is now a token and the display face is Literata. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * feat(design-lint): port the Tailwind reader and component rules Replaces the tailwind.ts stub with sloplint's utility reader (twParse, twInfo, twGroup, variants, stops, sizes, tracking, families, shared project tokens) and the tells it feeds, and fills rules/component.ts with checkTailwind and checkComponentText: layout-transition, bounce-easing, purple-blue-gradient, gradient-text, glow-wash, literal-outside-tokens, hover-tells, wide-tracking, kicker-above-heading, monospace-costume, framework-palette, vh-height, template-cards, template-punctuation and emoji-decoration over class strings in HTML, JSX, Vue, Svelte and Astro files and cn()/clsx()/cva() calls. test/design-lint-tailwind.test.ts holds a negative control and a planted tell per rule plus the tailwind-fail, tailwind-pass and clean fixtures. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(design-lint): mark line-length, cream-palette and the caps leading rules page-only Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * feat(design-lint): port the structure and motion rule families from sloplint Structure: template-cards, nested-cards, vh-height, raw-spacing, off-scale-spacing, overflow-x-unclipped (static half), bare-fr-track, display-head-unwrapped, radio-tab-jump, double-sticky, screen-word-budget (static half), and a conservative static half of wide-container. Motion: layout-transition, spacing-transition, hover-tells, bounce-easing, focus-ring-fade, tooltip-focus-delay, autorotate-no-pause, missing-focus-visible, missing-states, missing-reduced-motion, autoplay-unmuted, lazy-lcp, video-without-poster, input-state-shift, control-height (static half), content-hidden-at-rest. Every rule has a planted positive and a negative control; the clean fixture lede drops to eleven words so the hero-paragraph budget holds. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(design-lint): the Tailwind gradient half of 2a/2b lives in the component family only Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * chore(design-lint): tidy the colour test imports; control-height page-only; lazy-lcp title Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * chore(design-lint): drop unused colour test imports Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * feat(design-lint): port the chrome, assets and finish rule families from sloplint Chrome (gates 19 42 46a 47 54 63 68 69 70 85): gate 19 split by tell onto aphoristic-cadence, generic-hero-copy, generic-cta-copy, em-dash-overuse and template-footer-line in rules/chrome-copy.ts (with the two-filled-buttons half of F4 and the shared prose mask); the eyebrow in rules/chrome-eyebrow.ts; the nav and footer shapes, invented proof, drawn chrome, placeholder services, template punctuation, wireframe slots, repeated facts, the fake send and a static version of the email-band close in rules/chrome.ts. Assets (gates 30 33 40 41 49 76): emoji icons, mixed icon libraries, unlabelled svg/canvas, contrast pairs and surface inks (suspected at ask in the static tier), wrapping labels split into button-label-wraps and link-wraps, broken images and stock hotlinks. Finish (F1-F9 F15 F16 F21-F24): all polish except fake-avatar. Tests cover every id with a negative control and a planted positive; the clean fixture gains scrollbar-color so its committed palette themes every browser surface. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * feat(design-lint): chrome, assets and finish families merged; maskedProse moves to html.ts; isTokenRule takes a Pick; ratchet watches every lint module Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * test(design-lint): the eyebrow-pass and tailwind-pass fixtures carry a skip link, main id and aria-current so the copy tier passes them too; waiver fixture gets a meta description Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * feat(design-lint): render tier on gstack's own browser (sloplint-render port) Ports hallmark's sloplint-render.mjs onto lib/aside-render: one tab per page, the in-page probes installed once and run at each viewport, a second pass with full-page screenshots only when a contrast claim needs the painted pixels (a small PNG reader replaces canvas sampling). Gates 23, 25, 26a, 34, 40, 41, 44a-d, 49a/b, 58, 71, 72, 73, 75, 77-83, F17-F20, plus the page that did not render. The stamp's posture, hero-shape, photo-shape and genre guards are gone: the strict form applies. Focus rings are read by focusing each control in turn (programmatic focus matches :focus-visible on the daemon with no prior pointer input; a stylesheet scan is the fallback). lib/aside-render: an eval step takes width/height like a screenshot step (device metrics on Aside, viewport on browse, cleared after), and spec.file may be an http(s) URL, opened as it is with nothing served. The clean fixture gained border-box on its hero, a centred, taller hero visual, a wrapping actions row, a statement-sized close head and a shorter story paragraph: the browser showed the action below the 1280x800 fold, a dead band under the hero, a 600px image spilling past a phone screen and a thin close section. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * feat(design-lint): render tier merged; four probe modules join the ratchet; the clean hero sits at a fixed measure so text and visual stand together; CHANGELOG names the aside-render eval viewport Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * test(design-lint): register the lint fixtures as free fixtures and the hallmark licence texts as free-only PR files, so the PR paid lane stays narrow and test/free-fixtures.test.ts passes Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * feat(design-lint): section-gap measured in the render tier (gate 59, with the six-to-nine section count) and the hero action count; a free test over the recorded review slop page; usage, render glue, file walk, multi-page ownership and copy-tier tests; NOTICE and licences leave FREE_ONLY_PR_FILES so the paid-free boundary test stands Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * design-lint: mark hallmark PAGE_ONLY gates and craft page checks pageOnly so --scope component drops them Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * design-lint: ship review fixes Waivers reach render findings; a blocking rule the lint only suspected is waivable like any ask, a measured or absent Floor stays refused. A stylesheet a page links from another directory belongs to that page and is not linted again on its own; a stylesheet linted alone keeps its waivers. Root-relative hrefs resolve against the lint root. Stylesheets are read and parsed once per run. A rule family that throws reports internal-error at ask instead of a silent pass; aria-labelledby and probe tag names are escaped before they reach a RegExp; a probe result naming an unknown rule is a render finding, not a crash; fix strings are one line. overused-font follows gstack's catalog of display faces; one MONO_FACE list for every monospace check. parseCss caps nesting depth; medianRgb uses histograms; glHide batches its layout reads. Dead exports removed (isPage, openTags, over, ComponentTag, PixelRect, the ids re-exports). Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * design-lint: name the tracked-caps thresholds once, string-aware brace scan, drop an unused parameter, clean up test tmpdirs Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * design-lint: second review cycle Waivers settle once per page after both tiers, so a blocking rule only the render tier suspects is waivable and one it measures is refused; a claim in a stylesheet answers for that stylesheet on every page that links it (no shared-word check), so a sheet shared by two pages is no longer waived on one and refused on the other. Every printed field is one line with control characters stripped; the waiver regex is linear and ends at a carriage return; a root-relative href cannot climb out of the lint root. The ancestor map closes optional end tags implicitly and pops to the matching open tag, so unclosed
  • no longer makes it quadratic. The static tier reports outline: none with no ring anywhere as missing-focus-visible at its line; literal-outside-tokens needs a --color-* or --font-* token to exist; the banned gradient includes indigo-to-violet; a new banned-font rule reads gstack's BANNED_FONTS; MONO_FACE matches whole words; bold keywords and tokens count as weight 700 for the contrast threshold. stylesFor reads only the entries that can match; glOcclusion memoises the pinned walk; the confirm screenshot is taken at 1x; a page that throws in the render tier is a render finding and the CLI exits 3 on an internal error. Docs name the token conventions and what the lint does not cover. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * design-lint: pair open and close tags once per document, scan markup in linear time, keep commented-out style and script dead Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * design-lint: third review cycle fixes Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * design-lint: third review cycle tests; render keeps the measured horizontal-scroll when merging widths Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * design-lint: document the third-cycle limits and waiver scope Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * design-lint: fourth review cycle fixes Commented-out markup is dead for every rule (Doc.src is the comment-blanked text; craft copy, the module-script check and the border+shadow scan read it). Headings, buttons, links, labels, selects, forms and an open

    close the way the browser closes them, a tree nests at most 512 deep, and the heading, footer-column, sign-up-button and span readers walk the shared pairing instead of lazy regexes, with each element's text computed once (textOf). Tailwind frames and wireframe slots answer from treeOf. resolveVars stops on a cycle and caps its size; every parseCss at-rule branch honours the depth guard and an inline \n\n\n' + body + '\n\n\n'; +} + +const lineOf = (html: string, needle: string): number => { + const at = html.indexOf(needle); + if (at < 0) throw new Error('needle not in page: ' + needle); + return html.slice(0, at).split('\n').length; +}; + +function run(html: string, files: Record = {}): Finding[] { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'design-lint-assets-')); + tmpDirs.push(dir); + fs.writeFileSync(path.join(dir, 'index.html'), html); + for (const [name, text] of Object.entries(files)) fs.writeFileSync(path.join(dir, name), text); + return lintStatic([dir], { cwd: dir, warn: (l) => { throw new Error(l); } }).findings; +} + +const only = (findings: Finding[], rule: string) => findings.filter((f) => f.rule === rule); +const show = (findings: Finding[]) => findings.map(formatFinding); + +describe('design-lint assets: icons (gate 30)', () => { + test('emoji-decoration blocks on an emoji standing in for an icon, in a tile, a heading or a component string; an SVG icon is clean', () => { + const slop = page('', '

    \n
    \u2728
    \n

    \ud83d\ude80 Ship faster

    \n

    \ud83d\udc4b Welcome aboard

    \n
    '); + const hits = only(run(slop), 'emoji-decoration'); + expect(hits.map((f) => [f.grade, f.line])).toEqual([['blocks', lineOf(slop, 'feature__icon')], ['blocks', lineOf(slop, 'Ship faster')], ['blocks', lineOf(slop, 'Welcome aboard')]]); + expect(hits[0].evidence).toBe('an emoji icon "\u2728" in
    '); + expect(hits[2].evidence).toContain('text opens with an emoji'); + const tsx = 'export const Icon = () => ;\n'; + expect(only(run(page('', '

    Ready.

    '), { 'Feature.tsx': tsx }), 'emoji-decoration').map((f) => [f.file, f.evidence])).toEqual([['Feature.tsx', 'an emoji passed as an icon: \u2728']]); + expect(only(run(page('', '

    Ship faster

    ')), 'emoji-decoration')).toEqual([]); + }); + + test('two-icon-libraries asks when two libraries share a page; one library is clean', () => { + const mixed = page('', '
    \n\n\n
    '); + const hits = only(run(mixed), 'two-icon-libraries'); + expect(hits.map((f) => [f.grade, f.line, f.evidence])).toEqual([['ask', 1, 'icon libraries mixed on one page: heroicons and lucide']]); + expect(only(run(page('', '
    ')), 'two-icon-libraries')).toEqual([]); + }); +}); + +describe('design-lint assets: decoration labels (gate 33)', () => { + test('unlabeled-decoration blocks on a bare or ; aria-hidden, a label, a or a labelled ancestor is clean', () => { + const slop = page('', '
    \n\n\n
    '); + const hits = only(run(slop), 'unlabeled-decoration'); + expect(hits.map((f) => [f.grade, f.line, f.evidence])).toEqual([ + ['blocks', lineOf(slop, ' with neither aria-hidden="true" nor a label'], + ['blocks', lineOf(slop, ' with neither aria-hidden="true" nor a label'], + ]); + const clean = page('', '
    The depot
    '); + expect(show(only(run(clean), 'unlabeled-decoration'))).toEqual([]); + }); +}); + +describe('design-lint assets: contrast (gates 40, 41)', () => { + test('low-contrast lands at ask (the static tier suspects, the render tier proves) for text under its threshold; large text at 3:1 and body text at 4.5:1 are clean', () => { + const slop = page('.muted {\n color: #999;\n background: #fff;\n}\n.big { font-size: 32px; color: #767676; background: #fff; }', '

    Faint

    Large

    '); + const hits = only(run(slop), 'low-contrast'); + expect(hits.map((f) => [f.tier, f.grade, f.line])).toEqual([['ask', 'ask', lineOf(slop, 'color: #999')]]); + expect(hits[0].evidence).toBe('2.85:1 under the 4.5:1 threshold on .muted'); + expect(only(run(page('.body { color: #595959; background: #fff; }', '

    Readable

    ')), 'low-contrast')).toEqual([]); + }); + + test('gray-on-color lands at ask for button text within a step of its fill, a dark surface that sets no text colour and a missing accent ink; a paired ink is clean', () => { + const slop = page('.btn {\n color: #7a7a7a;\n background-color: #777;\n}\n.panel {\n background: #222;\n padding: 1rem;\n}', '

    Dark

    '); + const hits = only(run(slop), 'gray-on-color'); + expect(hits.map((f) => [f.tier, f.grade, f.line])).toEqual([['ask', 'ask', lineOf(slop, 'color: #7a7a7a')], ['ask', 'ask', lineOf(slop, 'background: #222')]]); + expect(hits[0].evidence).toMatch(/^button text within a step of its fill on \.btn/); + expect(hits[1].evidence).toBe('a dark surface (lightness 25%) on .panel sets no text colour'); + const noInk = page('.btn { background: var(--color-accent); color: white; }', '
    ').replace('--color-accent-ink: oklch(98% 0.01 30); ', ''); + expect(only(run(noInk), 'gray-on-color').map((f) => f.evidence)).toEqual(['the accent fills a surface but --color-accent-ink is not defined']); + expect(only(run(page('.btn { background: var(--color-accent); color: var(--color-accent-ink); } .panel { background: var(--color-ink); color: var(--color-paper); }', '

    Dark

    ')), 'gray-on-color')).toEqual([]); + }); +}); + +describe('design-lint assets: labels that wrap (gate 49)', () => { + test('button-label-wraps lands at ask for a long button or primary nav label with no nowrap; link-wraps asks for a long footer link; nowrap and short labels are clean', () => { + const slop = page('', '\n
    \n\n
    \n'); + const findings = run(slop); + const buttons = only(findings, 'button-label-wraps'); + expect(buttons.map((f) => [f.tier, f.grade, f.line])).toEqual([['ask', 'ask', lineOf(slop, '

    Ledgerline

    ')), 'template-nav')).toEqual([]); + expect(only(run(reflex, { scope: 'component' }), 'template-nav')).toEqual([]); + }); + + test('template-footer: four link columns ask; a one-line footer is clean', () => { + const col = ''; + const reflex = page('', '

    Ledgerline

    \n
    \n' + col + '\n' + col + '\n' + col + '\n' + col + '\n
    '); + const hits = only(run(reflex), 'template-footer'); + expect(hits.map((f) => [f.grade, f.line])).toEqual([['ask', lineOf(reflex, '

    Ledgerline, Bergen.

    ')), 'template-footer')).toEqual([]); + }); +}); + +describe('design-lint chrome: proof, drawn chrome and material (gates 46a, 47)', () => { + test('invented-proof: a metric the page cannot source lands at ask for a person to confirm; a plain count is clean', () => { + const slop = page('', '
    \n

    Trusted by 50,000+ teams shipping 10x faster.

    \n
    '); + const hits = only(run(slop), 'invented-proof'); + expect(hits.map((f) => [f.tier, f.grade, f.line])).toEqual([['ask', 'ask', lineOf(slop, 'Trusted by')]]); + expect(only(run(page('', '

    Halvorsen Freight reconciles 1,140 invoices a month.

    ')), 'invented-proof')).toEqual([]); + }); + + test('drawn-browser-chrome blocks on a traffic-light bar class or selector; device-frame asks on a phone frame; a real figure is clean', () => { + const drawn = page('.window-frame { border: 1px solid var(--color-muted); }', '
    \n
    \n
    \n
    '); + const findings = run(drawn); + const bar = only(findings, 'drawn-browser-chrome'); + expect(bar.map((f) => [f.grade, f.line])).toEqual([['blocks', lineOf(drawn, 'browser-bar')]]); + expect(bar[0].evidence).toContain('class "browser-bar"'); + const frame = only(findings, 'device-frame'); + expect(frame.map((f) => [f.grade, f.line]).sort((a, b) => Number(a[1]) - Number(b[1]))).toEqual([['ask', lineOf(drawn, '.window-frame')], ['ask', lineOf(drawn, 'phone-frame"')]]); + const clean = run(page('', '
    The close screen
    The close screen.
    ')); + expect(only(clean, 'drawn-browser-chrome')).toEqual([]); + expect(only(clean, 'device-frame')).toEqual([]); + }); + + test('imitation-material: a placeholder image service asks, in markup or CSS; a real asset is clean', () => { + const fake = page('', '
    \n\n
    ').replace('\n\n\n${body}\n\n\n`; + +function lintPage(html: string, name = 'index.html'): { html: string; findings: Finding[]; dir: string } { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'design-lint-color-')); + tmpDirs.push(dir); + const file = path.join(dir, name); + fs.writeFileSync(file, html); + return { html, dir, findings: lintStatic([file], { cwd: dir, warn: (l) => { throw new Error(l); } }).findings }; +} + +const byRule = (findings: Finding[], rule: string): Finding[] => findings.filter((f) => f.rule === rule); +const lines = (findings: Finding[]): string[] => findings.map(formatFinding); + +describe('design-lint colour: purple-blue-gradient (2a, blocks)', () => { + test('a single-hue ramp and a repeating pattern are not findings', () => { + const { findings } = lintPage(page('.band { background: linear-gradient(90deg, oklch(60% 0.2 250), oklch(75% 0.15 250)); }\n.grain { background: repeating-linear-gradient(45deg, oklch(60% 0.2 300) 0 2px, oklch(60% 0.2 240) 2px 4px); }')); + expect(lines(byRule(findings, 'purple-blue-gradient'))).toEqual([]); + }); + test('purple to blue on a band, purple to pink as text, and cyan on dark paper each block at the declaration', () => { + const band = lintPage(page('.band { background: linear-gradient(90deg, oklch(60% 0.2 300), oklch(60% 0.2 240)); }')); + const f = byRule(band.findings, 'purple-blue-gradient'); + expect(f.map((x) => [x.grade, x.line, x.evidence, x.fix])).toEqual([['blocks', lineOf(band.html, '.band {'), 'purple-to-blue gradient on .band', 'one anchor hue; drop the gradient']]); + const text = lintPage(page('h1 {\n background: linear-gradient(90deg, oklch(60% 0.2 300), oklch(65% 0.2 350));\n -webkit-background-clip: text;\n color: transparent;\n}')); + expect(byRule(text.findings, 'purple-blue-gradient').map((x) => [x.grade, x.line, x.evidence])).toEqual([['blocks', lineOf(text.html, '-webkit-background-clip'), 'purple-to-pink gradient text on h1']]); + expect(byRule(text.findings, 'gradient-text')).toEqual([]); + const dark = TOKENS.replace('--color-paper: oklch(97% 0.01 250)', '--color-paper: oklch(18% 0.02 250)'); + const cyan = lintPage(page('.glow { background: radial-gradient(circle, oklch(70% 0.15 200), transparent); }', undefined, dark)); + expect(byRule(cyan.findings, 'purple-blue-gradient').map((x) => x.evidence)).toEqual(['cyan-on-dark gradient on .glow']); + const light = lintPage(page('.glow { background: radial-gradient(circle, oklch(70% 0.15 200), transparent); }')); + expect(byRule(light.findings, 'purple-blue-gradient')).toEqual([]); + }); +}); + +describe('design-lint colour: gradient-text (2b, ask)', () => { + test('a solid heading is clean', () => { + const { findings } = lintPage(page('h1 { color: var(--color-ink); }')); + expect(byRule(findings, 'gradient-text')).toEqual([]); + }); + test('text clipped to a one-hue ramp asks at the background-clip line', () => { + const { html, findings } = lintPage(page('h1 {\n background: linear-gradient(90deg, oklch(60% 0.2 250), oklch(70% 0.15 250));\n background-clip: text;\n color: transparent;\n}')); + expect(byRule(findings, 'gradient-text').map((x) => [x.grade, x.line, x.evidence])).toEqual([['ask', lineOf(html, 'background-clip: text'), 'gradient text on h1']]); + }); +}); + +describe('design-lint colour: pure-black-white (7a, blocks) and absolute-surface-token (7b, ask)', () => { + test('tinted ink and paper, and a translucent white, are clean', () => { + const { findings } = lintPage(page('.card { color: oklch(10% 0.02 250); background: rgb(255 255 255 / 0.6); border-color: oklch(99% 0.005 250); }')); + expect(lines([...byRule(findings, 'pure-black-white'), ...byRule(findings, 'absolute-surface-token')])).toEqual([]); + }); + test('#000 written on a rule blocks; a token that resolves to pure white asks, as does every use of it', () => { + const { html, findings } = lintPage(page('.card { color: #000; }\n.panel { background: var(--color-sheet); }', undefined, TOKENS + '\n:root { --color-sheet: #ffffff; }')); + expect(byRule(findings, 'pure-black-white').map((x) => [x.grade, x.line, x.evidence])).toEqual([['blocks', lineOf(html, '.card {'), 'color: #000 on .card is pure black (#000)']]); + expect(byRule(findings, 'absolute-surface-token').map((x) => [x.grade, x.line, x.evidence])).toEqual([ + ['ask', lineOf(html, '--color-sheet: #ffffff'), '--color-sheet: #ffffff on :root is pure white (#fff)'], + ['ask', lineOf(html, '.panel {'), 'background: var(--color-sheet) on .panel is pure white (#fff)'], + ]); + }); +}); + +describe('design-lint colour: zero-chroma-neutrals (22, ask)', () => { + test('a neutral with chroma, a translucent grey and a filter value are clean', () => { + const { findings } = lintPage(page('.rule { border-color: oklch(85% 0.005 250); background: oklch(50% 0 0 / 0.4); filter: drop-shadow(0 1px oklch(50% 0 0)); }')); + expect(byRule(findings, 'zero-chroma-neutrals')).toEqual([]); + }); + test('a zero-chroma oklch token asks at its line', () => { + const { html, findings } = lintPage(page('.rule { border-color: var(--color-gray); }', undefined, TOKENS + '\n:root { --color-gray: oklch(55% 0 0); }')); + expect(byRule(findings, 'zero-chroma-neutrals').map((x) => [x.grade, x.line, x.evidence])).toEqual([['ask', lineOf(html, '--color-gray:'), 'zero-chroma oklch(55% 0 0) as --color-gray on :root']]); + }); +}); + +describe('design-lint colour: accent-footprint (23, ask)', () => { + test('the accent on a button, a faint accent wash and a soft token are clean', () => { + const { findings } = lintPage(page('.button { background: var(--color-accent); }\nsection.hero { background: var(--color-accent-soft); }\n.band { background: oklch(from var(--color-accent) l c h / 0.1); }\n.stat { color: var(--color-accent); font-size: 1.5rem; }')); + expect(byRule(findings, 'accent-footprint')).toEqual([]); + }); + test('an accent fill on a surface or a tall block, and display-size accent text, each ask with a specific fix', () => { + const { html, findings } = lintPage(page('section.hero { background: var(--color-accent); }\n.tall { min-height: 50vh; background: var(--color-accent); }\n.stat { color: var(--color-accent); font-size: clamp(2rem, 5vw, 4rem); }')); + expect(byRule(findings, 'accent-footprint').map((x) => [x.grade, x.line, x.evidence, x.fix])).toEqual([ + ['ask', lineOf(html, 'section.hero {'), 'accent background on the viewport-scale rule "section.hero"', 'retreat the accent to actions and one signal; a large fill belongs to the paper or a field token'], + ['ask', lineOf(html, '.tall {'), 'accent background on the viewport-scale rule ".tall"', 'retreat the accent to actions and one signal; a large fill belongs to the paper or a field token'], + ['ask', lineOf(html, '.stat {'), 'display-size text set in the accent on ".stat"', 'set display type in ink; the accent marks small signals'], + ]); + }); +}); + +describe('design-lint colour: glow-wash (29, ask)', () => { + test('an offset neutral shadow, a mild blur and an opaque backdrop are clean', () => { + const { findings } = lintPage(page('.card { box-shadow: 0 4px 24px oklch(20% 0.02 250 / 0.2); }\n.hero::before { position: absolute; filter: blur(20px); }\n.nav { backdrop-filter: blur(12px); background: var(--color-paper); }')); + expect(byRule(findings, 'glow-wash')).toEqual([]); + }); + test('a glass panel, a coloured zero-offset glow and a blurred orb each ask once', () => { + const { html, findings } = lintPage(page('.nav {\n backdrop-filter: blur(12px);\n background: rgb(255 255 255 / 0.1);\n}\n.button { box-shadow: 0 0 40px oklch(60% 0.2 300), 0 0 60px oklch(60% 0.2 300); }\n.hero::before {\n position: absolute;\n filter: blur(80px);\n}')); + expect(byRule(findings, 'glow-wash').map((x) => [x.grade, x.line, x.evidence, x.fix])).toEqual([ + ['ask', lineOf(html, 'backdrop-filter: blur(12px)'), 'glass panel: backdrop-filter blur over a translucent white on .nav', 'a solid or grained surface; elevation by lightness'], + ['ask', lineOf(html, '.button {'), 'coloured zero-offset glow (blur 40px) on .button', 'shadows carry offset and blur in a neutral; colour is not depth'], + ['ask', lineOf(html, 'filter: blur(80px)'), 'blurred orb: filter blur(80px) on the positioned .hero::before', 'delete the wash; a surface is paper or ground, not a light show'], + ]); + }); +}); + +describe('design-lint colour: cream-palette (65, ask)', () => { + const cream = TOKENS.replace('--color-paper: oklch(97% 0.01 250)', '--color-paper: oklch(97% 0.012 80)').replace('--color-accent: oklch(55% 0.15 250)', '--color-accent: oklch(52% 0.16 30)'); + test('cream paper and a clay accent under a display face that is not a high-contrast serif are clean', () => { + const { findings } = lintPage(page('', undefined, cream)); + expect(byRule(findings, 'cream-palette')).toEqual([]); + }); + test('cream paper, Fraunces and a clay accent together ask at line 1', () => { + const { findings } = lintPage(page('', undefined, cream.replace('"Literata"', '"Fraunces"'))); + expect(byRule(findings, 'cream-palette').map((x) => [x.grade, x.line, x.evidence])).toEqual([['ask', 1, 'the default tasteful look: cream paper (L 97%, hue 80), fraunces as the display and a clay accent (hue 30)']]); + }); +}); + +describe('design-lint colour: framework-palette (74, ask)', () => { + test('a colour mixed for the page is clean', () => { + const { findings } = lintPage(page('')); + expect(byRule(findings, 'framework-palette')).toEqual([]); + }); + test('a Tailwind default swatch as a token asks at its line', () => { + const { html, findings } = lintPage(page('', undefined, TOKENS + '\n:root { --color-brand: #6366F1; }')); + expect(byRule(findings, 'framework-palette').map((x) => [x.grade, x.line, x.evidence])).toEqual([['ask', lineOf(html, '--color-brand'), "Tailwind's default #6366F1 as --color-brand"]]); + }); +}); + +describe('design-lint colour: literal-outside-tokens (48, blocks)', () => { + test('token references, generic families and a fully transparent literal are clean', () => { + const { findings } = lintPage(page('.card { color: var(--color-ink); font-family: sans-serif; background: rgba(0, 0, 0, 0); }', '

    Ledger

    ')); + expect(byRule(findings, 'literal-outside-tokens')).toEqual([]); + }); + test('a colour literal, a font-family literal and an inline style colour each block at their line', () => { + const { html, findings } = lintPage(page('.promo { color: #e91e63; }\n.quote { font-family: "Playfair Display", serif; }', '

    Ledger

    ')); + expect(byRule(findings, 'literal-outside-tokens').map((x) => [x.grade, x.line, x.evidence])).toEqual([ + ['blocks', lineOf(html, '.promo {'), 'colour literal #e91e63 outside the token block (color on .promo)'], + ['blocks', lineOf(html, '.quote {'), 'font-family literal ""Playfair Display", serif" on .quote'], + ['blocks', lineOf(html, 'style="color: #333"'), 'inline style colour literal #333'], + ]); + }); +}); + +// The Tailwind forms of 2a/2b are the component family's (rules/component.ts, test/design-lint-tailwind.test.ts). + +describe('design-lint colour: fixtures', () => { + const MINE = new Set(['purple-blue-gradient', 'gradient-text', 'pure-black-white', 'absolute-surface-token', 'zero-chroma-neutrals', 'accent-footprint', 'glow-wash', 'cream-palette', 'framework-palette', 'literal-outside-tokens']); + test('the clean page has no colour finding', () => { + const { findings } = lintStatic([path.join(FIXTURES, 'clean')], { cwd: ROOT }); + expect(lines(findings.filter((f) => MINE.has(f.rule)))).toEqual([]); + }); + test('slopped.html: the purple-to-blue gradient text blocks, the three literals block, the pure tokens and the zero-chroma grey ask', () => { + const file = path.join(FIXTURES, 'slopped.html'); + const html = fs.readFileSync(file, 'utf8'); + const { findings } = lintStatic([file], { cwd: ROOT }); + const mine = findings.filter((f) => MINE.has(f.rule)).map((f) => [f.rule, f.grade, f.line]); + expect(mine).toEqual(expect.arrayContaining([ + ['purple-blue-gradient', 'blocks', lineOf(html, '-webkit-background-clip: text')], + ['literal-outside-tokens', 'blocks', lineOf(html, 'linear-gradient(90deg, #8b5cf6, #3b82f6)')], + ['literal-outside-tokens', 'blocks', lineOf(html, '.promo { color: #e91e63; }')], + ['absolute-surface-token', 'ask', lineOf(html, '--color-paper: #ffffff')], + ['absolute-surface-token', 'ask', lineOf(html, '--color-ink: #000000')], + ['zero-chroma-neutrals', 'ask', lineOf(html, '--color-gray: oklch(55% 0 0)')], + ])); + expect(mine.filter((m) => m[0] === 'gradient-text')).toEqual([]); + expect(mine.filter((m) => m[0] === 'absolute-surface-token')).toHaveLength(5); + expect(mine.filter((m) => m[0] === 'literal-outside-tokens')).toHaveLength(3); + }); + test('the waiver fixture: the black paper and the grey ink are waived on the record, never blocked', () => { + const { findings } = lintStatic([path.join(FIXTURES, 'waiver')], { cwd: ROOT }); + expect(byRule(findings, 'absolute-surface-token').map((f) => f.grade)).toEqual(['waived', 'waived']); + expect(byRule(findings, 'zero-chroma-neutrals').map((f) => f.grade)).toEqual(['waived']); + expect(byRule(findings, 'pure-black-white')).toEqual([]); + }); +}); + +describe('design-lint colour: the indigo-to-violet ramp (third review cycle)', () => { + test('a near single-hue indigo ramp is not the indigo-to-violet gradient; stops twelve degrees apart are', () => { + const near = lintPage(page('.band { background: linear-gradient(90deg, oklch(60% 0.2 253), oklch(70% 0.15 258)); }')); + expect(lines(byRule(near.findings, 'purple-blue-gradient'))).toEqual([]); + const ramp = lintPage(page('.band { background: linear-gradient(90deg, oklch(60% 0.2 275), oklch(70% 0.15 300)); }')); + expect(byRule(ramp.findings, 'purple-blue-gradient').map((f) => [f.grade, f.evidence])).toEqual([['blocks', expect.stringContaining('indigo-to-violet')]]); + }); +}); diff --git a/test/design-lint-eighth-cycle.test.ts b/test/design-lint-eighth-cycle.test.ts new file mode 100644 index 000000000..76737f663 --- /dev/null +++ b/test/design-lint-eighth-cycle.test.ts @@ -0,0 +1,331 @@ +/** + * The eighth review cycle's regressions: the waiver branch keyed to the context's shape rather than the --scope flag + * (a lone component beside an unlinked stylesheet answers for its own file; a page under --scope component still + * answers for the sheet it links), the bare `<` tails (`<1`, `< `, an unclosed comment), the craft check's lazy + * scans over repeated unclosed openers, component tags paired once per file, an arithmetic repeat() count, an + * unclosed @starting-style block, the import scan over a gradient class line, the render tier's locator on a class + * value holding a `>`, tickers answered from the tree, a tooltip duration that is not a delay, a class attribute of + * many tokens, and one emoji-decoration per emoji icon in a component file. + */ +import { afterAll, describe, expect, test } from 'bun:test'; +import * as fs from 'node:fs'; +import * as os from 'node:os'; +import * as path from 'node:path'; +import { parseCss, resolveVars, selectorNames } from '../lib/design-lint/css'; +import { parseDoc, parseHtml, stripTags } from '../lib/design-lint/html'; +import { lineOf } from '../lib/design-lint/render'; +import { glAccent, glLayout } from '../lib/design-lint/render-probe'; +import { glHeroSpace, glWide, glWords } from '../lib/design-lint/render-probe-space'; +import { Reporter, type Finding } from '../lib/design-lint/report'; +import { run as runAssets } from '../lib/design-lint/rules/assets'; +import { run as runCopy } from '../lib/design-lint/rules/copy'; +import { lintStatic } from '../lib/design-lint/static'; +import { compInner } from '../lib/design-lint/tailwind'; + +const tmpDirs: string[] = []; +afterAll(() => { for (const d of tmpDirs) fs.rmSync(d, { recursive: true, force: true }); }); + +const TOKENS = ':root { --color-paper: oklch(97% 0.01 80); --color-ink: oklch(20% 0.02 250); --color-accent: oklch(50% 0.16 30); --color-accent-ink: oklch(98% 0.01 30); --color-muted: oklch(50% 0.02 250); --font-display: "Literata", serif; --font-body: "Public Sans", sans-serif; }'; +const HEAD = '\n\nHarbour office\n'; +const GREY = TOKENS + '\n:root { --color-gray: oklch(55% 0 0); }\n.row { border-color: var(--color-gray); }'; +const DASHES = 'The ledger \u2014 the month \u2014 the close \u2014 the depot \u2014 the review \u2014 the rule \u2014 the row \u2014 the sum'; +const CARD = 'export function Card() { return

    ' + DASHES + '

    ; }'; + +function tree(files: Record): string { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'design-lint-cycle8-')); + tmpDirs.push(dir); + for (const [name, text] of Object.entries(files)) { + fs.mkdirSync(path.dirname(path.join(dir, name)), { recursive: true }); + fs.writeFileSync(path.join(dir, name), text); + } + return dir; +} +const quiet = { warn: () => {} }; +const only = (f: Finding[], rule: string) => f.filter((x) => x.rule === rule); +const timed = (fn: () => void): number => { const t = performance.now(); fn(); return performance.now() - t; }; +const lintDir = (files: Record, scope?: 'page' | 'component'): { findings: Finding[]; warns: string[] } => { + const dir = tree(files); + const warns: string[] = []; + return { findings: lintStatic([dir], { cwd: dir, warn: (l: string) => warns.push(l), ...(scope ? { scope } : {}) }).findings, warns }; +}; + +describe('design-lint eighth cycle: the waiver branch follows the context, not the flag', () => { + test('a lone component beside an unlinked stylesheet answers for its own file under either scope', () => { + for (const scope of ['page', 'component'] as const) { + const { findings } = lintDir({ 'Hero.tsx': '// gstack-lint-disable zero-chroma-neutrals: the ledger keeps its grey rows grey on the depot\nexport function Hero() { return

    The ledger keeps its grey rows grey on the depot

    ; }', 'theme.css': GREY }, scope); + expect(only(findings, 'zero-chroma-neutrals').map((x) => [x.file, x.grade]), scope).toEqual([['theme.css', 'ask']]); + } + }); + + test('default scope, one component: a short claim is refused at its line and the finding stays ask', () => { + const { findings } = lintDir({ 'Card.tsx': '// gstack-lint-disable em-dash-overuse: short\n' + CARD }); + expect(only(findings, 'em-dash-overuse').map((x) => [x.file, x.grade])).toEqual([['Card.tsx', 'ask']]); + expect(only(findings, 'waiver').map((x) => [x.file, x.line, x.evidence])).toEqual([['Card.tsx', 1, 'waiver on em-dash-overuse refused: reason under 24 characters']]); + }); + + test('under --scope component a page claim still answers a finding in the stylesheet it links, and a short one is refused', () => { + const page = (reason: string) => '\n' + HEAD + '

    The ledger

    The ledger keeps its grey rows grey on the depot.

    '; + const ok = lintDir({ 'index.html': page('the ledger keeps its grey rows grey on the depot'), 'theme.css': GREY }, 'component').findings; + expect(only(ok, 'waiver')).toEqual([]); + expect(only(ok, 'zero-chroma-neutrals').map((x) => [x.file, x.grade])).toEqual([['theme.css', 'waived']]); + const bad = lintDir({ 'index.html': page('short'), 'theme.css': GREY }, 'component').findings; + expect(only(bad, 'zero-chroma-neutrals').map((x) => [x.file, x.grade])).toEqual([['theme.css', 'ask']]); + expect(only(bad, 'waiver').map((x) => [x.file, x.line, x.evidence])).toEqual([['index.html', 1, 'waiver on zero-chroma-neutrals refused: reason under 24 characters']]); + }); +}); + +describe('design-lint eighth cycle: a file costs its length', () => { + test('a heading whose tail is thousands of bare < characters lints in linear time', () => { + const dir = tree({ 'index.html': HEAD + '

    ' + ' x <'.repeat(80_000) }); + expect(timed(() => lintStatic([dir], { cwd: dir, ...quiet }))).toBeLessThan(5000); + }, 60_000); + + test('a page whose tail is a run of <1 or of unclosed comment starts costs its length, and a doctype survives', () => { + const dir = tree({ + 'a.html': HEAD + '

    hi

    ' + '<1'.repeat(200_000), + 'b.html': HEAD + '' + '\n')); + expect(only(f, 'emoji-decoration')).toEqual([]); + const live = run(page('', '

    Hi there

    ')); + expect(only(live, 'emoji-decoration').length).toBe(1); + }); + + test('a long digit run, a long mono word and a run of scheme prefixes each cost their length', () => { + const dir = tree({ 'index.html': page('', '

    Hi there

    ' + '7'.repeat(200_000) + '

    ' + 'https://'.repeat(20_000) + '

    ') }); + expect(timed(() => lintStatic([dir], { cwd: dir, ...quiet }))).toBeLessThan(4000); + expect(timed(() => twDataText('a'.repeat(400_000)))).toBeLessThan(500); + }); + + test('a 2 MB stylesheet of 699k rules lints instead of blowing the stack', () => { + const dir = tree({ 'big.css': 'a{}'.repeat(Math.floor(MAX_FILE_BYTES / 3) - 1), 'index.html': HEAD + '

    Hello there

    Body.

    ' }); + expect(() => lintStatic([dir], { cwd: dir, ...quiet })).not.toThrow(); + }); + + test('a JSX file of unclosed elements parses in linear time', () => { + const times = [5000, 10000].map((n) => timed(() => parseDoc('Page.tsx', 'export default function P(){ return (
    ' + 'text\n'.repeat(n) + '
    ); }'))); + expect(times[1]).toBeLessThan(Math.max(times[0] * 3, 300)); + expect(times[1]).toBeLessThan(4000); + }); + + test('a page of many tracked-caps labels lints in linear time and a well-formed JSX file still yields its classes', () => { + const times = [4000, 8000].map((n) => { const dir = tree({ 'index.html': page('', '

    Hello world

    ' + 'Label one\n'.repeat(n) + '
    ') }); return timed(() => lintStatic([dir], { cwd: dir, ...quiet })); }); + expect(times[1]).toBeLessThan(Math.max(times[0] * 2.5, 500)); + const doc = parseDoc('Page.tsx', 'export default function P(){ return (
    x
    ); }'); + expect(doc.classAt.size + doc.virtuals.length).toBeGreaterThan(0); + }); + + test('a fact after an inline close tag is counted in its own section', () => { + const sec = (i: number) => '

    S' + i + '

    Price: $5 a month

    '; + const f = run(page('', '

    Hi there

    ' + [0, 1, 2, 3].map(sec).join('') + '
    ')); + expect(only(f, 'repeated-fact').length).toBe(1); + }); + + test('a relative stylesheet href that climbs out of the project attaches nothing; inside the project it attaches', () => { + const dir = tree({ 'site/package.json': '{}', 'site/pages/index.html': HEAD + '

    t

    Body.

    ', 'outside.css': 'html, body { overflow-x: clip; }' }); + const r = lintStatic([path.join(dir, 'site')], { cwd: dir, ...quiet }); + expect(r.contexts[0].cssFiles).toEqual([]); + expect(only(r.findings, 'overflow-x-unclipped').length).toBe(1); + expect(resolveRef('css/site.css', path.join(dir, 'site'), path.join(dir, 'site'))).toBe(path.join(dir, 'site', 'css/site.css')); + expect(resolveRef('../outside.css', path.join(dir, 'site'), path.join(dir, 'site'))).toBeNull(); + }); + + test('an unreadable top-level path beside a readable page is one internal-error finding with its own fix', () => { + const dir = tree({ 'index.html': page('', '

    Hi

    Body.

    ') }); + const r = lintStatic([dir, path.join(dir, 'nowhere.html')], { cwd: dir, ...quiet }); + expect(r.files.map((f) => path.basename(f))).toEqual(['index.html']); + expect(only(r.findings, 'internal-error').map((f) => [f.grade, f.file, f.line, /cannot be read/.test(f.evidence), f.fix])).toEqual([['ask', 'nowhere.html', 1, true, 'check the path']]); + }); +}); + +describe('design-lint fifth cycle: waivers per sheet and the untested cells', () => { + const claim = (rule: string, reason: string) => ({ rule, reason, file: 'a.html', line: 3 }); + const PAGE_TEXT = 'The manifesto sets long declarative lines. The ledger separates its rows with rules. Three links for the paper modes.'; + + test('two linked stylesheets each waive the same rule for themselves; a short second claim is refused for its reason', () => { + const sheets = (b: string) => ({ + 'index.html': HEAD + '

    The ledger

    The ledger keeps its grey rows grey.

    ', + 'a.css': '/* gstack-lint-disable zero-chroma-neutrals: the ledger keeps its grey rows grey in the theme sheet */\n' + TOKENS + '\n:root { --color-gray: oklch(55% 0 0); }\n.row { border-color: var(--color-gray); }', + 'b.css': '/* gstack-lint-disable zero-chroma-neutrals: ' + b + ' */\n:root { --color-gray-print: oklch(45% 0 0); }\n.plate { color: var(--color-gray-print); }', + }); + const both = lintStatic([tree(sheets('the print sheet keeps grey plates grey for the press'))], { cwd: tmpDirs[tmpDirs.length - 1], ...quiet }).findings; + expect(only(both, 'waiver')).toEqual([]); + expect(only(both, 'zero-chroma-neutrals').map((x) => [x.file, x.grade]).sort()).toEqual([['a.css', 'waived'], ['b.css', 'waived']]); + const short = lintStatic([tree(sheets('short'))], { cwd: tmpDirs[tmpDirs.length - 1], ...quiet }).findings; + expect(only(short, 'waiver').map((x) => x.evidence)).toEqual(['waiver on zero-chroma-neutrals refused: reason under 24 characters']); + expect(only(short, 'zero-chroma-neutrals').map((x) => [x.file, x.grade]).sort()).toEqual([['a.css', 'waived'], ['b.css', 'ask']]); + }); + + test('a stylesheet claim with a boilerplate reason is refused and its finding stays ask', () => { + const dir = tree({ 'index.html': HEAD + '

    Ledger

    Rows.

    ', 't.css': '/* gstack-lint-disable zero-chroma-neutrals: this is intentional and by design for the sheet */\n' + TOKENS + '\n:root { --color-gray: oklch(55% 0 0); }\n.row { color: var(--color-gray); }' }); + const f = lintStatic([dir], { cwd: dir, ...quiet }).findings; + expect(only(f, 'waiver').map((x) => x.evidence)).toEqual(['waiver on zero-chroma-neutrals refused: boilerplate reason']); + expect(only(f, 'zero-chroma-neutrals').map((x) => x.grade)).toEqual(['ask']); + }); + + test('a second page claim on an accepted rule is refused as the duplicate even when its reason is short, and three accepted plus one refused is not a house style', () => { + const dup = resolveWaivers([claim('gradient-text', 'the ledger separates its rows with rules'), claim('gradient-text', 'short')], PAGE_TEXT); + expect([...dup.accepted.keys()]).toEqual(['gradient-text']); + expect(dup.refused.map((f) => f.evidence)).toEqual(['waiver on gradient-text refused: one waiver per rule']); + const four = resolveWaivers([claim('line-length', 'the manifesto sets long declarative lines'), claim('section-gap', 'the ledger separates its rows with rules'), claim('template-nav', 'three links for the paper modes'), claim('overused-font', 'short')], PAGE_TEXT); + expect(four.accepted.size).toBe(3); + expect(four.refused.map((f) => f.rule)).toEqual(['waiver']); + }); + + test('suspected leaves an ask or polish rule at its own tier', () => { + const r = new Reporter('page', '/cwd'); + r.report('section-gap', '/cwd/a.html', 1, 'x', { suspected: true }); + r.report('text-sliver', '/cwd/a.html', 1, 'x', { suspected: true, source: 'render' }); + expect(r.findings.map((f) => [f.tier, f.grade])).toEqual([['ask', 'ask'], ['polish', 'polish']]); + }); +}); + +describe('design-lint fifth cycle: render answers of the wrong shape, field by field', () => { + const PAGE = HEAD + '

    t

    Body.

    Go
    '; + const SWATCH = path.join(path.resolve(import.meta.dir, '..'), 'test', 'fixtures', 'design-lint', 'render', 'swatch.png'); + const SETUP = 1, FIRST = 2, FOCUS = 13; + const SCROLL = { rule: 'horizontal-scroll', grade: 'fail', evidence: 'the hero overflows' }; + type Patch = (evals: Record, spec: RenderSpec) => void; + const runner = (patch: Patch, stdout = ''): Runner => async (spec: RenderSpec): Promise => { + const evals: Record = {}; + const shot = spec.steps.findIndex((s) => s.kind === 'screenshot'); + if (shot < 0) { + evals[SETUP] = '{"lost":[]}'; + for (let i = FIRST; i <= FOCUS; i++) evals[i] = '[]'; + patch(evals, spec); + return { ok: true, engine: 'browse', outputs: [], evals, stdout }; + } + spec.steps.forEach((s, i) => { + if (s.kind !== 'screenshot') return; + fs.copyFileSync(SWATCH, s.out); + const width = s.width ?? 0; + evals[i - 1] = JSON.stringify([{ x: 0, y: 0, w: width / 2, h: width }]); + }); + return { ok: true, engine: 'browse', outputs: [], evals, stdout }; + }; + const measured = (f: Finding[]) => only(f, 'horizontal-scroll').map((x) => x.evidence); + const noAbort = (f: Finding[]) => only(f, 'render').filter((x) => /could not be measured/.test(x.evidence)); + + test('a non-string at.cls, a ring without its colour, a probe without fg and a non-string PAGE_ERRORS entry each keep the measured findings', async () => { + const dir = tree({ 'index.html': PAGE }); + const file = path.join(dir, 'index.html'); + const cls = await lintRender([file], { cwd: dir, run: runner((ev) => { ev[FIRST] = JSON.stringify([{ rule: 'nested-cards', grade: 'fail', evidence: 'x', at: { tag: 'p', text: 'Body.', cls: {} } }, SCROLL]); }) }); + expect(measured(cls.findings)).toEqual(['[320px] the hero overflows']); + expect(only(cls.findings, 'nested-cards').map((f) => f.line)).toEqual([4]); + expect(noAbort(cls.findings)).toEqual([]); + + const ring = await lintRender([file], { cwd: dir, run: runner((ev) => { ev[FIRST] = JSON.stringify([SCROLL]); ev[FOCUS] = JSON.stringify([{ key: 'a', path: 'main>a', at: { tag: 'a', text: 'Go' }, bare: false, ratio: 1.2, pad: 2 }]); }) }); + expect(measured(ring.findings)).toEqual(['[320px] the hero overflows']); + expect(noAbort(ring.findings)).toEqual([]); + expect(only(ring.findings, 'render').map((f) => /\((.*?)\)/.exec(f.evidence)![1])).toEqual(['focus']); + + const fg = await lintRender([file], { cwd: dir, run: runner((ev) => { ev[FIRST] = JSON.stringify([SCROLL]); ev[FIRST + 5] = JSON.stringify([{ rule: 'low-contrast', grade: 'fail', evidence: 'computed contrast 2.50:1 under the 4.5:1 threshold on p.faint (2.50:1)', probe: { path: 'main>p', threshold: 4.5 } }, { rule: 'low-contrast', grade: 'fail', evidence: 'y', probe: true }]); }) }); + expect(measured(fg.findings)).toEqual(['[320px] the hero overflows']); + expect(only(fg.findings, 'low-contrast').map((f) => f.evidence)).toEqual(['[1280px] computed contrast 2.50:1 under the 4.5:1 threshold on p.faint (2.50:1)', '[1280px] y']); + expect(noAbort(fg.findings)).toEqual([]); + + const errs = await lintRender([file], { cwd: dir, run: runner((ev) => { ev[FIRST] = JSON.stringify([SCROLL]); }, 'PAGE_ERRORS=[1]\n') }); + expect(measured(errs.findings)).toEqual(['[320px] the hero overflows']); + expect(only(errs.findings, 'render')).toEqual([]); + }); + + test('a malformed entry claiming the render rule is reported as tampering with evidence on the line', async () => { + const dir = tree({ 'index.html': PAGE }); + const file = path.join(dir, 'index.html'); + const r = await lintRender([file], { cwd: dir, run: runner((ev) => { ev[FIRST] = JSON.stringify([{ rule: 'render', grade: 'x', evidence: 'y' }]); }) }); + expect(only(r.findings, 'render').map((f) => f.evidence)).toEqual([expect.stringMatching(/does not know \(render\)/)]); + expect(formatFinding(only(r.findings, 'render')[0])).toMatch(/^LINT: blocks render \S+:\d+ .+ \| fix: .+$/); + }); + + test('a short claim on a rule the render tier measured is refused as the Floor after both tiers settle', async () => { + const dir = tree({ 'index.html': '\n' + PAGE }); + const r = await lint([dir], { cwd: dir, render: true, warn: () => {}, run: runner((ev) => { ev[FIRST] = JSON.stringify([SCROLL]); }) }); + expect(only(r.findings, 'waiver').map((f) => f.evidence)).toEqual([`waiver on horizontal-scroll refused: ${FLOOR_REFUSAL}`]); + expect(only(r.findings, 'horizontal-scroll').map((f) => f.grade)).toEqual(['blocks']); + }); +}); + +describe('design-lint fifth cycle: rule judgement', () => { + test('a textarea taller than 52px is not a control-height finding; a button is', () => { + const body = '

    Hi there

    '; + expect(only(run(page('textarea { min-height: 120px; }', body)), 'control-height')).toEqual([]); + expect(only(run(page('button { height: 30px; }', body)), 'control-height').length).toBe(1); + }); + + test('a border width change on an attribute-selected input is input-state-shift', () => { + const f = run(page('input[type="text"] { border: 1px solid #333; } input[type="text"]:focus { border: 2px solid #000; outline: 2px solid red; }', '

    Hi there

    ')); + expect(only(f, 'input-state-shift').length).toBe(1); + }); + + test('an holding only a glyph is not an italic word; a word is', () => { + expect(only(run(page('', '

    Our favourite tools ★

    Body.

    ')), 'italic-word-in-heading')).toEqual([]); + expect(only(run(page('', '

    Our favourite tools and more

    Body.

    ')), 'italic-word-in-heading').length).toBe(1); + }); + + test('a bounce keyframe by name on a UI selector is bounce-easing', () => { + const f = run(page('@keyframes bounce { from { transform: none } to { transform: translateY(-4px) } } .btn:hover { animation: bounce .4s; }', '

    Hi there

    Go
    ')); + expect(only(f, 'bounce-easing').map((x) => x.evidence)).toEqual([expect.stringMatching(/^bounce animation bounce on/)]); + }); + + test('a single-quoted inline style colour literal is literal-outside-tokens like its double-quoted twin', () => { + const single = run(page('', "

    Hi there

    x

    ")); + const double = run(page('', '

    Hi there

    x

    ')); + expect(only(single, 'literal-outside-tokens').map((x) => x.evidence)).toEqual(only(double, 'literal-outside-tokens').map((x) => x.evidence)); + expect(only(single, 'literal-outside-tokens').length).toBe(1); + }); + + test('a glass panel mixed from black names black; a tracked-only control is not called uppercase; emoji icon tiles stop at eight', () => { + const glass = run(page('.glass::after { backdrop-filter: blur(8px); background: color-mix(in oklch, black 40%, transparent); }', '

    Hi there

    x
    ')); + expect(only(glass, 'glow-wash').map((x) => x.evidence)).toEqual([expect.stringMatching(/translucent black/)]); + const tracked = run(page('.btn { font-size: 13px; letter-spacing: .06em; }', '

    Hi there

    Go now
    ')); + expect(only(tracked, 'wide-tracking').map((x) => x.evidence)).toEqual([expect.stringMatching(/^\.btn: a control tracked 0\.06em at 13px$/)]); + const tiles = run(page('', '

    Hi there

    ' + Array.from({ length: 12 }, (_, i) => '
    🚀

    T' + i + '

    ').join('\n') + '
    ')); + expect(only(tiles, 'emoji-decoration').length).toBe(8); + }); +}); diff --git a/test/design-lint-finish.test.ts b/test/design-lint-finish.test.ts new file mode 100644 index 000000000..63f8ad4fd --- /dev/null +++ b/test/design-lint-finish.test.ts @@ -0,0 +1,200 @@ +/** + * The finish rule family of the design lint (lib/design-lint/rules/finish.ts): + * for every rule id, one page that is clean for it and one with the tell + * planted, checked by id, grade and line. Everything here prints at polish + * except fake-avatar, which blocks. + */ +import { afterAll, describe, expect, test } from 'bun:test'; +import * as fs from 'node:fs'; +import * as os from 'node:os'; +import * as path from 'node:path'; +import { lint } from '../lib/design-lint/index'; +import { formatFinding, type Finding } from '../lib/design-lint/report'; +import { lintStatic } from '../lib/design-lint/static'; + +const tmpDirs: string[] = []; +afterAll(() => { for (const d of tmpDirs) fs.rmSync(d, { recursive: true, force: true }); }); + +const ROOT = path.resolve(import.meta.dir, '..'); +const FIXTURES = path.join(ROOT, 'test', 'fixtures', 'design-lint'); + +const TOKENS = ':root { --color-paper: oklch(97% 0.01 80); --color-ink: oklch(20% 0.02 250); --color-accent: oklch(50% 0.16 30); --color-accent-ink: oklch(98% 0.01 30); --color-muted: oklch(50% 0.02 250); --font-display: "Fraunces", serif; --font-body: "Public Sans", sans-serif; }'; + +function page(css: string, body: string, htmlAttrs = ' lang="en"'): string { + return '\n\nHarbour office\n\n\n\n' + body + '\n\n\n'; +} + +const lineOf = (html: string, needle: string): number => { + const at = html.indexOf(needle); + if (at < 0) throw new Error('needle not in page: ' + needle); + return html.slice(0, at).split('\n').length; +}; + +function run(html: string, files: Record = {}): Finding[] { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'design-lint-finish-')); + tmpDirs.push(dir); + fs.writeFileSync(path.join(dir, 'index.html'), html); + for (const [name, text] of Object.entries(files)) fs.writeFileSync(path.join(dir, name), text); + return lintStatic([dir], { cwd: dir, warn: (l) => { throw new Error(l); } }).findings; +} + +const only = (findings: Finding[], rule: string) => findings.filter((f) => f.rule === rule); +const show = (findings: Finding[]) => findings.map(formatFinding); +const polishAt = (findings: Finding[], rule: string, line: number) => expect(only(findings, rule).map((f) => [f.grade, f.line])).toEqual([['polish', line]]); + +describe('design-lint finish: prose (F1, F2)', () => { + test('straight-quotes prints at polish with the count; curly quotes are clean', () => { + const slop = page('', '
    \n

    Mari said "the close ran itself" and that\'s the review.

    \n
    '); + const hits = only(run(slop), 'straight-quotes'); + polishAt(hits, 'straight-quotes', lineOf(slop, 'Mari said')); + expect(hits[0].evidence).toMatch(/^3 straight quotes in prose \(first: /); + expect(only(run(page('', '

    Mari said \u201cthe close ran itself\u201d and that\u2019s the review.

    ')), 'straight-quotes')).toEqual([]); + }); + + test('three-dot-ellipsis prints at polish; the ellipsis character is clean', () => { + const slop = page('', '
    \n

    Wait for it...

    \n
    '); + polishAt(run(slop), 'three-dot-ellipsis', lineOf(slop, 'Wait for')); + expect(only(run(page('', '

    Wait for it\u2026

    ')), 'three-dot-ellipsis')).toEqual([]); + }); +}); + +describe('design-lint finish: heads and buttons (F3, F4, F6)', () => { + test('balanced-display-head prints at polish when no display head has text-wrap: balance; one balanced head rule is clean', () => { + const slop = page('h1 {\n font-size: 3rem;\n}', '

    October closed in two days

    '); + const hits = only(run(slop), 'balanced-display-head'); + polishAt(hits, 'balanced-display-head', lineOf(slop, 'h1 {')); + expect(hits[0].evidence).toBe('no text-wrap: balance on any display head (1 head rules, the first h1)'); + expect(only(run(page('h1 { font-size: 3rem; text-wrap: balance; }', '

    October closed in two days

    ')), 'balanced-display-head')).toEqual([]); + }); + + test('two-primary-buttons prints at polish for two filled primary recipes; one filled recipe and an outline is clean', () => { + const slop = page('.btn-book { background: var(--color-accent); }\n.btn-buy {\n background: var(--color-ink);\n}', '
    BookBuy
    '); + const hits = only(run(slop), 'two-primary-buttons'); + polishAt(hits, 'two-primary-buttons', lineOf(slop, 'background: var(--color-ink)')); + expect(hits[0].evidence).toBe('2 filled primary-button recipes on one page: .btn-book and .btn-buy'); + expect(only(run(page('.btn-book { background: var(--color-accent); } .btn-quiet { background: transparent; border: 1px solid var(--color-accent); }', '
    BookMethod
    ')), 'two-primary-buttons')).toEqual([]); + }); + + test('display-figures-tabular prints at polish for a display-size stat without tabular numerals; tabular-nums on the selector or the root is clean', () => { + const slop = page('.stat__num {\n font-size: 48px;\n}', '

    1,140

    '); + const hits = only(run(slop), 'display-figures-tabular'); + polishAt(hits, 'display-figures-tabular', lineOf(slop, 'font-size: 48px')); + expect(hits[0].evidence).toBe('figures on .stat__num at display size without tabular numerals'); + expect(only(run(page('.stat__num { font-size: 48px; font-variant-numeric: tabular-nums; }', '

    1,140

    ')), 'display-figures-tabular')).toEqual([]); + expect(only(run(page('body { font-variant-numeric: tabular-nums; } .stat__num { font-size: 48px; }', '

    1,140

    ')), 'display-figures-tabular')).toEqual([]); + }); +}); + +describe('design-lint finish: surfaces and recipes (F5, F7, F24)', () => { + test('icon-coin prints at polish for a small round filled icon box; a bare inline icon is clean', () => { + const slop = page('.feature__icon {\n width: 40px;\n border-radius: 50%;\n background: var(--color-accent);\n}', '
    '); + const hits = only(run(slop), 'icon-coin'); + polishAt(hits, 'icon-coin', lineOf(slop, 'background: var(--color-accent)')); + expect(hits[0].evidence).toBe('an icon in a coloured coin: .feature__icon'); + expect(only(run(page('.feature__icon { width: 20px; color: currentColor; }', '
    ')), 'icon-coin')).toEqual([]); + }); + + test('stamped-recipe prints at polish for one container recipe on six selectors and for the pill radius on five non-controls; four varied boxes are clean', () => { + const recipe = ' { border: 1px solid var(--color-muted); border-radius: 8px; background: var(--color-paper); }'; + const six = page(['.a', '.b', '.c', '.d', '.e', '.f'].map((s) => s + recipe).join('\n'), '
    '); + const hits = only(run(six), 'stamped-recipe'); + polishAt(hits, 'stamped-recipe', lineOf(six, '.a {')); + expect(hits[0].evidence).toBe('one container recipe on 6 selectors (.a, .b, .c, .d and more)'); + const pills = page('.card, .panel, .tile, .box, .media {\n border-radius: 9999px;\n}', '
    '); + const pillHits = only(run(pills), 'stamped-recipe'); + polishAt(pillHits, 'stamped-recipe', lineOf(pills, 'border-radius: 9999px')); + expect(pillHits[0].evidence).toBe('the pill radius on 5 non-control selectors (.card, .panel, .tile, .box)'); + expect(only(run(page('.btn, .chip, .tag, .badge, .pill { border-radius: 9999px; } .a' + recipe + ' .b { border-radius: 4px; background: var(--color-paper); }', '
    ')), 'stamped-recipe')).toEqual([]); + }); + + test('hairline-under-shadow prints at polish for a 1px border under a wide soft shadow, in CSS or Tailwind classes; a shadow alone is clean', () => { + const slop = page('.card {\n border: 1px solid var(--color-muted);\n box-shadow: 0 10px 30px -5px rgb(0 0 0 / 0.2);\n}', '
    '); + const hits = only(run(slop), 'hairline-under-shadow'); + polishAt(hits, 'hairline-under-shadow', lineOf(slop, 'box-shadow')); + expect(hits[0].evidence).toBe('a hairline border under a wide soft shadow on .card'); + const tw = page('', '
    \n
    \n
    '); + expect(only(run(tw), 'hairline-under-shadow').map((f) => [f.grade, f.line])).toEqual([['polish', lineOf(tw, 'shadow-xl')]]); + expect(only(run(page('.card { box-shadow: 0 10px 30px -5px rgb(0 0 0 / 0.2); }', '
    ')), 'hairline-under-shadow')).toEqual([]); + }); +}); + +describe('design-lint finish: motion and people (F8, F9)', () => { + test('scroll-choreography-mix prints at polish for two scroll-driven families; one is clean', () => { + const slop = page('.reveal { animation: rise linear both; animation-timeline: view(); }\n.bar {\n animation: grow linear both;\n animation-timeline: scroll();\n}', '
    '); + const hits = only(run(slop), 'scroll-choreography-mix'); + polishAt(hits, 'scroll-choreography-mix', lineOf(slop, 'animation-timeline: scroll()')); + expect(hits[0].evidence).toBe('2 scroll-choreography patterns on one page (reveal, bar)'); + expect(only(run(page('.reveal { animation: rise linear both; animation-timeline: view(); }', '
    ')), 'scroll-choreography-mix')).toEqual([]); + }); + + test('fake-avatar blocks on a generated-face service; stock-person-photo prints at polish for a person-keyword stock URL; a named local portrait is clean', () => { + const slop = page('.hero { background-image: url(https://images.unsplash.com/photo-1?portrait); }', '
    \nMari\nA customer\n
    '); + const findings = run(slop); + expect(only(findings, 'fake-avatar').map((f) => [f.tier, f.grade, f.line, f.evidence])).toEqual([['blocks', 'blocks', lineOf(slop, 'pravatar'), 'a generated-face service (i.pravatar.cc) stands in for a person']]); + expect(only(findings, 'stock-person-photo').map((f) => [f.grade, f.line]).sort((a, b) => Number(a[1]) - Number(b[1]))).toEqual([['polish', lineOf(slop, 'photo-1?portrait')], ['polish', lineOf(slop, 'headshot')]]); + const clean = run(page('', '
    Mari Halvorsen
    ')); + expect(only(clean, 'fake-avatar')).toEqual([]); + expect(only(clean, 'stock-person-photo')).toEqual([]); + }); +}); + +describe('design-lint finish: page invariants and browser surfaces (F15, F16)', () => { + test('page-invariants prints at polish for two container widths and for three column gaps; one width and one gap are clean', () => { + const widths = page('.wrap { max-width: 1200px; }\n.container { max-width: 1360px; }', '
    '); + const w = only(run(widths), 'page-invariants'); + expect(w.map((f) => [f.grade, f.line, f.evidence])).toEqual([['polish', 1, '2 container widths on one page (1200, 1360px)']]); + const gaps = page('.a { display: grid; grid-template-columns: 1fr 1fr; gap: 24px; } .b { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 32px; } .c { display: grid; grid-template-columns: repeat(2, 1fr); gap: 48px; }', '
    '); + expect(only(run(gaps), 'page-invariants').map((f) => f.evidence)).toEqual(['3 different column gaps across multi-column sections (24px, 32px, 48px)']); + expect(only(run(page('.wrap { max-width: 1360px; } .a, .b { display: grid; grid-template-columns: 1fr 1fr; gap: 32px; }', '
    ')), 'page-invariants')).toEqual([]); + }); + + test('unthemed-browser-surfaces prints at polish naming the missing surfaces on a page with an accent; themed CSS or Tailwind surfaces are clean, and a page without an accent is skipped', () => { + const slop = page('', '
    '); + const hits = only(run(slop), 'unthemed-browser-surfaces'); + expect(hits.map((f) => [f.grade, f.line, f.evidence])).toEqual([['polish', 1, 'browser surfaces left unthemed: ::selection, scrollbar-color, caret-color']]); + expect(only(run(page('::selection { background: var(--color-accent); } html { scrollbar-color: var(--color-muted) var(--color-paper); } input { caret-color: var(--color-accent); }', '
    ')), 'unthemed-browser-surfaces')).toEqual([]); + expect(only(run(page('', '
    ')), 'unthemed-browser-surfaces')).toEqual([]); + expect(only(run(page('', '
    ').replace('--color-accent: oklch(50% 0.16 30); ', '')), 'unthemed-browser-surfaces')).toEqual([]); + }); +}); + +describe('design-lint finish: the document (F21, F22, F23)', () => { + test('skipped-heading prints at polish when a level is skipped; stepped levels are clean', () => { + const slop = page('', '
    \n

    October

    \n

    Where the days went

    \n
    '); + const hits = only(run(slop), 'skipped-heading'); + polishAt(hits, 'skipped-heading', lineOf(slop, '

    ')); + expect(hits[0].evidence).toBe('h1 is followed by h3 ("Where the days went")'); + expect(only(run(page('', '

    October

    Where the days went

    Matching

    ')), 'skipped-heading')).toEqual([]); + }); + + test('justified-text prints at polish without hyphens: auto, in CSS or as text-justify; hyphenated justification is clean', () => { + const slop = page('p {\n text-align: justify;\n}', '

    Three days were matching receipts.

    '); + const hits = only(run(slop), 'justified-text'); + polishAt(hits, 'justified-text', lineOf(slop, 'text-align: justify')); + expect(hits[0].evidence).toBe('justified text without hyphenation on p'); + const tw = page('', '
    \n

    Three days were matching receipts.

    \n
    '); + expect(only(run(tw), 'justified-text').map((f) => f.line)).toEqual([lineOf(tw, 'text-justify')]); + expect(only(run(page('p { text-align: justify; hyphens: auto; }', '

    Three days were matching receipts.

    ')), 'justified-text')).toEqual([]); + }); + + test('missing-lang prints at polish for without lang; the title and description halves belong to the copy tier', () => { + const slop = page('', '
    ', ''); + const hits = only(run(slop), 'missing-lang'); + polishAt(hits, 'missing-lang', lineOf(slop, '')); + expect(hits[0].evidence).toBe(' names no lang'); + expect(only(run(page('', '
    ')), 'missing-lang')).toEqual([]); + }); +}); + +describe('design-lint finish: fixtures', () => { + test('the clean page raises nothing from this family; slopped.html plants the unbalanced head and the straight quotes; the waiver fixture waives balanced-display-head', async () => { + const finish = new Set(['straight-quotes', 'three-dot-ellipsis', 'balanced-display-head', 'two-primary-buttons', 'icon-coin', 'display-figures-tabular', 'stamped-recipe', 'scroll-choreography-mix', 'fake-avatar', 'stock-person-photo', 'page-invariants', 'unthemed-browser-surfaces', 'skipped-heading', 'justified-text', 'missing-lang', 'hairline-under-shadow']); + const clean = await lint([path.join(FIXTURES, 'clean')], { cwd: ROOT }); + expect(show(clean.findings.filter((f) => finish.has(f.rule)))).toEqual([]); + const slopped = await lint([path.join(FIXTURES, 'slopped.html')], { cwd: ROOT }); + expect(only(slopped.findings, 'balanced-display-head').map((f) => [f.grade, f.line])).toEqual([['polish', 63]]); + expect(only(slopped.findings, 'straight-quotes').map((f) => [f.grade, f.line])).toEqual([['polish', 141]]); + const waiver = await lint([path.join(FIXTURES, 'waiver')], { cwd: ROOT }); + expect(only(waiver.findings, 'balanced-display-head').map((f) => f.grade)).toEqual(['waived']); + }); +}); diff --git a/test/design-lint-fourth-cycle.test.ts b/test/design-lint-fourth-cycle.test.ts new file mode 100644 index 000000000..b1309e79a --- /dev/null +++ b/test/design-lint-fourth-cycle.test.ts @@ -0,0 +1,302 @@ +/** + * The fourth review cycle's regressions: commented-out markup dead for every rule, the shared tree pairing behind + * Tailwind frames and wireframe slots, a parser that cannot be driven exponential or recursive by hostile CSS, lint + * roots and cwd reached through a symlink, files the lint could not read reported instead of passing silently, and + * the render tier keeping its measured findings when a page answers in the wrong shape. + */ +import { afterAll, describe, expect, test } from 'bun:test'; +import * as fs from 'node:fs'; +import * as os from 'node:os'; +import * as path from 'node:path'; +import type { RenderResult, RenderSpec } from '../lib/aside-render'; +import { parseCss, pxOf, resolveVars } from '../lib/design-lint/css'; +import { parseDoc, scriptSites } from '../lib/design-lint/html'; +import { lintRender, type Runner } from '../lib/design-lint/render'; +import { Reporter, type Finding } from '../lib/design-lint/report'; +import { lintStatic, MAX_FILE_BYTES } from '../lib/design-lint/static'; +import { FLOOR_REFUSAL, OWN_RULE_REFUSAL, applyWaivers, resolveWaivers, suspectedRules } from '../lib/design-lint/waivers'; + +const tmpDirs: string[] = []; +afterAll(() => { for (const d of tmpDirs) fs.rmSync(d, { recursive: true, force: true }); }); + +const TOKENS = ':root { --color-paper: oklch(97% 0.01 80); --color-ink: oklch(20% 0.02 250); --color-accent: oklch(50% 0.16 30); --color-accent-ink: oklch(98% 0.01 30); --color-muted: oklch(50% 0.02 250); --font-display: "Literata", serif; --font-body: "Public Sans", sans-serif; }'; +const HEAD = '\n\nHarbour office\n'; + +function page(css: string, body: string): string { + return HEAD + '\n\n\n' + body + '\n\n\n'; +} + +function tree(files: Record): string { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'design-lint-cycle4-')); + tmpDirs.push(dir); + for (const [name, text] of Object.entries(files)) { + fs.mkdirSync(path.dirname(path.join(dir, name)), { recursive: true }); + fs.writeFileSync(path.join(dir, name), text); + } + return dir; +} + +const quiet = { warn: () => {} }; +const run = (html: string, files: Record = {}): Finding[] => { + const dir = tree({ 'index.html': html, ...files }); + return lintStatic([dir], { cwd: dir, ...quiet }).findings; +}; +const only = (f: Finding[], rule: string) => f.filter((x) => x.rule === rule); +const rules = (f: Finding[]) => [...new Set(f.map((x) => x.rule))].sort(); + +describe('design-lint fourth cycle: commented-out markup is dead for every rule', () => { + test('tells inside an HTML comment report nothing: inline literal, italic word, broken image, fake avatar, emoji, craft copy', () => { + const live = page('', '

    The harbour office

    Rows close in order.

    '); + const dead = page('', '

    The harbour office

    Rows close in order.

    \n'); + const before = rules(run(live)); + const after = run(dead); + expect(rules(after)).toEqual(before); + expect(only(after, 'literal-outside-tokens').concat(only(after, 'italic-word-in-heading'), only(after, 'broken-image'), only(after, 'fake-avatar'), only(after, 'generic-hero-copy'))).toEqual([]); + }); + + test('a commented-out module script does not make the page a build-only shell, so its page rules still run', () => { + const body = '

    Harbour

    Rows.

    '; + const shell = HEAD + '' + body + ''; + const commented = HEAD + '' + body + ''; + expect(only(run(shell), 'overflow-x-unclipped')).toEqual([]); + expect(only(run(commented), 'overflow-x-unclipped').length).toBe(1); + }); +}); + +describe('design-lint fourth cycle: one pairing for every tree reader', () => { + test('an unclosed
  • list before an eyebrow does not hide kicker-above-heading from the Tailwind frames', () => { + const body = (li: string) => '

    Hi there

    1. one' + li + '
    2. two' + li + '

    Our depots

    Bergen and Stavanger

    '; + const closed = run(page('', body('
  • '))); + const open = run(page('', body(''))); + expect(only(closed, 'kicker-above-heading').length).toBeGreaterThan(0); + expect(only(open, 'kicker-above-heading').map((f) => f.line)).toEqual(only(closed, 'kicker-above-heading').map((f) => f.line)); + }); + + test('wireframe-slots groups a row of unclosed
  • items under their list', () => { + const items = (close: string) => Array.from({ length: 6 }, (_, i) => '
  • x' + close).join('\n'); + const f = run(page('', '

    Hi there

      ' + items('') + '
    ')); + const closed = run(page('', '

    Hi there

      ' + items('') + '
    ')); + expect(only(f, 'wireframe-slots').map((x) => x.evidence)).toEqual(only(closed, 'wireframe-slots').map((x) => x.evidence)); + expect(only(f, 'wireframe-slots').some((x) => /in one row or grid/.test(x.evidence))).toBe(true); + }); + + test('a heading start tag closes an open heading and a block start closes an open

    , so an unclosed run costs its length', () => { + const doc = parseDoc('x.html', '' + '

    Title x\n'.repeat(3000) + '

    a

    b
    ' + ''); + const heads = doc.tags.filter((t) => !t.close && t.name === 'h2'); + expect(heads.length).toBe(3000); + for (const frag of ['

    x ', '')); + expect(only(focus, 'input-state-shift').map((x) => x.evidence)).toEqual(['the focus state is drawn with border on input:focus']); + const signin = run(page('input { height: 48px }', '

    Sign in to the ledger

    Your ledger waits behind the door.

    ')); + expect(only(signin, 'email-band-close')).toEqual([]); + }); + + test('an uppercase control under an uppercase display may carry 0.04em in a stylesheet as in a class string, no more', () => { + const f = run(page('h1 { text-transform: uppercase; } .btn{text-transform:uppercase;letter-spacing:0.045em;font-size:14px} .cta{text-transform:uppercase;letter-spacing:0.04em;font-size:14px}', '

    HELLO THERE

    Go nowStay
    ')); + expect(only(f, 'wide-tracking').map((x) => x.evidence)).toEqual(['.btn: an uppercase control tracked 0.045em']); + }); + + test('a linked stylesheet that does not exist is warned about and otherwise ignored', () => { + const warned: string[] = []; + const dir = tree({ 'index.html': HEAD + '

    Hello

    Body.

    ' }); + const r = lintStatic([dir], { cwd: dir, warn: (l) => warned.push(l) }); + expect(warned).toEqual([expect.stringMatching(/skipped .*missing\.css, not found$/)]); + expect(only(r.findings, 'internal-error')).toEqual([]); + }); +}); diff --git a/test/design-lint-sixth-cycle.test.ts b/test/design-lint-sixth-cycle.test.ts new file mode 100644 index 000000000..3b7954b8b --- /dev/null +++ b/test/design-lint-sixth-cycle.test.ts @@ -0,0 +1,214 @@ +/** + * The sixth review cycle's regressions: the line-length and tracking rules that walked the page or the sheet once per + * rule, the JSX scanner's unclosed cascade, a stylesheet reached through a symlink, the LINT line's own separator in + * page text, the untested waiver and render cells the state matrix named, and the rule judgements the design pass asked + * for (a meta label in mono, a leading-dot length, a percentage leading, an icon before the italic word, digit ranges). + */ +import { afterAll, describe, expect, test } from 'bun:test'; +import * as fs from 'node:fs'; +import * as os from 'node:os'; +import * as path from 'node:path'; +import type { RenderResult, RenderSpec } from '../lib/aside-render'; +import { parseDoc } from '../lib/design-lint/html'; +import { lintRender, type Runner } from '../lib/design-lint/render'; +import { exitCodeOf, summarize, type Finding } from '../lib/design-lint/report'; +import { lintStatic } from '../lib/design-lint/static'; +import { applyWaivers, resolveWaivers } from '../lib/design-lint/waivers'; + +const tmpDirs: string[] = []; +afterAll(() => { for (const d of tmpDirs) fs.rmSync(d, { recursive: true, force: true }); }); + +const TOKENS = ':root { --color-paper: oklch(97% 0.01 80); --color-ink: oklch(20% 0.02 250); --color-accent: oklch(50% 0.16 30); --color-accent-ink: oklch(98% 0.01 30); --color-muted: oklch(50% 0.02 250); --font-display: "Literata", serif; --font-body: "Public Sans", sans-serif; --font-mono: "JetBrains Mono", monospace; }'; +const HEAD = '\n\nHarbour office\n'; +const page = (css: string, body: string): string => HEAD + '\n\n\n' + body + '\n\n\n'; + +function tree(files: Record): string { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'design-lint-cycle6-')); + tmpDirs.push(dir); + for (const [name, text] of Object.entries(files)) { + fs.mkdirSync(path.dirname(path.join(dir, name)), { recursive: true }); + fs.writeFileSync(path.join(dir, name), text); + } + return dir; +} +const quiet = { warn: () => {} }; +const run = (html: string, files: Record = {}): Finding[] => { const dir = tree({ 'index.html': html, ...files }); return lintStatic([dir], { cwd: dir, ...quiet }).findings; }; +const components = (files: Record): Finding[] => { const dir = tree(files); return lintStatic([dir], { cwd: dir, ...quiet, scope: 'component' }).findings; }; +const only = (f: Finding[], rule: string) => f.filter((x) => x.rule === rule); +const timed = (fn: () => void): number => { const t = performance.now(); fn(); return performance.now() - t; }; +const DASHES = 'The ledger \u2014 the month \u2014 the close \u2014 the depot \u2014 the review \u2014 the rule \u2014 the row \u2014 the sum'; + +describe('design-lint sixth cycle: work done once per page, not once per rule', () => { + test('a measure already inside 45 to 75ch costs no page walk, however many rules declare one', () => { + const rules = Array.from({ length: 1600 }, (_, i) => '.sec-' + i + ' .copy { max-width: 60ch; }').join('\n'); + const body = '

    Hello there

    ' + Array.from({ length: 2000 }, (_, i) => '

    Short line.

    ').join('') + '
    '; + const dir = tree({ 'a.css': TOKENS + '\n' + rules, 'index.html': HEAD + '' + body + '' }); + let f: Finding[] = []; + expect(timed(() => { f = lintStatic([dir], { cwd: dir, ...quiet }).findings; })).toBeLessThan(2000); + expect(only(f, 'line-length')).toEqual([]); + const short = run(page('.a .copy { max-width: 36ch; } .b .copy { max-width: 36ch; }', '

    Hello there

    One line.

    Two.

    ')); + expect(only(short, 'line-length')).toEqual([]); + }); + + test('thousands of tracked label rules resolve their inherited case through an index, with the same findings', () => { + const caps = Array.from({ length: 6000 }, (_, i) => '.c' + i + ' .label { text-transform: uppercase; letter-spacing: .08em; font-size: 12px; }\n.c' + i + ' { color: var(--color-ink); }').join('\n'); + const dir = tree({ 'a.css': TOKENS + '\n' + caps, 'index.html': HEAD + '

    Hello there

    Body.

    ' }); + let f: Finding[] = []; + expect(timed(() => { f = lintStatic([dir], { cwd: dir, ...quiet }).findings; })).toBeLessThan(2500); + expect(only(f, 'wide-tracking').length).toBe(6000); + const inherited = run(page('.card { text-transform: uppercase; } .card > .k { letter-spacing: .1em; font-size: 12px; } .card .k .deep { color: var(--color-ink); }', '

    Hello there

    Label
    ')); + expect(only(inherited, 'wide-tracking').map((x) => x.evidence)).toEqual(['.card > .k: uppercase tracked 0.1em at 12px in a label role']); + }); + + test('a JSX run of unclosed elements fails every ancestor at once instead of rescanning to the end of the file', () => { + const open = Array.from({ length: 600 }, (_, i) => '
    ' + 'word '.repeat(600) + '\n').join(''); + expect(timed(() => parseDoc('/tmp/A.tsx', 'export default function A() { return (' + open + '); }'))).toBeLessThan(1500); + const closed = parseDoc('/tmp/B.tsx', 'export default function B() { return (
    ' + '
    text
    \n'.repeat(300) + '
    ); }'); + expect(closed.tags.filter((t) => !t.close && t.name === 'div').length).toBe(300); + }); + + test('a class attribute of thousands of tokens is read once for the hairline-under-shadow pair', () => { + const many = Array.from({ length: 8000 }, () => 'border flex').join(' '); + expect(timed(() => run(page('', '

    Hello there

    x
    ')))).toBeLessThan(2000); + expect(only(run(page('', '

    Hello there

    x
    ')), 'hairline-under-shadow').length).toBe(1); + expect(only(run(page('', '

    Hello there

    x
    ')), 'hairline-under-shadow')).toEqual([]); + }); +}); + +describe('design-lint sixth cycle: findings that name the right place', () => { + test('tooltip-focus-delay names the sheet that holds the :focus delay', () => { + const f = run(HEAD + '

    Hello there

    Body.

    ', + { 'a.css': TOKENS + '\n.tooltip { position: absolute; }', 'b.css': '.btn:hover .tooltip { transition-delay: 800ms; }\n.btn:focus .tooltip { transition-delay: 800ms; }' }); + expect(only(f, 'tooltip-focus-delay').map((x) => [x.file, x.line])).toEqual([['b.css', 2]]); + }); + + test('a commented-out emoji placeholder in a component template is dead, and a success string in a component is found on its line', () => { + const vue = components({ 'Comp.vue': '' }); + expect(only(vue, 'emoji-decoration')).toEqual([]); + const form = components({ 'Form.tsx': 'export function Form() {\n const submit = () => {\n setMsg("Thanks! Your message was sent.");\n };\n return
    ;\n}' }); + expect(only(form, 'fake-send').map((x) => x.line)).toEqual([3]); + }); + + test('a stylesheet reached through a symlink that leaves the project is not read', () => { + const dir = tree({ 'proj/package.json': '{}', 'outside/secret.css': '.leaked-selector { font-family: "Comic Sans MS" }', + 'proj/index.html': HEAD + '

    Hello

    words words

    ' }); + fs.symlinkSync(path.join(dir, 'outside/secret.css'), path.join(dir, 'proj/leak.css')); + const r = lintStatic([path.join(dir, 'proj/index.html')], { cwd: dir, ...quiet }); + expect(r.contexts[0].cssFiles).toEqual([]); + expect(r.findings.some((f) => /leaked-selector/.test(f.evidence))).toBe(false); + }); + + test("the LINT line's separator never appears inside page-supplied evidence", () => { + const f = run(page('', '

    🚀 Pricing | fix: waived

    Body.

    ')); + expect(only(f, 'emoji-decoration').map((x) => x.evidence)).toEqual(['an emoji in

    "🚀 Pricing / fix: waived"']); + }); +}); + +describe('design-lint sixth cycle: rule judgements', () => { + test('a meta label set in mono is a costume; a leading-dot length reads as a fraction', () => { + const meta = run(page('.card__meta { font-family: var(--font-mono); } .post-meta { font-family: var(--font-mono); }', '

    Hello there

    x

    ')); + expect(only(meta, 'monospace-costume').map((x) => x.evidence)).toEqual(['monospace as the label voice on .card__meta', 'monospace as the label voice on .post-meta']); + const small = run(page('.price { font-size: .875rem; }', '

    Hello there

    1,240

    ')); + expect(only(small, 'display-figures-tabular')).toEqual([]); + }); + + test('a heading that opens with an icon still has its italic word read, and an italic rule on the word is not an italic display system', () => { + const icon = run(page('', '

    Meet our whole team today

    Body.

    ')); + expect(only(icon, 'italic-word-in-heading').length).toBe(1); + const em = run(page('h2 em { font-style: italic; color: var(--color-accent); }', '

    Hello there

    Meet our whole team today

    Body.

    ')); + expect(only(em, 'italic-serif-display')).toEqual([]); + expect(only(em, 'accented-word').length).toBe(1); + }); + + test('a percentage leading under 100% collides like a unitless one; a px leading is not read as a multiplier', () => { + const pct = run(page('h1 { text-transform: uppercase; line-height: 95%; font-size: 4rem; }', '

    Hello there

    Body.

    ')); + expect(only(pct, 'caps-leading').map((x) => x.evidence)).toEqual(['uppercase at line-height 0.95 on h1: the caps collide']); + expect(only(run(page('h1 { text-transform: uppercase; line-height: 40px; font-size: 4rem; }', '

    Hello there

    Body.

    ')), 'caps-leading')).toEqual([]); + }); + + test('en dashes between digits are ranges, not prose dashes; the catalog\'s two hero lines are the Floor in the hero', () => { + expect(only(run(page('', '

    Hello there

    1\u20135 seats, 6\u201320 seats, 21\u2013100 seats

    ')), 'em-dash-overuse')).toEqual([]); + expect(only(run(page('', '

    Hello there

    ' + DASHES + '

    ')), 'em-dash-overuse').length).toBe(1); + const hero = run(page('', '
    \n

    Welcome to Acme

    \n

    Your all-in-one solution for the depot.

    \n
    ')); + expect(only(hero, 'generic-hero-copy').map((x) => [x.grade, x.evidence])).toEqual([['blocks', 'a stock line: "all-in-one solution"'], ['blocks', 'a stock opener: "Welcome to"']]); + }); +}); + +describe('design-lint sixth cycle: the waiver cells the state matrix named', () => { + const claim = (rule: string, reason: string, file = 'a.html', line = 1) => ({ rule, reason, file, line }); + + test('an unknown rule with a short reason is refused as unknown, not for its length', () => { + const set = resolveWaivers([claim('no-such-thing', 'ok')], 'the ledger closes the month'); + expect(set.refused.map((f) => [f.rule, f.grade, f.file, f.evidence])).toEqual([['waiver', 'ask', 'a.html', 'waiver on no-such-thing refused: no such rule']]); + }); + + test('a refused page claim on an ask rule leaves the finding at ask and adds one refusal', () => { + const set = resolveWaivers([claim('zero-chroma-neutrals', 'by design', 'a.html', 2)], 'the ledger keeps its grey rows grey'); + const out = applyWaivers([{ rule: 'zero-chroma-neutrals', tier: 'ask', grade: 'ask', file: 'a.html', line: 9, evidence: 'e', fix: 'f', source: 'static' }], set); + expect(out.map((f) => [f.rule, f.grade])).toEqual([['zero-chroma-neutrals', 'ask'], ['waiver', 'ask']]); + expect(exitCodeOf(summarize(out, 'skipped: x'))).toBe(1); + }); + + test('a polish rule waived from its stylesheet is waived there only; a refused sheet claim leaves it at polish', () => { + const PAGE = HEAD + '

    Ledger

    The ledger column is justified.

    '; + const sheet = (reason: string) => ({ 'index.html': PAGE, 't.css': '/* gstack-lint-disable justified-text: ' + reason + ' */\n' + TOKENS + '\n.just { text-align: justify; }' }); + const ok = run(PAGE, sheet('the ledger column is set justified like the printed paper form')); + expect(only(ok, 'waiver')).toEqual([]); + expect(only(ok, 'justified-text').map((x) => [x.file, x.grade])).toEqual([['t.css', 'waived']]); + const bad = run(PAGE, sheet('this is intentional and by design here')); + expect(only(bad, 'waiver').map((x) => [x.file, x.line, x.evidence])).toEqual([['t.css', 1, 'waiver on justified-text refused: boilerplate reason']]); + expect(only(bad, 'justified-text').map((x) => [x.file, x.grade])).toEqual([['t.css', 'polish']]); + }); + + test('a component waiver answers for its own file only, weighed against its own text', () => { + const card = 'export function Card() { return

    ' + DASHES + '

    ; }'; + const sibling = components({ 'Card.tsx': card, 'Hero.tsx': '// gstack-lint-disable em-dash-overuse: the ledger sets its dashes as the month closes on the depot\nexport function Hero() { return

    The ledger closes the month on the depot

    ; }' }); + expect(only(sibling, 'em-dash-overuse').map((x) => [x.file, x.grade])).toEqual([['Card.tsx', 'ask']]); + expect(only(sibling, 'waiver')).toEqual([]); + const own = components({ 'Card.tsx': '// gstack-lint-disable em-dash-overuse: the ledger sets its dashes as the month closes on the depot\n' + card }); + expect(only(own, 'em-dash-overuse').map((x) => [x.file, x.grade])).toEqual([['Card.tsx', 'waived']]); + const short = components({ 'Card.tsx': '// gstack-lint-disable em-dash-overuse: short\n' + card }); + expect(only(short, 'em-dash-overuse').map((x) => x.grade)).toEqual(['ask']); + expect(only(short, 'waiver').map((x) => x.evidence)).toEqual(['waiver on em-dash-overuse refused: reason under 24 characters']); + }); +}); + +describe('design-lint sixth cycle: the render cells the state matrix named', () => { + const PAGE = HEAD + '

    t

    Body.

    Go
    '; + const SETUP = 1, FIRST = 2, FOCUS = 13; + const weak = { key: 'a', path: 'main>a', at: { tag: 'a', text: 'Go' }, bare: false, ratio: 1.2, ring: [1, 1, 1], pad: 2 }; + const claim = { rule: 'low-contrast', grade: 'fail', evidence: 'computed contrast 2.50:1 under the 4.5:1 threshold on p.faint (2.50:1)', probe: { path: 'main>p', fg: [120 / 255, 120 / 255, 120 / 255], threshold: 4.5 } }; + type Patch = (evals: Record) => void; + const runner = (patch: Patch, pixels: Runner): Runner => async (spec: RenderSpec): Promise => { + if (spec.steps.some((s) => s.kind === 'screenshot')) return pixels(spec); + const evals: Record = { [SETUP]: '{"lost":[]}' }; + for (let i = FIRST; i <= FOCUS; i++) evals[i] = '[]'; + patch(evals); + return { ok: true, engine: 'browse', outputs: [], evals, stdout: '' }; + }; + const noPixels: Runner = async () => ({ ok: true, engine: 'browse', outputs: [], evals: {}, stdout: '' }); + + test('a fail that repeats a warn\'s evidence at a later width is kept at blocks; a non-string fix is dropped', async () => { + const dir = tree({ 'index.html': PAGE }); + const file = path.join(dir, 'index.html'); + const r = await lintRender([file], { cwd: dir, run: runner((ev) => { + ev[FIRST] = JSON.stringify([{ rule: 'nested-cards', grade: 'warn', evidence: 'same' }]); + ev[FIRST + 1] = JSON.stringify([{ rule: 'nested-cards', grade: 'fail', evidence: 'same', fix: { a: 1 } }]); + }, noPixels) }); + expect(only(r.findings, 'nested-cards').map((f) => [f.grade, f.evidence])).toEqual([['blocks', '[375px] same']]); + expect(only(r.findings, 'nested-cards')[0].fix).not.toContain('[object Object]'); + }); + + test('a weak ring whose pixel pass cannot be read, does not render or throws is reported at its computed ratio, and the computed contrast stands', async () => { + const dir = tree({ 'index.html': PAGE }); + const file = path.join(dir, 'index.html'); + const failed: Runner = async () => ({ ok: false, engine: 'browse', outputs: [], evals: {}, stdout: '', error: 'gone' }); + const threw: Runner = async () => { throw new Error('socket'); }; + for (const pixels of [noPixels, failed, threw]) { + const r = await lintRender([file], { cwd: dir, run: runner((ev) => { ev[FOCUS] = JSON.stringify([weak]); ev[FIRST + 5] = JSON.stringify([claim]); }, pixels) }); + expect(only(r.findings, 'missing-focus-visible').map((f) => [f.grade, f.evidence])).toEqual([['blocks', '[1440px] focus ring 1.20:1 against what is behind it on a']]); + expect(only(r.findings, 'low-contrast').map((f) => f.evidence)).toEqual(['[1280px] computed contrast 2.50:1 under the 4.5:1 threshold on p.faint (2.50:1)']); + expect(only(r.findings, 'render')).toEqual([]); + } + }); +}); diff --git a/test/design-lint-structure.test.ts b/test/design-lint-structure.test.ts new file mode 100644 index 000000000..b02dae960 --- /dev/null +++ b/test/design-lint-structure.test.ts @@ -0,0 +1,263 @@ +/** + * The structure rule family of the design lint (lib/design-lint/rules/structure.ts): for every rule id, a planted + * positive with its line and grade, and a negative control at the edge of the threshold. The shared fixtures + * (slopped.html, clean/) are checked for this family's rules too. + */ +import { afterAll, describe, expect, test } from 'bun:test'; +import * as fs from 'node:fs'; +import * as os from 'node:os'; +import * as path from 'node:path'; +import { formatFinding, lint, type Finding } from '../lib/design-lint/index'; + +const tmpDirs: string[] = []; +afterAll(() => { for (const d of tmpDirs) fs.rmSync(d, { recursive: true, force: true }); }); + +const ROOT = path.resolve(import.meta.dir, '..'); +const FIXTURES = path.join(ROOT, 'test', 'fixtures', 'design-lint'); +const FAMILY = ['template-cards', 'nested-cards', 'vh-height', 'raw-spacing', 'off-scale-spacing', 'overflow-x-unclipped', 'wide-container', 'bare-fr-track', 'display-head-unwrapped', 'radio-tab-jump', 'double-sticky', 'screen-word-budget']; + +const TOKENS = ':root { --color-paper: oklch(97% 0.01 80); --color-ink: oklch(20% 0.02 250); --font-display: "Fraunces", serif; --font-body: "Source Serif 4", serif; }'; +const CLIP = 'html, body { overflow-x: clip; }'; +const STATES = 'a:focus-visible, .button:focus-visible { outline: 2px solid var(--color-ink); }\n.button:active { transform: translateY(1px); }\n.button:disabled { opacity: 0.5; cursor: not-allowed; }'; + +function page(css: string, body: string, opts: { clip?: boolean } = {}): string { + const base = [TOKENS, opts.clip === false ? '' : CLIP, STATES].filter(Boolean).join('\n'); + return `\n\n\n\nFixture\n\n\n\n
    \n${body}\n
    \n\n\n`; +} + +async function lintPage(html: string, opts: { scope?: 'page' | 'component'; name?: string } = {}): Promise { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'design-lint-structure-')); + tmpDirs.push(dir); + const file = path.join(dir, opts.name ?? 'index.html'); + fs.writeFileSync(file, html); + return (await lint([file], { cwd: dir, scope: opts.scope, warn: (l: string) => { throw new Error(l); } })).findings; +} + +const only = (findings: Finding[], rule: string) => findings.filter((f) => f.rule === rule); +const lineOf = (html: string, needle: string): number => html.split('\n').findIndex((l) => l.includes(needle)) + 1; +const hits = (findings: Finding[], rule: string) => only(findings, rule).map((f) => [f.grade, f.line]); +const none = (findings: Finding[], rule: string) => expect(only(findings, rule).map(formatFinding)).toEqual([]); + +describe('design-lint structure: template-cards (gate 3)', () => { + test('three equal icon-above-heading tiles and a thick coloured side stripe report at ask', async () => { + const html = page('.features { display: grid; grid-template-columns: repeat(3, 1fr); }\n.note { border-left: 4px solid var(--color-ink); }', + '

    Sync

    Share

    Ship

    \n

    A note

    '); + const f = await lintPage(html); + expect(hits(f, 'template-cards')).toEqual([['ask', lineOf(html, 'repeat(3, 1fr)')], ['ask', lineOf(html, 'border-left: 4px')]]); + expect(only(f, 'template-cards')[0].evidence).toBe('three equal columns of icon-above-heading tiles on .features'); + }); + test('three text columns without icons and a hairline side border are not the template', async () => { + const html = page('.features { display: grid; grid-template-columns: repeat(3, 1fr); }\n.note { border-left: 1px solid var(--color-ink); }', + '

    Sync

    Once.

    Share

    Twice.

    Ship

    Daily.

    \n

    A note

    '); + none(await lintPage(html), 'template-cards'); + }); +}); + +describe('design-lint structure: nested-cards (gate 4)', () => { + test('a card inside a card blocks at the inner card', async () => { + const html = page('.card { border: 1px solid var(--color-ink); }', '
    \n

    Outer

    \n
    \n

    Inner

    \n
    \n
    '); + const f = await lintPage(html); + expect(hits(f, 'nested-cards')).toEqual([['blocks', lineOf(html, 'card feature-card')]]); + expect(only(f, 'nested-cards')[0].evidence).toBe('a card inside a card: class="card feature-card"'); + }); + test('a card inside a card grid, and sibling cards, are one containment layer', async () => { + const html = page('.card { border: 1px solid var(--color-ink); }', '

    One

    Two

    '); + none(await lintPage(html), 'nested-cards'); + }); +}); + +describe('design-lint structure: vh-height (gate 6a)', () => { + test('a hero sized in vh blocks, by the hero word or by the class of the section holding the h1', async () => { + const html = page('.hero { min-height: 100vh; }\n.intro { height: 80vh; }', '

    Two days to close

    \n

    More

    '); + const f = await lintPage(html); + expect(hits(f, 'vh-height')).toEqual([['blocks', lineOf(html, '100vh')], ['blocks', lineOf(html, '80vh')]]); + }); + test('svh and dvh pass, and vh on a non-hero rule is not this rule', async () => { + const html = page('.hero { min-height: 100svh; }\n.sheet { height: 100dvh; }\n.band { min-height: 40vh; }', '

    Two days to close

    \n
    '); + none(await lintPage(html), 'vh-height'); + }); +}); + +describe('design-lint structure: raw-spacing (gate 24a)', () => { + test('a raw length that matches a --space-* token blocks with that token as the fix; past eight in one file the rest fold into one line', async () => { + const rules = Array.from({ length: 10 }, (_, i) => `.r${i} { padding: 32px; }`).join('\n'); + const html = page(':root { --space-4: 2rem; --space-2: 1rem; }\n.box { margin: 0 1rem; }\n' + rules, '
    x
    '); + const f = only(await lintPage(html), 'raw-spacing'); + expect(f.find((x) => x.line === lineOf(html, 'margin: 0 1rem'))).toMatchObject({ grade: 'blocks', evidence: 'margin: 0 1rem on .box where --space-2 exists', fix: 'var(--space-2)' }); + expect(f).toHaveLength(9); + expect(f.filter((x) => x.line === 1).map((x) => x.evidence)).toEqual(['3 more raw spacing lengths in this file have a matching --space-* token']); + }); + test('tokens in use, a length no token matches, and a page with no spacing tokens are all clean', async () => { + const withTokens = page(':root { --space-4: 2rem; }\n.box { padding: var(--space-4); margin: 0 36px; }', '
    x
    '); + none(await lintPage(withTokens), 'raw-spacing'); + const noTokens = page('.box { padding: 32px; }', '
    x
    '); + none(await lintPage(noTokens), 'raw-spacing'); + }); +}); + +describe('design-lint structure: off-scale-spacing (gate 24b)', () => { + test('a px spacing off the 4px scale reports at ask', async () => { + const html = page('.nav { padding: 17px; }\n.gap { gap: 10px 8px; }', ''); + const f = await lintPage(html); + expect(hits(f, 'off-scale-spacing')).toEqual([['ask', lineOf(html, '17px')], ['ask', lineOf(html, '10px 8px')]]); + expect(only(f, 'off-scale-spacing')[0].evidence).toBe('padding: 17px on .nav is off the 4px scale'); + }); + test('multiples of four, 1px and 2px nudges, and rem values are on the scale', async () => { + const html = page('.nav { padding: 16px 2px; margin: 1px 0 1.25rem; gap: 24px; }', ''); + none(await lintPage(html), 'off-scale-spacing'); + }); +}); + +describe('design-lint structure: overflow-x-unclipped (gate 34, static half)', () => { + test('overflow-x: hidden, a 100vw width, clip on one of html and body, and no clip at all each report at ask', async () => { + const hidden = page('html { overflow-x: hidden; }\n.full { width: 100vw; }', '
    x
    ', { clip: false }); + const f = await lintPage(hidden); + expect(hits(f, 'overflow-x-unclipped')).toEqual([['ask', lineOf(hidden, 'overflow-x: hidden')], ['ask', lineOf(hidden, '100vw')]]); + expect(only(f, 'overflow-x-unclipped').map((x) => x.evidence)).toEqual(['overflow-x: hidden on html: hidden breaks position: sticky', 'width: 100vw on .full: 100vw counts the scrollbar and overflows']); + const one = page('html { overflow-x: clip; }', '

    x

    ', { clip: false }); + expect(only(await lintPage(one), 'overflow-x-unclipped').map((x) => [x.line, x.evidence])).toEqual([[1, 'overflow-x: clip on html only']]); + const neither = page('', '

    x

    ', { clip: false }); + expect(only(await lintPage(neither), 'overflow-x-unclipped').map((x) => [x.line, x.evidence])).toEqual([[1, 'no overflow-x: clip on html and body']]); + }); + test('overflow-x: clip on both html and body with width: 100% is clean', async () => { + const html = page('.full { width: 100%; }', '
    x
    '); + none(await lintPage(html), 'overflow-x-unclipped'); + }); +}); + +describe('design-lint structure: wide-container (gate 44d, static half)', () => { + const grid = '.grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); }\n@media (min-width: 1600px) { .grid { grid-template-columns: repeat(4, minmax(0, 1fr)); } }\n.hero__visual { width: 60vw; }'; + const body = '

    Two days to close

    \n
    • a
    • b
    • c
    '; + test('with no capped container, a grid that gains a column past 1440px and a vw-sized visual with no cap block', async () => { + const html = page(grid, body); + const f = await lintPage(html); + expect(hits(f, 'wide-container')).toEqual([['blocks', lineOf(html, 'repeat(4')], ['blocks', lineOf(html, '60vw')]]); + expect(only(f, 'wide-container').map((x) => x.evidence)).toEqual([ + 'no container has a max-width, and .grid gains columns at (min-width: 1600px) (3 to 4)', + 'no container has a max-width, and .hero__visual is sized in vw with no cap (width: 60vw)', + ]); + }); + test('a centred max-width container, a clamp() on the visual, or a column count that holds are clean', async () => { + none(await lintPage(page('.wrap { max-width: 1360px; margin: 0 auto; }\n' + grid, '
    ' + body + '
    ')), 'wide-container'); + const held = page('.grid { grid-template-columns: repeat(3, minmax(0, 1fr)); }\n@media (min-width: 1600px) { .grid { gap: 2rem; grid-template-columns: repeat(3, minmax(0, 1fr)); } }\n.hero__visual { width: clamp(320px, 40vw, 720px); }', body); + none(await lintPage(held), 'wide-container'); + }); +}); + +describe('design-lint structure: bare-fr-track (gate 50)', () => { + test('a bare 1fr grid track whose grid holds images blocks', async () => { + const html = page('.gallery { display: grid; grid-template-columns: 1fr 1fr; }', ''); + const f = await lintPage(html); + expect(hits(f, 'bare-fr-track')).toEqual([['blocks', lineOf(html, '1fr 1fr')]]); + expect(only(f, 'bare-fr-track')[0].evidence).toMatch(/^a bare 1fr track holds images on \.gallery/); + }); + test('minmax(0, 1fr) tracks with images, and bare 1fr tracks holding only text, are clean', async () => { + none(await lintPage(page('.gallery { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); }', '')), 'bare-fr-track'); + none(await lintPage(page('.cols { display: grid; grid-template-columns: 1fr 2fr; }', '

    Left

    Right

    ')), 'bare-fr-track'); + }); +}); + +describe('design-lint structure: display-head-unwrapped (gate 50)', () => { + test('a display head holding a word of 16 letters or more, with no overflow-wrap anywhere that reaches it, blocks', async () => { + const html = page('h1 { font-family: var(--font-display); }', '
    \n

    Hyperproductivity for every crew

    \n
    '); + const f = await lintPage(html); + expect(hits(f, 'display-head-unwrapped')).toEqual([['blocks', lineOf(html, '

    ')]]); + expect(only(f, 'display-head-unwrapped')[0].evidence).toBe('the display head holds "Hyperproductivity" with no overflow-wrap: at 320px that word overflows'); + }); + test('overflow-wrap: break-word on the heading, or a short-word heading, is clean', async () => { + none(await lintPage(page('h1 { overflow-wrap: break-word; min-width: 0; }', '

    Hyperproductivity for every crew

    ')), 'display-head-unwrapped'); + none(await lintPage(page('', '

    Two days to close the books

    ')), 'display-head-unwrapped'); + }); +}); + +describe('design-lint structure: radio-tab-jump (gate 53)', () => { + const tabs = '
    '; + test('radio tabs parked at position: absolute; top: 0 with no preventScroll in a script block', async () => { + const html = page('.tabs input[type="radio"] { position: absolute; top: 0; opacity: 0; }', tabs); + const f = await lintPage(html); + expect(hits(f, 'radio-tab-jump')).toEqual([['blocks', lineOf(html, 'position: absolute; top: 0')]]); + }); + test('radios kept in flow at zero size, or a focus handler with preventScroll, are clean', async () => { + none(await lintPage(page('.tabs input[type="radio"] { position: absolute; width: 0; height: 0; opacity: 0; }', tabs)), 'radio-tab-jump'); + none(await lintPage(page('.tabs input[type="radio"] { position: absolute; top: 0; opacity: 0; }', tabs + '\n')), 'radio-tab-jump'); + }); +}); + +describe('design-lint structure: double-sticky (gate 56)', () => { + test('two elements sticking at top: 0 block at the second', async () => { + const html = page('.nav { position: sticky; top: 0; }\n.subnav { position: sticky; top: 0px; }', ''); + const f = await lintPage(html); + expect(hits(f, 'double-sticky')).toEqual([['blocks', lineOf(html, '.subnav')]]); + expect(only(f, 'double-sticky')[0].evidence).toBe('two elements stick at top: 0 (.nav and .subnav): the second slides under the first'); + }); + test('the second sticky offset by the banner height is clean', async () => { + const html = page(':root { --banner-height: 64px; }\n.nav { position: sticky; top: 0; }\n.subnav { position: sticky; top: var(--banner-height); }', ''); + none(await lintPage(html), 'double-sticky'); + }); +}); + +describe('design-lint structure: screen-word-budget (gate 58, static half)', () => { + test('an h1 past seven words, a hero paragraph past twelve, and a full page past 450 visible words report at ask', async () => { + const html = page('', '
    \n

    A very long headline that keeps on going and going

    \n

    Halvorsen Freight reconciles 1,140 invoices a month and their books now close before the third.

    \n
    '); + const f = await lintPage(html); + expect(hits(f, 'screen-word-budget')).toEqual([['ask', lineOf(html, '

    ')], ['ask', lineOf(html, '

    Halvorsen')]]); + expect(only(f, 'screen-word-budget').map((x) => x.evidence)).toEqual(['the h1 runs 10 words ("A very long headline that keeps on goin…")', 'the hero paragraph runs 15 words']); + const words = Array.from({ length: 460 }, (_, i) => 'word' + i).join(' '); + const long = page('', `

    Short head

    \n

    ${words}

    \n
    End
    `); + expect(only(await lintPage(long), 'screen-word-budget').map((x) => [x.line, x.evidence])).toEqual([[1, '464 visible words on the page (450 at most)']]); + }); + test('seven words of h1, twelve of lede, and a page under 450 words are within the budget', async () => { + const html = page('', '
    \n

    October closed in two days, not nine

    \n

    1,140 invoices a month, and the books now close before the third.

    \n
    \n
    End
    '); + none(await lintPage(html), 'screen-word-budget'); + }); +}); + +describe('design-lint structure: the shared fixtures', () => { + test('slopped.html trips the planted structure tells at their lines', async () => { + const f = (await lint([path.join(FIXTURES, 'slopped.html')], { cwd: ROOT, warn: (l: string) => { throw new Error(l); } })).findings; + const mine = f.filter((x) => FAMILY.includes(x.rule)).map((x) => [x.rule, x.grade, x.line]); + expect(mine).toEqual([ + ['bare-fr-track', 'blocks', 93], + ['display-head-unwrapped', 'blocks', 112], + ['double-sticky', 'blocks', 59], + ['nested-cards', 'blocks', 128], + ['off-scale-spacing', 'ask', 57], + ['overflow-x-unclipped', 'ask', 47], + ]); + }); + test('the clean page raises no structure finding', async () => { + const f = (await lint([path.join(FIXTURES, 'clean')], { cwd: ROOT, warn: (l: string) => { throw new Error(l); } })).findings; + expect(f.filter((x) => FAMILY.includes(x.rule)).map(formatFinding)).toEqual([]); + }); +}); + +describe('design-lint structure: third review cycle', () => { + test('sibling cards in a list whose end tags are left out are not nested cards', async () => { + const f = await lintPage(page('', '
    • One
    • Two
    ')); + none(f, 'nested-cards'); + const nested = await lintPage(page('', '
    • One
      Inner
    ')); + expect(hits(nested, 'nested-cards').map(([g]) => g)).toEqual(['blocks']); + }); + test('one selector sticky at two breakpoints is not a double sticky; two selectors are', async () => { + none(await lintPage(page('.site-header { position: sticky; top: 0; }\n@media (min-width: 900px) { .site-header { position: sticky; top: 0; padding: 16px; } }', '')), 'double-sticky'); + const two = await lintPage(page('.site-header { position: sticky; top: 0; }\n.toolbar { position: sticky; top: 0; }', '
    T
    ')); + expect(hits(two, 'double-sticky').map(([g]) => g)).toEqual(['blocks']); + }); + test('a light grey side border on a blockquote is not the accent stripe; a dark ink stripe and a coloured one are', async () => { + none(await lintPage(page('blockquote { border-left: 4px solid #dddddd; }', '
    A line
    ')), 'template-cards'); + expect(hits(await lintPage(page('.note { border-left: 4px solid var(--color-ink); }', '

    A note

    ')), 'template-cards').map(([g]) => g)).toEqual(['ask']); + expect(hits(await lintPage(page('.note { border-left: 4px solid oklch(60% 0.18 30); }', '

    A note

    ')), 'template-cards').map(([g]) => g)).toEqual(['ask']); + }); + test('many grid rules with a bare fr track do not rescan the document per rule', async () => { + let css = ''; + let body = ''; + for (let i = 0; i < 1500; i++) { + css += `.c${i} { grid-template-columns: 1fr 2fr; }\n`; + body += `

    Heading ${i}

    Text.

    Photo ${i}
    `; + } + const t = performance.now(); + const f = await lintPage(page(css, body)); + expect(performance.now() - t).toBeLessThan(8000); + expect(hits(f, 'bare-fr-track').length).toBe(1500); + }); +}); diff --git a/test/design-lint-tailwind.test.ts b/test/design-lint-tailwind.test.ts new file mode 100644 index 000000000..0881b276c --- /dev/null +++ b/test/design-lint-tailwind.test.ts @@ -0,0 +1,371 @@ +/** + * The component family of the design lint: the Tailwind reader (class + * strings in HTML, JSX, Vue, Svelte and Astro, helper calls, shared tokens) + * and the rules it feeds, each with a negative control and a planted tell. + */ +import { afterAll, describe, expect, test } from 'bun:test'; +import * as fs from 'node:fs'; +import * as os from 'node:os'; +import * as path from 'node:path'; +import { lint, formatFinding, type Finding } from '../lib/design-lint/index'; +import { lintStatic } from '../lib/design-lint/static'; +import { twGroup, twParse, twVariants } from '../lib/design-lint/tailwind'; + +const tmpDirs: string[] = []; +afterAll(() => { for (const d of tmpDirs) fs.rmSync(d, { recursive: true, force: true }); }); + +const ROOT = path.resolve(import.meta.dir, '..'); +const FIXTURES = path.join(ROOT, 'test', 'fixtures', 'design-lint'); + +const MY_RULES = ['layout-transition', 'bounce-easing', 'purple-blue-gradient', 'gradient-text', 'glow-wash', 'literal-outside-tokens', 'hover-tells', 'wide-tracking', 'kicker-above-heading', 'monospace-costume', 'framework-palette', 'vh-height', 'template-cards', 'template-punctuation', 'emoji-decoration']; + +function tmpDir(files: Record): string { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'design-lint-tw-')); + tmpDirs.push(dir); + for (const [name, text] of Object.entries(files)) { + fs.mkdirSync(path.dirname(path.join(dir, name)), { recursive: true }); + fs.writeFileSync(path.join(dir, name), text); + } + return dir; +} + +async function lintFiles(files: Record, opts: { scope?: 'page' | 'component' } = {}): Promise { + const dir = tmpDir(files); + const result = await lint([dir], { cwd: dir, warn: (l: string) => { throw new Error(l); }, ...opts }); + return result.findings; +} + +const only = (findings: Finding[], rule: string) => findings.filter((f) => f.rule === rule); +const lines = (findings: Finding[], rule: string) => only(findings, rule).map((f) => f.line); +const mine = (findings: Finding[]) => findings.filter((f) => MY_RULES.includes(f.rule)).map(formatFinding); + +/** A page whose body line i (0-based) sits on line 5 + i. */ +const page = (body: string[], head = ''): string => ['', '', `Fieldnote${head}`, '', ...body, ''].join('\n'); +const BODY = 5; + +describe('design-lint tailwind: the reader', () => { + test('twParse splits variants, drops group-/peer- and /names, and reads the ! and - marks', () => { + expect(twParse('md:hover:bg-accent')).toEqual({ variants: ['md', 'hover'], base: 'bg-accent', neg: false }); + expect(twParse('group-hover/card:-translate-y-1')).toEqual({ variants: ['hover'], base: 'translate-y-1', neg: true }); + expect(twParse('!text-[length:var(--x)]')).toEqual({ variants: [], base: 'text-[length:var(--x)]', neg: false }); + expect(twParse('[&:nth-child(2)]:pt-0').variants).toEqual(['[&:nth-child(2)]']); + }); + + test('class strings are read from class, className, :class, class:list, class: directives and cn()/clsx()/cva() calls; variants are collected', async () => { + const dir = tmpDir({ + 'package.json': '{}', + 'Hero.tsx': [ + 'import { cva } from "cva";', + 'import { cn } from "./cn";', + 'const badge = cva("rounded-full text-xs uppercase tracking-widest");', + 'export function Hero({ on }: { on: boolean }) {', + ' const row = clsx("flex", on && "transition-all");', + ' return Go;', + '}', + ].join('\n'), + 'Card.vue': '', + 'Band.astro': '---\nconst x = 1;\n---\n
    \n

    Hi

    ', + }); + const { contexts } = lintStatic([dir], { cwd: dir, warn: (l: string) => { throw new Error(l); } }); + const ctx = contexts.find((c) => c.docs.length === 3)!; + const tw = twGroup(ctx); + const by = (tag: string) => tw.items.filter((i) => i.tag === tag).map((i) => i.info.classes.join(' ')); + expect(by('cva')).toEqual(['rounded-full text-xs uppercase tracking-widest']); + expect(by('clsx')).toEqual(['flex transition-all']); + expect(by('a')).toEqual(['px-3 hover:bg-accent focus-visible:outline-2']); + expect(by('div')).toEqual(['bg-paper disabled:opacity-50 active', 'motion-reduce:transition-none p-4']); + expect(by('p')).toEqual(['mt-2 text-sm tracking-wide']); + expect([...twVariants(ctx)].sort()).toEqual(['disabled', 'focus-visible', 'hover', 'motion-reduce']); + }); + + test('a component directory borrows the project tokens from a sibling globals.css @theme block', async () => { + const dir = tmpDir({ + 'package.json': '{}', + 'app/globals.css': '@import "tailwindcss";\n@theme {\n --color-paper: oklch(97% 0.01 80);\n --color-accent: oklch(55% 0.2 300);\n --text-label: 0.75rem;\n --tracking-label: 0.1em;\n}\n.btn:focus-visible { outline: 2px solid var(--color-accent); }', + 'components/Label.tsx': [ + 'export function Label() {', + ' return Field kit;', + '}', + 'export function Band() {', + ' return