guard-my-design-system 1.1.1 → 1.3.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.
@@ -44,6 +49,22 @@ And what it deliberately ignores: everything that was already there. Even if
 the codebase carries years of mess, the guard asks one question of a change:
 does it make things worse?
 
+## When the guard is wrong
+
+Sometimes an off-system value is the right call: a partner's brand colour, a
+gradient that needs its own stops. Say so on the line above, and the guard
+lets that one line pass:
+
+```css
+/* guard-ignore-next-line — partner brand colour, agreed with design */
+background: #e4002b;
+```
+
+Works in any file the guard reads (`//` in components, `/* */` in styles).
+The exception is visible in code review by nature, silences exactly one line,
+and keeps working on later pull requests that touch the same line. No config
+file, no rule IDs — a sentence a reviewer can read is the whole mechanism.
+
 ## Why this exists
 
 Nobody can win the argument "please go and clean up the codebase". Everyone can
@@ -85,6 +106,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:
@@ -105,6 +129,38 @@ npx guard-my-design-system@latest
 
 Requires Node 18+ and git.
 
+## Not on GitHub?
+
+The CLI works anywhere git works; only the comment-posting Action is
+GitHub-specific. On GitLab, the merge request pipeline gets the failing check
+with two lines in `.gitlab-ci.yml`:
+
+```yaml
+guard:
+  image: node:22
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  script:
+    - git fetch origin $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
+    - npx guard-my-design-system@latest --strict --base origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME
+```
+
+Bitbucket Pipelines, same idea in `bitbucket-pipelines.yml`:
+
+```yaml
+pipelines:
+  pull-requests:
+    '**':
+      - step:
+          image: node:22
+          script:
+            - git fetch origin $BITBUCKET_PR_DESTINATION_BRANCH
+            - npx guard-my-design-system@latest --strict --base origin/$BITBUCKET_PR_DESTINATION_BRANCH
+```
+
+The verdict prints in the pipeline log and `--strict` fails the step; the
+sticky PR comment stays a GitHub luxury for now.
+
 ## What makes the verdict trustworthy
 
 - **Only added lines are checked.** The existing codebase is never judged,
@@ -141,9 +197,9 @@ in a pull request:
   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.
+- **Not on GitHub?** Covered — copy-paste GitLab and Bitbucket recipes live in
+  [Not on GitHub?](#not-on-github) above. Only the comment-posting Action is
+  GitHub-specific.
 
 ## The family
 

package/index.mjs

@@ -71,7 +71,21 @@ 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(judged, system);
+let findings = judge(judged, system);
+
+// 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
+// diff), so an exception granted last month still protects its line today.
+// Visible in code review by nature — that is the whole safety of it.
+const fileCache = new Map();
+const lineAbove = (file, line) => {
+  if (!fileCache.has(file)) {
+    try { fileCache.set(file, readFileSync(resolve(cwd, file), 'utf8').split('\n')); }
+    catch { fileCache.set(file, []); }
+  }
+  return fileCache.get(file)[line - 2] ?? '';
+};
+findings = findings.filter((f) => !lineAbove(f.file, f.line).includes('guard-ignore-next-line'));
 
 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.1",
+  "version": "1.3.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',