guard-my-design-system 1.3.4 → 1.4.0

package/README.md

@@ -8,15 +8,19 @@ The guard checks pull requests for design-system drift. It looks only at the
 lines a change adds. It never judges the code that was already there. For each
 problem it finds, it names the closest value your system already has:
 
-> `Card.tsx:24` — new colour `#4a7be8`. Nearest token: `var(--blue-500)`, `#3b6fe0`.
+> `Card.tsx:24` · new colour `#4a7be8`. Nearest token: `var(--blue-500)`, `#3b6fe0`.
 >
-> `site.css:31` — new spacing value `13px`. Nearest existing value: `12px`.
+> `site.css:31` · new spacing value `13px`. Nearest existing value: `12px`.
 >
-> `site.css:32` — new border radius `5px`. Nearest existing value: `6px`.
+> `site.css:32` · new border radius `5px`. Nearest existing value: `6px`.
 >
-> `site.css:33` — new typeface `Comic Sans MS`. First typeface declared in this codebase.
+> `site.css:33` · new typeface `Comic Sans MS`. First typeface declared in this codebase.
 >
-> `site.css:35` — `!important`. The cascade admitting defeat; raise specificity or fix the source order.
+> `site.css:35` · `!important`. The cascade admitting defeat; raise specificity or fix the source order.
+>
+> `Panel.tsx:12` · inline style block. The values are invisible to the system and to every agent that reads the file; move them to classes or tokens.
+>
+> `ButtonV2.tsx:1` · second definition of `Button`. Import components/Button.tsx rather than starting a second one.
 
 It learns your design system by scanning your repository with the
 [roast-my-design-system](https://github.com/gregkozakiewicz/roast-my-design-system)
@@ -36,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.
+  `var(--blue-500)`, not just a hex code. This works across colour notations:
+  a hex stray is matched to an hsl or oklch token, including shadcn's
+  bare-triplet variables.
 - **A spacing value your codebase has never used**, with the nearest existing
   step named.
 - **A border radius, font size or shadow your system does not declare**, with
@@ -44,6 +50,11 @@ it updates that same comment. It never adds more comments:
 - **A typeface your system does not declare.**
 - **`!important`.**
 - **Arbitrary Tailwind values** such as `w-[137px]` and `mt-[37px]`.
+- **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 second definition of a component you already have.** The finding names
+  the file that already defines it, and how many places use that one.
 
 It ignores everything that was already in the codebase. It asks one question
 of a change: does it make things worse?
@@ -172,10 +183,14 @@ updating PR comment works on GitHub only, for now.
   time. No AI model is involved.
 - **Read-only. No network. No telemetry.** Everything runs on your machine or
   your CI runner. Nothing about your code leaves it.
-- **Fair exemptions, inherited from roast.** Email and print styling must be
-  inline, so the guard never flags it. Files that draw SVG artwork are not
-  judged on their colours. Defining a new token is extending the system, not
-  a problem.
+- **Fair exemptions, shared with roast.** Some files cannot be on-system, so
+  judging them would be crying wolf. Email and print styling has to be inline,
+  because there is no cascade to inherit. An OG card or a PDF invoice is a
+  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.
 - **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/index.mjs

@@ -53,7 +53,7 @@ let added;
 try {
   added = addedLines(cwd, base);
 } catch (e) {
-  console.error(`guard: git diff failed — ${e.message.split('\n')[0]}`);
+  console.error(`guard: git diff failed. ${e.message.split('\n')[0]}`);
   process.exit(2);
 }
 
@@ -71,7 +71,17 @@ ignorePrefixes = ignorePrefixes.map((p) => p.replace(/^\.?\//, '').replace(/\/?$
 const judged = added.filter(({ file }) => !ignorePrefixes.some((p) => (file + '/').startsWith(p)));
 
 const system = learnSystem(cwd, { exclude });
-let findings = judge(judged, system);
+// The judge asks for whole files when deciding what to leave alone: a satori
+// import or an SVG drawing sits at the top of a file the diff never touches.
+const wholeFile = new Map();
+const readWhole = (file) => {
+  if (!wholeFile.has(file)) {
+    try { wholeFile.set(file, readFileSync(resolve(cwd, file), 'utf8')); }
+    catch { wholeFile.set(file, null); }
+  }
+  return wholeFile.get(file);
+};
+let findings = judge(judged, system, { readFile: readWhole });
 
 // The escape hatch: a `guard-ignore-next-line` comment silences every finding
 // on the line below it. Checked against the file as it stands (not just the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guard-my-design-system",
-  "version": "1.3.4",
+  "version": "1.4.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": "5.7.2"
+    "roast-my-design-system": "5.11.0"
   },
   "keywords": [
     "design-system",

package/src/judge.mjs

@@ -10,55 +10,60 @@
 import {
   extractStyling, normalizeHex, nearestColor, nearestLength,
   isCodeFile, isStyleFile, typefaceOf, GENERIC_FONTS,
+  definedComponents, exemptReason,
+  EXTRA_KINDS, FONT_LINE_RE, extraValue,
 } from 'roast-my-design-system/engine';
 
-// Same honesty exemptions the engine applies: email and print styling must be
-// inline, always. Artwork-named files (Icon, Logo, Badge…) are exempt only
-// when their added lines actually draw SVG — a Badge component that is plain
-// styled UI gets guarded like everything else.
-const EMAIL_PRINT_RE = /email|(^|[/.])print([/.]|$)/i;
-const ARTWORK_NAME_RE = /(^|\/)[\w.-]*(icon|logo|badge|illustration|artwork)[\w.-]*\.(tsx|jsx)$/i;
-const SVG_MARKUP_RE = /<(svg|path|rect|circle|ellipse|polygon|defs|mask)\b/i;
-
-function exemptFiles(added) {
-  const svgish = new Set();
-  for (const { file, text } of added) {
-    if (ARTWORK_NAME_RE.test(file) && SVG_MARKUP_RE.test(text)) svgish.add(file);
+// git prints diff paths from the repository root; the engine lists them from
+// the directory it scanned. When the guard runs in a subdirectory the two
+// disagree by a prefix, so a suffix match stands in for equality. It errs
+// towards calling them the same file, which errs towards silence.
+const samePath = (a, b) => a === b || a.endsWith(`/${b}`) || b.endsWith(`/${a}`);
+
+// The honesty exemptions come from the engine now: email and print styling
+// that must be inline, OG cards and PDF invoices, pixel renderers, and artwork
+// that actually draws. This file used to keep its own copy and claim in a
+// comment that the engine applied the same one. It did not, and that gap is
+// how roast --check came to raise findings on email templates. One list, read
+// from the doorway, so the claim is true by construction.
+
+/**
+ * Which files to leave alone. The whole file decides, not the added lines: a
+ * satori import or an SVG drawing sits at the top of a file a diff may never
+ * touch. readFile is how the caller hands over the working tree; without one
+ * the added lines stand in, which sees less and so exempts less.
+ */
+function exemptFiles(added, readFile) {
+  const text = new Map();
+  for (const { file } of added) {
+    if (text.has(file)) continue;
+    let whole = null;
+    if (readFile) { try { whole = readFile(file); } catch { whole = null; } }
+    text.set(file, whole ?? added.filter((a) => a.file === file).map((a) => a.text).join('\n'));
   }
-  return (file) => EMAIL_PRINT_RE.test(file) || svgish.has(file);
+  const verdict = new Map();
+  return (file) => {
+    if (!verdict.has(file)) verdict.set(file, Boolean(exemptReason(file, text.get(file) ?? '')));
+    return verdict.get(file);
+  };
 }
 
-const FONT_LINE_RE = /font-family\s*:\s*([^;{}]+)/i;
-
-// The other declarations the engine harvests and the guard judges in style
-// files. One regex per kind; the whole trimmed value is the unit of
-// comparison, exactly as the harvest counts it.
-const EXTRA_KINDS = [
-  { kind: 'radius', re: /border-radius\s*:\s*([^;{}]+)/i, learned: 'radii' },
-  { kind: 'fontsize', re: /(?:^|[^-\w])font-size\s*:\s*([^;{}]+)/i, learned: 'fontSizes' },
-  { kind: 'shadow', re: /box-shadow\s*:\s*([^;{}]+)/i, learned: 'shadows' },
-];
-// Disciplined values that are never sins: token use, resets, inheritance.
-const BENIGN_VALUE_RE = /^(var\(--[\w-]+\)|inherit|initial|unset|none|normal|0)$/i;
-const extraValue = (re, text) => {
-  const m = re.exec(text);
-  if (!m) return null;
-  const v = m[1].trim().replace(/\s+/g, ' ');
-  return BENIGN_VALUE_RE.test(v) ? null : v;
-};
+// Radius, font size and shadow, and what counts as a disciplined value, also
+// come from the engine, so the harvest and the guard measure the same thing.
 
 /**
  * Judge added lines against the learned system.
  * Returns [{ file, line, kind, value, advice }] sorted by file then line.
- * kinds: color | spacing | arbitrary | important | font
+ * kinds: color | spacing | radius | fontsize | shadow | arbitrary |
+ *        important | font | inline | component
  */
-export function judge(added, system) {
+export function judge(added, system, { readFile } = {}) {
   const tokenSet = new Set(system.tokens);
 
   // The system was learned from the tree that already CONTAINS these added
   // lines, so a new value would vouch for itself. A value is only "known"
   // if the repo uses it more times than this change added it.
-  const exempt = exemptFiles(added);
+  const exempt = exemptFiles(added, readFile);
   const addedLengths = new Map(), addedFaces = new Map();
   const addedExtras = { radius: new Map(), fontsize: new Map(), shadow: new Map() };
   for (const { file, line, text } of added) {
@@ -90,7 +95,10 @@ export function judge(added, system) {
   // "use var(--blue-500)", not "go hunt this hex": name a value when the
   // system defines it as a custom property.
   const named = (value) => {
-    const n = system.tokenNames?.[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.
+    const n = system.tokenNames?.[value]
+      ?? system.tokenNames?.[value.replace(/^hsla?\((.*)\)$/i, '$1')];
     return n ? `var(${n}), ${value}` : value;
   };
   const faceCounts = new Map();
@@ -101,6 +109,18 @@ export function judge(added, system) {
   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.
+  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);
+    }
+  }
+
   const findings = [];
 
   for (const { file, line, text } of added) {
@@ -118,7 +138,7 @@ export function judge(added, system) {
         advice: near && near.distance <= 48
           ? `nearest token: ${named(near.value)}`
           : system.tokenFile
-            ? `no token resembles it — if it is a real decision, it belongs in ${system.tokenFile}`
+            ? `no token resembles it, and if it is a real decision it belongs in ${system.tokenFile}`
             : 'no token layer found to compare against',
       });
     }
@@ -148,6 +168,37 @@ export function judge(added, system) {
       }
     }
 
+    // Styling inside style={{ }} is invisible to the system and to every
+    // agent that reads the file, so it can never be on-system by definition.
+    // Only static blocks count; extractStyling already ignores the ones built
+    // from variables, where the values are decided elsewhere.
+    for (const _ of seen.inlineBlocks) {
+      findings.push({
+        file, line, kind: 'inline', value: 'style={{ }}',
+        advice: 'the values are invisible to the system and to every agent that reads the file; move them to classes or tokens',
+      });
+    }
+
+    // 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 elsewhere = (componentsByName.get(name) ?? []).filter((c) => !samePath(c.file, file));
+        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` : ''}`,
+        });
+      }
+    }
+
     for (const a of seen.arbitrary) {
       findings.push({
         file, line, kind: 'arbitrary', value: a.value,

package/src/report.mjs

@@ -13,8 +13,13 @@ const KIND_LABEL = {
   arbitrary: 'arbitrary Tailwind value',
   important: '!important',
   font: 'new typeface',
+  inline: 'inline style block',
+  component: 'second definition of',
 };
 
+// Kinds whose label already says everything; printing the value repeats it.
+const VALUELESS = new Set(['important', 'inline']);
+
 const FOOTER = 'Full picture of the whole codebase: `npx roast-my-design-system`';
 
 export function terminalReport(findings) {
@@ -23,7 +28,7 @@ export function terminalReport(findings) {
   }
   const lines = [`guard-my-design-system: ${findings.length} new issue${findings.length === 1 ? '' : 's'} in this change\n`];
   for (const f of findings) {
-    lines.push(`  ${f.file}:${f.line} — ${KIND_LABEL[f.kind]} ${f.value === '!important' ? '' : f.value}`.trimEnd() + `. ${capitalise(f.advice)}.`);
+    lines.push(`  ${f.file}:${f.line} · ${KIND_LABEL[f.kind]} ${VALUELESS.has(f.kind) ? '' : f.value}`.trimEnd() + `. ${capitalise(f.advice)}.`);
   }
   lines.push('');
   lines.push('  Only lines added in this change were counted. The existing codebase was not judged.');
@@ -43,8 +48,7 @@ export function markdownReport(findings) {
   }
   const out = [`**🛡 guard-my-design-system: ${findings.length} new issue${findings.length === 1 ? '' : 's'} in this pull request**`, ''];
   for (const f of findings) {
-    const val = f.kind === 'important' ? '`!important`' : `\`${f.value}\``;
-    out.push(`- \`${f.file}:${f.line}\` — ${KIND_LABEL[f.kind]} ${f.kind === 'important' ? '' : val}`.trimEnd() + `. ${capitalise(f.advice)}.`);
+    out.push(`- \`${f.file}:${f.line}\` · ${KIND_LABEL[f.kind]} ${VALUELESS.has(f.kind) ? '' : `\`${f.value}\``}`.trimEnd() + `. ${capitalise(f.advice)}.`);
   }
   out.push('');
   out.push(`<sub>Only added lines are checked; the existing codebase is never judged. ${FOOTER}</sub>`);