roast-my-design-system 9.2.0 → 9.2.1

package/README.md

@@ -17,7 +17,7 @@ npx roast-my-design-system@latest
 Run it at the root of a UI repo. One second later, a report opens.
 No account. No network. No telemetry. Nothing in your repo changes.
 
-**Current release: 9.1.** Version history in [CHANGELOG.md](CHANGELOG.md).
+**Current release: 9.2.** Version history in [CHANGELOG.md](CHANGELOG.md).
 
 ## The idea
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "9.2.0",
+  "version": "9.2.1",
   "mcpName": "io.github.gregkozakiewicz/roast-my-design-system",
   "description": "Your AI can write the UI. This makes sure it writes your UI. A deterministic scanner scores your design system 0-100 against 112 public repos, reads React and web components (Stencil, Lit), hands you a copy-paste fix prompt for each top finding, writes rules for Claude, Cursor, Copilot and Windsurf with --apply, and runs as a local MCP server with --mcp.",
   "keywords": [

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

@@ -158,7 +158,10 @@ export function definedComponents(src) {
   return [...names];
 }
 
-const looksLikeJSXFile = (src) => /<[A-Za-z][\w.]*[\s/>]/.test(src);
+// A file with no markup defines no component the report can count: a stub
+// returning null, a wrapper built with a factory call. Asked by the harvest
+// and by the live checks, so both read the same files as component files.
+export const looksLikeJSXFile = (src) => /<[A-Za-z][\w.]*[\s/>]/.test(src);
 
 // ---------- web components: the tag-registered world ----------
 // Stencil, Lit and raw customElements.define register components by TAG, and
@@ -241,6 +244,28 @@ function importedDef(src, file, name, defs, workspaces = [], aliases = []) {
   return null;
 }
 
+const JSX_FILE_RE = /\.(tsx|jsx|js)$/;
+
+/**
+ * Every component a file defines, by either door the harvest reads: a React
+ * component in a file with markup in it, and a web component registered by
+ * tag (Stencil, Lit, customElements.define), generated bindings left out.
+ * The live checks ask here, so a file defines for them what it defines for
+ * the report.
+ */
+export function componentNamesIn(src, file = null) {
+  // .js too, never .ts: a TypeScript generic reads like a tag, and the
+  // harvest takes React components from the same three extensions
+  const react = (!file || JSX_FILE_RE.test(file)) && looksLikeJSXFile(src) ? definedComponents(src) : [];
+  const web = GENERATED_RE.test(src.slice(0, 2000)) ? [] : webComponentDefs(src).map((d) => d.name);
+  return [...new Set([...react, ...web])];
+}
+
+// A page is a route, not a reusable part. Asked by the harvest for every file
+// it reads and by the live checks for the one file under review.
+export const isPageFile = (file) => /(^|\/)(app\/.*page|pages\/(?!_app|_document|api))/.test(file)
+  || /(^|\/)app\/.*\/(layout|template|error|loading)\.(tsx|jsx)$/.test(file);
+
 /**
  * Harvest all components: definitions (with variants/props) + usages across the
  * repo. `codeFiles` are relative paths; returns { components, totalDefined }.
@@ -248,7 +273,7 @@ function importedDef(src, file, name, defs, workspaces = [], aliases = []) {
 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 jsxFiles = codeFiles.filter((f) => JSX_FILE_RE.test(f));
   const sources = new Map();
   for (const f of jsxFiles) {
     const src = readSource(join(root, f));
@@ -259,8 +284,7 @@ export function harvestComponents(root, codeFiles) {
   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);
+    const isPage = isPageFile(file);
     for (const name of definedComponents(src)) {
       components.push({
         name,

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

@@ -54,8 +54,59 @@ const ROUTE_FRAGMENT_RE = /(^|\/)app\/.*\/(form|header|footer|nav|page|layout|lo
 // and _dashboard.analytics.tsx both export Page, 2026-09-17). A story is a
 // demo of a component, not a second implementation of it (medplum keeps a
 // MockDateWrapper in two stories folders).
-const ROUTE_FILE_RE = /(^|\/)routes\/[^/]+\.[jt]sx?$|(^|\/)(page|layout|route|loading|error|not-found|template|default)\.[jt]sx?$/;
+// Next.js's crash page is one more of these: every app in a monorepo has its
+// own global-error, and a starter keeps a second one in its templates folder
+// (9.2.1).
+const ROUTE_FILE_RE = /(^|\/)routes\/[^/]+\.[jt]sx?$|(^|\/)(page|layout|route|loading|error|global-error|not-found|template|default)\.[jt]sx?$/;
 const STORY_FILE_RE = /(^|\/)(stories|__stories__|\.storybook)\/|\.stories\.[jt]sx?$/;
+// Email templates legitimately mirror web component names (email Footer !=
+// web Footer); cross-matching them manufactures duplicates. An email folder
+// or file is one whose name carries "email" as a word of its own: emails/,
+// email-templates/, twenty-emails/, welcome-email.tsx. A screen about email
+// (ConfirmUserEmail, EmailInput) is interface and stays in (9.2.1: the rule
+// asked for the word at the start of the name and missed twenty-emails/).
+const EMAIL_PATH_RE = /(^|\/)(?:[a-z0-9]+[-_.])*emails?(?:[-_][a-z0-9]+)*(?:\/|\.[jt]sx?$)/i;
+// 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;
+
+/**
+ * Whether a definition can be a duplicate at all. The report's finder and the
+ * live checks both ask here, so a name the report lets repeat by design is
+ * never a finding on the file an agent just wrote (9.2.1: every TanStack
+ * route file was told its Route already existed in 40 places).
+ */
+export function canBeDuplicate({ name, file = '', isPage = false }) {
+  return !isPage && !NOT_DUPLICATES.has(name)
+    && !ROUTE_FRAGMENT_RE.test(file) && !ROUTE_FILE_RE.test(file)
+    && !STORY_FILE_RE.test(file) && !EMAIL_PATH_RE.test(file);
+}
+
+/**
+ * The other copies that make one definition a duplicate, or none. The live
+ * checks and the guard ask here, so their answer is the report's answer.
+ *
+ * A file the scan has read is settled by the report: the definition is a
+ * duplicate when the report counts the name and this file is one of the
+ * copies it counts. A wrapper, shadcn's own overlap inside the catalogue and
+ * two icon libraries colliding are listed by the report and never counted,
+ * so they are not findings on the file either. A file the scan has not read
+ * (content validated before it is saved) is judged on the copies that exist.
+ *
+ * @param def     { name, file, isPage } the definition under review
+ * @param copies  the ledger's entries for the name: [{ file, isPage, usageCount }]
+ * @param counted the files of the duplicate the report counts under the name,
+ *                or null when it counts none
+ * @param same    how two paths are compared (a guard matches on path tails)
+ */
+export function duplicateCopies({ name, file = '', isPage = false }, copies, counted = null, same = (a, b) => a === b) {
+  if (!canBeDuplicate({ name, file, isPage })) return [];
+  const others = (copies ?? []).filter((c) => !same(c.file, file) && canBeDuplicate({ ...c, name }));
+  if (!others.length) return [];
+  if ((copies ?? []).some((c) => same(c.file, file))) return (counted ?? []).some((f) => same(f, file)) ? others : [];
+  if (ICON_DIR_RE.test(file) && others.every((c) => ICON_DIR_RE.test(c.file))) return [];
+  return others;
+}
 
 /**
  * @param components output of harvestComponents (non-page components matter most)
@@ -66,12 +117,7 @@ const STORY_FILE_RE = /(^|\/)(stories|__stories__|\.storybook)\/|\.stories\.[jt]
  */
 export function findDuplicates(components, uiDir = null, root = null, uiDirs = null) {
   const catalogueDirs = uiDirs ?? (uiDir ? [uiDir] : []);
-  // 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) && !ROUTE_FILE_RE.test(c.file)
-    && !STORY_FILE_RE.test(c.file) && !EMAIL_PATH_RE.test(c.file));
+  const comps = components.filter(canBeDuplicate);
 
   // 1. exact same component name defined in >1 file
   const byName = new Map();
@@ -88,9 +134,6 @@ export function findDuplicates(components, uiDir = null, root = null, uiDirs = n
     }))
     .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));
 

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

@@ -35,6 +35,21 @@ export { extractStyling, normalizeHex, isGrey, hexRgb, typefaceOf, GENERIC_FONTS
 // The components a piece of text defines. With the ledger below, a guard can
 // tell a second <Button> from an edit to the first one.
 export { definedComponents };
+// Duplicates, by the report's own answer (9.2.1). duplicateCopies(def,
+// copies, counted, same) returns the other copies that make one definition a
+// duplicate, or none: `copies` is the ledger's entries for the name
+// (learnSystem's components), `counted` the files of the duplicate the report
+// counts under it (the copies in learnSystem's duplicates), `same` how two
+// paths compare. canBeDuplicate({ name, file, isPage }) is the first question
+// it asks: a framework's Route, a page, a route file, the crash page, a story
+// and an email template repeat by design. isPageFile(file) answers isPage for
+// a file not in the ledger. componentNamesIn(text, file) lists what a whole
+// file defines for the report: React components in a .tsx, .jsx or .js file
+// with markup in it, and web components registered by tag. The exemptions
+// (exemptReason) are about styling, so a duplicate is still a duplicate in
+// an exempt file.
+export { canBeDuplicate, duplicateCopies } from '../harvest/duplicates.mjs';
+export { isPageFile, looksLikeJSXFile, componentNamesIn } from '../harvest/components.mjs';
 
 // The files no checker should judge. Exported so a guard reads the same list
 // as the engine rather than keeping a copy that drifts.
@@ -115,7 +130,7 @@ export function learnSystem(repoRoot, { exclude = [] } = {}) {
   // the same two lists the MCP knowledge builds (mcp/knowledge.mjs), from the
   // same helpers, for tokenTwinFindings and avoidedImportFindings (8.6.1)
   const read = (f) => readSource(join(repoRoot, f));
-  const hardDupes = (findDuplicates(ledger, profile.uiDir, repoRoot).exactDuplicates ?? []).filter((d) => !d.wrapped);
+  const hardDupes = (findDuplicates(ledger, profile.uiDir, repoRoot, profile.uiDirs ?? null).exactDuplicates ?? []).filter((d) => !d.wrapped);
   const P = profileOf(profile);
   const installedNow = installedDirs(P);
   const charts = chartSystemOf(files, read, { own: (f) => !installedNow.some((d) => f === d || f.startsWith(`${d}/`)) });

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

@@ -1,7 +1,7 @@
 // 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 = '9.2.0';
+export const VERSION = '9.2.1';
 // The shape of harvest.json and summary.json. Bumped only when a field is
 // renamed, removed or changes meaning; a new field is not a new schema. A
 // tool comparing two scans compares like with like by this number, not by VERSION.

package/skills/roast-my-design-system/scripts/mcp/engine.mjs

@@ -11,7 +11,8 @@
  *    in the repo means saying so, not inventing one.
  */
 import { extractStyling } from '../harvest/tokens.mjs';
-import { definedComponents } from '../harvest/components.mjs';
+import { componentNamesIn, isPageFile } from '../harvest/components.mjs';
+import { duplicateCopies } from '../harvest/duplicates.mjs';
 import { hexRgb } from '../lib/nearpairs.mjs';
 import { exemptReason } from '../lib/exempt.mjs';
 import { extraDeclarations, fontDeclarations } from '../lib/declarations.mjs';
@@ -83,6 +84,29 @@ function nearestToken(value, k) {
   return best;
 }
 
+/**
+ * The report's answer on duplicates, asked of one file: a name that repeats
+ * by design, a pair the report lists without counting and a file that
+ * defines nothing the report reads are not duplicates here either
+ * (harvest/duplicates.mjs).
+ */
+function duplicateFindings({ text, file, k, add }) {
+  for (const name of componentNamesIn(text, file)) {
+    const dupe = k.dupeByName.get(name);
+    const counted = dupe ? dupe.files.map((f) => (typeof f === 'string' ? f : f.file)) : null;
+    const existing = duplicateCopies({ name, file: file ?? '', isPage: !!file && isPageFile(file) }, k.byName.get(name), counted);
+    if (!existing.length) continue;
+    // the scan may already include this very file — count the OTHER copies
+    const otherCopies = counted ? counted.filter((f) => f !== file) : null;
+    const best = [...existing].sort((a, b) => b.usageCount - a.usageCount)[0];
+    add('duplicate-component', 'violation', text.indexOf(name),
+      otherCopies && otherCopies.length > 1
+        ? `Defines <${name}>, which already exists in ${otherCopies.length} other places. This makes ${otherCopies.length + 1} competing copies, and every wrong pick becomes the example the next agent copies.`
+        : `Defines <${name}>, but ${best.file} already defines it${best.usageCount ? ` (used ${best.usageCount}x)` : ''}.`,
+      `Import ${best.file} instead of creating a copy.`);
+  }
+}
+
 /**
  * Validate one piece of content against the repo's knowledge.
  * @param content { text, file?, before? } — file name decides css-vs-code
@@ -91,7 +115,8 @@ function nearestToken(value, k) {
  *   unknown), so a token or an import the change ADDS can be told from one
  *   that was already there
  * @returns { findings: [{ rule, severity, line, message, fix? }], checked,
- *   exempt? } — exempt is a sentence saying why the file was not judged
+ *   exempt? } — exempt is a sentence saying why the file's styling was not
+ *   judged; its findings are then duplicates only, and checked says so
  */
 export function validateContent(content, k) {
   const { text, file = null, before } = content;
@@ -99,13 +124,20 @@ export function validateContent(content, k) {
   // checker earns its reputation for crying wolf, and a checker people
   // distrust gets switched off. Say nothing, and say why nothing was said.
   const exempt = exemptReason(file, text);
-  if (exempt) return { findings: [], checked: checksFor(k), exempt };
   const css = file ? CSS_FILE_RE.test(file) : looksLikeCss(text);
-  const got = extractStyling(text, { css });
   const findings = [];
   const add = (rule, severity, index, message, fix) => findings.push({
     rule, severity, line: lineOf(text, index), message, ...(fix ? { fix } : {}),
   });
+  // The exemption is about styling: what an email, a drawing or a crash page
+  // cannot take from the system. A second copy of a component is a second
+  // copy in any medium, and the report counts it, so that one check still
+  // runs and the result says it was the only one.
+  if (exempt) {
+    if (!css) duplicateFindings({ text, file, k, add });
+    return { findings, checked: css ? [] : ['duplicate component definitions'], exempt };
+  }
+  const got = extractStyling(text, { css });
 
   // The knowledge scan includes the working tree, so a file under review has
   // already leaked its own values into the repo counts — without a discount,
@@ -258,9 +290,13 @@ export function validateContent(content, k) {
     // a raw value the repo already uses, in a non-Tailwind repo, is consistency,
     // not a new offence — silence
   }
+  // Bracket values inside installed code (the shadcn catalogue, kit blocks,
+  // registries) are the kit's own choices. The report names them and keeps
+  // them out of the count; a file under review is judged by the same line.
+  const installed = !!file && (k.installedDirs ?? []).some((d) => file === d || file.startsWith(`${d}/`));
   const localArb = new Map();
   for (const a of got.arbitrary) localArb.set(a.value, (localArb.get(a.value) ?? 0) + 1);
-  for (const a of got.arbitrary) {
+  for (const a of installed ? [] : got.arbitrary) {
     const repoArb = (k.tokens.tailwind?.arbitrary ?? []).find((x) => x.value === a.value);
     const priorArb = discount(repoArb?.count, localArb, a.value);
     add('arbitrary-value', 'violation', a.index,
@@ -345,23 +381,7 @@ export function validateContent(content, k) {
   }
 
   // ---------- duplicate components ----------
-  if (!css) {
-    for (const name of definedComponents(text)) {
-      const existing = (k.byName.get(name) ?? []).filter((c) => !file || c.file !== file);
-      if (!existing.length) continue;
-      const dupe = k.dupeByName.get(name);
-      // the scan may already include this very file — count the OTHER copies
-      const otherCopies = dupe
-        ? dupe.files.map((f) => (typeof f === 'string' ? f : f.file)).filter((f) => f !== file)
-        : null;
-      const best = [...existing].sort((a, b) => b.usageCount - a.usageCount)[0];
-      add('duplicate-component', 'violation', text.indexOf(name),
-        otherCopies && otherCopies.length > 1
-          ? `Defines <${name}>, which already exists in ${otherCopies.length} other places. This makes ${otherCopies.length + 1} competing copies, and every wrong pick becomes the example the next agent copies.`
-          : `Defines <${name}>, but ${best.file} already defines it${best.usageCount ? ` (used ${best.usageCount}x)` : ''}.`,
-        `Import ${best.file} instead of creating a copy.`);
-    }
-  }
+  if (!css) duplicateFindings({ text, file, k, add });
 
   // ---------- an import of the copy the canon replaces ----------
   if (!css) {

package/skills/roast-my-design-system/scripts/mcp/hook.mjs

@@ -114,7 +114,8 @@ function judge(real, root, k, warned = new Set()) {
   const text = readFileSync(real, 'utf8');
   const before = beforeOf(k, rel);
   const { findings: all, exempt } = validateContent({ text, file: rel, before }, k);
-  if (exempt || !all.length) return null;
+  // an exempt file is judged on duplicates only; with none, there is nothing to say
+  if (!all.length) return null;
   // Only what this edit added. A legacy file carries its old findings on
   // every touch; repeating them after each edit is noise, and the review
   // (--check, roast_review) already reports them once at the end. Same rule
@@ -129,5 +130,5 @@ function judge(real, root, k, warned = new Set()) {
     return true;
   });
   if (!findings.length) return null;
-  return { text: `Design-system check of ${rel} (roast-my-design-system, the same engine as roast_validate): ${findingLines(findings, k).join('\n')}`, total: findings.length };
+  return { text: `Design-system check of ${rel} (roast-my-design-system, the same engine as roast_validate): ${findingLines(findings, k, exempt).join('\n')}`, total: findings.length };
 }

package/skills/roast-my-design-system/scripts/mcp/knowledge.mjs

@@ -74,7 +74,10 @@ export function loadKnowledge(root) {
     // same shape as a harvested colour, so every reader of `files` keeps working
     for (const v of themeSet) if (!tokens.colors.some((c) => c.value === v)) tokens.colors.push({ value: v, count: 1, files: [{ file: kit.themeFiles[0] ?? '', count: 1 }], isToken: true });
   }
-  const duplicates = findDuplicates(components, profile.uiDir, root);
+  // every catalogue folder, as the report passes them (harvest/index.mjs): a
+  // monorepo with two installs has two, and shadcn's own overlap in the
+  // second is no more the team's than in the first
+  const duplicates = findDuplicates(components, profile.uiDir, root, profile.uiDirs ?? null);
   const context = harvestContext(root);
   const workspaces = resolveWorkspaces(root);
 
@@ -196,6 +199,10 @@ export function loadKnowledge(root) {
     neverImported,
     // stock, not debt: see profiles/index.mjs
     vendoredUi: P.vendoredUi,
+    // folders the team did not write, by the same line the guard doorway
+    // draws (lib/guard-api.mjs): only a shadcn kit has installed code, and a
+    // registry's published folders are its own work
+    installedDirs: P.isShadcn && !P.isRegistry ? installed : [],
     // the kit the product is built on, and the Tailwind theme it names its
     // colours in: null when the repo is neither (see profiles/)
     kit,

package/skills/roast-my-design-system/scripts/mcp/tools.mjs

@@ -306,19 +306,22 @@ export function validate(k, { code, file = null } = {}) {
   if (file != null && typeof file !== 'string') return invalidInput('file is optional, but when sent it must be a repo-relative path as a string.');
   if (code.length > MAX_VALIDATE_CHARS) return invalidInput(`That is ${Math.round(code.length / 1000)}k characters; send the part you changed (up to ${MAX_VALIDATE_CHARS / 1000}k).`);
   const { findings, exempt } = validateContent({ text: code, file, before: beforeOf(k, file) }, k);
-  if (exempt) return `Not judged: ${file} is exempt because ${exempt}. Nothing here was checked.`;
+  if (exempt && !findings.length) return `Not judged: ${file} is exempt because ${exempt}. Nothing here was checked.`;
   if (!findings.length) return cleanResultText(k);
-  return findingLines(findings, k).join('\n');
+  return findingLines(findings, k, exempt).join('\n');
 }
 
 /** The finding list as roast_validate prints it; the edit hook prints the same. */
-export function findingLines(findings, k) {
+export function findingLines(findings, k, exempt = null) {
   const L = [`${findings.length} finding${findings.length === 1 ? '' : 's'}:`];
   for (const f of findings.slice(0, 12)) {
     L.push(`${f.severity === 'violation' ? '✕' : '⚠'} L${f.line} ${f.message}${f.fix ? `\n   Fix: ${f.fix}` : ''}`);
   }
   if (findings.length > 12) L.push(`(+${findings.length - 12} more of the same kinds)`);
-  L.push(`Checked: ${checksFor(k).join(', ')}.`);
+  // an exempt file is judged on one thing, and the reader is told which
+  L.push(exempt
+    ? `Checked: duplicate component definitions. The styling was not judged, because ${exempt}.`
+    : `Checked: ${checksFor(k).join(', ')}.`);
   return L;
 }
 
@@ -355,12 +358,12 @@ export function reviewData(k) {
     try { text = readFileSync(join(gitRoot, f), 'utf8'); } catch { continue; }
     // knowledge paths are scanned-root-relative; git paths are toplevel-relative
     const { findings, exempt } = validateContent({ text, file: relative(realRoot, join(gitRoot, f)), before: headVersion(gitRoot, f) }, k);
-    if (exempt) { exemptCount++; continue; }
+    if (exempt) exemptCount++;
     if (findings.length) { perFile.push({ f, findings }); total += findings.length; }
   }
   // Skipped is not the same as clean, and the reader is owed the difference.
   const exemptNote = exemptCount
-    ? ` ${exemptCount} file${exemptCount === 1 ? ' was' : 's were'} left unjudged: email, print, artwork or pictures drawn with code.`
+    ? ` The styling of ${exemptCount} file${exemptCount === 1 ? ' was' : 's were'} left unjudged: email, print, artwork or pictures drawn with code.`
     : '';
   if (!total) {
     return { text: `Reviewed ${changed.length} changed file${changed.length === 1 ? '' : 's'}. ${cleanResultText(k)}${exemptNote}`, total: 0 };