roast-my-design-system 3.2.0

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

@@ -0,0 +1,189 @@
+/**
+ * Component harvest — every component defined in the repo, with its REAL prop
+ * signature and where it is actually used. Parsers lifted from 1.0's
+ * compile-skill.mjs (proffer-spine/tools) — brace/string-aware regex parsing,
+ * no AST dependency — then extended to scan the whole repo, not one ui/ dir.
+ */
+import { readFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+
+const QUOTES = new Set(['"', "'", '`']);
+
+// ---- brace/string-aware helpers (verbatim from 1.0) ----
+export function sliceObject(text, from) {
+  const open = text.indexOf('{', from);
+  if (open === -1) return null;
+  let depth = 0, str = null;
+  for (let i = open; i < text.length; i++) {
+    const c = text[i];
+    if (str) { if (c === str && text[i - 1] !== '\\') str = null; continue; }
+    if (QUOTES.has(c)) { str = c; continue; }
+    if (c === '{') depth++;
+    else if (c === '}') { depth--; if (depth === 0) return { inner: text.slice(open + 1, i), end: i }; }
+  }
+  return null;
+}
+function topLevelKeys(inner) {
+  const keys = [];
+  let depth = 0, str = null, i = 0;
+  while (i < inner.length) {
+    const c = inner[i];
+    if (str) { if (c === str && inner[i - 1] !== '\\') str = null; i++; continue; }
+    if (QUOTES.has(c)) { str = c; i++; continue; }
+    if (c === '{' || c === '(' || c === '[') depth++;
+    else if (c === '}' || c === ')' || c === ']') depth--;
+    else if (depth === 0 && (i === 0 || /[\s,{]/.test(inner[i - 1]))) {
+      const m = /^([A-Za-z_][\w-]*)\s*:/.exec(inner.slice(i));
+      if (m) { keys.push(m[1]); i += m[0].length; continue; }
+    }
+    i++;
+  }
+  return [...new Set(keys)];
+}
+function topLevelColon(s) {
+  let depth = 0, str = null;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (str) { if (c === str && s[i - 1] !== '\\') str = null; continue; }
+    if (QUOTES.has(c)) { str = c; continue; }
+    if ('{<(['.includes(c)) depth++;
+    else if ('}>)]'.includes(c)) depth--;
+    else if (c === ':' && depth === 0) return i;
+  }
+  return -1;
+}
+
+// ---- extraction (from 1.0, generalized) ----
+function extractVariants(src) {
+  const idx = src.indexOf('variants:');
+  if (idx === -1) return {};
+  const block = sliceObject(src, idx);
+  if (!block) return {};
+  const out = {};
+  for (const group of topLevelKeys(block.inner)) {
+    const gi = block.inner.indexOf(`${group}:`);
+    const gb = sliceObject(block.inner, gi);
+    if (gb) out[group] = topLevelKeys(gb.inner);
+  }
+  return out;
+}
+
+function extractPropsHint(src, name) {
+  const sig = new RegExp(`function\\s+${name}\\s*\\(([\\s\\S]*?)\\)\\s*\\{`).exec(src)
+           || new RegExp(`const\\s+${name}\\s*=[\\s\\S]{0,120}?\\(\\s*([\\s\\S]*?)\\)\\s*=>`).exec(src);
+  if (!sig) return null;
+  const params = sig[1].trim();
+  const colon = topLevelColon(params);
+  const destructure = colon > -1 ? params.slice(0, colon) : params;
+  const typeAnno = (colon > -1 ? params.slice(colon + 1) : '').trim().replace(/\s+/g, ' ');
+  const skip = new Set(['className', 'children', 'props', 'ref', 'key',
+    'true', 'false', 'null', 'undefined']); // default-value literals, not props
+  const named = [...new Set([...destructure.matchAll(/([A-Za-z_]\w*)\s*(?=[,}=:])/g)].map((m) => m[1]))]
+    .filter((n) => !skip.has(n));
+  return (typeAnno || named.length) ? { type: typeAnno || null, named } : null;
+}
+
+/** Capitalized components DEFINED in a source file (declared, not just re-exported). */
+function definedComponents(src) {
+  const names = new Set();
+  for (const m of src.matchAll(/export\s+(?:default\s+)?(?:async\s+)?function\s+([A-Z]\w*)/g)) names.add(m[1]);
+  for (const m of src.matchAll(/export\s+const\s+([A-Z]\w*)\s*(?::[^=]+)?=\s*([^\s;]{1,40})/g)) {
+    // ALL_CAPS names are constants; a value starting with a literal
+    // ({...}, [...], "...", 42) is data, not a component
+    if (/^[A-Z][A-Z0-9_]+$/.test(m[1])) continue;
+    if (/^[\[{'"`0-9]/.test(m[2])) continue;
+    names.add(m[1]);
+  }
+  // Class components (CRA/redux-era): `class Login extends React.Component`
+  for (const m of src.matchAll(/class\s+([A-Z]\w*)\s+extends\s+(?:React\.)?(?:Pure)?Component/g)) names.add(m[1]);
+  // `export default Foo` / `export default connect(...)(Foo)` — the LAST
+  // capitalized identifier on the line is the component being exported.
+  for (const m of src.matchAll(/export\s+default\s+([^\n;]{1,200})/g)) {
+    const ids = m[1].match(/\b[A-Z]\w*/g);
+    const last = ids?.[ids.length - 1];
+    if (last && new RegExp(`(?:function|const|class)\\s+${last}\\b`).test(src)) names.add(last);
+  }
+  // `function Foo(...)` declared then exported via `export { Foo }`
+  const exported = new Set();
+  for (const m of src.matchAll(/export\s*\{([^}]*)\}/g)) {
+    for (const part of m[1].split(',')) {
+      const n = part.trim().split(/\s+as\s+/).pop().trim().replace(/^type\s+/, '');
+      if (/^[A-Z]\w*$/.test(n)) exported.add(n);
+    }
+  }
+  for (const n of exported) {
+    if (new RegExp(`(?:function|const)\\s+${n}\\b`).test(src)) names.add(n);
+  }
+  // Only keep names that render JSX or wrap a primitive (heuristic: file has JSX at all)
+  return [...names];
+}
+
+const looksLikeJSXFile = (src) => /<[A-Za-z][\w.]*[\s/>]/.test(src);
+
+/** Count real `<Name` tag usages of `name` in `src` (tag boundary checked). */
+function countUsages(src, name) {
+  let count = 0, from = 0, open;
+  while ((open = src.indexOf(`<${name}`, from)) !== -1) {
+    const after = src[open + name.length + 1];
+    if (!after || /[\s/>]/.test(after)) count++;
+    from = open + name.length + 1;
+  }
+  return count;
+}
+
+/**
+ * Harvest all components: definitions (with variants/props) + usages across the
+ * repo. `codeFiles` are relative paths; returns { components, totalDefined }.
+ */
+export function harvestComponents(root, codeFiles) {
+  // .js too — CRA-era repos (a big slice of the messy-repo audience) put JSX in
+  // plain .js files; requiring .tsx/.jsx made whole repos read as empty.
+  const jsxFiles = codeFiles.filter((f) => /\.(tsx|jsx|js)$/.test(f));
+  const sources = new Map();
+  for (const f of jsxFiles) {
+    try {
+      const src = readFileSync(join(root, f), 'utf8');
+      if (looksLikeJSXFile(src)) sources.set(f, src);
+    } catch { /* skip */ }
+  }
+
+  // Pass 1: definitions
+  const components = [];
+  for (const [file, src] of sources) {
+    if (!looksLikeJSXFile(src)) continue;
+    const isPage = /(^|\/)(app\/.*page|pages\/(?!_app|_document|api))/.test(file)
+      || /(^|\/)app\/.*\/(layout|template|error|loading)\.(tsx|jsx)$/.test(file);
+    for (const name of definedComponents(src)) {
+      components.push({
+        name,
+        file,
+        isPage,
+        variants: extractVariants(src),
+        propsHint: extractPropsHint(src, name),
+        usageCount: 0,
+        usedIn: [],
+      });
+    }
+  }
+
+  // Pass 2: usages (skip the defining file's own render of itself is fine to count)
+  const byName = new Map();
+  for (const c of components) {
+    if (!byName.has(c.name)) byName.set(c.name, []);
+    byName.get(c.name).push(c);
+  }
+  for (const [file, src] of sources) {
+    for (const [name, defs] of byName) {
+      const n = countUsages(src, name);
+      if (n === 0) continue;
+      for (const def of defs) {
+        if (def.file === file) continue; // internal render/recursion, not adoption
+        def.usageCount += n;
+        if (def.usedIn.length < 8) def.usedIn.push(file);
+      }
+    }
+  }
+
+  components.sort((a, b) => b.usageCount - a.usageCount || a.name.localeCompare(b.name));
+  return { components, totalDefined: components.length };
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Context-file harvest — the agent-facing and design-facing docs the repo
+ * already has. Step 5 (wire up their agent) needs to know what exists so it
+ * extends rather than clobbers; the diagnosis mentions what's missing.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const CONTEXT_FILES = [
+  { file: 'CLAUDE.md',        kind: 'agent-rules', tool: 'Claude Code' },
+  { file: 'AGENTS.md',        kind: 'agent-rules', tool: 'generic (AGENTS.md standard)' },
+  { file: '.cursorrules',     kind: 'agent-rules', tool: 'Cursor (legacy format)' },
+  { file: '.cursor/rules',    kind: 'agent-rules', tool: 'Cursor', dir: true },
+  { file: '.github/copilot-instructions.md', kind: 'agent-rules', tool: 'GitHub Copilot' },
+  { file: '.windsurfrules',   kind: 'agent-rules', tool: 'Windsurf' },
+  { file: 'components.json',  kind: 'design-config', tool: 'shadcn/ui' },
+  { file: 'tailwind.config.js',  kind: 'design-config', tool: 'Tailwind' },
+  { file: 'tailwind.config.ts',  kind: 'design-config', tool: 'Tailwind' },
+  { file: 'design-system.md', kind: 'design-doc' },
+  { file: 'DESIGN.md',        kind: 'design-doc' },
+  { file: 'STYLEGUIDE.md',    kind: 'design-doc' },
+];
+
+export function harvestContext(root) {
+  const found = [];
+  for (const c of CONTEXT_FILES) {
+    const p = join(root, c.file);
+    if (!existsSync(p)) continue;
+    let size = 0, mentionsDesign = false;
+    try {
+      const st = statSync(p);
+      if (c.dir || st.isDirectory()) { found.push({ ...c, size: null, mentionsDesign: null }); continue; }
+      size = st.size;
+      if (size < 200_000) {
+        const text = readFileSync(p, 'utf8').toLowerCase();
+        mentionsDesign = /design system|component|token|color|colour|styling|tailwind|css/.test(text);
+      }
+    } catch { /* unreadable */ }
+    found.push({ file: c.file, kind: c.kind, tool: c.tool ?? null, size, mentionsDesign });
+  }
+  return found;
+}

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

@@ -0,0 +1,153 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Duplicate detection — the "4 Button implementations" finder. Two signals:
+ *
+ * 1. Same-name components defined in different files (Button in ui/button.tsx
+ *    AND legacy/Button.jsx) — a straight duplicate.
+ * 2. Name families: components whose normalized names contain a shared root
+ *    (Button, PrimaryButton, IconBtn) — likely re-implementations of one idea.
+ *
+ * Both are heuristics for the diagnosis; the proposal step decides what merges.
+ */
+
+const norm = (name) => name.toLowerCase().replace(/[^a-z]/g, '');
+
+// Common roots worth clustering on. Order matters: longest match wins.
+const ROOTS = [
+  'button', 'btn', 'input', 'textfield', 'select', 'dropdown', 'modal', 'dialog',
+  'card', 'badge', 'chip', 'tag', 'tooltip', 'popover', 'table', 'list', 'menu',
+  'nav', 'header', 'footer', 'sidebar', 'tabs', 'tab', 'accordion', 'alert',
+  'toast', 'notification', 'avatar', 'spinner', 'loader', 'checkbox',
+  'radio', 'switch', 'toggle', 'slider', 'progress', 'form', 'label', 'link',
+];
+// Roots that are aliases of each other (btn → button, dialog ↔ modal…)
+// NB: 'icon' is deliberately NOT a root — an icon set is a glyph library
+// (Excalidraw has 100+), not duplication to consolidate.
+const ALIASES = { btn: 'button', dialog: 'modal', loader: 'spinner', tab: 'tabs', notification: 'toast' };
+
+// CamelCase words of a component name: "DownlinkPanel" → ["downlink","panel"].
+// A root must match a WHOLE word — "link" must not match inside "Downlink".
+const camelWords = (name) => name.split(/(?=[A-Z])/).map((w) => w.toLowerCase()).filter(Boolean);
+
+function rootOf(name) {
+  const words = camelWords(name);
+  for (const r of ROOTS) {
+    if (words.includes(r)) return ALIASES[r] ?? r;
+  }
+  return null;
+}
+
+// Framework-boilerplate exports that recur by design, not by accident.
+const NOT_DUPLICATES = new Set(['Route', 'Layout', 'App', 'Providers', 'Provider',
+  // Next.js route-handler exports — HTTP verbs, never components.
+  'GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
+
+// Route-colocated page fragments (app/**/form.tsx, header.tsx…) share names by
+// Next.js convention, not by duplication.
+const ROUTE_FRAGMENT_RE = /(^|\/)app\/.*\/(form|header|footer|nav|page|layout|loading|error|route)\.[jt]sx?$/;
+
+/**
+ * @param components output of harvestComponents (non-page components matter most)
+ * @param uiDir the design-system dir if one exists (e.g. "src/components/ui")
+ * @param root repo root; when given, same-name pairs where one file imports the
+ *   name from the other are tagged wrapped:true (composition, not competition)
+ * @returns { exactDuplicates: [{name, files, wrapped?}], families: [{root, members: [{name, file, usageCount}]}] }
+ */
+export function findDuplicates(components, uiDir = null, root = null) {
+  // Email templates legitimately mirror web component names (email Footer !=
+  // web Footer); cross-matching them manufactures duplicates.
+  const EMAIL_PATH_RE = /(^|\/)emails?(\/|-)/i;
+  const comps = components.filter((c) => !c.isPage && !NOT_DUPLICATES.has(c.name)
+    && !ROUTE_FRAGMENT_RE.test(c.file) && !EMAIL_PATH_RE.test(c.file));
+
+  // 1. exact same component name defined in >1 file
+  const byName = new Map();
+  for (const c of comps) {
+    if (!byName.has(c.name)) byName.set(c.name, []);
+    byName.get(c.name).push(c);
+  }
+  let exactDuplicates = [...byName.entries()]
+    .filter(([, defs]) => new Set(defs.map((d) => d.file)).size > 1)
+    .map(([name, defs]) => ({
+      name,
+      files: [...new Set(defs.map((d) => d.file))],
+      totalUsages: defs.reduce((s, d) => s + d.usageCount, 0),
+    }))
+    .sort((a, b) => b.files.length - a.files.length);
+
+  // Same-name components living in different icons/ directories are ONE
+  // problem — two icon libraries colliding — not N separate duplicates.
+  const ICON_DIR_RE = /(^|\/)icons?\//i;
+  const iconCollisions = exactDuplicates.filter((d) => d.files.every((f) => ICON_DIR_RE.test(f)));
+  exactDuplicates = exactDuplicates.filter((d) => !iconCollisions.includes(d));
+
+  // A "duplicate" where one file imports the same identifier from the other is
+  // a wrapper/composition (memoized variant, styled passthrough) — still an
+  // agent trap worth listing, but not a competing implementation.
+  const perFile = new Map();
+  for (const c of comps) perFile.set(c.file, (perFile.get(c.file) ?? 0) + 1);
+  if (root) {
+    for (const d of exactDuplicates) {
+      if (d.files.length !== 2) continue;
+      // A file defining 8+ components is an API surface (menu-item variants of
+      // real components elsewhere) — same-name there is deliberate, not a copy.
+      if (d.files.some((f) => (perFile.get(f) ?? 0) >= 8)) { d.wrapped = true; continue; }
+      const base = (f) => f.replace(/\.[jt]sx?$/, '').split('/').pop();
+      // Wrapper evidence must be strong: the same name imported ALIASED
+      // (`EmptyState as EmptyStateBlock`) — a bare same-name import next to a
+      // competing local definition would be a redeclaration error anyway, and
+      // a loose match here would excuse real duplicates.
+      const importsAliased = (fromFile, name, otherBase) => {
+        let src; try { src = readFileSync(join(root, fromFile), 'utf8'); } catch { return false; }
+        return new RegExp(`import\\s*(?:type\\s*)?{[^}]*\\b${name}\\s+as\\s+\\w+[^}]*}\\s*from`).test(src)
+          || new RegExp(`import\\s*(?:type\\s*)?{[^}]*\\b${name}\\b[^}]*}\\s*from\\s*['"][^'"]*${otherBase}['"]`).test(src);
+      };
+      const [a, b] = d.files;
+      if (importsAliased(a, d.name, base(b)) || importsAliased(b, d.name, base(a))) d.wrapped = true;
+    }
+  }
+
+  // 2. name families around a shared root (only interesting with >1 distinct component)
+  const byRoot = new Map();
+  for (const c of comps) {
+    const r = rootOf(c.name);
+    if (!r) continue;
+    if (!byRoot.has(r)) byRoot.set(r, []);
+    byRoot.get(r).push(c);
+  }
+  const families = [...byRoot.entries()]
+    .map(([root, members]) => {
+      const uniq = new Map();
+      for (const m of members) uniq.set(`${m.name}::${m.file}`, m);
+      return { root, members: [...uniq.values()].map((m) => ({ name: m.name, file: m.file, usageCount: m.usageCount })) };
+    })
+    // A compound component (DialogHeader/DialogTitle/… in ONE file) is good
+    // structure, not duplication — require multiple files. And when the repo
+    // HAS a ui/ dir, sibling primitives inside it (ContextMenu vs Menubar) are
+    // the library, not duplication: only flag families that CROSS the boundary
+    // (a re-implementation outside echoing a root that exists inside).
+    .filter((f) => {
+      if (new Set(f.members.map((m) => m.name)).size < 2) return false;
+      if (new Set(f.members.map((m) => m.file)).size < 2) return false;
+      if (!uiDir) return true;
+      const inside = f.members.filter((m) => m.file.startsWith(uiDir));
+      const outside = f.members.filter((m) => !m.file.startsWith(uiDir));
+      if (inside.length === 0 || outside.length === 0) return false;
+      // The inside anchor must BE the root primitive (Card, Form) — a compound
+      // part that merely contains the word (BreadcrumbList) is not a List
+      // primitive, and outside echoes of it are not duplication.
+      const canonical = inside.filter((m) => norm(m.name) === f.root
+        || Object.entries(ALIASES).some(([a, r]) => r === f.root && norm(m.name) === a));
+      if (canonical.length === 0) return false;
+      f.members = [...canonical, ...outside];
+      return true;
+    })
+    // Past ~8 members a "family" is a generic word (Input matching 37
+    // components), not a consolidation target — noise that costs credibility.
+    .filter((f) => f.members.length <= 8)
+    .sort((a, b) => b.members.length - a.members.length);
+
+  return { exactDuplicates, iconCollisions, families };
+}

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

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Harvest — step 1 of the Proffer pipeline. Non-destructive scan of a repo:
+ * components (real props, real usages), all styling, implicit tokens with
+ * frequency counts, duplicates, context files. Writes harvest.json; prints a
+ * one-screen summary (the seed of the step-2 diagnosis).
+ *
+ *   node src/harvest/index.mjs <repo-path> [--out harvest.json]
+ */
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { walkRepo, profileRepo } from './walk.mjs';
+import { harvestComponents } from './components.mjs';
+import { harvestTokens } from './tokens.mjs';
+import { findDuplicates } from './duplicates.mjs';
+import { harvestContext } from './context.mjs';
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i > -1 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
+}
+
+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]');
+  process.exit(1);
+}
+const outPath = resolve(arg('out', 'harvest.json'));
+
+const t0 = Date.now();
+const files = walkRepo(target);
+const profile = profileRepo(target, files);
+const { components } = harvestComponents(target, files.code);
+const tokens = harvestTokens(target, files.styles, files.code);
+const duplicates = findDuplicates(components, profile.uiDir, target);
+const context = harvestContext(target);
+
+const harvest = {
+  repo: target,
+  harvestedAt: new Date().toISOString(),
+  tookMs: null, // set below
+  profile,
+  files: {
+    code: files.code.length,
+    styles: files.styles.length,
+    styleFiles: files.styles,
+  },
+  components,
+  tokens,
+  duplicates,
+  context,
+};
+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('#'));
+const top = (list, n = 5) => list.slice(0, n).map((e) => `${e.value} ×${e.count}`).join(', ');
+
+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`);
+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: ${top(tokens.colors, 4)}`);
+console.log(`  spacing: ${tokens.spacing.length} distinct CSS values   top: ${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'}`);
+console.log(`\n  → ${outPath}   (${harvest.tookMs}ms)\n`);