guard-my-design-system 1.1.1 → 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guard-my-design-system",
-  "version": "1.1.1",
+  "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',