roast-my-design-system 4.3.0 → 4.4.0

package/README.md

@@ -12,7 +12,7 @@ Run it 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. `--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.
+- **Rules that stop the mess coming back.** A generated `design-system-rules.md` with canonical components, your token file, and known duplicates to avoid, so your AI agent follows your system instead of guessing at it. `--apply` injects them into every agent file you have: Claude, Cursor, GitHub Copilot, and Windsurf. Every scan also checks the rules you already have for stale references: paths that no longer exist, components named canonical that nothing imports anymore.
 
 ## Why this exists
 
@@ -36,7 +36,7 @@ One scan powers all of it; the flags decide what lands on disk. Combine freely.
 | `... --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 |
 
-Every scan also checks the agent rules you already have and flags stale references, no flag needed.
+**One scan writes rules for every agent: Claude, Cursor, GitHub Copilot, and Windsurf.** Every scan also checks the agent rules you already have and flags stale references, no flag needed.
 
 ## Example use cases
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "roast-my-design-system",
-  "version": "4.3.0",
-  "description": "Your AI can write the UI. This makes sure it writes your UI. A deterministic scanner counts every colour, spacing value and duplicate component, scores you 0-100 against 34 public repos, scopes the scan with .roastignore, injects agent rules with --apply.",
+  "version": "4.4.0",
+  "description": "Your AI can write the UI. This makes sure it writes your UI. A deterministic scanner scores your design system 0-100 against 34 public repos, scopes the scan with .roastignore, and writes rules for Claude, Cursor, GitHub Copilot and Windsurf with --apply.",
   "keywords": [
     "design-system",
     "design-tokens",

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

@@ -185,5 +185,69 @@ export function harvestComponents(root, codeFiles) {
   }
 
   components.sort((a, b) => b.usageCount - a.usageCount || a.name.localeCompare(b.name));
+
+  // Pass 3: golden examples — for the most-used components, quote the repo's
+  // own most common usage, verbatim, with a receipt. Descriptive, never
+  // invented: we photograph the plate that leaves the kitchen most often.
+  // A component with no dominant pattern gets no example (printing one would
+  // be a lie), and a component used a handful of times is not a pattern yet.
+  const uniqueNames = new Set([...byName].filter(([, d]) => d.length === 1).map(([n]) => n));
+  const candidates = components
+    .filter((c) => !c.isPage && c.usageCount >= 6 && uniqueNames.has(c.name))
+    .slice(0, 12);
+  for (const c of candidates) {
+    const found = []; // { tag, file }
+    for (const [file, src] of sources) {
+      if (file === c.file) continue;
+      let from = 0, open;
+      while ((open = src.indexOf(`<${c.name}`, from)) !== -1) {
+        from = open + c.name.length + 1;
+        const after = src[open + c.name.length + 1];
+        if (after && !/[\s/>]/.test(after)) continue;
+        const tag = sliceTag(src, open);
+        if (tag && tag.length <= 220 && !tag.includes('`')) found.push({ tag, file });
+        if (found.length > 400) break;
+      }
+    }
+    if (found.length < 5) continue;
+    // Group by prop-name signature; the winner must be a real majority habit.
+    const sigOf = (tag) => [...tag.matchAll(/[\s({]([A-Za-z_][\w-]*)=/g)].map((m) => m[1]).sort().join(',');
+    const groups = new Map();
+    for (const u of found) {
+      const s = sigOf(u.tag);
+      (groups.get(s) ?? groups.set(s, []).get(s)).push(u);
+    }
+    const [sig, top] = [...groups.entries()].sort((a, b) => b[1].length - a[1].length)[0];
+    if (top.length < 3 || top.length / found.length < 0.4) continue;
+    // The shortest real tag with the dominant signature is the cleanest quote.
+    const best = [...top].sort((a, b) => a.tag.length - b.tag.length)[0];
+    const selfClosed = /\/>\s*$/.test(best.tag);
+    c.usageExample = {
+      snippet: `${best.tag.replace(/\s+/g, ' ').trim()}${selfClosed ? '' : `…</${c.name}>`}`,
+      file: best.file,
+      matches: top.length,
+      total: found.length,
+      props: sig || null,
+    };
+  }
+
   return { components, totalDefined: components.length };
 }
+
+/**
+ * Slice a JSX opening tag from `<` to its matching `>`, string- and
+ * brace-aware so `onClick={() => a > b}` cannot end the tag early.
+ */
+function sliceTag(src, open) {
+  let depth = 0, str = null;
+  const limit = Math.min(src.length, open + 400);
+  for (let i = open; i < limit; i++) {
+    const c = src[i];
+    if (str) { if (c === str && src[i - 1] !== '\\') str = null; continue; }
+    if (QUOTES.has(c)) { str = c; continue; }
+    if (c === '{') depth++;
+    else if (c === '}') depth--;
+    else if (c === '>' && depth === 0) return src.slice(open, i + 1);
+  }
+  return 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.3.0';
+export const VERSION = '4.4.0';

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

@@ -78,10 +78,18 @@ const repoName = h.profile?.name ?? 'this repo';
     .sort((a, b) => b.usageCount - a.usageCount).slice(0, CAP.components);
   if (top.length) {
     section('Canonical components');
-    rule('Use these existing components instead of writing new ones:');
+    rule(compact
+      ? 'Use these existing components instead of writing new ones:'
+      : 'Use these existing components instead of writing new ones, the way this repo already uses them:');
     for (const c of top) {
       const props = !compact && c.propsHint?.named?.length ? ` · props: ${c.propsHint.named.slice(0, 4).join(', ')}` : '';
       lines.push(`  - \`<${c.name}>\` from \`${c.file}\` (used ${c.usageCount}x${props})`);
+      // Golden example: the repo's own most common real usage, quoted with a
+      // receipt. Full variant only; compact hosts trade examples for size.
+      const ex = c.usageExample;
+      if (!compact && ex) {
+        lines.push(`    - most common usage, as in \`${ex.file}\` (matching ${ex.matches} of ${ex.total} usages): \`${ex.snippet}\``);
+      }
     }
   }