roast-my-design-system 4.1.1 → 4.2.0

package/README.md

@@ -31,6 +31,7 @@ One scan powers all of it; the flags decide what lands on disk. Combine freely.
 | `... --card` | `roast-card.svg`: a shareable 1200x630 card with the score and worst findings. Pure SVG, embeds in a README |
 | `... --sarif` | `design-system-roast.sarif` for GitHub code scanning: upload it in CI and findings appear in the Security tab, annotated on files |
 | `... --by "Ada Lovelace"` | A requester credit in the report header, next to the scan date |
+| `... --exclude lab/` | Leave a folder out of the scan (repeat the flag or comma-separate). Or list folders in a `.roastignore` file at the repo root. Either way the report says so in the header; see [Scoping the scan](#scoping-the-scan) |
 | `... --json` | The scan summary as JSON on stdout, for scripts and pipelines |
 | `... --theme light` / `--out <file>` / `--no-open` | Light report, custom report path, don't open the browser |
 | `/roast-my-design-system` (in Claude Code) | The full experience: the roast in chat, the report, the rules offer, and the fix loop with Claude on your own numbers |
@@ -57,11 +58,29 @@ The same report in light mode (one file, built-in toggle):
 - **Deterministic scanner, not AI sampling.** A zero-dependency Node script reads *every* file (about a second on a normal repo, a few on a large monorepo) and returns the same numbers every run. Claude narrates; it never counts.
 - **Read-only.** Nothing in your repo is modified. The only outputs are a temp JSON and the HTML report.
 - **No network, no telemetry.** Everything runs locally. Nothing about your code leaves your machine.
-- **Honest exclusions.** Test files, Storybook stories, docs sites, example apps, SVG artwork, and email templates (which *must* inline styles) are excluded, so you can't discredit the numbers on a technicality.
+- **Honest exclusions.** Test files, Storybook stories, docs sites, example apps, SVG artwork, and email templates (which *must* inline styles) are excluded, so you can't discredit the numbers on a technicality. Your own exclusions (`.roastignore`, `--exclude`) are printed in the report header with file counts, so a scoped scan can never pass itself off as the whole repo.
 - **Intent-aware counting (v3).** Runtime-computed inline styles, compound-component APIs and wrapper components are not crimes and are not counted as ones. Token-led repos are judged on their hardcoded strays, not their token architecture. Repeated arbitrary values are read as decisions without names, not drift.
 - **A real benchmark.** The "Avg Design System" yardstick comes from scanning 34 public React repos (cal.com, excalidraw, supabase, grafana, twenty, dub, langfuse…). Median: 130 colours, 17 greys, 20 duplicated components, 49 inline style blocks, 70 arbitrary Tailwind values.
 - **A second yardstick: reputable systems.** Curated, scoped scans of 10 well-known design systems (shadcn/ui, Primer, Polaris, Carbon, Material UI, Chakra, Ant Design, GOV.UK, Spectrum, Cloudscape) show what disciplined looks like at scale.
 
+## Scoping the scan
+
+Some repos host more than one visual world on purpose: the product plus a marketing site, a playground, a batch of experiments. Blending them produces a score that describes none of them. Scope the scan to the design system you are actually judging:
+
+```bash
+npx roast-my-design-system --exclude lab/ --exclude playground/
+```
+
+Or make it permanent with a `.roastignore` file at the repo root, one repo-relative folder per line:
+
+```
+# separate visual worlds, not the product's design system
+lab/
+playground/
+```
+
+Both routes merge, and both are loud on purpose. The harvest JSON records every active pattern and how many files it removed, and the report prints a line in the header ("2 folders excluded by .roastignore (lab/, playground/) · 946 files kept out of this scan"). You can narrow the question, but the report always says which question was asked, so a scoped score can't be quietly gamed. There is no negation and no glob syntax: plain folder prefixes, nothing clever.
+
 ## Install
 
 **No install, no Claude needed — just try it:**

package/bin/roast.mjs

@@ -6,7 +6,7 @@
  * write design-system-roast.html, open it, print the score.
  *
  *   npx roast-my-design-system [path] [--theme dark|light] [--out report.html] [--no-open]
- *                              [--rules] [--json]
+ *                              [--rules] [--json] [--exclude <path>]
  */
 import { spawnSync } from 'node:child_process';
 import { mkdtempSync, rmSync, readFileSync, existsSync, statSync } from 'node:fs';
@@ -32,6 +32,15 @@ function opt(name, fallback) {
   argv.splice(i, 2);
   return v;
 }
+// repeatable option: collects every occurrence, comma-separated values split
+function optAll(name) {
+  const out = [];
+  let v;
+  while ((v = opt(name, null)) !== null) {
+    out.push(...v.split(',').map((s) => s.trim()).filter(Boolean));
+  }
+  return out;
+}
 
 if (flag('version') || flag('v')) { console.log(VERSION); process.exit(0); }
 if (flag('help') || flag('h')) {
@@ -54,6 +63,11 @@ Usage: npx roast-my-design-system [path] [options]
                   scanning: findings annotated on files in the Security tab
   --by <name>     put a requester credit in the report header, next to the
                   scan date ("commissioned by <name>")
+  --exclude <p>   leave a folder out of the scan (repo-relative, e.g.
+                  --exclude lab/ --exclude piglet/ or --exclude lab/,piglet/;
+                  same as listing it in a .roastignore file at the repo root).
+                  Every exclusion is printed in the report header with the
+                  number of files it removed, so a scoped scan says so
   --json          print the scan summary as JSON on stdout (implies --no-open)
 
 Read-only scan (--apply and --rules write only the files they name).
@@ -69,6 +83,7 @@ const asJson = flag('json') === true;
 const noOpen = flag('no-open') === true || asJson;
 const theme = opt('theme', 'dark');
 const commissionedBy = opt('by', null);
+const excludes = optAll('exclude');
 const target = resolve(argv.find((a) => !a.startsWith('--')) || process.cwd());
 if (!existsSync(target) || !statSync(target).isDirectory()) {
   console.error(`Not a directory: ${target}`);
@@ -91,7 +106,8 @@ function run(script, args) {
 const say = (s) => { if (!asJson) console.log(s); };
 
 say(`roast-my-design-system ${VERSION} · read-only scan, nothing leaves your machine\n`);
-run('harvest/index.mjs', [target, '--out', harvestPath]);
+run('harvest/index.mjs', [target, '--out', harvestPath,
+  ...excludes.flatMap((e) => ['--exclude', e])]);
 say('');
 run('diagnose/index.mjs', [harvestPath, '--out', outPath, '--theme', theme, '--summary', summaryPath,
   ...(commissionedBy ? ['--by', commissionedBy] : [])]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "4.1.1",
+  "version": "4.2.0",
   "description": "Your AI can write the UI. This makes sure it writes your UI. 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",

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

@@ -891,6 +891,22 @@ const stack = [
   h.profile.monorepo ? 'monorepo' : null,
 ].filter(Boolean);
 
+// User exclusions are printed in the header, never hidden: a scoped scan must
+// say it is scoped, or the score could be quietly gamed. Grouped by source
+// (.roastignore vs --exclude), with the total number of files kept out.
+function exclusionsLine() {
+  const patterns = h.exclusions?.patterns ?? [];
+  if (!patterns.length) return '';
+  const sources = [...new Set(patterns.map((p) => p.source))];
+  const parts = sources.map((src) => {
+    const own = patterns.filter((p) => p.source === src);
+    const list = own.map((p) => `<span class="mono">${esc(p.pattern)}/</span>`).join(', ');
+    return `${own.length} ${own.length === 1 ? 'folder' : 'folders'} excluded by ${esc(src)} (${list})`;
+  });
+  const total = h.exclusions.filesExcluded ?? 0;
+  return `<div class="excl">${parts.join(' · ')} · ${n(total)} files kept out of this scan</div>`;
+}
+
 const html = `<!doctype html>
 <html lang="en" data-theme="${themeName}"><head><meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
@@ -942,6 +958,8 @@ 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; }
+  .excl { margin-top:10px; font:500 12px/1.6 var(--sans); color:var(--dim); }
+  .excl .mono { font-size:11.5px; color:var(--text); }
   .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); }
@@ -1201,6 +1219,7 @@ const html = `<!doctype html>
     ${healthScore !== null ? `<div class="score${noSystemLikely ? ' muted' : ''}">${eyebrow('Health score')}<div class="val">${healthScore}<span class="slash">/</span><span class="of">100</span></div>${noSystemLikely ? '<div class="note">little here to score · see the note below</div>' : ''}</div>` : ''}
   </div>
   <div class="chips">${stack.map((s) => `<span class="chip">${esc(s)}</span>`).join('')}${agentFiles.map((c) => `<span class="chip chip-agent">${esc(c.file)}</span>`).join('')}</div>
+  ${exclusionsLine()}
   ${noSystemLikely ? `<div class="nods">${ICONS.warn}<span>There is most likely <b>no design system in this repo</b>: almost no colour or spacing values were found. Styling may live outside this codebase (CDN stylesheets, a parent repo, or generated output).</span></div>` : ''}
   <div class="glass verdict-card">
     <div class="blob b1"></div><div class="blob b2"></div>
@@ -1290,6 +1309,7 @@ if (summaryPath) {
     repo: repoName,
     version: VERSION,
     ...(commissionedBy ? { commissionedBy } : {}),
+    ...(h.exclusions ? { exclusions: h.exclusions } : {}),
     score: healthScore,
     noSystemLikely,
     verdict,

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

@@ -6,6 +6,11 @@
  * one-screen summary (the seed of the step-2 diagnosis).
  *
  *   node src/harvest/index.mjs <repo-path> [--out harvest.json]
+ *                              [--exclude <path>] (repeatable, comma-separated ok)
+ *
+ * Exclusions also come from a .roastignore file at the repo root (one
+ * repo-relative path per line). Every active pattern lands in the harvest
+ * JSON with the number of files it removed — visible, never silent.
  */
 import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
@@ -15,6 +20,7 @@ import { harvestTokens } from './tokens.mjs';
 import { findDuplicates } from './duplicates.mjs';
 import { harvestContext } from './context.mjs';
 import { resolveWorkspaces } from '../lib/workspaces.mjs';
+import { loadExclusions } from '../lib/exclusions.mjs';
 import { nearColorPairs } from '../lib/nearpairs.mjs';
 import { ruleStaleness } from '../lib/staleness.mjs';
 import { neverImportedComponents } from '../lib/neverimported.mjs';
@@ -24,6 +30,17 @@ function arg(name, fallback) {
   return i > -1 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
 }
 
+// --exclude is repeatable and each value may be comma-separated
+function argAll(name) {
+  const out = [];
+  for (let i = 2; i < process.argv.length; i++) {
+    if (process.argv[i] === `--${name}` && process.argv[i + 1]) {
+      out.push(...process.argv[i + 1].split(',').map((s) => s.trim()).filter(Boolean));
+    }
+  }
+  return out;
+}
+
 const target = process.argv[2] && !process.argv[2].startsWith('--') ? resolve(process.argv[2]) : null;
 if (!target) {
   console.error('Usage: node src/harvest/index.mjs <repo-path> [--out harvest.json]');
@@ -32,7 +49,8 @@ if (!target) {
 const outPath = resolve(arg('out', 'harvest.json'));
 
 const t0 = Date.now();
-const files = walkRepo(target);
+const exclusions = loadExclusions(target, argAll('exclude'));
+const files = walkRepo(target, 14, exclusions);
 const profile = profileRepo(target, files);
 const { components } = harvestComponents(target, files.code);
 const tokens = harvestTokens(target, files.styles, files.code);
@@ -125,6 +143,14 @@ const harvest = {
   context,
   staleRules,
   packages,
+  // Active user exclusions with per-pattern removal counts. Present only when
+  // something was excluded, so downstream renderers can trust its presence.
+  ...(exclusions.patterns.length ? {
+    exclusions: {
+      patterns: exclusions.patterns,
+      filesExcluded: exclusions.patterns.reduce((sum, p) => sum + p.files, 0),
+    },
+  } : {}),
 };
 harvest.tookMs = Date.now() - t0;
 
@@ -138,6 +164,10 @@ const top = (list, n = 5) => list.slice(0, n).map((e) => `${e.value} ×${e.count
 console.log(`\nHarvest: ${profile.name ?? target}`);
 console.log(`  framework: ${profile.framework}${profile.typescript ? ' + TS' : ''}   design system: ${profile.designSystem.kind}${profile.designSystem.name ? ` (${profile.designSystem.name})` : ''}   styling: ${profile.stylingDeps.join(', ') || 'none detected'}`);
 console.log(`  files: ${files.code.length} code, ${files.styles.length} style`);
+if (exclusions.patterns.length) {
+  const list = exclusions.patterns.map((p) => `${p.pattern} (${p.files} files, ${p.source})`).join(', ');
+  console.log(`  excluded by you: ${list}`);
+}
 console.log(`\n  components: ${components.length} defined (${nonPage.length} reusable, ${components.length - nonPage.length} pages)`);
 console.log(`  duplicates: ${duplicates.exactDuplicates.length} exact same-name, ${duplicates.families.length} name families`);
 for (const d of duplicates.exactDuplicates.slice(0, 3)) console.log(`    · ${d.name} defined in ${d.files.length} files`);

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

@@ -56,8 +56,24 @@ const STYLE_EXTS = new Set(['.css', '.scss', '.sass', '.less']);
  * twenty and formbricks. Measured across the fleet, file counts stop growing at
  * 12; 14 leaves headroom. Single-package repos are unaffected either way.
  */
-export function walkRepo(root, maxDepth = 14) {
+export function walkRepo(root, maxDepth = 14, exclusions = null) {
   const files = { code: [], styles: [], other: [] };
+  const excluded = exclusions?.match ?? (() => null);
+  // An excluded directory is still walked once, just to count what the scan
+  // would otherwise have read — the harvest reports how many files each
+  // pattern removed, so an exclusion is always visible, never a silent trim.
+  const countExcluded = (dir, depth, hit) => {
+    if (depth > maxDepth) return;
+    let entries = [];
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name.startsWith('.') && e.name !== '.cursorrules') continue;
+      if (SKIP_DIRS.has(e.name)) continue;
+      if (e.isDirectory()) { countExcluded(join(dir, e.name), depth + 1, hit); continue; }
+      if (TEST_FILE_RE.test(e.name)) continue;
+      hit.files += 1;
+    }
+  };
   const recurse = (dir, depth) => {
     if (depth > maxDepth) return;
     let entries = [];
@@ -67,9 +83,15 @@ export function walkRepo(root, maxDepth = 14) {
       if (SKIP_DIRS.has(e.name)) continue;
       const p = join(dir, e.name);
       if (e.name === 'public' && e.isDirectory() && !hasComponentSource(p)) continue;
+      const rel = relative(root, p).replaceAll('\\', '/');
+      const hit = excluded(rel);
+      if (hit) {
+        if (e.isDirectory()) countExcluded(p, depth + 1, hit);
+        else if (!TEST_FILE_RE.test(e.name)) hit.files += 1;
+        continue;
+      }
       if (e.isDirectory()) { recurse(p, depth + 1); continue; }
       if (TEST_FILE_RE.test(e.name)) continue;
-      const rel = relative(root, p).replaceAll('\\', '/');
       const ext = extname(e.name);
       if (STYLE_EXTS.has(ext)) files.styles.push(rel);
       else if (CODE_EXTS.has(ext)) files.code.push(rel);

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

@@ -0,0 +1,58 @@
+/**
+ * User-declared scan exclusions. Two sources, merged: a .roastignore file at
+ * the scanned repo's root (one pattern per line, # comments and blank lines
+ * ignored) and --exclude values from the CLI. Patterns are repo-relative
+ * directory or file paths ("lab/", "piglet/", "apps/playground"); matching is
+ * a whole-segment prefix on the relative path, so "lab" excludes lab/ and
+ * everything under it but never labs.css. No negation, no globs: this scopes
+ * the scan to the design system being judged, it is not a gitignore clone.
+ *
+ * Honesty is the point: every active pattern is recorded in the harvest JSON
+ * with the number of files it removed, and the report prints them in the
+ * header, so an exclusion can narrow the question but never hide the answer.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function normalize(raw) {
+  return raw.trim()
+    .replaceAll('\\', '/')
+    .replace(/^\.\//, '')
+    .replace(/^\/+/, '')
+    .replace(/\/+$/, '');
+}
+
+/** Parse a .roastignore body into normalized patterns. */
+export function parseRoastignore(text) {
+  return (text ?? '').split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('#'))
+    .map(normalize)
+    .filter(Boolean);
+}
+
+/**
+ * Merge .roastignore (read from repoRoot) with CLI --exclude values into a
+ * pattern list plus a matcher. Each entry carries its source and a `files`
+ * counter the walker increments, so the harvest can report what each pattern
+ * actually removed. Duplicate patterns keep the first source seen.
+ */
+export function loadExclusions(repoRoot, cliExcludes = []) {
+  const patterns = [];
+  const seen = new Set();
+  const add = (raw, source) => {
+    const p = normalize(raw);
+    if (!p || seen.has(p)) return;
+    seen.add(p);
+    patterns.push({ pattern: p, source, files: 0 });
+  };
+
+  let ignoreText = null;
+  try { ignoreText = readFileSync(join(repoRoot, '.roastignore'), 'utf8'); } catch { /* no file, fine */ }
+  for (const p of parseRoastignore(ignoreText)) add(p, '.roastignore');
+  for (const p of cliExcludes) add(p, '--exclude');
+
+  // Whole-segment prefix: pattern "lab" matches "lab" and "lab/…", never "labs".
+  const matcher = (rel) => patterns.find((e) => rel === e.pattern || rel.startsWith(`${e.pattern}/`)) ?? null;
+  return { patterns, match: patterns.length ? matcher : () => null };
+}

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 = '4.1.1';
+export const VERSION = '4.2.0';