roast-my-design-system 4.2.6 → 4.3.1

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
 
@@ -26,7 +26,7 @@ One scan powers all of it; the flags decide what lands on disk. Combine freely.
 |---|---|
 | `npx roast-my-design-system` | The scan and `design-system-roast.html`, opened in your browser |
 | `npx roast-my-design-system <path>` | Scan a different repo than the current directory |
-| `... --apply` | The generated agent rules injected straight into your `CLAUDE.md`, `AGENTS.md`, `.cursorrules` or `.cursor/rules/`, inside a marked block. Re-running replaces only that block, never your own text |
+| `... --apply` | The generated agent rules injected straight into every agent file you have: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.cursor/rules/`, `.windsurfrules` and `.github/copilot-instructions.md`, inside a marked block. Re-running replaces only that block, never your own text. Windsurf and Copilot get a compact variant sized for their limits |
 | `... --rules` | The same rules written to `design-system-rules.md` instead, for pasting by hand |
 | `... --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 |
@@ -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/bin/roast.mjs

@@ -55,8 +55,10 @@ Usage: npx roast-my-design-system [path] [options]
   --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
+                  AGENTS.md, .cursorrules, .cursor/rules/, .windsurfrules,
+                  .github/copilot-instructions.md) inside a marked block;
+                  re-running replaces only that block. Windsurf and Copilot
+                  get a compact variant sized for their limits
   --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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "roast-my-design-system",
-  "version": "4.2.6",
-  "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.3.1",
+  "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/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.2.6';
+export const VERSION = '4.3.1';

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

@@ -9,6 +9,12 @@
  *     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.
+ *   .windsurfrules                      -> COMPACT rules injected (Windsurf
+ *     caps rules files at a few thousand characters). Injected only when the
+ *     file already exists; .windsurf/rules/ (directory) gets its own file.
+ *   .github/copilot-instructions.md     -> COMPACT rules injected; created
+ *     when .github/ exists (Copilot chat and code review read this file, and
+ *     Copilot's guidance prefers short instructions).
  * 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>
@@ -30,17 +36,20 @@ 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}`;
+// Size-aware variant for hosts with tight practical limits (Windsurf, Copilot)
+const compactText = rulesMarkdown(h, { compact: true }).text;
+const blockOf = (t) => `${BEGIN}\n\n${t.trim()}\n\n${END}`;
+const block = blockOf(text);
 
 /** Inject or replace our marked block in an existing file's content. */
-function inject(content) {
+function inject(content, b0 = block) {
   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' };
+    return { next: content.slice(0, b) + b0 + 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' };
+  return { next: content + sep + b0 + '\n', how: 'added' };
 }
 
 const done = [];
@@ -60,10 +69,39 @@ if (existsSync(cursorDir) && statSync(cursorDir).isDirectory()) {
   done.push(`.cursor/rules/design-system-rules.mdc (${existed ? 'rewritten' : 'created'})`);
 }
 
+// Windsurf: the compact variant, because .windsurfrules has a hard character
+// cap. Injected only into a file the user already has; a .windsurf/rules/
+// directory gets its own file, same as Cursor's.
+const windsurfFile = join(target, '.windsurfrules');
+if (existsSync(windsurfFile) && statSync(windsurfFile).isFile()) {
+  const { next, how } = inject(readFileSync(windsurfFile, 'utf8'), blockOf(compactText));
+  writeFileSync(windsurfFile, next);
+  done.push(`.windsurfrules (${how} the compact rules block)`);
+}
+const windsurfDir = join(target, '.windsurf', 'rules');
+if (existsSync(windsurfDir) && statSync(windsurfDir).isDirectory()) {
+  const p = join(windsurfDir, 'design-system-rules.md');
+  const existed = existsSync(p);
+  writeFileSync(p, `${compactText.trim()}\n`);
+  done.push(`.windsurf/rules/design-system-rules.md (${existed ? 'rewritten' : 'created'})`);
+}
+
+// Copilot chat and code review read .github/copilot-instructions.md, and
+// Copilot's guidance prefers short instructions: compact variant, created
+// when .github/ exists (a strong signal the repo lives on GitHub).
+const githubDir = join(target, '.github');
+if (existsSync(githubDir) && statSync(githubDir).isDirectory()) {
+  const p = join(githubDir, 'copilot-instructions.md');
+  const existing = existsSync(p) && statSync(p).isFile() ? readFileSync(p, 'utf8') : '';
+  const { next, how } = inject(existing, blockOf(compactText));
+  writeFileSync(p, next);
+  done.push(`.github/copilot-instructions.md (${existing ? `${how} the compact rules block` : '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(`No agent file found (CLAUDE.md, AGENTS.md, .cursorrules, .cursor/rules/, .windsurfrules, .github/).`);
   console.log(`✓ Wrote design-system-rules.md instead; point your agent at it.`);
 } else {
   console.log(`✓ ${ruleCount} rules applied, every one with a receipt:`);

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

@@ -9,7 +9,13 @@ import { nearColorPairs } from './../lib/nearpairs.mjs';
 import { neverImportedComponents } from '../lib/neverimported.mjs';
 import { VERSION } from '../lib/version.mjs';
 
-export function rulesMarkdown(h) {
+export function rulesMarkdown(h, opts = {}) {
+  // compact: the size-aware variant for agent files with tight practical
+  // limits (.windsurfrules caps out at a few thousand characters and Copilot's
+  // guidance prefers short instructions). Fewer receipts per rule, no prose
+  // preamble, and a hard character budget as a safety net. Same rules, tighter.
+  const compact = opts.compact === true;
+  const CAP = { components: compact ? 5 : 8, dupes: compact ? 3 : 6 };
 const repoName = h.profile?.name ?? 'this repo';
   const t = h.tokens ?? {};
   const reusable = (h.components ?? []).filter((c) => !c.isPage);
@@ -21,18 +27,24 @@ const repoName = h.profile?.name ?? 'this repo';
   
   lines.push('## Design system rules');
   lines.push('');
-  lines.push(`<!-- Generated by roast-my-design-system from a scan of ${repoName} on ${scanDate}.`);
-  lines.push('     Paste into CLAUDE.md, .cursor/rules or AGENTS.md. Regenerate after big refactors:');
-  lines.push('     npx roast-my-design-system --rules -->');
-  lines.push('');
+  if (!compact) {
+    lines.push(`<!-- Generated by roast-my-design-system from a scan of ${repoName} on ${scanDate}.`);
+    lines.push('     Paste into CLAUDE.md, .cursor/rules or AGENTS.md. Regenerate after big refactors:');
+    lines.push('     npx roast-my-design-system --rules -->');
+    lines.push('');
+  }
   // Mirror of the report's "no design system" banner: with almost no colour or
   // spacing signal there is nothing to derive receipts from, so the preamble
   // must not claim any. Keep the two universal defaults, labelled as defaults.
   const spacingSignal = (t.spacing ?? []).length + (t.tailwind?.spacing ?? []).filter((v) => v.value.startsWith('[')).length;
   const noSystemLikely = (t.colors ?? []).length === 0 || ((t.colors ?? []).length < 3 && spacingSignal === 0);
   lines.push(noSystemLikely
-    ? 'The scan found too little styling in this repo to derive repo-specific rules; there is most likely no design system in here yet. The rules below are universal defaults, not findings. Rescan once real UI lands and they will be rebuilt from receipts.'
-    : 'Follow these rules when writing or editing UI in this repo. Every rule below was derived from a scan of this codebase, with real paths and usage counts.');
+    ? (compact
+      ? 'Too little styling found to derive repo-specific rules; these are universal defaults. Rescan once real UI lands.'
+      : 'The scan found too little styling in this repo to derive repo-specific rules; there is most likely no design system in here yet. The rules below are universal defaults, not findings. Rescan once real UI lands and they will be rebuilt from receipts.')
+    : (compact
+      ? `Follow these rules when writing or editing UI in this repo; derived from a scan on ${scanDate}.`
+      : 'Follow these rules when writing or editing UI in this repo. Every rule below was derived from a scan of this codebase, with real paths and usage counts.'));
   
   // ---------- tokens ----------
   const strays = (t.colors ?? []).filter((c) => !c.isToken);
@@ -63,12 +75,12 @@ const repoName = h.profile?.name ?? 'this repo';
   for (const c of reusable) nameCounts.set(c.name, (nameCounts.get(c.name) ?? 0) + 1);
   const top = reusable
     .filter((c) => c.usageCount > 0 && !FRAMEWORK_NAMES.has(c.name) && nameCounts.get(c.name) === 1)
-    .sort((a, b) => b.usageCount - a.usageCount).slice(0, 8);
+    .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:');
     for (const c of top) {
-      const props = c.propsHint?.named?.length ? ` · props: ${c.propsHint.named.slice(0, 4).join(', ')}` : '';
+      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})`);
     }
   }
@@ -81,7 +93,7 @@ const repoName = h.profile?.name ?? 'this repo';
     // No per-file usage data here, so rank by how shared the location looks;
     // when nothing stands out, do not guess a canonical.
     const sharedScore = (f) => (f.includes('packages/') ? 4 : 0) + (/\/ui\//.test(f) ? 2 : 0) + (f.includes('components/') ? 1 : 0) - (/\bapp\//.test(f) ? 2 : 0) - (f.includes('/icons/') ? 4 : 0);
-    for (const d of dupes.slice(0, 6)) {
+    for (const d of dupes.slice(0, CAP.dupes)) {
       const files = d.files.map((f) => (typeof f === 'string' ? f : f.file));
       const ranked = [...files].sort((a, b) => sharedScore(b) - sharedScore(a));
       const clear = sharedScore(ranked[0]) > sharedScore(ranked[1]);
@@ -129,10 +141,23 @@ if (neverImported.length >= 3) {
   rule('Before styling anything new, look at a neighbouring component and match how it does it. Consistency with the repo beats personal preference.');
   
   lines.push('');
-  lines.push('---');
-  lines.push(`*Generated by [roast-my-design-system](https://github.com/pencilrebel/roast-my-design-system) ver. ${VERSION}. Rescan after refactors to keep these rules honest.*`);
+  if (compact) {
+    lines.push(`*Compact rules by roast-my-design-system ver. ${VERSION}; the full set with receipts: npx roast-my-design-system --rules*`);
+  } else {
+    lines.push('---');
+    lines.push(`*Generated by [roast-my-design-system](https://github.com/pencilrebel/roast-my-design-system) ver. ${VERSION}. Rescan after refactors to keep these rules honest.*`);
+  }
   lines.push('');
-  const text = lines.join('\n');
-  const ruleCount = lines.filter((l) => l.startsWith('- ')).length;
+  let text = lines.join('\n');
+  // Safety net for tight hosts: if a very messy repo still blows the budget,
+  // cut at the last section boundary under the cap and say the set continues.
+  const MAX_COMPACT = 5000;
+  if (compact && text.length > MAX_COMPACT) {
+    const cut = text.lastIndexOf('\n### ', MAX_COMPACT);
+    if (cut > 0) {
+      text = `${text.slice(0, cut).trimEnd()}\n\n*Trimmed to fit this file's limits; the full rules: npx roast-my-design-system --rules*\n`;
+    }
+  }
+  const ruleCount = text.split('\n').filter((l) => l.startsWith('- ')).length;
   return { text, ruleCount };
 }