roast-my-design-system 4.2.5 → 4.3.0

package/README.md

@@ -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 |

package/bin/roast.mjs

@@ -12,7 +12,7 @@ import { spawnSync } from 'node:child_process';
 import { mkdtempSync, rmSync, readFileSync, existsSync, statSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const SCRIPTS = join(HERE, '../skills/roast-my-design-system/scripts');
@@ -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
@@ -115,6 +117,19 @@ say('');
 run('diagnose/index.mjs', [harvestPath, '--out', outPath, '--theme', theme, '--summary', summaryPath,
   ...(commissionedBy ? ['--by', commissionedBy] : [])]);
 
+// The verdict leads, the evidence follows: harvest details print here, after
+// the diagnosis, rendered from harvest.json via the same lines the direct
+// harvest run uses.
+if (!asJson) {
+  try {
+    const harvestData = JSON.parse(readFileSync(harvestPath, 'utf8'));
+    const { detailLines } = await import(pathToFileURL(join(SCRIPTS, 'harvest/summary.mjs')).href);
+    console.log('');
+    for (const l of detailLines(harvestData)) console.log(l);
+    console.log(`\n  scanned in ${harvestData.tookMs}ms`);
+  } catch { /* details are garnish; the report exists either way */ }
+}
+
 const rulesPath = resolve(join(target, 'design-system-rules.md'));
 if (wantRules) {
   say('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "4.2.5",
+  "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.",
   "keywords": [
     "design-system",

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

@@ -15,6 +15,7 @@
 import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { walkRepo, profileRepo } from './walk.mjs';
+import { headerLines, detailLines } from './summary.mjs';
 import { harvestComponents } from './components.mjs';
 import { harvestTokens } from './tokens.mjs';
 import { findDuplicates } from './duplicates.mjs';
@@ -157,47 +158,12 @@ harvest.tookMs = Date.now() - t0;
 writeFileSync(outPath, JSON.stringify(harvest, null, 2));
 
 // ---------- one-screen summary ----------
-const nonPage = components.filter((c) => !c.isPage);
-const hexColors = tokens.colors.filter((c) => c.value.startsWith('#'));
-// A truncated capture like "rgba(var(--ink-rgb)" reads as a glitch in the
-// terminal; the token reference inside it is the real story, so show that.
-const showVal = (v) => {
-  const m = /var\((--[A-Za-z0-9_-]+)/.exec(v);
-  const balanced = (v.match(/\(/g) ?? []).length === (v.match(/\)/g) ?? []).length;
-  return m && !balanced ? `var(${m[1]})` : v;
-};
-// A "top" list is only news when something repeats; all-×1 says nothing.
-const top = (list, n = 5) => list.some((e) => e.count > 1)
-  ? `   top: ${list.slice(0, n).map((e) => `${showVal(e.value)} ×${e.count}`).join(', ')}`
-  : (list.length ? ', none repeated' : '');
-
-console.log(`Harvest: ${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) {
-  // Same voice as the report header: source named once, slashes on folders,
-  // and the total at the end because that is the number that lands.
-  const groups = [...new Set(exclusions.patterns.map((p) => p.source))].map((src) => {
-    const own = exclusions.patterns.filter((p) => p.source === src);
-    return `(${src}): ${own.map((p, i) => `${p.pattern}/ ${p.files}${i === 0 ? ' files' : ''}`).join(', ')}`;
-  });
-  const total = exclusions.patterns.reduce((sum, p) => sum + p.files, 0);
-  console.log(`  excluded by you ${groups.join(' · ')} · ${total} files kept out of this scan`);
-}
-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`);
-for (const f of duplicates.families.slice(0, 3)) console.log(`    · ${f.root} family: ${f.members.map((m) => m.name).join(', ')}`);
-console.log(`\n  colours: ${tokens.colors.length} distinct (${hexColors.length} hex, of which ${tokens.greyCount} greys)${top(tokens.colors, 4)}`);
-console.log(`  spacing: ${tokens.spacing.length} distinct CSS values${top(tokens.spacing, 5)}`);
-console.log(`  radii: ${tokens.radii.length}   font sizes: ${tokens.fontSizes.length}   font families: ${tokens.fontFamilies.length}   shadows: ${tokens.shadows.length}`);
-console.log(`  tailwind: ${tokens.tailwind.colors.length} colour utils, ${tokens.tailwind.spacing.length} spacing utils, ${tokens.tailwind.textSizes.length} text sizes`);
-console.log(`  inline styles: ${tokens.inlineStyles.count} blocks`);
-console.log(`  context files: ${context.map((c) => c.file).join(', ') || 'none'}`);
-// The npx wrapper writes the harvest to a temp dir it deletes right after;
-// pointing the user at a path that will not exist is noise there.
-if (process.env.ROAST_EPHEMERAL_OUT === '1') {
-  console.log(`\n  scanned in ${harvest.tookMs}ms`);
-} else {
+// The npx wrapper reorders the story (header, then the diagnosis, then these
+// details), so the lines live in summary.mjs and the wrapper prints details
+// itself from harvest.json. Run directly (the skill flow), everything prints
+// here in one go, with the real output path at the end.
+for (const l of headerLines(harvest)) console.log(l);
+if (process.env.ROAST_EPHEMERAL_OUT !== '1') {
+  for (const l of detailLines(harvest)) console.log(l);
   console.log(`\n  → ${outPath}   (${harvest.tookMs}ms)`);
 }

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

@@ -0,0 +1,61 @@
+/**
+ * Terminal summary lines for a harvest, split so the npx wrapper can change
+ * the running order: header first, diagnosis from step 2 next, details after.
+ * Running harvest/index.mjs directly (the skill flow) prints both in one go.
+ * Everything reads from the harvest object itself, so the wrapper can render
+ * details from harvest.json after the harvest process has exited.
+ */
+
+// A truncated capture like "rgba(var(--ink-rgb)" reads as a glitch in the
+// terminal; the token reference inside it is the real story, so show that.
+const showVal = (v) => {
+  const m = /var\((--[A-Za-z0-9_-]+)/.exec(v);
+  const balanced = (v.match(/\(/g) ?? []).length === (v.match(/\)/g) ?? []).length;
+  return m && !balanced ? `var(${m[1]})` : v;
+};
+
+// A "top" list is only news when something repeats; all-×1 says nothing.
+const top = (list, n = 5) => list.some((e) => e.count > 1)
+  ? `   top: ${list.slice(0, n).map((e) => `${showVal(e.value)} ×${e.count}`).join(', ')}`
+  : (list.length ? ', none repeated' : '');
+
+export function headerLines(h) {
+  const p = h.profile;
+  return [
+    `Harvest: ${p.name ?? h.repo}`,
+    `  → framework: ${p.framework}${p.typescript ? ' + TS' : ''}   design system: ${p.designSystem.kind}${p.designSystem.name ? ` (${p.designSystem.name})` : ''}   styling: ${p.stylingDeps.join(', ') || 'none detected'}`,
+  ];
+}
+
+export function detailLines(h) {
+  const lines = [];
+  const components = h.components ?? [];
+  const duplicates = h.duplicates ?? { exactDuplicates: [], families: [] };
+  const tokens = h.tokens;
+  const nonPage = components.filter((c) => !c.isPage);
+  const hexColors = tokens.colors.filter((c) => c.value.startsWith('#'));
+
+  lines.push(`  files: ${h.files.code} code, ${h.files.styles} style`);
+  if (h.exclusions?.patterns?.length) {
+    // Same voice as the report header: source named once, slashes on folders,
+    // and the total at the end because that is the number that lands.
+    const groups = [...new Set(h.exclusions.patterns.map((p) => p.source))].map((src) => {
+      const own = h.exclusions.patterns.filter((p) => p.source === src);
+      return `(${src}): ${own.map((p, i) => `${p.pattern}/ ${p.files}${i === 0 ? ' files' : ''}`).join(', ')}`;
+    });
+    lines.push(`  excluded by you ${groups.join(' · ')} · ${h.exclusions.filesExcluded} files kept out of this scan`);
+  }
+  lines.push('');
+  lines.push(`  components: ${components.length} defined (${nonPage.length} reusable, ${components.length - nonPage.length} pages)`);
+  lines.push(`  duplicates: ${duplicates.exactDuplicates.length} exact same-name, ${duplicates.families.length} name families`);
+  for (const d of duplicates.exactDuplicates.slice(0, 3)) lines.push(`    · ${d.name} defined in ${d.files.length} files`);
+  for (const f of duplicates.families.slice(0, 3)) lines.push(`    · ${f.root} family: ${f.members.map((m) => m.name).join(', ')}`);
+  lines.push('');
+  lines.push(`  colours: ${tokens.colors.length} distinct (${hexColors.length} hex, of which ${tokens.greyCount} greys)${top(tokens.colors, 4)}`);
+  lines.push(`  spacing: ${tokens.spacing.length} distinct CSS values${top(tokens.spacing, 5)}`);
+  lines.push(`  radii: ${tokens.radii.length}   font sizes: ${tokens.fontSizes.length}   font families: ${tokens.fontFamilies.length}   shadows: ${tokens.shadows.length}`);
+  lines.push(`  tailwind: ${tokens.tailwind.colors.length} colour utils, ${tokens.tailwind.spacing.length} spacing utils, ${tokens.tailwind.textSizes.length} text sizes`);
+  lines.push(`  inline styles: ${tokens.inlineStyles.count} blocks`);
+  lines.push(`  context files: ${(h.context ?? []).map((c) => c.file).join(', ') || 'none'}`);
+  return lines;
+}

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.5';
+export const VERSION = '4.3.0';

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 };
 }