guard-my-design-system 2.0.0 → 2.2.0

package/README.md

@@ -40,7 +40,9 @@ it updates that same comment. It never adds more comments:
 ## What it catches
 
 - **A hard-coded colour where a token exists.** The finding names the token:
-  `var(--blue-500)`, not just a hex code. This works across colour notations:
+  `var(--blue-500)`, not just a hex code. A token's own value pasted into a
+  component or a stylesheet counts too: the finding says use the name, not
+  the value. This works across colour notations:
   a hex stray is matched to an hsl or oklch token, including shadcn's
   bare-triplet variables. Dark-theme values count as the system too, so a
   stray in a dark block snaps to the dark token, never its light twin.
@@ -54,8 +56,17 @@ it updates that same comment. It never adds more comments:
 - **An inline `style={{ }}` block.** Styling written there is invisible to the
   system and to every agent that reads the file. Blocks built from variables
   are decided elsewhere, so they are left alone.
+- **A button built from scratch where the repo already has a Button.** A
+  styled button, or a button tag dressed as one, in a file whose package
+  can import a Button that at least 20 files already use. The finding
+  gives the import line. Rows, tabs, close crosses and select triggers
+  built on a button tag are left alone.
 - **A second definition of a component you already have.** The finding names
-  the file that already defines it, and how many places use that one.
+  the file that already defines it, and how many places use that one. Web
+  components registered by tag count too. What a copy is, is the roast
+  report's answer: a framework's `Route` or `Layout`, a page, a story, an
+  email template and a wrapper built on the component it shares a name with
+  are not second copies.
 - **A new import of a duplicate component.** When a name is defined in more
   than one file and one copy is clearly the main one, importing another copy
   is flagged. The finding names the main copy, how often each is used, and
@@ -232,8 +243,9 @@ updating PR comment works on GitHub only, for now.
   picture drawn with code. A canvas renderer draws pixels. A file that draws
   SVG is artwork, not interface. The guard reads that list from the roast
   engine rather than keeping its own, so the two can never drift apart and
-  give you different answers about the same file. Defining a new token is
-  extending the system, not a problem.
+  give you different answers about the same file. The exemptions are about
+  styling: a second `Logo` is still a second `Logo`, and is flagged. Defining
+  a new token is extending the system, not a problem.
 - **Every finding comes with a fix.** The guard names the on-system value the
   author probably meant, so most fixes take under a minute and no meeting.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guard-my-design-system",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Your design system dies one pull request at a time. This makes sure it doesn't. A guard that judges only the lines a change adds, against the system the repo already has, and names the on-system value the author probably meant.",
   "type": "module",
   "bin": {
@@ -11,7 +11,7 @@
     "src/"
   ],
   "dependencies": {
-    "roast-my-design-system": "9.0.0"
+    "roast-my-design-system": "9.2.1"
   },
   "keywords": [
     "design-system",

package/src/judge.mjs

@@ -10,10 +10,10 @@
 import {
   extractStyling, normalizeHex, nearestColor, nearestLength,
   isCodeFile, isStyleFile, typefaceOf, GENERIC_FONTS,
-  definedComponents, exemptReason,
+  definedComponents, componentNamesIn, duplicateCopies, isPageFile, exemptReason,
   EXTRA_KINDS, extraValue, fontDeclarations,
   WIDGET_CSS_RE, isLibraryClass, PALETTE_CLASS_RE, blankComments, kitPaintFindings,
-  tokenTwinFindings, avoidedImportFindings, isChartFile, chartFindings,
+  tokenTwinFindings, avoidedImportFindings, isChartFile, chartFindings, handmadeButtonFindings,
 } from 'roast-my-design-system/engine';
 
 // Folder membership, the way the engine's own splits do it.
@@ -163,6 +163,9 @@ export function judge(added, system, { readFile, readBase } = {}) {
   }
   // "use var(--blue-500)", not "go hunt this hex": name a value when the
   // system defines it as a custom property.
+  const statesTokens = (file) => (system.tokenSources ?? []).some((t) => samePath(t, file));
+  // on a kit repo the theme is where a colour is decided (mcp/knowledge reads it the same way)
+  const themeFile = system.profile?.kit?.themeFiles?.[0] ?? system.tokenFile ?? null;
   const named = (value) => {
     // shadcn-style tokens are defined as bare triplets (--primary: 222.2 47.4%
     // 11.2%) but normalised to hsl(...); try the unwrapped form too.
@@ -178,12 +181,13 @@ export function judge(added, system, { readFile, readBase } = {}) {
   const knownFaces = new Set(
     [...faceCounts].filter(([face, n]) => n > (addedFaces.get(face) ?? 0)).map(([face]) => face)
   );
-  // Components the repo already defines, by name. Pages are routes rather than
-  // reusable parts, so two of a name there is not a second Button.
+  // Components the repo already defines, by name: the whole ledger. What
+  // counts as a second copy is the engine's call (duplicateCopies), so the
+  // guard and the report give one answer. A page, a framework's Route, a
+  // story, a wrapper and two icon libraries colliding are not second copies.
   const componentsByName = new Map();
   if (definedComponents && Array.isArray(system.components)) {
     for (const c of system.components) {
-      if (c.isPage) continue;
       const list = componentsByName.get(c.name) ?? [];
       list.push(c);
       componentsByName.set(c.name, list);
@@ -233,10 +237,54 @@ export function judge(added, system, { readFile, readBase } = {}) {
     return isChartFile(file, w ?? '');
   };
 
+  // A hand-rolled second <Button> is the most expensive thing a pull request
+  // can add, and it was the one thing the guard could not see. The scan
+  // includes this change, so the new copy is in the ledger too: what counts
+  // is whether the name lives anywhere ELSE, and the engine answers that the
+  // way the report does (duplicateCopies).
+  const definedByFile = new Map();
+  const definedIn = (file) => {
+    if (!definedByFile.has(file)) definedByFile.set(file, new Set(componentNamesIn(wholeText(file) ?? '', file)));
+    return definedByFile.get(file);
+  };
+  const secondCopies = (file, line, text) => {
+    const out = [];
+    if (!componentsByName.size) return out;
+    // what the whole file defines for the report, kept to what this line declares
+    const onLine = new Set(definedComponents(text));
+    const names = wholeText(file) === null
+      ? [...onLine]
+      : [...definedIn(file)].filter((n) => onLine.has(n) || new RegExp(`\\bclass\\s+${n}\\b`).test(text));
+    for (const name of names) {
+      const variantOf = (f) => variants.find((v) => underAny(f, [v])) ?? null;
+      const counted = system.duplicates?.get?.(name)?.copies.map((c) => c.file) ?? null;
+      const elsewhere = duplicateCopies({ name, file, isPage: isPageFile(file) }, componentsByName.get(name), counted, samePath)
+        // a registry keeps the same component in sibling variants, and a
+        // block installs alone: neither is a second Button
+        .filter((c) => !(variantOf(file) && variantOf(c.file) && variantOf(c.file) !== variantOf(file)))
+        .filter((c) => !(underAny(file, blockDirs) && underAny(c.file, blockDirs)));
+      if (!elsewhere.length) continue;
+      const best = [...elsewhere].sort((a, b) => b.usageCount - a.usageCount)[0];
+      out.push({
+        file, line, kind: 'component', value: name,
+        // never open the advice with the path: the report capitalises the
+        // first letter, and a capitalised path is the wrong path
+        advice: elsewhere.length > 1
+          ? `${elsewhere.length} other files define it too; import ${best.file}, the one the codebase leans on`
+          : `import ${best.file} rather than starting a second one${best.usageCount ? `, which ${best.usageCount} place${best.usageCount === 1 ? '' : 's'} already do` : ''}`,
+      });
+    }
+    return out;
+  };
+
   for (const { file, line, text } of added) {
-    if (exempt(file) || outOfScope(file)) continue;
+    if (outOfScope(file)) continue;
     const css = isStyleFile(file);
     if (!css && !isCodeFile(file)) continue;
+    // The exemptions are 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.
+    if (exempt(file)) { if (!css) findings.push(...secondCopies(file, line, text)); continue; }
 
     const seen = extractStyling(text, { css });
 
@@ -259,7 +307,21 @@ export function judge(added, system, { readFile, readBase } = {}) {
 
     for (const c of seen.colors) {
       if (onKit || chart) break; // the kit rule or the chart rule owns colours here
-      if (tokenSet.has(c.value)) continue; // disciplined token use
+      if (tokenSet.has(c.value)) {
+        // A token's raw value is the definition only inside a file that
+        // states the palette (system.tokenSources, roast 9.1.3). Anywhere
+        // else it is the value pasted where the name belongs: the system
+        // cannot see it, and the next reader copies the hex.
+        if (!system.tokenSources || statesTokens(file)) continue;
+        const n = named(c.value);
+        findings.push({
+          file, line, kind: 'color', value: c.value,
+          advice: n !== c.value
+            ? `this is already the token ${n}; use the name, not the value`
+            : `the theme already holds this value${themeFile ? ` (${themeFile})` : ''}; read it from there rather than pasting it`,
+        });
+        continue;
+      }
       const near = c.value.startsWith('#') ? nearestColor(c.value, system.tokens) : null;
       findings.push({
         file, line, kind: 'color', value: c.value,
@@ -308,30 +370,7 @@ export function judge(added, system, { readFile, readBase } = {}) {
       });
     }
 
-    // A hand-rolled second <Button> is the most expensive thing a pull request
-    // can add, and it was the one thing the guard could not see. The scan
-    // includes this change, so the new copy is in the ledger too: what counts
-    // is whether the name lives anywhere ELSE.
-    if (!css && componentsByName.size) {
-      for (const name of definedComponents(text)) {
-        const variantOf = (f) => variants.find((v) => underAny(f, [v])) ?? null;
-        const elsewhere = (componentsByName.get(name) ?? []).filter((c) => !samePath(c.file, file))
-          // a registry keeps the same component in sibling variants, and a
-          // block installs alone: neither is a second Button
-          .filter((c) => !(variantOf(file) && variantOf(c.file) && variantOf(c.file) !== variantOf(file)))
-          .filter((c) => !(underAny(file, blockDirs) && underAny(c.file, blockDirs)));
-        if (!elsewhere.length) continue;
-        const best = [...elsewhere].sort((a, b) => b.usageCount - a.usageCount)[0];
-        findings.push({
-          file, line, kind: 'component', value: name,
-          // never open the advice with the path: the report capitalises the
-          // first letter, and a capitalised path is the wrong path
-          advice: elsewhere.length > 1
-            ? `${elsewhere.length} other files define it too; import ${best.file}, the one the codebase leans on`
-            : `import ${best.file} rather than starting a second one${best.usageCount ? `, which ${best.usageCount} place${best.usageCount === 1 ? '' : 's'} already do` : ''}`,
-        });
-      }
-    }
+    if (!css) findings.push(...secondCopies(file, line, text));
 
     for (const a of seen.arbitrary) {
       findings.push({
@@ -414,7 +453,13 @@ export function judge(added, system, { readFile, readBase } = {}) {
           others: system.tokenDefs.filter((d) => !samePath(d.file, file)),
           tailwind: prof.kind === 'tailwind' || /@theme\b/.test(w),
         }) : [])
-      : (system.duplicates ? avoidedImportFindings(w, { file, before: baseText(file), dupes: system.duplicates }) : []);
+      : [
+        ...(system.duplicates ? avoidedImportFindings(w, { file, before: baseText(file), dupes: system.duplicates }) : []),
+        // a button built from scratch where the file's own package can
+        // import the repo's Button (roast 9.2.0); a warning in the engine,
+        // a finding here, on the line the button starts
+        ...(system.buttons?.length ? handmadeButtonFindings(w, { file }, system) : []),
+      ];
     for (const f of hits) {
       const line = lineAt(w, f.index);
       if (!lines.has(line)) continue;

package/src/report.mjs

@@ -26,11 +26,14 @@ const KIND_LABEL = {
   // painting by hand where the repo keeps none
   'chart-colour': 'chart colour written by hand',
   'chart-palette': 'chart painted by hand',
+  // a styled.button or a dressed button tag where the repo has a Button
+  // (roast 9.2.0); the engine's sentence names the Button and its import
+  'handmade-button': 'button built from scratch',
 };
 const labelOf = (f) => f.label ?? KIND_LABEL[f.kind];
 
 // Kinds whose label already says everything; printing the value repeats it.
-const VALUELESS = new Set(['important', 'inline', 'twin-token', 'avoided-copy', 'chart-palette']);
+const VALUELESS = new Set(['important', 'inline', 'twin-token', 'avoided-copy', 'chart-palette', 'handmade-button']);
 
 const FOOTER = 'Full picture of the whole codebase: `npx roast-my-design-system`';