guard-my-design-system 0.0.1 → 1.0.0

package/README.md

@@ -6,30 +6,80 @@ Design systems don't die in a redesign. They die one pull request at a time:
 a colour that's nearly the token, a spacing value that's off the scale, an
 `!important` that seemed harmless on a Friday.
 
-This is the smoke alarm at the door. It checks only the lines a pull request
-adds, says nothing about the past, and points each new sin at the on-system
+This is the smoke alarm at the door. It checks **only the lines a pull request
+adds**, says nothing about the past, and points each new sin at the on-system
 value the author probably meant. Old wiring is not its business; new sparks
 are.
 
-## Status
+It learns your system by scanning your repo with the
+[roast-my-design-system](https://github.com/gregkozakiewicz/roast-my-design-system)
+engine, then judges the diff against what it learned. No config files, no
+rules to write, no tokens to register. Your codebase is the rulebook.
+
+## What it catches
+
+- a hard-coded colour where a token exists, with the nearest token named
+- a spacing value the codebase has never used, with the nearest step named
+- a typeface the system doesn't declare
+- `!important`
+- arbitrary Tailwind values (`w-[137px]`, `mt-[37px]`)
+
+And what it deliberately ignores: everything that was already there. Even if
+the codebase carries years of mess, the guard only asks one question of a
+change: does it make things worse?
+
+## On a pull request
+
+```yaml
+# .github/workflows/guard.yml
+name: guard
+on: pull_request
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: gregkozakiewicz/guard-my-design-system@v1
+```
+
+Every pull request gets one comment, updated in place, like:
+
+> **🛡 guard-my-design-system: 2 new issues in this pull request**
+>
+> - `Card.tsx:24` — new colour `#4a7be8`. Nearest token: `#3b6fe0`.
+> - `Card.tsx:31` — new spacing value `13px`. Nearest existing value: `12px`.
 
-Not ready yet. This publish reserves the name while v1 is built.
+Prefer a failed check over a comment? Strict mode is the one setting:
 
-When it ships, setup will be five minutes: one devDependency and a copy-paste
-GitHub Action. After that you forget it exists, which is the whole point of a
-smoke alarm.
+```yaml
+      - uses: gregkozakiewicz/guard-my-design-system@v1
+        with:
+          strict: true
+```
 
-## In the meantime
+## On your machine
 
-Find out how bad things already are:
+Judge your uncommitted work before anyone else sees it:
 
 ```bash
-npx roast-my-design-system
+npx guard-my-design-system
 ```
 
+Flags: `--base <ref>` to diff against something other than main,
+`--strict` to exit 1 on findings, `--json` for machines,
+`--exclude <paths>` to leave folders out of the system scan.
+
+## The family
+
 [roast-my-design-system](https://github.com/gregkozakiewicz/roast-my-design-system)
 diagnoses the whole codebase and scores it against a 34-repo benchmark.
-roast diagnoses it, guard protects it.
+guard keeps new work from adding to the pile. Roast diagnoses it, guard
+protects it.
 
 ## Licence
 

package/index.mjs

@@ -1,14 +1,55 @@
 #!/usr/bin/env node
+/**
+ * guard-my-design-system — no new mess.
+ *
+ * Judges ONLY the lines a change adds against the design system the repo
+ * already has. Learns the system with the roast engine, reads the diff,
+ * says what strayed and what was probably meant instead.
+ *
+ *   npx guard-my-design-system [path] [--base <ref>] [--strict] [--json]
+ *                              [--exclude <path>]
+ *
+ * Exit codes: 0 clean (or findings without --strict), 1 findings with
+ * --strict, 2 could not run.
+ */
+import { resolve } from 'node:path';
+import { learnSystem } from 'roast-my-design-system/engine';
+import { defaultBase, addedLines } from './src/diff.mjs';
+import { judge } from './src/judge.mjs';
+import { terminalReport, markdownReport } from './src/report.mjs';
 
-console.log(`
-guard-my-design-system — no new mess.
+const argv = process.argv.slice(2);
+const flag = (name) => argv.includes(`--${name}`);
+const opt = (name) => {
+  const i = argv.indexOf(`--${name}`);
+  return i > -1 && argv[i + 1] ? argv[i + 1] : null;
+};
 
-A pull request guard that stops design system drift one diff at a time.
-It is not ready yet. This publish reserves the name while it is built.
+const cwd = resolve(argv[0] && !argv[0].startsWith('--') ? argv[0] : '.');
+const base = opt('base') ?? defaultBase(cwd);
+if (!base) {
+  console.error('guard: cannot find a base to diff against (no origin/main, origin/master, main or master). Pass one with --base <ref>.');
+  process.exit(2);
+}
 
-In the meantime, find out how bad things already are:
+let added;
+try {
+  added = addedLines(cwd, base);
+} catch (e) {
+  console.error(`guard: git diff failed — ${e.message.split('\n')[0]}`);
+  process.exit(2);
+}
 
-  npx roast-my-design-system
+const exclude = opt('exclude') ? opt('exclude').split(',').map((s) => s.trim()) : [];
+const system = learnSystem(cwd, { exclude });
+const findings = judge(added, system);
 
-Follow along: https://github.com/gregkozakiewicz/guard-my-design-system
-`);
+if (flag('json')) {
+  console.log(JSON.stringify({ base, addedLines: added.length, findings }, null, 2));
+} else if (flag('markdown')) {
+  console.log(markdownReport(findings));
+} else {
+  console.log(terminalReport(findings));
+}
+
+process.exit(findings.length && flag('strict') ? 1 : 0);

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "guard-my-design-system",
-  "version": "0.0.1",
-  "description": "No new mess. A pull request guard that stops design system drift one diff at a time. Coming soon.",
+  "version": "1.0.0",
+  "description": "No new mess. A pull request guard that judges only the lines a change adds against the design system the repo already has, and names the on-system value the author probably meant.",
   "type": "module",
   "bin": {
     "guard-my-design-system": "index.mjs"
   },
   "files": [
-    "index.mjs"
+    "index.mjs",
+    "src/"
   ],
+  "dependencies": {
+    "roast-my-design-system": "5.5.2"
+  },
   "keywords": [
     "design-system",
     "design-tokens",

package/src/diff.mjs

@@ -0,0 +1,57 @@
+/**
+ * Diff reading — the guard's field of vision. It sees ONLY the lines a change
+ * adds; the rest of the codebase is deliberately invisible. Old mess is not
+ * its business; new sparks are.
+ */
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** The ref new work is measured against: merge-base with the main branch. */
+export function defaultBase(cwd) {
+  for (const ref of ['origin/main', 'origin/master', 'main', 'master']) {
+    try {
+      return execFileSync('git', ['merge-base', 'HEAD', ref], { cwd, encoding: 'utf8' }).trim();
+    } catch { /* try the next spelling */ }
+  }
+  return null;
+}
+
+/**
+ * Added lines between base and the working tree (committed or not), as
+ * [{ file, line, text }]. Unified diff with zero context so every '+' line
+ * is genuinely new.
+ */
+export function addedLines(cwd, base) {
+  const out = execFileSync('git', ['diff', '-U0', '--no-color', base, '--'], {
+    cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+  });
+  const added = [];
+  let file = null, line = 0;
+  for (const raw of out.split('\n')) {
+    if (raw.startsWith('+++ ')) {
+      file = raw.slice(4).replace(/^b\//, '');
+      if (file === '/dev/null') file = null;
+      continue;
+    }
+    if (raw.startsWith('@@')) {
+      const m = /\+(\d+)/.exec(raw);
+      line = m ? parseInt(m[1], 10) : 0;
+      continue;
+    }
+    if (!file) continue;
+    if (raw.startsWith('+')) { added.push({ file, line, text: raw.slice(1) }); line++; }
+    // '-' lines belong to the old world; context lines don't appear at -U0
+  }
+  // A brand-new file not yet staged never appears in git diff; every one of
+  // its lines is added work all the same.
+  const untracked = execFileSync('git', ['ls-files', '--others', '--exclude-standard'], {
+    cwd, encoding: 'utf8',
+  }).split('\n').filter(Boolean);
+  for (const f of untracked) {
+    let text;
+    try { text = readFileSync(join(cwd, f), 'utf8'); } catch { continue; }
+    text.split('\n').forEach((t, i) => { if (t.trim()) added.push({ file: f, line: i + 1, text: t }); });
+  }
+  return added;
+}

package/src/judge.mjs

@@ -0,0 +1,115 @@
+/**
+ * The judge — added lines on one side, the learned system on the other.
+ * All detection comes from the roast engine's official doorway; this file
+ * only decides what counts as "new mess" in the context of a diff.
+ *
+ * The rule for every sin: it must be NEW. A colour that is already a token,
+ * a length the codebase already uses, a typeface the system already declares
+ * — all invisible. The guard never asks anyone to clean the past.
+ */
+import {
+  extractStyling, normalizeHex, nearestColor, nearestLength,
+  isCodeFile, isStyleFile, typefaceOf, GENERIC_FONTS,
+} from 'roast-my-design-system/engine';
+
+// Same honesty exemptions the engine applies: email and print styling must be
+// inline, and artwork files carry hex that is drawing, not styling.
+const EXEMPT_FILE_RE = /email|(^|[/.])print([/.]|$)|(^|\/)[\w.-]*(icon|logo|badge|illustration|artwork)[\w.-]*\.(tsx|jsx)$/i;
+
+const FONT_LINE_RE = /font-family\s*:\s*([^;{}]+)/i;
+
+/**
+ * Judge added lines against the learned system.
+ * Returns [{ file, line, kind, value, advice }] sorted by file then line.
+ * kinds: color | spacing | arbitrary | important | font
+ */
+export function judge(added, system) {
+  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 addedLengths = new Map(), addedFaces = new Map();
+  for (const { file, line, text } of added) {
+    if (EXEMPT_FILE_RE.test(file)) continue;
+    const css = isStyleFile(file);
+    if (!css && !isCodeFile(file)) continue;
+    for (const s of extractStyling(text, { css }).spacing) {
+      addedLengths.set(s.value, (addedLengths.get(s.value) ?? 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);
+  }
+  const knownLengths = new Set(
+    system.spacing.filter((s) => s.count > (addedLengths.get(s.value) ?? 0)).map((s) => s.value)
+  );
+  const faceCounts = new Map();
+  for (const f of system.fontFamilies) {
+    const face = typefaceOf(f.value);
+    if (face) faceCounts.set(face, (faceCounts.get(face) ?? 0) + f.count);
+  }
+  const knownFaces = new Set(
+    [...faceCounts].filter(([face, n]) => n > (addedFaces.get(face) ?? 0)).map(([face]) => face)
+  );
+  const findings = [];
+
+  for (const { file, line, text } of added) {
+    if (EXEMPT_FILE_RE.test(file)) continue;
+    const css = isStyleFile(file);
+    if (!css && !isCodeFile(file)) continue;
+
+    const seen = extractStyling(text, { css });
+
+    for (const c of seen.colors) {
+      if (tokenSet.has(c.value)) continue; // disciplined token use
+      const near = c.value.startsWith('#') ? nearestColor(c.value, system.tokens) : null;
+      findings.push({
+        file, line, kind: 'color', value: c.value,
+        advice: near && near.distance <= 48
+          ? `nearest token: ${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',
+      });
+    }
+
+    for (const s of seen.spacing) {
+      if (knownLengths.has(s.value)) continue; // the codebase already uses it
+      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',
+      });
+    }
+
+    for (const a of seen.arbitrary) {
+      findings.push({
+        file, line, kind: 'arbitrary', value: a.value,
+        advice: 'an arbitrary Tailwind value sidesteps the scale; use a scale step or add one',
+      });
+    }
+
+    for (const _ of seen.important) {
+      findings.push({
+        file, line, kind: 'important', value: '!important',
+        advice: 'the cascade admitting defeat; raise specificity or fix the source order',
+      });
+    }
+
+    const fm = css ? FONT_LINE_RE.exec(text) : null;
+    if (fm && !/^(var\(--[\w-]+\)|inherit)$/i.test(fm[1].trim())) {
+      const face = typefaceOf(fm[1].trim());
+      if (face && !GENERIC_FONTS.has(face.toLowerCase()) && !knownFaces.has(face)) {
+        findings.push({
+          file, line, kind: 'font', value: face,
+          advice: knownFaces.size
+            ? `the system declares: ${[...knownFaces].join(', ')}`
+            : 'first typeface declared in this codebase',
+        });
+      }
+    }
+  }
+
+  return findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+}

package/src/report.mjs

@@ -0,0 +1,51 @@
+/**
+ * The voice — findings are blunt, advice is calm and starts from intent.
+ * One format for the terminal, one for the PR comment (markdown). Both end
+ * by pointing at the inspector for the full picture.
+ */
+
+const KIND_LABEL = {
+  color: 'new colour',
+  spacing: 'new spacing value',
+  arbitrary: 'arbitrary Tailwind value',
+  important: '!important',
+  font: 'new typeface',
+};
+
+const FOOTER = 'Full picture of the whole codebase: `npx roast-my-design-system`';
+
+export function terminalReport(findings) {
+  if (!findings.length) {
+    return 'guard-my-design-system: no new mess. Nothing added in this change strays from the system.';
+  }
+  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('');
+  lines.push('  Only lines added in this change were counted. The existing codebase was not judged.');
+  lines.push(`  ${FOOTER.replaceAll('`', '')}`);
+  return lines.join('\n');
+}
+
+export function markdownReport(findings) {
+  if (!findings.length) {
+    return [
+      '**🛡 guard-my-design-system: no new mess**',
+      '',
+      'Nothing added in this pull request strays from the design system.',
+      '',
+      `<sub>Only added lines are checked; the existing codebase is never judged. ${FOOTER}</sub>`,
+    ].join('\n');
+  }
+  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('');
+  out.push(`<sub>Only added lines are checked; the existing codebase is never judged. ${FOOTER}</sub>`);
+  return out.join('\n');
+}
+
+const capitalise = (s) => s.charAt(0).toUpperCase() + s.slice(1);