guard-my-design-system 1.6.0 → 1.8.0

package/README.md

@@ -59,8 +59,18 @@ it updates that same comment. It never adds more comments:
 - **A palette colour where a theme variable exists.** On a shadcn repo whose
   theme file holds the variables, `text-slate-500` in the app's own code is
   flagged and the theme file named. Off on utility-class installs.
-
-It reads the repo the way the roast report does. On a shadcn repo the
+- **A colour or a pixel size written onto a kit component.** On a product
+  built on MUI, Mantine, Chakra UI or Ant Design, `color: '#667085'` in an
+  `sx` prop or a style object is flagged and the finding says whether the
+  theme already holds that colour, or tells you to add it there once. A
+  pixel size such as `p: '12px'` is turned into the theme's spacing step. The
+  advice is in the kit's own words: `sx` paths on MUI, props on Mantine,
+  style props on Chakra, the theme config on Ant Design.
+
+It reads the repo the way the roast report does. On a kit repo the theme's
+colours are the token set, and a colour the theme already holds is flagged
+on a kit component all the same: writing it by hand is the exact mistake the
+check exists for. On a shadcn repo the
 installed catalogue, installed registries and kit blocks are not judged:
 `shadcn add` is not a sin. On a repo that publishes a shadcn registry only
 the published folders are judged. `!important` in an embedded widget's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guard-my-design-system",
-  "version": "1.6.0",
+  "version": "1.8.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": "7.8.0"
+    "roast-my-design-system": "8.4.6"
   },
   "keywords": [
     "design-system",

package/src/judge.mjs

@@ -12,7 +12,7 @@ import {
   isCodeFile, isStyleFile, typefaceOf, GENERIC_FONTS,
   definedComponents, exemptReason,
   EXTRA_KINDS, extraValue, fontDeclarations,
-  WIDGET_CSS_RE, isLibraryClass, PALETTE_CLASS_RE,
+  WIDGET_CSS_RE, isLibraryClass, PALETTE_CLASS_RE, blankComments, kitPaintFindings,
 } from 'roast-my-design-system/engine';
 
 // Folder membership, the way the engine's own splits do it.
@@ -106,6 +106,20 @@ export function judge(added, system, { readFile } = {}) {
   };
   const isWidgetFile = (file) => underAny(file, prof.widgetDirs) || WIDGET_CSS_RE.test(wholeText(file) ?? '');
   const paletteRe = new RegExp(PALETTE_CLASS_RE.source, 'g');
+  // The added line with its comments blanked, the way the report and the
+  // live checks read a file before matching (roast 8.4.4): a class named in
+  // a comment paints nothing. Blanked from the whole file when it is at hand,
+  // so a block comment opened on an earlier line still counts as a comment.
+  const blanked = new Map();
+  const codeText = (file, lineNo, text) => {
+    const w = wholeText(file);
+    if (w == null) return blankComments(text);
+    if (!blanked.has(file)) blanked.set(file, blankComments(w).split('\n'));
+    // blanking keeps every character's place, so the file's line is the
+    // diff's line only if the lengths match; otherwise the file has moved on
+    const l = blanked.get(file)[lineNo - 1];
+    return l != null && l.length === text.length ? l : blankComments(text);
+  };
 
   // 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"
@@ -171,6 +185,35 @@ export function judge(added, system, { readFile } = {}) {
     }
   }
 
+  // A product built on a kit (MUI, Mantine, Chakra UI, Ant Design), roast
+  // 8.4.6: a colour or a pixel size written onto a kit component where the
+  // theme has a value. The engine judges the whole file (the import that makes
+  // it a kit file sits at the top, where the diff never looks) and the guard
+  // keeps the hits on added lines. On a kit file the kit rule owns colours
+  // and the pixel sizes it named, so the generic rules stay quiet about the
+  // same value: one line, one finding, the same words as the roast report's
+  // live checks.
+  const kit = prof.kit ?? null;
+  const kitJudged = new Map();
+  const kitLines = (file) => {
+    if (!kit) return null;
+    if (!kitJudged.has(file)) {
+      const w = wholeText(file);
+      const j = w == null ? null : kitPaintFindings(w, kit, { file });
+      if (!j || j.exempt) kitJudged.set(file, null);
+      else {
+        const byLine = new Map();
+        for (const f of j.findings) {
+          const ln = w.slice(0, f.index).split('\n').length;
+          if (!byLine.has(ln)) byLine.set(ln, []);
+          byLine.get(ln).push(f);
+        }
+        kitJudged.set(file, byLine);
+      }
+    }
+    return kitJudged.get(file);
+  };
+
   const findings = [];
 
   for (const { file, line, text } of added) {
@@ -180,7 +223,18 @@ export function judge(added, system, { readFile } = {}) {
 
     const seen = extractStyling(text, { css });
 
+    const onKit = css ? null : kitLines(file);
+    const kitPx = new Set();
+    for (const f of onKit?.get(line) ?? []) {
+      if (f.rule === 'kit-px') kitPx.add(f.value.split(': ')[1]);
+      findings.push({
+        file, line, kind: f.rule, value: f.value, label: f.label,
+        advice: f.note ? `${f.note}. ${f.fix.replace(/\.$/, '')}` : f.fix.replace(/\.$/, ''),
+      });
+    }
+
     for (const c of seen.colors) {
+      if (onKit) break; // the kit rule owns colours on a kit file
       if (tokenSet.has(c.value)) continue; // disciplined token use
       const near = c.value.startsWith('#') ? nearestColor(c.value, system.tokens) : null;
       findings.push({
@@ -194,6 +248,7 @@ export function judge(added, system, { readFile } = {}) {
     }
 
     for (const s of seen.spacing) {
+      if (kitPx.has(s.value)) continue; // the kit rule said it
       if (knownLengths.has(s.value)) continue; // the codebase already uses it
       const near = nearestLength(s.value, [...knownLengths]);
       findings.push({
@@ -282,10 +337,10 @@ export function judge(added, system, { readFile } = {}) {
     // CSS-variable mode): paint from a tin. The same pattern the report
     // counts per 100 files; here, per added line.
     if (!css && prof.paletteReady) {
-      for (const m of text.matchAll(paletteRe)) {
+      for (const m of codeText(file, line, text).matchAll(paletteRe)) {
         findings.push({
           file, line, kind: 'palette', value: m[0],
-          advice: `a theme variable covers this; use a semantic class such as bg-primary or text-muted-foreground, or add a variable${prof.sheetFile ? ` to ${prof.sheetFile}` : ''}`,
+          advice: `a theme token covers this; use it as the class (bg-primary, text-muted-foreground), or add one${prof.sheetFile ? ` to ${prof.sheetFile}` : ' to the theme'} once`,
         });
       }
     }

package/src/report.mjs

@@ -16,7 +16,11 @@ const KIND_LABEL = {
   inline: 'inline style block',
   component: 'second definition of',
   palette: 'palette colour where a theme variable exists',
+  // on a kit repo the engine words the label with the kit's name (f.label)
+  'kit-colour': 'colour written onto a kit component',
+  'kit-px': 'pixel size on a kit component',
 };
+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']);
@@ -29,7 +33,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]} ${VALUELESS.has(f.kind) ? '' : f.value}`.trimEnd() + `. ${capitalise(f.advice)}.`);
+    lines.push(`  ${f.file}:${f.line} · ${labelOf(f)} ${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.');
@@ -49,7 +53,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) {
-    out.push(`- \`${f.file}:${f.line}\` · ${KIND_LABEL[f.kind]} ${VALUELESS.has(f.kind) ? '' : `\`${f.value}\``}`.trimEnd() + `. ${capitalise(f.advice)}.`);
+    out.push(`- \`${f.file}:${f.line}\` · ${labelOf(f)} ${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>`);