guard-my-design-system 1.1.0 → 1.2.0

package/README.md

@@ -10,10 +10,12 @@ probably meant. Old wiring is not its business; new sparks are.
 
 It speaks in nearests, not scoldings:
 
-> `Card.tsx:24` — new colour `#4a7be8`. Nearest token: `#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: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:35` — `!important`. The cascade admitting defeat; raise specificity or fix the source order.
@@ -34,8 +36,11 @@ a fix and the same comment counts down instead of piling up:
 
 ## What it catches
 
-- **A hard-coded colour where a token exists**, with the nearest token named.
+- **A hard-coded colour where a token exists**, with the nearest token named by
+  its variable: `var(--blue-500)`, not a hex to go hunting for.
 - **A spacing value the codebase has never used**, with the nearest step named.
+- **A border radius, font size or shadow** the system does not declare, with
+  the nearest existing value named.
 - **A typeface the system does not declare.**
 - **`!important`**, the cascade admitting defeat.
 - **Arbitrary Tailwind values** (`w-[137px]`, `mt-[37px]`) that sidestep the scale.
@@ -85,6 +90,9 @@ Prefer a failed check over a comment? Strict mode is the one setting:
 
 `exclude` keeps folders out of the system scan, same syntax as the CLI below.
 
+Security-conscious teams can pin to an exact commit instead of a version tag:
+`uses: gregkozakiewicz/guard-my-design-system@<commit-sha>`.
+
 ## On your machine
 
 Judge your uncommitted work before anyone else sees it:
@@ -123,6 +131,28 @@ Requires Node 18+ and git.
   on-system value the author probably meant, so the fix takes thirty seconds
   and no meeting.
 
+## Honest limits
+
+Things the guard deliberately does not do, said here so they never surprise you
+in a pull request:
+
+- **Monorepos are judged as one world.** The system is learned from the whole
+  repo, so a colour that is legitimate in `packages/ui` counts as known when it
+  appears in `apps/web`. Per-package judgement is roast's territory today.
+- **Spacing is compared within one unit.** A repo on a rem scale that receives
+  `13px` gets the flag, but "nearest existing value" never converts units:
+  claiming `0.75rem` is nearest to `13px` would be a judgement faked, not made.
+- **Taste is not judged, and tokens are a passport.** The right token in the
+  wrong place sails through, and defining a new token is never a sin. The
+  guard polices drift, not decisions: extending the system is legitimate work.
+- **On a fork's pull request, the comment cannot be posted** (GitHub hands the
+  workflow a read-only token). The guard still runs; the verdict lands in the
+  workflow log instead, with a line saying why. The same happens if the
+  workflow is missing `pull-requests: write`.
+- **Not on GitHub?** The CLI works anywhere git works: GitLab and Bitbucket CI
+  can run `npx guard-my-design-system --strict --base <target branch sha>` and
+  get the failing check. Only the comment-posting Action is GitHub-specific.
+
 ## The family
 
 [roast-my-design-system](https://github.com/gregkozakiewicz/roast-my-design-system)

package/index.mjs

@@ -58,8 +58,20 @@ try {
 }
 
 const exclude = opt('exclude') ? opt('exclude').split(',').map((s) => s.trim()) : [];
+
+// Excluded folders are invisible to the whole tool: not learned from, and not
+// judged either. Same sources as the scan (--exclude and .roastignore), same
+// plain folder prefixes, nothing clever.
+let ignorePrefixes = [...exclude];
+try {
+  ignorePrefixes.push(...readFileSync(resolve(cwd, '.roastignore'), 'utf8')
+    .split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#')));
+} catch { /* no .roastignore, nothing to add */ }
+ignorePrefixes = ignorePrefixes.map((p) => p.replace(/^\.?\//, '').replace(/\/?$/, '/'));
+const judged = added.filter(({ file }) => !ignorePrefixes.some((p) => (file + '/').startsWith(p)));
+
 const system = learnSystem(cwd, { exclude });
-const findings = judge(added, system);
+const findings = judge(judged, system);
 
 if (flag('json')) {
   console.log(JSON.stringify({ base, addedLines: added.length, findings }, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guard-my-design-system",
-  "version": "1.1.0",
+  "version": "1.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": "5.5.2"
+    "roast-my-design-system": "5.5.3"
   },
   "keywords": [
     "design-system",

package/src/judge.mjs

@@ -30,6 +30,23 @@ function exemptFiles(added) {
 
 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;
+};
+
 /**
  * Judge added lines against the learned system.
  * Returns [{ file, line, kind, value, advice }] sorted by file then line.
@@ -43,6 +60,7 @@ export function judge(added, system) {
   // if the repo uses it more times than this change added it.
   const exempt = exemptFiles(added);
   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) {
     if (exempt(file)) continue;
     const css = isStyleFile(file);
@@ -50,6 +68,12 @@ export function judge(added, system) {
     for (const s of extractStyling(text, { css }).spacing) {
       addedLengths.set(s.value, (addedLengths.get(s.value) ?? 0) + 1);
     }
+    if (css) {
+      for (const { kind, re } of EXTRA_KINDS) {
+        const v = extraValue(re, text);
+        if (v) addedExtras[kind].set(v, (addedExtras[kind].get(v) ?? 0) + 1);
+      }
+    }
     const fm = css ? FONT_LINE_RE.exec(text) : null;
     const face = fm ? typefaceOf(fm[1].trim()) : null;
     if (face) addedFaces.set(face, (addedFaces.get(face) ?? 0) + 1);
@@ -57,6 +81,18 @@ export function judge(added, system) {
   const knownLengths = new Set(
     system.spacing.filter((s) => s.count > (addedLengths.get(s.value) ?? 0)).map((s) => s.value)
   );
+  const knownExtras = {};
+  for (const { kind, learned } of EXTRA_KINDS) {
+    knownExtras[kind] = new Set(
+      (system[learned] ?? []).filter((e) => e.count > (addedExtras[kind].get(e.value) ?? 0)).map((e) => e.value)
+    );
+  }
+  // "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];
+    return n ? `var(${n}), ${value}` : value;
+  };
   const faceCounts = new Map();
   for (const f of system.fontFamilies) {
     const face = typefaceOf(f.value);
@@ -80,7 +116,7 @@ export function judge(added, system) {
       findings.push({
         file, line, kind: 'color', value: c.value,
         advice: near && near.distance <= 48
-          ? `nearest token: ${near.value}`
+          ? `nearest token: ${named(near.value)}`
           : system.tokenFile
             ? `no token resembles it — if it is a real decision, it belongs in ${system.tokenFile}`
             : 'no token layer found to compare against',
@@ -92,10 +128,26 @@ export function judge(added, system) {
       const near = nearestLength(s.value, [...knownLengths]);
       findings.push({
         file, line, kind: 'spacing', value: s.value,
-        advice: near ? `nearest existing value: ${near.value}` : 'first value of its unit in this codebase',
+        advice: near ? `nearest existing value: ${named(near.value)}` : 'first value of its unit in this codebase',
       });
     }
 
+    if (css) {
+      for (const { kind, re } of EXTRA_KINDS) {
+        const v = extraValue(re, text);
+        if (!v || knownExtras[kind].has(v)) continue;
+        const near = nearestLength(v, [...knownExtras[kind]]);
+        findings.push({
+          file, line, kind, value: v,
+          advice: near
+            ? `nearest existing value: ${named(near.value)}`
+            : knownExtras[kind].size
+              ? `differs from every one the system declares`
+              : 'first of its kind in this codebase',
+        });
+      }
+    }
+
     for (const a of seen.arbitrary) {
       findings.push({
         file, line, kind: 'arbitrary', value: a.value,

package/src/report.mjs

@@ -7,6 +7,9 @@
 const KIND_LABEL = {
   color: 'new colour',
   spacing: 'new spacing value',
+  radius: 'new border radius',
+  fontsize: 'new font size',
+  shadow: 'new shadow',
   arbitrary: 'arbitrary Tailwind value',
   important: '!important',
   font: 'new typeface',