mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-11 21:57:14 +03:00
Track the rule registry as a generated artifact (#728)
* Track the rule registry as a generated artifact `cargo xtask bundle` already wrote the registry to `dist/antipatterns.json` and into `extension/detector/`, but neither is tracked, so a consumer reading this repo from a source checkout or a tarball had no way to get the rule list without a Rust toolchain. The Rust swap made that concrete: impeccable.style imported `cli/engine/registry/antipatterns.mjs` for its rule count and its Slop catalog, and that file is gone. Write the same JSON to `crates/live/assets/antipatterns.json`, next to the in-page bundle and tracked like it, and extend `cargo xtask bundle --check` to fail when either asset is stale. The build's rule-count check now reads the tracked copy first and falls back to the extension copy, so a fresh checkout validates counts instead of skipping the check. Co-Authored-By: Claude Code <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Vau2X53xGTjjTCXWMVBoNY * Registry: wire the staleness gate into CI, harden the count read Two review findings on the tracked-registry change. `cargo xtask bundle --check` was never run by CI, so a rule whose name, category, or description changed without changing the rule count could ship a stale `crates/live/assets/antipatterns.json`. The extension job already runs `bun run build:extension` (and so `cargo xtask bundle`) and then asserts a clean tree; adding that file to the path list covers it with the gate that is already there. The bundle beside it stays out: its bytes carry a wasm module built by whatever wasm-pack and wasm-opt the runner installed, so diffing it would fail on toolchain drift rather than on a real change. `readDetectionRuleCount` counted `new Set(rules.map(r => r.id))`, so a shape change would collapse to a set of one `undefined` and read as a one-rule registry, flagging every count claim as stale. Count only non-empty string ids, and say "no readable antipatterns.json" when the file is present but unparseable. Co-Authored-By: Claude Code <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Vau2X53xGTjjTCXWMVBoNY * Registry gate: make the trigger honest, name the real count condition The tracked-registry diff check ran on every PR, but the step that regenerates the registry (`bun run build:extension`, which is `cargo xtask bundle`) only runs when the detector trigger fires, and that trigger did not list `crates/bundle`. A PR that changed how the registry is serialized therefore never rebuilt it, and the check compared the committed file against an untouched tree and passed on stale bytes. Two changes. The detector trigger now covers every input the bundle reads: `crates/(bundle|core|foundation|wasm|xtask)/` plus `crates/live/assets/` so a hand-edit of a tracked artifact is regenerated over. And the registry check moved into its own step carrying the same condition as the build it validates, so it no longer claims to check something that was never regenerated; the provider-output check stays unconditional, because `bun run build` runs on every PR. Separately, `readDetectionRuleCount` returns the reason it found no count. "no antipatterns.json" covered three different conditions, and a registry that is present but unparseable sends anyone debugging a count failure to the wrong place. It now reports the paths it looked at, or names the file that is not readable as JSON, or names the file that carries no rule ids. Co-Authored-By: Claude Code <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Vau2X53xGTjjTCXWMVBoNY --------- Co-authored-by: Claude Code <noreply@anthropic.com>
This commit is contained in:
Paul Bakaus
co-authored by
Claude Code
Claude Code
parent
3d17a8e40f
commit
87d8f6d686
@@ -120,7 +120,21 @@ jobs:
|
||||
# errors here.
|
||||
run: npx --yes web-ext@10 lint --source-dir dist/extension-firefox
|
||||
|
||||
# Only meaningful right after the bundle was rebuilt, so it carries the
|
||||
# same condition as that step rather than running unconditionally and
|
||||
# comparing a committed artifact against an untouched tree. Every input
|
||||
# `cargo xtask bundle` reads is in the detector trigger
|
||||
# (scripts/test-suites.mjs), so a change to the registry rows or to how
|
||||
# they are serialized lands here. The in-page bundle beside it is
|
||||
# deliberately not checked: its bytes carry a wasm module built by
|
||||
# whatever wasm-pack and wasm-opt the runner installed, so diffing it
|
||||
# would fail on toolchain drift rather than on a real change.
|
||||
- name: Verify the tracked rule registry is current
|
||||
if: needs.changes.outputs.detector == 'true'
|
||||
run: git diff --exit-code -- crates/live/assets/antipatterns.json
|
||||
|
||||
- name: Verify generated tracked outputs
|
||||
# What `bun run build` writes, which runs on every PR.
|
||||
# extension/detector/ is gitignored (built by `cargo xtask bundle`);
|
||||
# it stays listed so a stray tracked copy shows up here.
|
||||
run: git diff --exit-code -- .agents .claude .cursor .gemini .github/skills plugin extension/detector
|
||||
|
||||
@@ -53,7 +53,7 @@ Other area-to-suite obligations (the canonical mapping is the `triggers` lists i
|
||||
|
||||
## Anti-pattern detection rules
|
||||
|
||||
The rule engine lives in the engine repo, not here. What this repo owns is the behavior contract: `docs/CLI-CONTRACT.md` describes every verb, `tests/oracle/` holds the recorded goldens and replays them against the binary (`tests/oracle.test.mjs`), and `tests/fixtures/antipatterns/*.html` are the fixtures those goldens scan. A rule change lands in the engine, then here as a new oracle case (`node tests/oracle/record.mjs --bin <prefix>`, golden reviewed by hand) and, when it introduces new design guidance, an edit to `skill/SKILL.src.md` or `skill/reference/*.md`. Rule counts quoted in `README.md` and `README.npm.md` are checked by the build against `extension/detector/antipatterns.json` when that vendored file is present.
|
||||
The rule engine lives in the engine repo, not here. What this repo owns is the behavior contract: `docs/CLI-CONTRACT.md` describes every verb, `tests/oracle/` holds the recorded goldens and replays them against the binary (`tests/oracle.test.mjs`), and `tests/fixtures/antipatterns/*.html` are the fixtures those goldens scan. A rule change lands in the engine, then here as a new oracle case (`node tests/oracle/record.mjs --bin <prefix>`, golden reviewed by hand) and, when it introduces new design guidance, an edit to `skill/SKILL.src.md` or `skill/reference/*.md`. Rule counts quoted in `README.md` and `README.npm.md` are checked by the build against `crates/live/assets/antipatterns.json`, the tracked registry `cargo xtask bundle` writes (it falls back to the gitignored `extension/detector/antipatterns.json`).
|
||||
|
||||
## Commit & Pull Request Guidelines
|
||||
|
||||
|
||||
@@ -353,10 +353,11 @@ The rule logic lives in `crates/core`: every check, the browser rule adapters ov
|
||||
| `tests/oracle/golden/*` | Recorded from the binary with `node tests/oracle/record.mjs --bin detect-`, reviewed by hand |
|
||||
| `tests/oracle/vectors/calls/` | Frozen function-level vectors; replayed by `crates/core/tests/vectors.rs` through `impeccable_core::vectors::call` |
|
||||
| `crates/live/assets/detect-antipatterns-browser.js` | The in-page bundle, a tracked generated file. `cargo xtask bundle` rewrites it; the binary embeds it and serves it as `/detect.js` |
|
||||
| `extension/detector/` | The five generated pieces (`core.js`, `core_bg.wasm`, `snapshot.js`, `overlay.js`, `antipatterns.json`) written by `cargo xtask bundle`, which `bun run build:extension` runs. Gitignored, never tracked; the build's rule-count check reads `antipatterns.json` when present |
|
||||
| `crates/live/assets/antipatterns.json` | The registry as `[{ id, name, category, description }]`, the second tracked generated file. Same writer and the same `cargo xtask bundle --check` staleness gate. It exists because `extension/detector/` is gitignored: this is how a consumer without a Rust toolchain (impeccable.style, working from a tarball of this repo) reads the rule list. Adding or renaming a rule means committing this file too |
|
||||
| `extension/detector/` | The five generated pieces (`core.js`, `core_bg.wasm`, `snapshot.js`, `overlay.js`, `antipatterns.json`) written by `cargo xtask bundle`, which `bun run build:extension` runs. Gitignored, never tracked |
|
||||
| `skill/SKILL.src.md` and `reference/*.md` | Hand-edited if the rule introduces new design guidance |
|
||||
|
||||
Order for a new rule: fixture here first, registry row in `crates/foundation/src/registry.rs`, the check in `crates/core` against that fixture, oracle case + golden, `cargo xtask bundle` to refresh the tracked live asset, then `bun run build && bun run test` with a binary present. Rule counts quoted in `README.md` / `README.npm.md` are validated by `generateCounts` against the vendored registry.
|
||||
Order for a new rule: fixture here first, registry row in `crates/foundation/src/registry.rs`, the check in `crates/core` against that fixture, oracle case + golden, `cargo xtask bundle` to refresh the two tracked live assets, then `bun run build && bun run test` with a binary present. Rule counts quoted in `README.md` / `README.npm.md` are validated by `generateCounts` against `crates/live/assets/antipatterns.json`.
|
||||
|
||||
### Rule packs (downstream crates adding rules)
|
||||
|
||||
|
||||
@@ -1,16 +1,26 @@
|
||||
# Live browser assets
|
||||
|
||||
Two generated files, both tracked, both rewritten by `cargo xtask bundle`.
|
||||
Do not hand-edit either one.
|
||||
|
||||
`detect-antipatterns-browser.js` is the in-page detector bundle: the rule
|
||||
core (`crates/core`) compiled to WebAssembly by `crates/wasm`, concatenated
|
||||
with the page JS in `browser-bundle/` and the module embedded as base64.
|
||||
`crates/live/src/browser_assets.rs` embeds it with `include_str!` and the
|
||||
live server hands it to the browser as `/detect.js`, so the binary has to
|
||||
carry it.
|
||||
|
||||
It is **generated, and tracked**: `crates/live/src/browser_assets.rs` embeds
|
||||
it with `include_str!` and the live server hands it to the browser as
|
||||
`/detect.js`, so the binary has to carry it. Do not hand-edit. Rebuild with:
|
||||
`antipatterns.json` is the rule registry (`crates/foundation/src/registry.rs`)
|
||||
as `[{ id, name, category, description }]`, the same slice
|
||||
`cargo xtask bundle` vendors into the extension's `extension/detector/`. It
|
||||
is tracked because `extension/detector/` is not: a consumer working from a
|
||||
source checkout or a repo tarball (impeccable.style counts and renders the
|
||||
rules from it) has no other way to read the registry without a Rust
|
||||
toolchain.
|
||||
|
||||
```bash
|
||||
cargo xtask bundle # rewrites this file (and extension/detector/)
|
||||
cargo xtask bundle --check # fails when this file is stale
|
||||
cargo xtask bundle # rewrites both (and extension/detector/)
|
||||
cargo xtask bundle --check # fails when either is stale
|
||||
```
|
||||
|
||||
The other browser scripts the live server serves (`live-browser*.js`,
|
||||
|
||||
@@ -0,0 +1,368 @@
|
||||
[
|
||||
{
|
||||
"id": "side-tab",
|
||||
"name": "Side-tab accent border",
|
||||
"category": "slop",
|
||||
"description": "Thick colored border on one side of a card — the most recognizable tell of AI-generated UIs. Use a subtler accent or remove it entirely."
|
||||
},
|
||||
{
|
||||
"id": "border-accent-on-rounded",
|
||||
"name": "Border accent on rounded element",
|
||||
"category": "slop",
|
||||
"description": "Thick accent border on a rounded card — the border clashes with the rounded corners. Remove the border or the border-radius."
|
||||
},
|
||||
{
|
||||
"id": "overused-font",
|
||||
"name": "Overused font",
|
||||
"category": "slop",
|
||||
"description": "Inter, Roboto, Fraunces, Geist, Plus Jakarta Sans, and Space Grotesk are used on so many sites they no longer feel distinctive. Each new wave of AI-generated UIs converges on the same handful of faces. Choose a face that gives your interface personality."
|
||||
},
|
||||
{
|
||||
"id": "flat-type-hierarchy",
|
||||
"name": "Flat type hierarchy",
|
||||
"category": "slop",
|
||||
"description": "Dominant heading and body roles are separated by less than 1.25× at every step, leaving the size hierarchy flat. Add at least one stronger size step."
|
||||
},
|
||||
{
|
||||
"id": "gradient-text",
|
||||
"name": "Gradient text",
|
||||
"category": "slop",
|
||||
"description": "Gradient text is decorative rather than meaningful — a common AI tell, especially on headings and metrics. Use solid colors for text."
|
||||
},
|
||||
{
|
||||
"id": "ai-color-palette",
|
||||
"name": "AI color palette",
|
||||
"category": "slop",
|
||||
"description": "Purple/violet gradients and cyan-on-dark are the most recognizable tells of AI-generated UIs. Choose a distinctive, intentional palette."
|
||||
},
|
||||
{
|
||||
"id": "cream-palette",
|
||||
"name": "Cream / beige palette",
|
||||
"category": "slop",
|
||||
"description": "A warm cream or beige page background has become the default \"tasteful\" AI surface, reached for by reflex. Choose a background that comes from a deliberate palette, not the safe warm off-white."
|
||||
},
|
||||
{
|
||||
"id": "nested-cards",
|
||||
"name": "Nested cards",
|
||||
"category": "slop",
|
||||
"description": "Cards inside cards create visual noise and excessive depth. Flatten the hierarchy — use spacing, typography, and dividers instead of nesting containers."
|
||||
},
|
||||
{
|
||||
"id": "monotonous-spacing",
|
||||
"name": "Monotonous spacing",
|
||||
"category": "slop",
|
||||
"description": "The same spacing value used everywhere — no rhythm, no variation. Use tight groupings for related items and generous separations between sections."
|
||||
},
|
||||
{
|
||||
"id": "bounce-easing",
|
||||
"name": "Bounce or elastic easing",
|
||||
"category": "slop",
|
||||
"description": "Bounce and elastic easing feel dated and tacky. Real objects decelerate smoothly — use exponential easing (ease-out-quart/quint/expo) instead."
|
||||
},
|
||||
{
|
||||
"id": "pulsing-dot",
|
||||
"name": "Pulsing status dot",
|
||||
"category": "slop",
|
||||
"description": "Small pulsing status dots simulate liveness decoratively. Reserve pulse animation for indicators tied to genuinely live, changing data; a static indicator with clear labeling is honest and calmer."
|
||||
},
|
||||
{
|
||||
"id": "blinking-cursor",
|
||||
"name": "Decorative blinking cursor",
|
||||
"category": "slop",
|
||||
"description": "A blinking text cursor animated into a hero or landing section simulates typing where no input exists. It borrows the dev-tool aesthetic as decoration. Real editable fields draw their own caret; anywhere else, let the composition hold attention without a fake prompt."
|
||||
},
|
||||
{
|
||||
"id": "shape-assembled-illustration",
|
||||
"name": "Shape-assembled illustration",
|
||||
"category": "slop",
|
||||
"description": "A large inline SVG that builds a pictorial scene from a pile of primitive shapes reads as placeholder clip art, not illustration. Icons, logos, and data graphics are fine at their scale; a hero-sized visual deserves real artwork, a photograph, or a deliberately drawn graphic."
|
||||
},
|
||||
{
|
||||
"id": "organic-clip-path",
|
||||
"name": "Organic contour drawn as clip-path",
|
||||
"category": "quality",
|
||||
"description": "A clip-path polygon with many arbitrary vertices, or a curved clip-path path(), is CSS approximating a torn edge, blob, or silhouette. It reads as the cheap version of the effect and is usually a produced or photographic material replaced with code. Derive an alpha matte from the real image, or ship the shape as a cut-out raster; keep clip-path for geometry (cut corners, diagonals, hexagons)."
|
||||
},
|
||||
{
|
||||
"id": "buried-raster",
|
||||
"name": "Raster buried under a wash or opacity",
|
||||
"category": "quality",
|
||||
"description": "A background image under a near-opaque gradient wash, or a raster on an element at near-zero opacity, never reaches the screen: the page shows the wash, and the produced texture or photo ships as a compliance token. Let the material show (a tint under 0.9 alpha, a blend mode, an opacity you can see) or remove the file."
|
||||
},
|
||||
{
|
||||
"id": "dark-glow",
|
||||
"name": "Glowing shadow accents",
|
||||
"category": "slop",
|
||||
"description": "Colored glow shadows — a zero-offset chromatic halo (box- or text-shadow) on any background, or any colored blurred shadow on a dark background — are the default \"cool\" look of AI-generated UIs. Use neutral elevation shadows and subtle, purposeful lighting instead."
|
||||
},
|
||||
{
|
||||
"id": "radial-halo",
|
||||
"name": "Radial-gradient background halo",
|
||||
"category": "slop",
|
||||
"description": "A chromatic radial-gradient wash — saturated at the center, fading to transparent — used as a decorative background glow on a dark page. Same tell as glowing shadows, drawn with a gradient instead of a shadow. Ground the surface with a solid or subtly shifted background instead."
|
||||
},
|
||||
{
|
||||
"id": "radial-spotlight-glow",
|
||||
"name": "Decorative radial spotlight glow",
|
||||
"category": "slop",
|
||||
"description": "A soft, low-opacity accent-colored radial gradient fading to transparent, dropped behind a hero or section as a \"spotlight.\" It is a reflex AI decoration — the translucent cousin of the saturated radial halo. Let the surface stand on its own, or light the composition with a deliberate material accent rather than a floating colored haze."
|
||||
},
|
||||
{
|
||||
"id": "marquee",
|
||||
"name": "Auto-scrolling marquee",
|
||||
"category": "slop",
|
||||
"description": "Continuously auto-scrolling content demands attention it has not earned and hides half its content at any moment. Reserve motion for content that changes; let readers move at their own pace."
|
||||
},
|
||||
{
|
||||
"id": "icon-tile-stack",
|
||||
"name": "Icon tile stacked above heading",
|
||||
"category": "slop",
|
||||
"description": "A small rounded-square icon container above a heading is the universal AI feature-card template — every generator outputs this exact shape. Try a side-by-side icon and heading, or let the icon sit in flow without its own container."
|
||||
},
|
||||
{
|
||||
"id": "italic-serif-display",
|
||||
"name": "Italic serif display headline",
|
||||
"category": "slop",
|
||||
"description": "Oversized italic serif (Fraunces, Recoleta, Playfair, Newsreader-italic) as the primary hero headline reads as taste in isolation but has become the universal AI-startup landing page hero. Set roman, or move to a non-serif display face. Editorial / magazine register may legitimately want this — judge by context."
|
||||
},
|
||||
{
|
||||
"id": "hero-eyebrow-chip",
|
||||
"name": "Hero eyebrow / pill chip",
|
||||
"category": "slop",
|
||||
"description": "A tiny uppercase letter-spaced label sitting immediately above an oversized hero headline — or the same shape rendered as a pill chip — is now the default AI SaaS hero. Drop the eyebrow, integrate the kicker into the headline, or run it as a navigation breadcrumb instead."
|
||||
},
|
||||
{
|
||||
"id": "kicker-above-heading",
|
||||
"name": "Kicker / eyebrow label above heading",
|
||||
"category": "slop",
|
||||
"description": "A tiny tracked uppercase or small-caps label sitting as its own block directly above a heading is banned outright, repeated or not. Generated kickers never earn their place: the heading carries its own weight. Delete the label and let the heading speak; if the words matter, work them into the heading or the body."
|
||||
},
|
||||
{
|
||||
"id": "numbered-section-labels",
|
||||
"name": "Tiny numbered section labels",
|
||||
"category": "slop",
|
||||
"description": "Small numeric index labels riding next to section headings, repeated section after section, are AI editorial scaffolding — a page numbering its own chapters instead of earning structure. Let hierarchy, content, and rhythm carry the sequence."
|
||||
},
|
||||
{
|
||||
"id": "em-dash-overuse",
|
||||
"name": "Em-dash overuse",
|
||||
"category": "slop",
|
||||
"description": "Em-dash saturation in body copy is an AI cadence tell. Advisory only: humans use em-dashes legitimately, so this fires only on saturation — at least 8 em-dashes (— or --) at a density near one per 500 characters of body text — never on a long article that uses a few. Prefer commas, colons, periods, or parentheses."
|
||||
},
|
||||
{
|
||||
"id": "marketing-buzzword",
|
||||
"name": "Marketing buzzword",
|
||||
"category": "slop",
|
||||
"description": "Generic SaaS phrases (streamline / empower / supercharge / world-class / enterprise-grade / next-generation / cutting-edge / etc) are instant AI tells. Pick a specific verb and noun that says what the product literally does."
|
||||
},
|
||||
{
|
||||
"id": "aphoristic-cadence",
|
||||
"name": "Aphoristic-cadence copy",
|
||||
"category": "slop",
|
||||
"description": "Three or more sections landing on a short rebuttal sentence (\"X. No Y.\" / \"X. Just Y.\") or a manufactured-contrast aphorism (\"Not a feature. A platform.\") reads as AI cadence, not voice. Once is fine; the pattern is the tell."
|
||||
},
|
||||
{
|
||||
"id": "oversized-h1",
|
||||
"name": "Oversized hero headline",
|
||||
"category": "slop",
|
||||
"description": "A full-sentence headline set at display size ends up dominating the viewport, leaving no room for anything else above the fold. A punchy one- or two-word headline at that size is fine — the problem is a long headline blown up too large. Set long headlines smaller, or tighten the copy."
|
||||
},
|
||||
{
|
||||
"id": "extreme-negative-tracking",
|
||||
"name": "Crushed letter spacing",
|
||||
"category": "slop",
|
||||
"description": "Letter-spacing pulled tighter than the point where characters keep their own shapes costs legibility. Tighten display type optically, not destructively."
|
||||
},
|
||||
{
|
||||
"id": "broken-image",
|
||||
"name": "Broken or placeholder image",
|
||||
"category": "quality",
|
||||
"description": "<img> tags with empty src, missing src, or placeholder values ship as broken-image boxes. Use real images, generated assets, or remove the tag."
|
||||
},
|
||||
{
|
||||
"id": "script-error",
|
||||
"name": "Uncaught script error on load",
|
||||
"category": "quality",
|
||||
"description": "A script threw an uncaught exception or failed to parse while the page loaded. Broken JavaScript silently kills reveals, interactions, and dynamic content, and can leave most of a page invisible. Fix the error before judging anything else."
|
||||
},
|
||||
{
|
||||
"id": "content-hidden-at-rest",
|
||||
"name": "Content invisible at rest",
|
||||
"category": "quality",
|
||||
"description": "A large share of the page text sits at opacity 0 or visibility hidden even after every reveal handler had a chance to run. This is the failed-reveal signature: the content shipped but never becomes visible. Make content visible by default and let JavaScript enhance its entrance instead of gating its existence."
|
||||
},
|
||||
{
|
||||
"id": "edge-flush-cards",
|
||||
"name": "Cards flush against the scroller edge",
|
||||
"category": "quality",
|
||||
"description": "Cards inside a horizontal scroller or tab panel sit flush against the container edge at rest while keeping a gutter on the other side, so their edges and rounded corners get cut off. Usually the panel is sized wider than its clip box. Keep a consistent inset on both sides."
|
||||
},
|
||||
{
|
||||
"id": "text-occlusion",
|
||||
"name": "Text occluded by an overlapping element",
|
||||
"category": "quality",
|
||||
"description": "Text is painted under an opaque element or a second text run, so part of it cannot be read. A decorative box, a stacked layer, or an inline element with leaked padding lands on the words instead of beside them. Give overlapping layers room, or move the text out from under the layer above it."
|
||||
},
|
||||
{
|
||||
"id": "first-viewport-column-overflow",
|
||||
"name": "One column stretches the first viewport",
|
||||
"category": "quality",
|
||||
"description": "A multi-column opening section lets one column run far past the fold while its sibling fits in a single viewport, so the short column floats in dead space and the fold falls deep inside one section. Balance the columns, cap the tall one, or let the long content flow below the opening row."
|
||||
},
|
||||
{
|
||||
"id": "gray-on-color",
|
||||
"name": "Gray text on colored background",
|
||||
"category": "quality",
|
||||
"description": "Gray text looks washed out on colored backgrounds. Use a darker shade of the background color instead, or white/near-white for contrast."
|
||||
},
|
||||
{
|
||||
"id": "low-contrast",
|
||||
"name": "Low contrast text",
|
||||
"category": "quality",
|
||||
"description": "Text does not meet WCAG AA contrast requirements (4.5:1 for body, 3:1 for large text). Increase the contrast between text and background."
|
||||
},
|
||||
{
|
||||
"id": "layout-transition",
|
||||
"name": "Layout property animation",
|
||||
"category": "quality",
|
||||
"description": "Animating width, height, padding, or margin causes layout thrash and janky performance. Use transform and opacity instead, or grid-template-rows for height animations."
|
||||
},
|
||||
{
|
||||
"id": "line-length",
|
||||
"name": "Line length too long",
|
||||
"category": "quality",
|
||||
"description": "Text lines wider than ~80 characters are hard to read. The eye loses its place tracking back to the start of the next line. Add a max-width (65ch to 75ch) to text containers."
|
||||
},
|
||||
{
|
||||
"id": "cramped-padding",
|
||||
"name": "Cramped padding",
|
||||
"category": "quality",
|
||||
"description": "Text is too close to the edge of its container. Two shapes: (1) an element with its own text where the padding is too low for the font size, and (2) a wrapper with text-bearing children and near-zero padding against a visible boundary (border, outline, or non-transparent background) — children land flush against the boundary line. Add at least 8px (ideally 12–16px) of padding inside bordered, outlined, or colored containers."
|
||||
},
|
||||
{
|
||||
"id": "body-text-viewport-edge",
|
||||
"name": "Body text touching viewport edge",
|
||||
"category": "quality",
|
||||
"description": "Body paragraphs render flush against the left or right viewport edge with no container providing horizontal padding. Wrap content in a container with at least 16px (ideally 24-32px) of horizontal padding, or apply max-width with mx-auto."
|
||||
},
|
||||
{
|
||||
"id": "tight-leading",
|
||||
"name": "Tight line height",
|
||||
"category": "quality",
|
||||
"description": "Line height below 1.3x the font size makes multi-line text hard to read. Use 1.5 to 1.7 for body text so lines have room to breathe."
|
||||
},
|
||||
{
|
||||
"id": "skipped-heading",
|
||||
"name": "Skipped heading level",
|
||||
"category": "quality",
|
||||
"description": "Heading levels should not skip (e.g. h1 then h3 with no h2). Screen readers use heading hierarchy for navigation. Skipping levels breaks the document outline."
|
||||
},
|
||||
{
|
||||
"id": "heading-rhythm",
|
||||
"name": "Heading crowded against the previous block",
|
||||
"category": "quality",
|
||||
"description": "A heading binds to the content it introduces, so the rendered space above it should exceed the space below it. When headings across a page sit as close or closer to the block above than to their own content, every section reads as if it captions the previous one. Open up the space above each heading."
|
||||
},
|
||||
{
|
||||
"id": "justified-text",
|
||||
"name": "Justified text",
|
||||
"category": "quality",
|
||||
"description": "Justified text without hyphenation creates uneven word spacing (\"rivers of white\"). Use text-align: left for body text, or enable hyphens: auto if you must justify."
|
||||
},
|
||||
{
|
||||
"id": "tiny-text",
|
||||
"name": "Tiny body text",
|
||||
"category": "quality",
|
||||
"description": "Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal."
|
||||
},
|
||||
{
|
||||
"id": "undersized-ui-text",
|
||||
"name": "Undersized functional text",
|
||||
"category": "quality",
|
||||
"description": "Interactive and content-bearing UI text (links, buttons, nav items, labels, table cells, meta rows, timecodes) below 11px is a legibility failure, not a style choice. WCAG sets no absolute pixel floor, but functional text under 11px is a defensible quality bar: it fails on high-DPI and small viewports and it degrades tap and read targets. The 11px floor holds even inside a footer; only non-interactive legal smallprint gets the softer 10px floor. Being ON the DESIGN.md size ramp does not exempt a value here: adding 8px to the ramp launders the token but not the legibility problem, and that is exactly the escape hatch this rule closes. Exempts sup/sub, visually-hidden (sr-only) text, and code/terminal contexts. Decorative letterspaced micro-labels are still functional and stay in scope."
|
||||
},
|
||||
{
|
||||
"id": "all-caps-body",
|
||||
"name": "All-caps body text",
|
||||
"category": "quality",
|
||||
"description": "Long passages in uppercase are hard to read. We recognize words by shape (ascenders and descenders), which all-caps removes. Reserve uppercase for short labels and headings."
|
||||
},
|
||||
{
|
||||
"id": "wide-tracking",
|
||||
"name": "Wide letter spacing on body text",
|
||||
"category": "quality",
|
||||
"description": "Letter spacing above 0.05em on body text disrupts natural character groupings and slows reading. Reserve wide tracking for short uppercase labels only."
|
||||
},
|
||||
{
|
||||
"id": "text-overflow",
|
||||
"name": "Content overflowing its container",
|
||||
"category": "quality",
|
||||
"description": "Content renders wider than its container, spilling out or forcing a horizontal scrollbar. Let text wrap, constrain widths, or give the region a deliberate scroll affordance."
|
||||
},
|
||||
{
|
||||
"id": "repeated-container-text",
|
||||
"name": "Same text repeated inside one container",
|
||||
"category": "quality",
|
||||
"description": "The same literal text rendered three or more times in structurally different spots inside a single card or panel is redundant messaging — usually a status or label wired into every slot of a template. Say it once, in the slot where it matters most."
|
||||
},
|
||||
{
|
||||
"id": "clipped-overflow-container",
|
||||
"name": "Positioned child clipped by overflow container",
|
||||
"category": "quality",
|
||||
"description": "A clipping container (overflow hidden or clip) wrapping an absolutely-positioned child cuts off tooltips, menus, and popovers that need to escape. Let the overflow be visible, or move the positioned layer out of the clip."
|
||||
},
|
||||
{
|
||||
"id": "design-system-font",
|
||||
"name": "Font outside DESIGN.md",
|
||||
"category": "quality",
|
||||
"description": "A font is used that is not declared in DESIGN.md typography. Use the documented type system or update DESIGN.md if this is an intentional brand addition."
|
||||
},
|
||||
{
|
||||
"id": "design-system-color",
|
||||
"name": "Color outside DESIGN.md",
|
||||
"category": "quality",
|
||||
"description": "A literal color is outside the DESIGN.md palette and sidecar tonal ramps. This may be legitimate, but it should be an intentional design-system addition rather than drift."
|
||||
},
|
||||
{
|
||||
"id": "design-system-radius",
|
||||
"name": "Radius outside DESIGN.md",
|
||||
"category": "quality",
|
||||
"description": "A border-radius value is outside the DESIGN.md rounded scale. Use a documented radius token or update the design system if the new shape is intentional."
|
||||
},
|
||||
{
|
||||
"id": "design-system-font-size",
|
||||
"name": "Font size outside DESIGN.md",
|
||||
"category": "quality",
|
||||
"description": "A literal font-size is off the type ramp documented in DESIGN.md typography. Use a documented size step or update the design system if the new step is intentional."
|
||||
},
|
||||
{
|
||||
"id": "gpt-thin-border-wide-shadow",
|
||||
"name": "Hairline border with wide shadow",
|
||||
"category": "slop",
|
||||
"description": "A hairline border paired with a wide, diffuse shadow is a recurring generated-UI signature. Commit to one — a defined edge or a soft elevation — rather than both at once."
|
||||
},
|
||||
{
|
||||
"id": "repeating-stripes-gradient",
|
||||
"name": "Repeating-gradient stripes",
|
||||
"category": "slop",
|
||||
"description": "Repeating-gradient stripes used as surface decoration are a recurring generated-UI signature. Reach for a deliberate texture or leave the surface plain."
|
||||
},
|
||||
{
|
||||
"id": "codex-grid-background",
|
||||
"name": "Decorative grid-line background",
|
||||
"category": "slop",
|
||||
"description": "A decorative grid or line-field background drawn with hairline linear-gradient layers tiled by a fixed pixel cell is a recurring generated-UI signature. Reserve grid overlays for actual canvas, map, blueprint, or measurement surfaces; elsewhere use product structure or a plain surface."
|
||||
},
|
||||
{
|
||||
"id": "theater-slop-phrase",
|
||||
"name": "Theater framing copy",
|
||||
"category": "slop",
|
||||
"description": "Dismissing something as \"theater\" is a recurring generated-copy tic. Say plainly what the thing does or does not do."
|
||||
},
|
||||
{
|
||||
"id": "image-hover-transform",
|
||||
"name": "Image hover transform",
|
||||
"category": "slop",
|
||||
"description": "Scaling or rotating an image on hover is a recurring generated-UI signature. Let imagery sit still, or use a subtler, purposeful interaction."
|
||||
}
|
||||
]
|
||||
+33
-15
@@ -12,9 +12,10 @@
|
||||
//! the .wasm embedded as base64;
|
||||
//! 3. writes `dist/detect-antipatterns-browser.js` (deterministic: same
|
||||
//! sources, same bytes) and `dist/antipatterns.json` (the registry
|
||||
//! slice the extension panel reads), and copies the bundle to
|
||||
//! `crates/live/assets/detect-antipatterns-browser.js`, the tracked
|
||||
//! generated file live mode embeds and serves as `/detect.js`;
|
||||
//! slice the extension panel reads), and copies both into
|
||||
//! `crates/live/assets/`, where they are tracked: live mode embeds the
|
||||
//! bundle and serves it as `/detect.js`, and `antipatterns.json` is the
|
||||
//! registry a downstream consumer reads out of a source checkout;
|
||||
//! 4. writes the extension pieces into `extension/detector/`:
|
||||
//! `snapshot.js` (content-script snapshot producer), `overlay.js`
|
||||
//! (content-script overlay UI), `core.js` + `core_bg.wasm`
|
||||
@@ -22,11 +23,11 @@
|
||||
//! gitignored and vendored by `bun run build:extension`, which runs
|
||||
//! this task.
|
||||
//!
|
||||
//! Run this after touching `crates/core`, `crates/wasm`, or
|
||||
//! `browser-bundle/`, and commit the refreshed live asset.
|
||||
//! Run this after touching `crates/core`, `crates/foundation`,
|
||||
//! `crates/wasm`, or `browser-bundle/`, and commit the refreshed assets.
|
||||
//!
|
||||
//! `cargo xtask bundle --check` rebuilds and fails when the tracked live
|
||||
//! asset differs (CI staleness gate).
|
||||
//! `cargo xtask bundle --check` rebuilds and fails when either tracked asset
|
||||
//! differs (CI staleness gate).
|
||||
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
@@ -74,23 +75,40 @@ fn bundle(check: bool, pure: bool) {
|
||||
let ext = impeccable_bundle::extension_pieces(&glue, &wasm, ®istry);
|
||||
|
||||
let dist = root.join("dist");
|
||||
// The one tracked generated file: live mode embeds it (include_str! in
|
||||
// crates/live/src/browser_assets.rs) and serves it as /detect.js.
|
||||
let live_asset = root.join("crates/live/assets/detect-antipatterns-browser.js");
|
||||
// The two tracked generated files. live mode embeds the bundle
|
||||
// (include_str! in crates/live/src/browser_assets.rs) and serves it as
|
||||
// /detect.js, so the binary has to carry it; antipatterns.json is the
|
||||
// registry slice downstream consumers read out of a source checkout
|
||||
// (impeccable.style counts and renders the rules from it).
|
||||
let assets = root.join("crates/live/assets");
|
||||
let tracked: [(PathBuf, &[u8]); 2] = [
|
||||
(assets.join("detect-antipatterns-browser.js"), out.as_bytes()),
|
||||
(assets.join("antipatterns.json"), registry.as_bytes()),
|
||||
];
|
||||
if check {
|
||||
if std::fs::read(&live_asset).unwrap_or_default() != out.as_bytes() {
|
||||
eprintln!("crates/live/assets/detect-antipatterns-browser.js is stale");
|
||||
let mut stale = false;
|
||||
for (path, want) in &tracked {
|
||||
let name = path.strip_prefix(&root).unwrap_or(path).display();
|
||||
if std::fs::read(path).unwrap_or_default() != *want {
|
||||
eprintln!("{name} is stale");
|
||||
stale = true;
|
||||
} else {
|
||||
println!("{name} is up to date");
|
||||
}
|
||||
}
|
||||
if stale {
|
||||
eprintln!("run `cargo xtask bundle` and commit crates/live/assets");
|
||||
std::process::exit(1);
|
||||
}
|
||||
println!("crates/live/assets/detect-antipatterns-browser.js is up to date");
|
||||
return;
|
||||
}
|
||||
std::fs::create_dir_all(&dist).expect("dist dir");
|
||||
std::fs::write(dist.join("detect-antipatterns-browser.js"), &out).expect("write bundle");
|
||||
std::fs::write(dist.join("antipatterns.json"), ®istry).expect("write registry");
|
||||
std::fs::create_dir_all(live_asset.parent().unwrap()).expect("live assets dir");
|
||||
std::fs::write(&live_asset, &out).expect("write live asset");
|
||||
std::fs::create_dir_all(&assets).expect("live assets dir");
|
||||
for (path, bytes) in &tracked {
|
||||
std::fs::write(path, bytes).expect("write tracked asset");
|
||||
}
|
||||
// extension/detector/: gitignored, vendored by `bun run build:extension`.
|
||||
let ext_dir = root.join("extension/detector");
|
||||
std::fs::create_dir_all(&ext_dir).expect("extension dir");
|
||||
|
||||
+10
-7
@@ -81,17 +81,20 @@ The same rules that run natively run in a page, compiled to WebAssembly.
|
||||
implements the `Dom` probe, marshals JSON, and draws the overlay; no rule
|
||||
logic lives there.
|
||||
3. Write `dist/detect-antipatterns-browser.js` and `dist/antipatterns.json`,
|
||||
and copy the bundle to
|
||||
**`crates/live/assets/detect-antipatterns-browser.js`**. That copy is a
|
||||
tracked generated file: `crates/live/src/browser_assets.rs` embeds it with
|
||||
and copy both into **`crates/live/assets/`**. Those two copies are tracked
|
||||
generated files. `crates/live/src/browser_assets.rs` embeds the bundle with
|
||||
`include_str!` and the live server hands it to the browser as `/detect.js`,
|
||||
so the binary has to carry it.
|
||||
so the binary has to carry it. `antipatterns.json` is the registry
|
||||
(`[{ id, name, category, description }]`) that a consumer working from a
|
||||
source checkout or a repo tarball reads without a Rust toolchain, since
|
||||
`extension/detector/` is gitignored; impeccable.style counts and renders
|
||||
the rules from it.
|
||||
4. Write the five extension pieces into `extension/detector/`
|
||||
(`snapshot.js`, `overlay.js`, `core.js`, `core_bg.wasm`,
|
||||
`antipatterns.json`). That directory is gitignored;
|
||||
`bun run build:extension` runs this task and then packages the zips.
|
||||
|
||||
`cargo xtask bundle --check` rebuilds and fails when the tracked live asset is
|
||||
`cargo xtask bundle --check` rebuilds and fails when either tracked asset is
|
||||
stale, which is the CI staleness gate. The build is deterministic: same
|
||||
sources, same bytes.
|
||||
|
||||
@@ -103,8 +106,8 @@ alone. `IMPECCABLE_EXTENSION_SKIP_BUNDLE=1` lets `bun run build:extension`
|
||||
skip the bundle step when `extension/detector/` is already complete, for CI
|
||||
matrices that pre-built it.
|
||||
|
||||
Run `cargo xtask bundle` after touching `crates/core`, `crates/wasm`, or
|
||||
`browser-bundle/`, and commit the refreshed live asset.
|
||||
Run `cargo xtask bundle` after touching `crates/core`, `crates/foundation`,
|
||||
`crates/wasm`, or `browser-bundle/`, and commit the refreshed assets.
|
||||
|
||||
### Reusing the bundler downstream
|
||||
|
||||
|
||||
+47
-14
@@ -61,12 +61,12 @@ function generateCounts(rootDir, skills, buildDir) {
|
||||
commandCount = activeCommands.length;
|
||||
}
|
||||
|
||||
// Count detection rules from the engine's rule registry as vendored by
|
||||
// build:extension (extension/detector/antipatterns.json). The registry
|
||||
// lives in the engine repo now, so when that file is absent (fresh
|
||||
// checkout, no extension build) the detection-count check is skipped
|
||||
// rather than guessed.
|
||||
const detectionCount = readDetectionRuleCount(rootDir);
|
||||
// Count detection rules from the rule registry as `cargo xtask bundle`
|
||||
// emits it. crates/live/assets/antipatterns.json is tracked, so a fresh
|
||||
// checkout has it; extension/detector/antipatterns.json is the gitignored
|
||||
// extension copy and only stands in for an older tree. With neither, the
|
||||
// detection-count check is skipped rather than guessed.
|
||||
const { count: detectionCount, reason: detectionReason } = readDetectionRuleCount(rootDir);
|
||||
|
||||
// Validate counts in key files
|
||||
const filesToCheck = [
|
||||
@@ -118,19 +118,52 @@ function generateCounts(rootDir, skills, buildDir) {
|
||||
console.error(`\n❌ ${errors} stale count reference(s) found. Update them to match source of truth.`);
|
||||
}
|
||||
|
||||
console.log(`✓ Generated counts: ${commandCount} commands, ${detectionCount == null ? 'detection rules unchecked (no extension/detector/antipatterns.json)' : `${detectionCount} detection rules`}`);
|
||||
console.log(`✓ Generated counts: ${commandCount} commands, ${detectionCount == null ? `detection rules unchecked: ${detectionReason}` : `${detectionCount} detection rules`}`);
|
||||
return errors;
|
||||
}
|
||||
|
||||
const RULE_REGISTRY_PATHS = [
|
||||
['crates', 'live', 'assets', 'antipatterns.json'],
|
||||
['extension', 'detector', 'antipatterns.json'],
|
||||
];
|
||||
|
||||
/**
|
||||
* The number of distinct rule ids in the registry, or `{ count: null, reason }`
|
||||
* when no location yields one. The reason names the actual condition and the
|
||||
* path it applies to: a registry that is present but unparseable reads very
|
||||
* differently from one that was never generated, and "no antipatterns.json"
|
||||
* for both sends anyone debugging a count failure to the wrong place.
|
||||
*/
|
||||
function readDetectionRuleCount(rootDir) {
|
||||
const registry = path.join(rootDir, 'extension', 'detector', 'antipatterns.json');
|
||||
if (!fs.existsSync(registry)) return null;
|
||||
try {
|
||||
const rules = JSON.parse(fs.readFileSync(registry, 'utf-8'));
|
||||
return new Set((Array.isArray(rules) ? rules : []).map(rule => rule.id)).size || null;
|
||||
} catch {
|
||||
return null;
|
||||
const problems = [];
|
||||
for (const parts of RULE_REGISTRY_PATHS) {
|
||||
const rel = parts.join('/');
|
||||
const registry = path.join(rootDir, ...parts);
|
||||
if (!fs.existsSync(registry)) continue;
|
||||
let rules;
|
||||
try {
|
||||
rules = JSON.parse(fs.readFileSync(registry, 'utf-8'));
|
||||
} catch (err) {
|
||||
problems.push(`${rel} is not readable as JSON (${err.message})`);
|
||||
continue;
|
||||
}
|
||||
// Only string ids count. A shape change (a wrapper object, a row without
|
||||
// an id) would otherwise collapse to a Set of one `undefined` and read as
|
||||
// a one-rule registry, which validates every count claim as stale.
|
||||
const ids = (Array.isArray(rules) ? rules : [])
|
||||
.map(rule => rule?.id)
|
||||
.filter(id => typeof id === 'string' && id.length > 0);
|
||||
if (ids.length === 0) {
|
||||
problems.push(`${rel} carries no rule ids`);
|
||||
continue;
|
||||
}
|
||||
return { count: new Set(ids).size };
|
||||
}
|
||||
const where = RULE_REGISTRY_PATHS.map(parts => parts.join('/')).join(' or ');
|
||||
return {
|
||||
count: null,
|
||||
reason: problems.length > 0 ? problems.join('; ') : `no antipatterns.json at ${where}`,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -106,7 +106,15 @@ export const SUITES = {
|
||||
/^extension\/(background|content|detector|devtools|offscreen|popup|manifest\.json)/,
|
||||
/^scripts\/build-extension\.js$/,
|
||||
/^browser-bundle\//,
|
||||
/^crates\/(core|foundation|wasm|xtask)\//,
|
||||
// Everything `cargo xtask bundle` reads: the rules and the registry
|
||||
// rows (core, foundation), the wasm module (wasm), the assembly and the
|
||||
// registry serialization (bundle), and the task itself (xtask). Leaving
|
||||
// one out means a PR that changes what the bundle emits never rebuilds
|
||||
// it, and the tracked-output check in ci.yml then compares a committed
|
||||
// artifact against an untouched tree and passes on stale bytes.
|
||||
/^crates\/(bundle|core|foundation|wasm|xtask)\//,
|
||||
// The tracked artifacts themselves, so a hand-edit is regenerated over.
|
||||
/^crates\/live\/assets\//,
|
||||
],
|
||||
commands: [
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user