roast-my-design-system 3.8.0 → 3.9.0

package/README.md

@@ -7,6 +7,7 @@
 Run this skill on your codebase and get, in about a second:
 
 - **A health score you can defend in a meeting.** 0-100, deterministic, benchmarked against Ideal Design System norms, 30 scanned public repos and 10 reputable design systems (Primer, Polaris, Carbon, shadcn/ui…).
+- **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.
@@ -24,15 +25,15 @@ Your AI agent (Claude, Cursor, Copilot) builds UI by imitating what's already in
 
 The full report for vercel/ai-chatbot, top to bottom:
 
-![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, three-yardstick tiles, palette forensics, spacing receipts, typography, offenders, duplicates, and the where-to-start close](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-full-dark.png?v=3.8.0)
+![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, three-yardstick tiles, palette forensics, spacing receipts, typography, offenders, duplicates, and the where-to-start close](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-full-dark.png?v=3.9.0)
 
 The same report in light mode (one file, built-in toggle):
 
-![The diagnosis report in light mode](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-light-hero.png?v=3.8.0)
+![The diagnosis report in light mode](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-light-hero.png?v=3.9.0)
 
 ## What makes the numbers trustworthy
 
-- **Deterministic scanner, not AI sampling.** A zero-dependency Node script reads *every* file (a 5,000-file monorepo takes ~1.5s) and returns the same numbers every run. Claude narrates; it never counts.
+- **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.
@@ -132,4 +133,4 @@ MIT. The code is yours to fork, modify and redistribute; the copyright notice tr
 
 **roast-my-design-system**™ and the GK mark are trademarks of Greg Kozakiewicz. Forking is welcome, republishing under this name is not: see [brand and attribution](https://pencilrebel.github.io/roast-my-design-system/brand.html).
 
-Built and designed by <a href="https://gregkozakiewicz.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark-dark.png?v=3.8.0"><img src="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark.png?v=3.8.0" height="15" alt="GK mark"></picture> Greg Kozakiewicz</a>.
+Built and designed by <a href="https://gregkozakiewicz.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark-dark.png?v=3.9.0"><img src="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark.png?v=3.9.0" height="15" alt="GK mark"></picture> Greg Kozakiewicz</a>.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "3.8.0",
+  "version": "3.9.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 30-repo benchmark, generates a shareable HTML diagnosis, and with --rules writes the agent rules file (CLAUDE.md, .cursor/rules) that stops the mess coming back.",
   "keywords": [
     "design-system",

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

@@ -36,7 +36,7 @@ const GK_MASK = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqa
 const GK_MARK = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAIAAAD8GO2jAAAACXBIWXMAAAAAAAAAAQCEeRdzAAACPklEQVR4nOVWTYh5URR/PlJYEKV8LKwkZalsmI2dZmMnK8pKmaZ87JSanexEkayUhSxsZyfJNBQ7UYqVhSShfM+v/6mXmtU81+p/Frfze+/d3++ce88993Hcf2cikehZ1GazWafTPUVDLBZjLBQKnU6HMTVvcrl8Op3ebrdsNgsokUiYUVP4Pp/v9s96vd79cwZGK95sNkkgGAwC2u12lhrY3u12C/b1ei2TyV5eXjabjV6vZ6BBa51MJin8arUKWKlU4H99fSkUCo5JUQ2HQxJwuVzIYLVawcdIVSs8CQoNpMQ+Go0Aw+EwwXw+D+h2u4Vr0LRSqUSMqVQKsN1uE3Q4HEql8ng8BgIBTnDhqlSqxWIBuvP5bDAYLBbL5XIBHAwGeBuJRODvdjun0/nnPOjraDRK8TYaDcBMJkMwFosBfn9/E0wkEn9OgjYgnU6fTidQwAGcTCbw9/u9VqvFUYB/vV5RskajkRNcTiaTKR6PI9j5fE7xlstlPM/lcgTr9ToneJ/5oOB4PB70O8Tb7/f9fv9sNqPkXl9fhQsQ9f1ktVqNvUVCxA6ZRxsf5pMAxnsuVBSOwvv7+6Phk0PsBNn0OOLC9haLReqdvBL/wUNKNPnt7Q0LjeVutVqhUEij0TwU9W8BVA4JUEUul8tarcZGhpbIarWiSeA0HQ4Hkvn4+GB56VMvov6DA+z1eplR89btdsE+Ho9tNhv3jOv+8/MTFz06M3ypVMqMnTfcwPhn4djG/tue+Mf4RGom9gMt6lAx16huIwAAAABJRU5ErkJggg==';
 
 // Shown in the report footer; keep in step with plugin.json when releasing.
-const VERSION = '3.8.0';
+const VERSION = '3.9.0';
 
 // Report identity. The scan id is a stable digest of this scan's shape, salted
 // with the report namespace, so the same repo scanned twice reads the same and
@@ -280,14 +280,16 @@ const WARN_TOLERANCE = { exactDuplicates: 2, inlineStyles: 10, nearPairs: 2, imp
 // Absence rule also skipped for arbitrary values: zero brackets is discipline
 // (nine of ten reputable systems sit at 0, including Tailwind-native shadcn/ui).
 const NO_ABSENCE_RULE = new Set(['colors', 'greys', 'arbitrary']);
-function healthOf(metric, value) {
+function healthOf(metric, value, opts = {}) {
   const iv = ideal(metric);
   if (iv === null) return 'info';
   if (ZERO_IDEAL.has(metric)) {
     if (value === 0) return 'good';
     return value <= WARN_TOLERANCE[metric] ? 'warn' : 'bad';
   }
-  if (!NO_ABSENCE_RULE.has(metric) && value < Math.max(1, iv * 0.05)) return 'bad';
+  // "almost nothing found" reads as a missing design system for a whole repo,
+  // but a single package with no spacing values is just a small package.
+  if (!opts.noAbsence && !NO_ABSENCE_RULE.has(metric) && value < Math.max(1, iv * 0.05)) return 'bad';
   if (value <= iv) return 'good';
   const mv = median(metric);
   const warnCap = mv && mv > iv ? mv : iv * 1.5;
@@ -792,6 +794,61 @@ function whereToStartSection() {
       </div>`).join('')}</div></section>`;
 }
 
+// ---------- package by package ----------
+// One number for a monorepo hides which package is the problem. Each package
+// is judged on the same nine tiles, with usage counted repo-wide, so a shared
+// component another package imports is adopted rather than dead.
+const PKG_LABELS = {
+  colors: 'stray colours', greys: 'greys', spacing: 'off-scale spacing values',
+  exactDuplicates: 'duplicated components', inlineStyles: 'inline style blocks',
+  nearPairs: 'near-identical colour pairs', important: '!important declarations',
+  neverImported: 'components nobody imports', arbitrary: 'arbitrary bracket values',
+};
+function scorePackage(m) {
+  const tokenLed = m.colorTokens >= m.colorStrays && m.colorTokens > 0;
+  const vals = {
+    colors: tokenLed ? m.colorStrays : m.colors,
+    greys: tokenLed ? m.greyStrays : m.greys,
+    spacing: m.spacing,
+    exactDuplicates: m.exactDuplicates,
+    inlineStyles: m.inlineStyles,
+    nearPairs: m.nearPairs,
+    important: m.important,
+    neverImported: m.neverImported,
+    arbitrary: m.arbitrary,
+  };
+  const rows = Object.entries(vals).map(([metric, v]) => ({ metric, value: v, health: healthOf(metric, v, { noAbsence: true }) }));
+  const scored = rows.filter((r) => r.health in SCORE_OF);
+  if (!scored.length) return null;
+  const score = Math.round(scored.reduce((sum, r) => sum + SCORE_OF[r.health], 0) / scored.length);
+  // the worst finding: furthest past its ideal among the failing tiles
+  const over = (r) => { const iv = ideal(r.metric); return iv ? r.value / Math.max(iv, 1) : r.value; };
+  const worst = scored.filter((r) => r.health === 'bad').sort((a, b) => over(b) - over(a))[0]
+    ?? scored.filter((r) => r.health === 'warn').sort((a, b) => over(b) - over(a))[0];
+  return { score, worst };
+}
+function packagesSection() {
+  const pkgs = (h.packages ?? []).filter((p) => p.scored && p.metrics);
+  if (pkgs.length < 2) return '';
+  const rated = pkgs.map((p) => ({ ...p, ...scorePackage(p.metrics) })).filter((p) => p.score !== undefined && p.score !== null);
+  if (rated.length < 2) return '';
+  rated.sort((a, b) => a.score - b.score);
+  const shown = rated.slice(0, 10);
+  const band = (sc) => (sc >= 85 ? 'good' : sc >= 55 ? 'warn' : 'bad');
+  const skipped = (h.packages ?? []).length - rated.length;
+  const rows = shown.map((p) => `
+    <tr><td class="mono strong">${esc(p.dir)}</td>
+    <td><span class="pkg-score pkg-${band(p.score)}">${p.score}</span></td>
+    <td>${p.worst ? `${n(p.worst.value)} ${esc(PKG_LABELS[p.worst.metric] ?? p.worst.metric)}` : '<span class="dim">nothing over the line</span>'}</td>
+    <td class="dim">${n(p.codeFiles)} files</td></tr>`).join('');
+  return `<section class="glass pad">
+    ${sectionHead('Package by package', `${rated.length} package${rated.length === 1 ? '' : 's'} with enough UI to judge · the repo score above is the whole thing blended${skipped > 0 ? `, and ${skipped} package${skipped === 1 ? ' was' : 's were'} too small or too backend to score` : ''}`)}
+    <div class="tbl-wrap"><table><thead><tr><th>package</th><th>score</th><th>worst finding</th><th>size</th></tr></thead><tbody>${rows}</tbody></table></div>
+    ${rated.length > 10 ? `<div class="spec-more">and ${rated.length - 10} more</div>` : ''}
+    ${healthScore !== null && rated.length && Math.min(...rated.map((p) => p.score)) > healthScore
+      ? `<p class="sub" style="margin-top:12px">A repo scores below its own packages by arithmetic, not by accident: distinct values add up across packages, so the whole always carries more than any part. Read the package scores for where each team stands, and the repo score for what your agent sees when it looks at everything at once.</p>` : ''}</section>`;
+}
+
 function agentSection() {
   const have = agentFiles.map((c) => `<span class="chip chip-agent">${esc(c.file)} · ${esc(c.tool ?? c.kind)}</span>`).join('');
   const msg = agentFiles.length
@@ -1031,6 +1088,11 @@ const html = `<!doctype html>
   footer .brand { color:var(--accent); font-weight:700; text-decoration:none; }
   footer .brand:hover { text-decoration:underline; }
   footer .creds { display:flex; gap:16px; font:700 9.5px/1.6 var(--sans); letter-spacing:.16em; text-transform:uppercase; color:var(--dim2); }
+  .pkg-score { display:inline-block; min-width:38px; text-align:center; font:700 12.5px/1 var(--sans);
+    padding:6px 8px; border-radius:8px; }
+  .pkg-good { background:var(--ok-soft); color:var(--ok); }
+  .pkg-warn { background:var(--amber-soft); color:var(--amber); }
+  .pkg-bad { background:var(--coral-soft); color:var(--coral); }
   .spec { margin-top:18px; }
   .spec-rows { display:grid; gap:2px; margin-top:8px; }
   .spec-type { display:flex; align-items:baseline; gap:16px; padding:5px 0; border-bottom:1px solid var(--line-soft); }
@@ -1126,6 +1188,8 @@ ${giftSection()}
 
 <div class="stats">${bigStats.map((s) => statTile(s)).join('')}</div>
 
+${packagesSection()}
+
 ${agentSection()}
 
 <section style="margin-top:16px">${paletteSection()}</section>
@@ -1202,6 +1266,10 @@ if (summaryPath) {
     noSystemLikely,
     verdict,
     tiles: bigStats.map((s) => ({ label: s.label, value: s.num, health: s.health })),
+    packages: (h.packages ?? []).filter((p) => p.scored && p.metrics)
+      .map((p) => ({ dir: p.dir, name: p.name, ...(scorePackage(p.metrics) ?? {}) }))
+      .filter((p) => p.score !== undefined)
+      .sort((a, b) => a.score - b.score),
     report: outPath,
   }, null, 2));
 }

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

@@ -14,6 +14,9 @@ import { harvestComponents } from './components.mjs';
 import { harvestTokens } from './tokens.mjs';
 import { findDuplicates } from './duplicates.mjs';
 import { harvestContext } from './context.mjs';
+import { resolveWorkspaces } from '../lib/workspaces.mjs';
+import { nearColorPairs } from '../lib/nearpairs.mjs';
+import { neverImportedComponents } from '../lib/neverimported.mjs';
 
 function arg(name, fallback) {
   const i = process.argv.indexOf(`--${name}`);
@@ -35,6 +38,70 @@ const tokens = harvestTokens(target, files.styles, files.code);
 const duplicates = findDuplicates(components, profile.uiDir, target);
 const context = harvestContext(target);
 
+// ---------- per-package pass (monorepos) ----------
+// Styling is measured inside each package, but usage is counted repo-wide: a
+// component another package imports is adopted, not dead. Files are already
+// walked, so this re-reads each package's own files once, not the whole repo
+// per package. Packages with too little UI to judge are listed, never scored.
+const workspaces = resolveWorkspaces(target);
+const packages = [];
+if (workspaces.length > 1) {
+  const inDir = (f, dir) => f === dir || f.startsWith(`${dir}/`);
+  // deepest-first so apps/web/sub is attributed to itself, not to apps/web
+  const byDepth = [...workspaces].sort((a, b) => b.dir.split('/').length - a.dir.split('/').length);
+  const claimed = new Map();
+  const claim = (f) => byDepth.find((w) => inDir(f, w.dir))?.dir ?? null;
+  for (const f of files.code) { const d = claim(f); if (d) (claimed.get(d) ?? claimed.set(d, { code: [], styles: [] }).get(d)).code.push(f); }
+  for (const f of files.styles) { const d = claim(f); if (d) (claimed.get(d) ?? claimed.set(d, { code: [], styles: [] }).get(d)).styles.push(f); }
+
+  // Only packages that actually contain UI are worth reading twice: a backend
+  // or config package has no styling to judge, and scanning it would cost time
+  // to produce a meaningless perfect score. Biggest UI packages first, capped,
+  // so a 100-package monorepo cannot blow the scan budget.
+  const UI_RE = /\.(tsx|jsx|vue|svelte)$/;
+  const uiCount = (w) => {
+    const own = claimed.get(w.dir);
+    return own ? own.code.filter((f) => UI_RE.test(f)).length + own.styles.length : 0;
+  };
+  const candidates = workspaces
+    .map((w) => ({ w, ui: uiCount(w) }))
+    .sort((a, b) => b.ui - a.ui);
+  const scanning = new Set(candidates.filter((c) => c.ui >= 8).slice(0, 30).map((c) => c.w.dir));
+
+  for (const w of workspaces) {
+    const own = claimed.get(w.dir);
+    if (!own) continue;
+    const codeCount = own.code.length, styleCount = own.styles.length;
+    const entry = { name: w.name, dir: w.dir, codeFiles: codeCount, styleFiles: styleCount, scored: false };
+    if (!scanning.has(w.dir)) { packages.push(entry); continue; }
+    const t = harvestTokens(target, own.styles, own.code);
+    const comps = components.filter((c) => inDir(c.file, w.dir));
+    const dupes = duplicates.exactDuplicates.filter((d) => !d.wrapped
+      && d.files.every((f) => inDir(typeof f === 'string' ? f : f.file, w.dir)));
+    const colorTokens = t.colors.filter((c) => c.isToken).length;
+    const signal = t.colors.length + t.spacing.length + t.inlineStyles.count
+      + (t.tailwind.colors.length + t.tailwind.spacing.length);
+    if (signal < 5) { packages.push(entry); continue; }   // nothing to judge, so no verdict
+    entry.scored = true;
+    entry.metrics = {
+      colors: t.colors.length,
+      colorTokens,
+      colorStrays: t.colors.length - colorTokens,
+      greys: t.greyCount,
+      greyStrays: t.colors.filter((c) => !c.isToken && c.value.startsWith('#')).length,
+      spacing: t.spacing.length + t.tailwind.spacing.filter((v) => v.value.startsWith('[')).length,
+      exactDuplicates: dupes.length,
+      inlineStyles: t.inlineStyles.count,
+      nearPairs: nearColorPairs(t.colors).length,
+      important: t.important?.count ?? 0,
+      neverImported: neverImportedComponents(comps, null).length,
+      arbitrary: (t.tailwind.arbitrary ?? []).reduce((sum, a) => sum + a.count, 0),
+      components: comps.filter((c) => !c.isPage).length,
+    };
+    packages.push(entry);
+  }
+}
+
 const harvest = {
   repo: target,
   harvestedAt: new Date().toISOString(),
@@ -49,6 +116,7 @@ const harvest = {
   tokens,
   duplicates,
   context,
+  packages,
 };
 harvest.tookMs = Date.now() - t0;
 

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

@@ -0,0 +1,92 @@
+/**
+ * Workspace resolution. A monorepo declares its packages in one of a few
+ * places and always as globs, never as a fixed folder shape — guessing from
+ * folder depth misses most of them (cal.com keeps 23 packages that a naive
+ * two-level scan reports as zero). Read the declaration instead.
+ *
+ * Supports: package.json `workspaces` (array or { packages: [] }),
+ * pnpm-workspace.yaml, and negation patterns.
+ */
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const readJSON = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; } };
+
+/** Expand one glob ('packages/*', 'apps/**', 'tools/x') to existing directories. */
+function expand(root, pattern) {
+  if (pattern === '.' || pattern === './') return [];
+  const parts = pattern.replace(/\/+$/, '').split('/').filter(Boolean);
+  let dirs = [''];
+  for (const part of parts) {
+    const next = [];
+    for (const d of dirs) {
+      const abs = join(root, d);
+      if (part === '*' || part === '**') {
+        let entries;
+        try { entries = readdirSync(abs, { withFileTypes: true }); } catch { continue; }
+        for (const e of entries) {
+          if (!e.isDirectory() || e.name.startsWith('.') || e.name === 'node_modules') continue;
+          const rel = d ? `${d}/${e.name}` : e.name;
+          next.push(rel);
+          // '**' also matches deeper levels
+          if (part === '**') dirs.push(rel);
+        }
+      } else {
+        const rel = d ? `${d}/${part}` : part;
+        if (existsSync(join(root, rel))) next.push(rel);
+      }
+    }
+    dirs = next;
+  }
+  return dirs.filter((d) => { try { return statSync(join(root, d)).isDirectory(); } catch { return false; } });
+}
+
+/**
+ * Resolve a repo's workspace packages.
+ * Returns [{ name, dir }] with dir relative to the repo root, or [] when the
+ * repo is not a workspace monorepo.
+ */
+export function resolveWorkspaces(root) {
+  const patterns = [];
+  const pkg = readJSON(join(root, 'package.json'));
+  const ws = pkg?.workspaces;
+  if (Array.isArray(ws)) patterns.push(...ws);
+  else if (Array.isArray(ws?.packages)) patterns.push(...ws.packages);
+
+  // pnpm-workspace.yaml: the "packages:" block, read line by line. Comments and
+  // blank lines are legal inside it (langfuse opens with one), and sibling
+  // top-level keys such as "catalog:" end it.
+  try {
+    const lines = readFileSync(join(root, 'pnpm-workspace.yaml'), 'utf8').split('\n');
+    let inBlock = false;
+    for (const line of lines) {
+      if (/^packages:\s*$/.test(line)) { inBlock = true; continue; }
+      if (!inBlock) continue;
+      if (/^\s*(#.*)?$/.test(line)) continue;              // comment or blank
+      if (/^\S/.test(line)) break;                          // next top-level key
+      const m = /^\s*-\s*["']?([^"'#]+?)["']?\s*$/.exec(line);
+      if (m) patterns.push(m[1].trim());
+    }
+  } catch { /* not a pnpm workspace */ }
+
+  if (!patterns.length) return [];
+
+  const negations = patterns.filter((p) => p.startsWith('!')).map((p) => p.slice(1).replace(/\/+$/, ''));
+  const isNegated = (dir) => negations.some((neg) => {
+    if (neg.includes('*')) return expand(root, neg).includes(dir);
+    return dir === neg || dir.startsWith(`${neg}/`);
+  });
+
+  const seen = new Map();
+  for (const pattern of patterns) {
+    if (pattern.startsWith('!')) continue;
+    for (const dir of expand(root, pattern)) {
+      if (!dir || dir === '.' || isNegated(dir) || seen.has(dir)) continue;
+      // a workspace package is one that declares itself
+      const own = readJSON(join(root, dir, 'package.json'));
+      if (!own) continue;
+      seen.set(dir, { name: own.name || dir, dir });
+    }
+  }
+  return [...seen.values()].sort((a, b) => a.dir.localeCompare(b.dir));
+}