roast-my-design-system 5.5.0 → 5.5.2

package/README.md

@@ -59,7 +59,7 @@ One scan powers all of it; the flags decide what lands on disk. Combine freely.
 
 The full report for vercel/ai-chatbot, top to bottom — including "What the numbers mean", Claude's read of the scan, embedded right under the verdict:
 
-![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, the What the numbers mean analysis written by Claude, priced Where to start moves, the wrapped present with the agent rules, an agent trap callout, three-yardstick tiles, palette forensics, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-full-dark.png?v=5.2.3)
+![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, the What the numbers mean analysis written by Claude, priced Where to start moves, the wrapped present with the agent rules, an agent trap callout, three-yardstick tiles, the adoption map treemap, palette forensics, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-full-dark.png?v=5.5.1)
 
 The same report in light mode (one file, built-in toggle):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "5.5.0",
+  "version": "5.5.2",
   "mcpName": "io.github.gregkozakiewicz/roast-my-design-system",
   "description": "Your AI can write the UI. This makes sure it writes your UI. A deterministic scanner scores your design system 0-100 against 34 public repos, writes rules for Claude, Cursor, Copilot and Windsurf with --apply, and runs as a local MCP server with --mcp.",
   "keywords": [
@@ -30,6 +30,10 @@
   "license": "MIT",
   "author": "Greg Kozakiewicz (https://gregkozakiewicz.com)",
   "type": "module",
+  "exports": {
+    "./engine": "./skills/roast-my-design-system/scripts/lib/guard-api.mjs",
+    "./package.json": "./package.json"
+  },
   "bin": {
     "roast-my-design-system": "bin/roast.mjs"
   },

package/skills/roast-my-design-system/scripts/lib/guard-api.mjs

@@ -0,0 +1,98 @@
+/**
+ * guard-api — the one official doorway into the engine for OTHER packages.
+ *
+ * guard-my-design-system imports this file (through the roast npm package's
+ * "./engine" export). Everything else in the engine stays private and free to
+ * refactor; what is exported here is a public promise — rename or reshape it
+ * only with a deliberate version bump and a changelog line.
+ *
+ * Kept deliberately narrow: learn what the repo's system is, scan a piece of
+ * text for styling, and say which on-system value a stray most resembles.
+ */
+import { extname } from 'node:path';
+import { walkRepo } from '../harvest/walk.mjs';
+import { harvestTokens, extractStyling, normalizeHex, isGrey } from '../harvest/tokens.mjs';
+import { loadExclusions } from './exclusions.mjs';
+import { hexRgb } from './nearpairs.mjs';
+import { typefaceOf, GENERIC_FONTS } from './typefaces.mjs';
+
+export { extractStyling, normalizeHex, isGrey, hexRgb, typefaceOf, GENERIC_FONTS };
+
+// Same classification walkRepo uses, exposed so a caller looking at one file
+// (a diff hunk) treats it the way the full scan would.
+const CODE_EXTS = new Set(['.tsx', '.jsx', '.ts', '.js', '.mjs', '.cjs']);
+const STYLE_EXTS = new Set(['.css', '.scss', '.sass', '.less']);
+export const isCodeFile = (p) => CODE_EXTS.has(extname(p));
+export const isStyleFile = (p) => STYLE_EXTS.has(extname(p));
+
+/**
+ * Scan the whole repo once and return what its design system IS — the
+ * reference a guard judges new lines against. Respects .roastignore.
+ *
+ * Returns {
+ *   tokenFile,        // the file defining the most --vars, or null
+ *   colors,           // [{ value, count, isToken, files }] every colour seen
+ *   tokens,           // shorthand: just the token colour values
+ *   spacing,          // [{ value, count, files }] every length seen
+ *   fontFamilies,     // [{ value, count, files }] every family declared
+ *   tailwind,         // { colors, spacing, radii, textSizes, arbitrary }
+ *   files,            // { styles: n, code: n } — how much was read
+ * }
+ */
+export function learnSystem(repoRoot, { exclude = [] } = {}) {
+  const exclusions = loadExclusions(repoRoot, exclude);
+  const files = walkRepo(repoRoot, 14, exclusions);
+  const t = harvestTokens(repoRoot, files.styles, files.code);
+  return {
+    tokenFile: t.tokenFile,
+    colors: t.colors,
+    tokens: t.colors.filter((c) => c.isToken).map((c) => c.value),
+    spacing: t.spacing,
+    fontFamilies: t.fontFamilies,
+    tailwind: t.tailwind,
+    files: { styles: files.styles.length, code: files.code.length },
+  };
+}
+
+/**
+ * The token a stray colour most resembles. Distance is the largest channel
+ * difference (the same yardstick nearColorPairs uses), so "8" here means what
+ * "near-identical" means everywhere else in the engine. Hex-parseable values
+ * only; returns { value, distance } or null.
+ */
+export function nearestColor(value, tokenValues) {
+  const target = hexRgb(normalizeHex(value));
+  if (!target) return null;
+  let best = null;
+  for (const t of tokenValues) {
+    const rgb = hexRgb(t);
+    if (!rgb || rgb.a !== target.a) continue;
+    const d = Math.max(Math.abs(rgb.r - target.r), Math.abs(rgb.g - target.g), Math.abs(rgb.b - target.b));
+    if (d === 0) continue; // identical to a token: not a stray at all
+    if (!best || d < best.distance) best = { value: t, distance: d };
+  }
+  return best;
+}
+
+/**
+ * The on-scale length a stray spacing value most resembles. Same-unit
+ * comparison only (12px is not "near" 0.75rem here; unit conversion is a
+ * judgement the guard should not fake). Returns { value, distance } or null.
+ */
+export function nearestLength(value, scaleValues) {
+  const parse = (v) => {
+    const m = /^(-?\d*\.?\d+)(px|rem|em|%|vh|vw|pt)$/.exec(String(v).trim());
+    return m ? { n: parseFloat(m[1]), unit: m[2] } : null;
+  };
+  const target = parse(value);
+  if (!target) return null;
+  let best = null;
+  for (const s of scaleValues) {
+    const p = parse(s);
+    if (!p || p.unit !== target.unit) continue;
+    const d = Math.abs(p.n - target.n);
+    if (d === 0) continue;
+    if (!best || d < best.distance) best = { value: s, distance: d };
+  }
+  return best;
+}

package/skills/roast-my-design-system/scripts/lib/version.mjs

@@ -1,4 +1,4 @@
 // Single version constant for the engine — imported by diagnose (report
 // footer) and rules (generated-by line). This is the bump spot that used to
 // live as a const inside diagnose/index.mjs.
-export const VERSION = '5.5.0';
+export const VERSION = '5.5.2';