roast-my-design-system 3.12.0 → 4.0.0

package/README.md

@@ -10,7 +10,7 @@ Run this skill on your codebase and get, in about a second:
 - **Per-package scores for monorepos.** One blended number hides which package is the problem: `packages/ui` scores 80 while `apps/web` scores 40, and now you can see it.
 - **The receipts behind it.** Every colour and its near-identical twin, every spacing value, typeface, duplicated or never-imported component, inline style and !important, with real file paths, in one self-contained HTML report you can open, Slack or email.
 - **The first fixes ranked by payoff.** A "Where to start" list derived from your own numbers: keep the report as the audit, or hand it to Claude as the punch list for the fix.
-- **Rules that stop the mess coming back.** A generated `design-system-rules.md` for your CLAUDE.md or .cursor/rules: canonical components, your token file, known duplicates to avoid, so your AI agent follows your system instead of guessing at it.
+- **Rules that stop the mess coming back.** A generated `design-system-rules.md` for your CLAUDE.md or .cursor/rules: canonical components, your token file, known duplicates to avoid, so your AI agent follows your system instead of guessing at it. `--apply` injects them for you, and every scan checks the rules you already have for stale references: paths that no longer exist, components named canonical that nothing imports anymore.
 
 ## Why this exists
 
@@ -49,7 +49,7 @@ The same report in light mode (one file, built-in toggle):
 npx roast-my-design-system
 ```
 
-Run it inside any repo. Same scanner, same report, straight from npm. Add `--rules` to also generate the agent rules file, `--json` for a machine-readable summary, or `--theme light`, `--out <file>`, `--no-open` as you like. The Claude Code skill below adds the conversation on top: the roast in chat, then a punch list you can actually work through with Claude.
+Run it inside any repo. Same scanner, same report, straight from npm. Add `--apply` to inject the generated agent rules straight into your CLAUDE.md, AGENTS.md or .cursor/rules (inside a marked block; re-running replaces only that block), `--rules` to write them as a file instead, `--card` for a shareable SVG roast card, `--sarif` for GitHub code scanning, `--json` for a machine-readable summary, or `--theme light`, `--out <file>`, `--no-open` as you like. The Claude Code skill below adds the conversation on top: the roast in chat, then a punch list you can actually work through with Claude.
 
 **Claude Code (recommended):**
 

package/bin/roast.mjs

@@ -45,13 +45,24 @@ Usage: npx roast-my-design-system [path] [options]
   --no-open       write the report without opening it
   --rules         also write design-system-rules.md: agent rules (for
                   CLAUDE.md / .cursor/rules) generated from the scan
+  --apply         inject the rules straight into your agent files (CLAUDE.md,
+                  AGENTS.md, .cursorrules, .cursor/rules/) inside a marked
+                  block; re-running replaces only that block
+  --card          also write roast-card.svg: a shareable 1200x630 card with
+                  the score and worst findings (pure SVG, embeds in READMEs)
+  --sarif         also write design-system-roast.sarif for GitHub code
+                  scanning: findings annotated on files in the Security tab
   --json          print the scan summary as JSON on stdout (implies --no-open)
 
-Read-only scan. No network, no telemetry, nothing leaves your machine.`);
+Read-only scan (--apply and --rules write only the files they name).
+No network, no telemetry, nothing leaves your machine.`);
   process.exit(0);
 }
 
 const wantRules = flag('rules') === true;
+const wantApply = flag('apply') === true;
+const wantCard = flag('card') === true;
+const wantSarif = flag('sarif') === true;
 const asJson = flag('json') === true;
 const noOpen = flag('no-open') === true || asJson;
 const theme = opt('theme', 'dark');
@@ -86,6 +97,20 @@ if (wantRules) {
   say('');
   run('rules/index.mjs', [harvestPath, '--out', rulesPath]);
 }
+if (wantApply) {
+  say('');
+  run('rules/apply.mjs', [harvestPath, '--target', target]);
+}
+const cardPath = resolve(join(target, 'roast-card.svg'));
+if (wantCard) {
+  say('');
+  run('card/index.mjs', [summaryPath, '--out', cardPath]);
+}
+const sarifPath = resolve(join(target, 'design-system-roast.sarif'));
+if (wantSarif) {
+  say('');
+  run('sarif/index.mjs', [harvestPath, '--out', sarifPath]);
+}
 
 let summary = null;
 try { summary = JSON.parse(readFileSync(summaryPath, 'utf8')); } catch { /* report still exists */ }
@@ -100,9 +125,12 @@ if (asJson) {
   }
 }
 
-if (wantRules && !asJson) {
+if (wantApply && !asJson) {
+  console.log(`\n  rules are in place: your agent reads them on its next run.`);
+} else if (wantRules && !asJson) {
   console.log(`\n  design-system-rules.md is ready: paste it into CLAUDE.md or .cursor/rules
-  so your AI agent stops repeating this repo's mistakes.`);
+  so your AI agent stops repeating this repo's mistakes. Or run --apply
+  next time and skip the paste.`);
 } else if (!asJson) {
   console.log(`\n  there is a present wrapped inside the report: your agent rules file,
   generated from this scan. Or run with --rules to write it straight to disk.`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "roast-my-design-system",
-  "version": "3.12.0",
-  "description": "Roast your design system with real data. A deterministic, zero-dependency scanner that counts everything that betrays a design system, from colours and their near-identical twins to greys, spacing values, typefaces, duplicated and never-imported components, inline styles, !important and arbitrary Tailwind values, scores it 0-100 against Ideal Design System norms and a 34-repo benchmark, scores monorepos package by package from the workspace declaration, generates a shareable HTML diagnosis, and with --rules writes the agent rules file (CLAUDE.md, .cursor/rules) that stops the mess coming back.",
+  "version": "4.0.0",
+  "description": "Roast your design system with real data. A deterministic, zero-dependency scanner that counts everything that betrays a design system, from colours and their near-identical twins to greys, spacing values, typefaces, duplicated and never-imported components, inline styles, !important and arbitrary Tailwind values, scores it 0-100 against Ideal Design System norms and a 34-repo benchmark, scores monorepos package by package from the workspace declaration, generates a shareable HTML diagnosis, flags stale references in the agent rules you already have, and with --apply injects the generated rules file straight into CLAUDE.md, AGENTS.md or .cursor/rules so the mess stops coming back. Also ships --card (shareable SVG roast card) and --sarif (GitHub code scanning export).",
   "keywords": [
     "design-system",
     "design-tokens",

package/skills/roast-my-design-system/scripts/card/index.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Card — a shareable roast card from a scan summary. Pure SVG built at scan
+ * time: no browser, no server, no dependency, nothing leaves the machine.
+ * 1200x630 (the OG-image ratio), dark glass look matching the report.
+ *
+ *   node src/card/index.mjs <summary.json> --out roast-card.svg
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > -1 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
+}
+const inPath = process.argv[2] && !process.argv[2].startsWith('--') ? resolve(process.argv[2]) : null;
+if (!inPath) { console.error('Usage: node src/card/index.mjs <summary.json> --out roast-card.svg'); process.exit(1); }
+const outPath = resolve(arg('out', 'roast-card.svg'));
+
+const s = JSON.parse(readFileSync(inPath, 'utf8'));
+const esc = (t) => String(t).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+const score = s.score ?? 0;
+const band = score >= 85 ? 'good' : score >= 55 ? 'warn' : 'bad';
+const COLORS = { good: '#2dd4bf', warn: '#fbbf24', bad: '#fb7185' };
+const scoreColor = COLORS[band];
+
+// top findings: bad tiles first, then warn, by how far past zero/ideal they read
+const order = { bad: 0, warn: 1, good: 2, info: 3 };
+const tiles = [...(s.tiles ?? [])].sort((a, b) => (order[a.health] ?? 9) - (order[b.health] ?? 9));
+const findings = tiles.filter((t) => t.health === 'bad' || t.health === 'warn').slice(0, 3);
+const allGood = findings.length === 0;
+
+const repoName = esc((s.repo ?? 'this repo').split('/').slice(-2).join('/'));
+const date = new Date().toISOString().slice(0, 10);
+const SANS = "-apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif";
+const MONO = "'SF Mono', 'Cascadia Code', Consolas, Menlo, monospace";
+
+const rows = allGood
+  ? `<text x="620" y="300" font-family="${SANS}" font-size="30" font-weight="600" fill="#e6e9ef">nothing over the line</text>
+     <text x="620" y="344" font-family="${SANS}" font-size="22" fill="#8b93a7">this repo is in better shape than most of the internet</text>`
+  : findings.map((t, i) => {
+    const y = 262 + i * 74;
+    const c = COLORS[t.health] ?? '#8b93a7';
+    return `<circle cx="632" cy="${y - 9}" r="7" fill="${c}"/>
+      <text x="660" y="${y}" font-family="${SANS}" font-size="30" font-weight="700" fill="#e6e9ef">${esc(t.value)}</text>
+      <text x="660" y="${y + 32}" font-family="${SANS}" font-size="21" fill="#8b93a7">${esc(t.label)}</text>`;
+  }).join('\n');
+
+const svg = `<svg width="1200" height="630" viewBox="0 0 1200 630" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <radialGradient id="blob1" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" stop-color="${scoreColor}" stop-opacity="0.16"/>
+      <stop offset="100%" stop-color="${scoreColor}" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="blob2" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" stop-color="#6366f1" stop-opacity="0.14"/>
+      <stop offset="100%" stop-color="#6366f1" stop-opacity="0"/>
+    </radialGradient>
+  </defs>
+  <rect width="1200" height="630" fill="#0b0d11"/>
+  <circle cx="1080" cy="80" r="360" fill="url(#blob1)"/>
+  <circle cx="140" cy="580" r="330" fill="url(#blob2)"/>
+  <rect x="44" y="44" width="1112" height="542" rx="28" fill="#11141a" fill-opacity="0.72" stroke="#272c37" stroke-width="1.5"/>
+
+  <text x="96" y="132" font-family="${MONO}" font-size="21" letter-spacing="3" fill="#8b93a7">${repoName.toUpperCase()}</text>
+  <text x="1104" y="132" font-family="${MONO}" font-size="18" letter-spacing="2" fill="#5a6172" text-anchor="end">DESIGN SYSTEM ROAST</text>
+
+  <text x="96" y="360" font-family="${SANS}" font-size="190" font-weight="800" fill="${scoreColor}">${score}</text>
+  <text x="${96 + String(score).length * 105 + 14}" y="360" font-family="${SANS}" font-size="52" font-weight="600" fill="#5a6172">/100</text>
+  <text x="96" y="416" font-family="${SANS}" font-size="24" fill="#8b93a7">design system health</text>
+
+  <line x1="560" y1="200" x2="560" y2="430" stroke="#272c37" stroke-width="1.5"/>
+  <text x="620" y="212" font-family="${MONO}" font-size="17" letter-spacing="2.5" fill="#5a6172">${allGood ? 'THE VERDICT' : 'WHAT YOUR AGENT LEARNS FROM'}</text>
+  ${rows}
+
+  <line x1="96" y1="486" x2="1104" y2="486" stroke="#272c37" stroke-width="1.5"/>
+  <text x="96" y="536" font-family="${MONO}" font-size="20" fill="#8b93a7">npx roast-my-design-system</text>
+  <text x="1104" y="536" font-family="${MONO}" font-size="17" fill="#5a6172" text-anchor="end">scanned ${date} · ver. ${esc(s.version ?? '')}</text>
+</svg>
+`;
+writeFileSync(outPath, svg);
+console.log(`✓ Roast card: ${outPath}`);
+console.log(`  1200x630, pure SVG. Post it, or screenshot it for platforms that reject SVG.`);

package/skills/roast-my-design-system/scripts/diagnose/index.mjs

@@ -234,8 +234,8 @@ const effGreys = tokenLed ? greyStrays : greys.length;
 if (typefaces.length > 3) candidates.push({ ratio: typefaces.length / 3, text: `${typefaces.length} typefaces, brands use 2 or 3` });
 else if (typefaces.length && fontFamilies.length > 6) candidates.push({ ratio: fontFamilies.length / 6, text: `${typefaces.length} typeface${typefaces.length > 1 ? 's' : ''} declared ${fontFamilies.length} different ways` });
 if (effColors > 24 * 1.25) candidates.push({ ratio: effColors / 24, text: tokenLed
-  ? `${n(colorStrays)} hardcoded colours outside the token set`
-  : `${n(colors.length)} distinct colours, a design system needs ~24` });
+  ? `${n(colorStrays)} hardcoded colours outside the token set, your agent will happily copy them at random`
+  : `${n(colors.length)} distinct colours for your agent to pick from, a design system needs ~24` });
 if (effGreys > 13 * 1.25) candidates.push({ ratio: effGreys / 13, text: tokenLed
   ? `${greyStrays} hardcoded greys outside the token set`
   : `${greys.length} shades of grey doing the job of 13` });
@@ -243,10 +243,11 @@ if (spacingTotal > 15) candidates.push({ ratio: spacingTotal / 12, text: `${spac
 if (nearPairs.length >= 3) candidates.push({ ratio: 1 + nearPairs.length / 6, text: `${nearPairs.length} colour pairs are nearly identical (${nearPairs[0].a.value} next to ${nearPairs[0].b.value}), copy-paste, not decisions` });
 if (important.count >= 10) candidates.push({ ratio: 1 + important.count / 30, text: `${n(important.count)} !important declarations, the cascade admitting defeat` });
 if (iconCollisions.length >= 5) candidates.push({ ratio: 1 + iconCollisions.length / 8, text: `two icon sets collide on ${iconCollisions.length} names` });
-if (hardDupes.length > 0) candidates.push({ ratio: 1 + hardDupes.length / 5, text: `${hardDupes.length} component${hardDupes.length > 1 ? 's' : ''} implemented more than once` });
-if (inline.count > 20) candidates.push({ ratio: inline.count / 20, text: `${n(inline.count)} inline style blocks bypassing every system` });
-if (arbitraryCount >= 20) candidates.push({ ratio: arbitraryCount / 30, text: `${n(arbitraryCount)} arbitrary values like ${arbitrary[0].value} punched through the Tailwind scale` });
+if (hardDupes.length > 0) candidates.push({ ratio: 1 + hardDupes.length / 5, text: `${hardDupes.length} component${hardDupes.length > 1 ? 's' : ''} implemented more than once, so an agent asked for a Button has several random options` });
+if (inline.count > 20) candidates.push({ ratio: inline.count / 20, text: `${n(inline.count)} inline style blocks bypassing every system, and teaching your agent to do the same` });
+if (arbitraryCount >= 20) candidates.push({ ratio: arbitraryCount / 30, text: `${n(arbitraryCount)} arbitrary values like ${arbitrary[0].value} punched through the Tailwind scale, each one a precedent your agent will follow` });
 if (agentFiles.length === 0) candidates.push({ ratio: 1.3, text: `no agent rules, so your AI is guessing` });
+if ((h.staleRules ?? []).length >= 2) candidates.push({ ratio: 1.2 + h.staleRules.length / 10, text: `${h.staleRules.length} references in your agent rules point at things this scan can no longer find` });
 const findings = candidates.sort((a, b) => b.ratio - a.ratio).map((c) => c.text);
 
 let verdict = findings.length === 0
@@ -489,7 +490,7 @@ function duplicatesSection() {
       </div>
     </div>`).join('');
   return `<div class="glass pad half">
-    ${sectionHead('Duplicated components', 'every duplicate is a place where your agent has to guess which one is canonical, and it picks wrong half the time. Paths open in VS Code')}
+    ${sectionHead('Duplicated components', 'an agent asking which one is canonical gets several plausible answers. Paths open in VS Code')}
     <div class="fams">${iconCard}${dupeCards}${famCards}</div></div>`;
 }
 
@@ -624,7 +625,7 @@ function componentsSection() {
     ${sectionHead('What you actually use', `${n(reusable.length)} components defined · top by adoption · the real system, buried in here`)}
     ${top.length ? `<div class="tbl-wrap"><table><thead><tr><th>component</th><th>used</th><th>defined in</th><th>props</th></tr></thead><tbody>${rows}</tbody></table></div>` : ''}
     ${neverImported.length >= 2 ? `
-    <div class="receipts">${eyebrow(`${n(neverImported.length)} components defined but never imported · candidates for deletion, or the system nobody found`)}
+    <div class="receipts">${eyebrow(`${n(neverImported.length)} components defined but never imported · they sit in the system as wrong answers waiting to be picked`)}
     <div class="chips-row">${neverImported.slice(0, 8).map((c) => `<span class="vchip" title="${esc(c.file)}">&lt;${esc(c.name)}&gt;</span>`).join('')}${neverImported.length > 8 ? `<span class="vchip dim">+${neverImported.length - 8} more</span>` : ''}</div>
     <p class="sub" style="margin-top:8px">Routers, dynamic imports and barrel files can hide real usage, so treat this as a shortlist to check, not a demolition order.</p>` : ''}</section>`;
 }
@@ -861,9 +862,21 @@ function agentSection() {
   const msg = agentFiles.length
     ? `<p class="sub">Your agent reads ${agentFiles.map((c) => `<span class="mono">${esc(c.file)}</span>`).join(', ')}. But none of it points at a single source of truth for components and tokens, because there isn't one yet. The numbers below are what your agent actually works from.</p>`
     : `<p class="sub">No <span class="mono">CLAUDE.md</span>, no <span class="mono">AGENTS.md</span>, no <span class="mono">.cursorrules</span>. Every time your AI builds UI here, it guesses, from everything below. This is why its output looks almost-but-not-quite right.</p>`;
+  const stale = h.staleRules ?? [];
+  const staleRows = stale.map((s) => `
+    <div class="ledger-row">
+      <span class="mono strong">${esc(s.ref)}</span>
+      <span class="dim">${s.problem === 'missing' ? 'named in' : 'named canonical in'} ${esc(s.file)}, ${s.problem === 'missing' ? 'but the path no longer exists' : 'but nothing imports it this scan'}</span>
+    </div>`).join('');
+  const staleBlock = stale.length ? `
+    <div class="stale">
+      ${eyebrow(`${stale.length} rule reference${stale.length === 1 ? '' : 's'} gone stale · a rule your agent obeys is worse than no rule when the repo has moved on`)}
+      <div class="ledger">${staleRows}</div>
+      <p class="sub" style="margin-top:10px">Rules rot quietly: nobody edits them when a component is renamed or a file moves. Regenerate them from a fresh scan, or fix the lines by hand.</p>
+    </div>` : '';
   return `<section class="glass pad agent">
     ${sectionHead('What your AI agent sees today', '')}
-    ${msg}${have ? `<div class="chips">${have}</div>` : ''}</section>`;
+    ${msg}${have ? `<div class="chips">${have}</div>` : ''}${staleBlock}</section>`;
 }
 
 // ---------- page ----------
@@ -926,6 +939,7 @@ const html = `<!doctype html>
   .chip { border:1px solid var(--line); background:var(--card); border-radius:99px;
     padding:4px 12px; font:500 11.5px/1.5 var(--sans); color:var(--text); }
   .chip-agent { background:var(--text); color:var(--bg); border-color:var(--text); font-weight:600; }
+  .stale { margin-top:18px; }
   .chip-xs { display:inline-block; border:1px solid var(--line); background:var(--chip-bg); border-radius:99px;
     padding:1px 8px; font:500 10px/1.6 var(--mono); color:var(--text); }
 

package/skills/roast-my-design-system/scripts/harvest/index.mjs

@@ -16,6 +16,7 @@ import { findDuplicates } from './duplicates.mjs';
 import { harvestContext } from './context.mjs';
 import { resolveWorkspaces } from '../lib/workspaces.mjs';
 import { nearColorPairs } from '../lib/nearpairs.mjs';
+import { ruleStaleness } from '../lib/staleness.mjs';
 import { neverImportedComponents } from '../lib/neverimported.mjs';
 
 function arg(name, fallback) {
@@ -37,6 +38,9 @@ const { components } = harvestComponents(target, files.code);
 const tokens = harvestTokens(target, files.styles, files.code);
 const duplicates = findDuplicates(components, profile.uiDir, target);
 const context = harvestContext(target);
+const staleRules = ruleStaleness(target, components,
+  new Set(neverImportedComponents(components, profile.uiDir).map((c) => c.name)),
+  [...files.code, ...files.styles, ...files.other]);
 
 // ---------- per-package pass (monorepos) ----------
 // Styling is measured inside each package, but usage is counted repo-wide: a
@@ -119,6 +123,7 @@ const harvest = {
   tokens,
   duplicates,
   context,
+  staleRules,
   packages,
 };
 harvest.tookMs = Date.now() - t0;

package/skills/roast-my-design-system/scripts/lib/staleness.mjs

@@ -0,0 +1,114 @@
+/**
+ * Rule staleness — checks the agent rules a repo already has against what the
+ * scan just measured. Rules are written once and rot silently: a rule naming
+ * Button.tsx keeps mistraining every agent long after ButtonV2 took over.
+ * Deterministic on purpose: only claims we can verify are flagged —
+ * referenced paths that no longer exist, referenced components that no file
+ * defines, and referenced components that nothing imports anymore.
+ */
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const AGENT_FILES = ['CLAUDE.md', 'AGENTS.md', '.cursorrules', '.windsurfrules', '.github/copilot-instructions.md', 'design-system-rules.md'];
+const MAX_BYTES = 200_000;
+const MAX_FINDINGS = 10;
+
+// path-like token with a source extension; must contain a slash so bare
+// filenames in prose ("edit package.json") don't fire
+const PATH_RE = /(?:^|[\s`("'])([\w@.-]+(?:\/[\w@.-]+)+\.(?:tsx|jsx|ts|js|mjs|cjs|css|scss|sass|less|vue|svelte))(?=[\s`)"',.:]|$)/g;
+// component reference: <Name ...> or `Name` in backticks, PascalCase, 4+ chars
+const TAG_RE = /<([A-Z][A-Za-z0-9]{3,})[\s/>]/g;
+const TICK_RE = /`<?([A-Z][A-Za-z0-9]{3,})>?`/g;
+
+// Our own generated rules deliberately name never-imported components as
+// warnings, so re-reading those mentions as "named canonical" would make
+// --apply trigger the staleness alarm on itself. In our content, only path
+// claims are checked (they rot for real); component-usage claims are not.
+const OURS_RE = /roast-my-design-system/i;
+const BLOCK_RE = /<!-- roast-my-design-system:rules:begin[\s\S]*?roast-my-design-system:rules:end -->/g;
+
+function ruleTexts(root) {
+  const texts = [];
+  // `text` keeps everything (paths are checked everywhere); `handWritten` is
+  // the file minus our injected block, and component checks run only on it.
+  const push = (file, text) => {
+    const handWritten = text.replace(BLOCK_RE, '');
+    texts.push({ file, text, handWritten, ours: OURS_RE.test(handWritten) });
+  };
+  for (const f of AGENT_FILES) {
+    const p = join(root, f);
+    try { if (statSync(p).isFile() && statSync(p).size <= MAX_BYTES) push(f, readFileSync(p, 'utf8')); } catch { /* absent */ }
+  }
+  const dir = join(root, '.cursor', 'rules');
+  try {
+    for (const e of readdirSync(dir)) {
+      if (!/\.(md|mdc)$/.test(e)) continue;
+      const p = join(dir, e);
+      if (statSync(p).size <= MAX_BYTES) push(`.cursor/rules/${e}`, readFileSync(p, 'utf8'));
+    }
+  } catch { /* no cursor rules dir */ }
+  return texts;
+}
+
+/**
+ * Returns [{ file, ref, kind: 'path'|'component', problem: 'missing'|'unused' }]
+ * capped at MAX_FINDINGS across all rule files.
+ */
+// Placeholder segments from pattern docs ("packages/features/myfeature/…",
+// "path/to/test.ts") are examples, not claims. Build outputs exist only after
+// a build, so a fresh clone can't judge them.
+const PLACEHOLDER_SEG = /^(path|to|my[\w.-]+|your[\w.-]*|example[\w.-]*|some[\w.-]+|foo|bar|baz)$/i;
+// test/story files are excluded from the walk, so a package-relative
+// reference to one can never be verified; stay silent rather than guess
+const UNVERIFIABLE_RE = /\.(test|spec|stories|story|cy)\.[cm]?[jt]sx?$/;
+const BUILD_DIRS = new Set(['dist', 'build', 'out', '.next', 'node_modules', 'coverage']);
+
+/**
+ * @param neverImportedNames names from the hardened never-imported detector;
+ *   component claims are only flagged when that detector agrees, so routing
+ *   and dynamic-import usage never produces a false "nothing imports it".
+ * @param fileSuffixes every walked file path; a rule path that does not exist
+ *   at the root but matches the tail of a real file is written relative to a
+ *   package dir, not stale.
+ */
+export function ruleStaleness(root, components, neverImportedNames = new Set(), fileSuffixes = []) {
+  const byName = new Map();
+  for (const c of components) {
+    const prev = byName.get(c.name);
+    if (!prev || c.usageCount > prev.usageCount) byName.set(c.name, c);
+  }
+  const findings = [];
+  const seen = new Set();
+  const add = (file, ref, kind, problem) => {
+    const key = `${ref}|${problem}`;
+    if (seen.has(key) || findings.length >= MAX_FINDINGS) return;
+    seen.add(key);
+    findings.push({ file, ref, kind, problem });
+  };
+  const isPlaceholder = (ref) => ref.split('/').some((seg) => PLACEHOLDER_SEG.test(seg));
+  const existsAsSuffix = (ref) => fileSuffixes.some((f) => f === ref || f.endsWith(`/${ref}`));
+
+  for (const { file, text, handWritten, ours } of ruleTexts(root)) {
+    for (const m of text.matchAll(PATH_RE)) {
+      const ref = m[1].replace(/^\.\//, '');
+      if (isPlaceholder(ref)) continue;
+      if (BUILD_DIRS.has(ref.split('/')[0])) continue;
+      if (existsSync(join(root, ref))) continue;
+      if (existsAsSuffix(ref)) continue;
+      // a short test-file ref is almost surely package-relative and unverifiable;
+      // a deep root-relative one was checked by existsSync above and is real drift
+      if (UNVERIFIABLE_RE.test(ref) && ref.split('/').length < 4) continue;
+      add(file, ref, 'path', 'missing');
+    }
+    if (ours) continue; // fully generated file: paths checked above, component claims are ours to regenerate, not to second-guess
+    const compRefs = new Set();
+    for (const m of handWritten.matchAll(TAG_RE)) compRefs.add(m[1]);
+    for (const m of handWritten.matchAll(TICK_RE)) compRefs.add(m[1]);
+    for (const name of compRefs) {
+      const def = byName.get(name);
+      if (!def) continue; // never claim a component is missing from a name we can't resolve: could be a library import
+      if (!def.isPage && def.usageCount === 0 && neverImportedNames.has(name)) add(file, name, 'component', 'unused');
+    }
+  }
+  return findings;
+}

package/skills/roast-my-design-system/scripts/lib/version.mjs

@@ -1,4 +1,4 @@
 // Single version constant for the engine — imported by diagnose (report
 // footer) and rules (generated-by line). This is the bump spot that used to
 // live as a const inside diagnose/index.mjs.
-export const VERSION = '3.12.0';
+export const VERSION = '4.0.0';

package/skills/roast-my-design-system/scripts/rules/apply.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Apply — injects the generated agent rules straight into the files agents
+ * already read, so the npx path ends where the skill's conversational merge
+ * ends: rules in place, zero copy-paste.
+ *
+ * Targets, all that exist at the repo root:
+ *   CLAUDE.md, AGENTS.md, .cursorrules  -> rules injected inside a marked
+ *     block; re-running replaces only our block, never touching their text.
+ *   .cursor/rules/ (directory)          -> design-system-rules.mdc written
+ *     whole, with the frontmatter Cursor expects.
+ * If none exist, falls back to design-system-rules.md at the root and says so.
+ *
+ *   node src/rules/apply.mjs <harvest.json> --target <repo-root>
+ */
+import { readFileSync, writeFileSync, existsSync, statSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { rulesMarkdown } from './build.mjs';
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > -1 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
+}
+const inPath = process.argv[2] && !process.argv[2].startsWith('--') ? resolve(process.argv[2]) : null;
+if (!inPath) { console.error('Usage: node src/rules/apply.mjs <harvest.json> --target <repo-root>'); process.exit(1); }
+const target = resolve(arg('target', '.'));
+
+const BEGIN = '<!-- roast-my-design-system:rules:begin (generated from a scan; this block is replaced by --apply, text outside it is never touched) -->';
+const END = '<!-- roast-my-design-system:rules:end -->';
+
+const h = JSON.parse(readFileSync(inPath, 'utf8'));
+const { text, ruleCount } = rulesMarkdown(h);
+const block = `${BEGIN}\n\n${text.trim()}\n\n${END}`;
+
+/** Inject or replace our marked block in an existing file's content. */
+function inject(content) {
+  const b = content.indexOf(BEGIN);
+  const e = content.indexOf(END);
+  if (b !== -1 && e !== -1 && e > b) {
+    return { next: content.slice(0, b) + block + content.slice(e + END.length), how: 'replaced' };
+  }
+  const sep = content.length === 0 ? '' : content.endsWith('\n\n') ? '' : content.endsWith('\n') ? '\n' : '\n\n';
+  return { next: content + sep + block + '\n', how: 'added' };
+}
+
+const done = [];
+for (const name of ['CLAUDE.md', 'AGENTS.md', '.cursorrules']) {
+  const p = join(target, name);
+  if (!existsSync(p) || !statSync(p).isFile()) continue;
+  const { next, how } = inject(readFileSync(p, 'utf8'));
+  writeFileSync(p, next);
+  done.push(`${name} (${how} the rules block)`);
+}
+
+const cursorDir = join(target, '.cursor', 'rules');
+if (existsSync(cursorDir) && statSync(cursorDir).isDirectory()) {
+  const p = join(cursorDir, 'design-system-rules.mdc');
+  const existed = existsSync(p);
+  writeFileSync(p, `---\ndescription: Design system rules generated by roast-my-design-system from a scan of this repo\nalwaysApply: true\n---\n\n${text.trim()}\n`);
+  done.push(`.cursor/rules/design-system-rules.mdc (${existed ? 'rewritten' : 'created'})`);
+}
+
+if (done.length === 0) {
+  const p = join(target, 'design-system-rules.md');
+  writeFileSync(p, text);
+  console.log(`No agent file found (CLAUDE.md, AGENTS.md, .cursorrules, .cursor/rules/).`);
+  console.log(`✓ Wrote design-system-rules.md instead; point your agent at it.`);
+} else {
+  console.log(`✓ ${ruleCount} rules applied, every one with a receipt:`);
+  for (const d of done) console.log(`  → ${d}`);
+}

package/skills/roast-my-design-system/scripts/sarif/index.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * SARIF export — the same findings, written in the format GitHub's code
+ * scanning tab and enterprise tooling ingest (SARIF 2.1.0). File-level
+ * results (the scanner counts per file, it does not keep line numbers), which
+ * code scanning renders as file annotations.
+ *
+ *   node src/sarif/index.mjs <harvest.json> --out design-system-roast.sarif
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { VERSION } from '../lib/version.mjs';
+import { nearColorPairs } from '../lib/nearpairs.mjs';
+import { neverImportedComponents } from '../lib/neverimported.mjs';
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > -1 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
+}
+const inPath = process.argv[2] && !process.argv[2].startsWith('--') ? resolve(process.argv[2]) : null;
+if (!inPath) { console.error('Usage: node src/sarif/index.mjs <harvest.json> --out design-system-roast.sarif'); process.exit(1); }
+const outPath = resolve(arg('out', 'design-system-roast.sarif'));
+
+const h = JSON.parse(readFileSync(inPath, 'utf8'));
+const t = h.tokens;
+
+const RULES = {
+  'duplicate-component': { name: 'Duplicated component', desc: 'A component implemented more than once. An agent asked for it has several plausible answers.' },
+  'never-imported-component': { name: 'Component nobody imports', desc: 'Defined in the system, imported by nothing. It sits there as a wrong answer waiting to be picked.' },
+  'inline-styles': { name: 'Inline style blocks', desc: 'Static values written as style attributes, bypassing the system and teaching the agent to do the same.' },
+  'important-styles': { name: '!important declarations', desc: 'The cascade admitting defeat. Fix specificity at the source and these stop being necessary.' },
+  'stray-colors': { name: 'Hardcoded colours', desc: 'Colour values no token names. Each one is a value the agent will happily copy.' },
+  'stale-rule-reference': { name: 'Stale agent-rule reference', desc: 'The agent rules reference something this scan can no longer find. A rule the agent obeys is worse than no rule when the repo has moved on.' },
+};
+
+const results = [];
+const loc = (file) => [{ physicalLocation: { artifactLocation: { uri: file } } }];
+const push = (ruleId, level, text, file) => results.push({ ruleId, level, message: { text }, locations: loc(file) });
+
+for (const d of (h.duplicates?.exactDuplicates ?? [])) {
+  if (d.wrapped) continue;
+  for (const f of d.files) {
+    const file = typeof f === 'string' ? f : f.file;
+    push('duplicate-component', 'warning', `<${d.name}> is implemented in ${d.files.length} places. This is one of them; an agent has to guess which is canonical.`, file);
+  }
+}
+for (const c of neverImportedComponents(h.components ?? [], h.profile?.uiDir ?? null)) {
+  push('never-imported-component', 'note', `<${c.name}> is defined here and imported by nothing.`, c.file);
+}
+for (const f of (t.inlineStyles?.files ?? [])) {
+  push('inline-styles', 'warning', `${f.count} static inline style block${f.count === 1 ? '' : 's'} in this file. Dynamic positioning is already excluded, so these could be classes or tokens today.`, f.file);
+}
+for (const f of (t.important?.files ?? [])) {
+  push('important-styles', 'warning', `${f.count} !important declaration${f.count === 1 ? '' : 's'} in this file.`, f.file);
+}
+// stray colours: per file, counting only non-token values
+const strayByFile = new Map();
+for (const c of (t.colors ?? [])) {
+  if (c.isToken) continue;
+  for (const f of (c.files ?? [])) strayByFile.set(f.file, (strayByFile.get(f.file) ?? 0) + 1);
+}
+for (const [file, count] of [...strayByFile.entries()].sort((a, b) => b[1] - a[1]).slice(0, 50)) {
+  push('stray-colors', 'note', `${count} hardcoded colour value${count === 1 ? '' : 's'} no token names.`, file);
+}
+for (const s of (h.staleRules ?? [])) {
+  push('stale-rule-reference', 'warning', `${s.ref} is ${s.problem === 'missing' ? 'referenced here but no longer exists in the repo' : 'named here but nothing imports it this scan'}.`, s.file);
+}
+
+const sarif = {
+  $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json',
+  version: '2.1.0',
+  runs: [{
+    tool: {
+      driver: {
+        name: 'roast-my-design-system',
+        version: VERSION,
+        informationUri: 'https://github.com/pencilrebel/roast-my-design-system',
+        rules: Object.entries(RULES).map(([id, r]) => ({
+          id, name: r.name,
+          shortDescription: { text: r.name },
+          fullDescription: { text: r.desc },
+          helpUri: 'https://github.com/pencilrebel/roast-my-design-system',
+        })),
+      },
+    },
+    results,
+  }],
+};
+writeFileSync(outPath, JSON.stringify(sarif, null, 2));
+console.log(`✓ SARIF: ${results.length} findings → ${outPath}`);
+console.log(`  Upload it in CI and they appear in GitHub's code scanning tab, annotated on files.`);