@weatherboard/gyde-design 0.3.0

package/normalise.mjs

@@ -0,0 +1,416 @@
+/**
+ * G-51 — one representation every styling idiom reduces to.
+ *
+ * WHY THIS EXISTS.
+ *
+ * Every design-system audit we have was written against one repository's
+ * spelling, and each one was correct locally and useless one repository over:
+ *
+ *   System B               /\brounded-(lg|xl|2xl|3xl)\b/       Tailwind classes
+ *   System A  /border-radius:\s*(.+)/             CSS declarations
+ *   System C   —                                   (no audit at all)
+ *
+ * System B's rules would match nothing in System A, which has no Tailwind;
+ * System A's would match nothing in System C's cva strings.
+ * A rule that matches nothing reports zero and is indistinguishable from a rule
+ * that is working — CHARTER §5's failure mode, reached in the rule layer.
+ *
+ * And it is not only cross-repo. One repository recorded its own `no-rounded-lg`
+ * matching one literal spelling, missing every `rounded-xl` / `-2xl` / `-3xl`,
+ * and reporting **zero** while 178 real hits existed.
+ *
+ * THE FIX IS NOT A BIGGER REGEX. It is to stop matching source text. Every
+ * idiom below expresses the same four decisions — a radius, a spacing, a type
+ * size, a colour — so we parse each into a `Decl` and write the rules once,
+ * against that:
+ *
+ *   rounded-lg              Tailwind utility        → radius 8px
+ *   border-radius: 8px      CSS declaration         → radius 8px
+ *   borderRadius: 8         JS/StyleX object        → radius 8px
+ *   borderRadius: radius.card                       → radius, tokenised
+ *   var(--radius-card)      custom property         → radius, tokenised
+ *
+ * A rule then asks "is this radius tokenised?", which is the question it was
+ * always trying to ask, and gets the same answer in all five spellings.
+ *
+ * WHAT THIS IS NOT. It is a lexical pass, not a renderer. It cannot know that
+ * `p-4` resolved to 16px through a customised Tailwind scale, and it does not
+ * try — `scaleHint` carries the assumption so a caller can correct it, and
+ * `confidence` marks what was inferred rather than read. G-11 renders the real
+ * artifact and is the place to measure computed style; this is what runs on
+ * source, at commit time, without a browser.
+ */
+
+/** Canonical properties. Deliberately few — these are the decisions a token dictionary makes. */
+export const PROP = {
+  RADIUS: "radius",
+  SPACE: "space",
+  TYPE: "type",
+  COLOR: "color",
+  SHADOW: "shadow",
+  FONT: "font",
+  BORDER_WIDTH: "borderWidth",
+};
+
+/**
+ * Tailwind's default scales, as the ASSUMPTION they are.
+ *
+ * System C runs stock Tailwind 3.4, so these hold there. A project that
+ * customises `theme.extend.spacing` makes them wrong, which is why every Decl
+ * built from a utility carries `confidence: "assumed"` and `scaleHint`. A rule
+ * that needs certainty must check `confidence` rather than trusting the number:
+ * being wrong quietly is the thing this module exists to stop.
+ */
+export const TAILWIND_SPACING_STEP = 4; // p-4 → 16px
+export const TAILWIND_RADIUS = {
+  none: 0, sm: 2, DEFAULT: 4, md: 6, lg: 8, xl: 12, "2xl": 16, "3xl": 24, full: 9999,
+};
+export const TAILWIND_TEXT = {
+  xs: 12, sm: 14, base: 16, lg: 18, xl: 20, "2xl": 24, "3xl": 30,
+  "4xl": 36, "5xl": 48, "6xl": 60, "7xl": 72, "8xl": 96, "9xl": 128,
+};
+
+/** Values that are never a design decision and must never be reported. */
+const NEUTRAL = new Set([
+  "0", "0px", "none", "inherit", "initial", "unset", "revert", "auto", "currentcolor",
+  "transparent", "normal",
+]);
+
+/**
+ * A single normalised decision.
+ *
+ * `tokenised` is the field the rules care about: true when the value came from
+ * a dictionary (a `var(--x)`, a `tokens.radius.card`, a Tailwind semantic class
+ * backed by a CSS variable) rather than being spelled literally at the call site.
+ */
+function decl(property, { px = null, token = null, raw, source, confidence = "read", scaleHint = null }) {
+  return {
+    property,
+    px,                      // comparable number where one could be derived
+    token,                   // the token reference, when the value was tokenised
+    tokenised: token !== null,
+    neutral: NEUTRAL.has(String(raw).trim().toLowerCase()),
+    raw: String(raw).trim(),
+    source,                  // "tailwind" | "css" | "object" | "var"
+    confidence,              // "read" (literally present) | "assumed" (from a default scale)
+    scaleHint,               // which assumption was applied, when confidence is "assumed"
+  };
+}
+
+/** `8px` / `1.5rem` / `8` → px. Returns null for anything not a length. */
+export function toPx(value, { rootFontSize = 16 } = {}) {
+  const v = String(value).trim();
+  let m = v.match(/^(-?[\d.]+)px$/); if (m) return parseFloat(m[1]);
+  m = v.match(/^(-?[\d.]+)(?:rem|em)$/); if (m) return parseFloat(m[1]) * rootFontSize;
+  m = v.match(/^(-?[\d.]+)$/); if (m) return parseFloat(m[1]);        // unitless JS style
+  return null;
+}
+
+/** Any reference to a dictionary: `var(--x)`, `tokens.radius.card`, `radius.card`, `$radius.card`. */
+function tokenRef(value) {
+  const v = String(value).trim();
+  const cssVar = v.match(/var\(\s*(--[\w-]+)/);
+  if (cssVar) return cssVar[1];
+  // A StyleX/JS member expression into a token object. Deliberately narrow: a
+  // bare identifier is not evidence of a dictionary, and treating it as one
+  // would make every local variable look tokenised.
+  const member = v.match(/^\$?((?:tokens|colors|color|space|spacing|radius|text|type|fonts?|elevation|shadow)(?:\.[A-Za-z_$][\w$]*)+)$/);
+  if (member) return member[1];
+  return null;
+}
+
+/** The CSS properties we map, and to which canonical property. */
+const CSS_PROPERTY = new Map(Object.entries({
+  "border-radius": PROP.RADIUS,
+  "border-top-left-radius": PROP.RADIUS, "border-top-right-radius": PROP.RADIUS,
+  "border-bottom-left-radius": PROP.RADIUS, "border-bottom-right-radius": PROP.RADIUS,
+  padding: PROP.SPACE, "padding-top": PROP.SPACE, "padding-right": PROP.SPACE,
+  "padding-bottom": PROP.SPACE, "padding-left": PROP.SPACE,
+  margin: PROP.SPACE, "margin-top": PROP.SPACE, "margin-right": PROP.SPACE,
+  "margin-bottom": PROP.SPACE, "margin-left": PROP.SPACE,
+  gap: PROP.SPACE, "row-gap": PROP.SPACE, "column-gap": PROP.SPACE,
+  "font-size": PROP.TYPE,
+  "font-family": PROP.FONT,
+  color: PROP.COLOR, background: PROP.COLOR, "background-color": PROP.COLOR,
+  "border-color": PROP.COLOR, "border-top-color": PROP.COLOR, "border-right-color": PROP.COLOR,
+  "border-bottom-color": PROP.COLOR, "border-left-color": PROP.COLOR,
+  "outline-color": PROP.COLOR, fill: PROP.COLOR, stroke: PROP.COLOR,
+  "box-shadow": PROP.SHADOW, "text-shadow": PROP.SHADOW,
+  "border-width": PROP.BORDER_WIDTH, "border-top-width": PROP.BORDER_WIDTH,
+}));
+
+/** camelCase → kebab-case, so `borderRadius` and `border-radius` reach one lookup. */
+const kebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+
+/**
+ * Shorthands carry several decisions in one value.
+ *
+ * `padding: 8px 16px` is two spacings, and System A's rule found this
+ * the hard way — checking only the first value passed `margin: 0 auto 12px`
+ * while the 12px was untokenised. Split on whitespace outside parentheses, so
+ * `0 0 0 var(--space-2)` and `1px solid rgb(0 0 0 / 10%)` both survive.
+ */
+function splitValues(value) {
+  const parts = [];
+  let depth = 0, cur = "";
+  for (const ch of String(value)) {
+    if (ch === "(") depth++;
+    if (ch === ")") depth--;
+    if (/\s/.test(ch) && depth === 0) { if (cur) parts.push(cur); cur = ""; continue; }
+    cur += ch;
+  }
+  if (cur) parts.push(cur);
+  return parts;
+}
+
+/** A colour literal: hex, rgb(), hsl(), oklch(), or a CSS named colour we care about. */
+const COLOUR_LITERAL = /^(#[0-9a-f]{3,8}|(rgb|hsl|hwb|lab|lch|oklab|oklch|color)a?\()/i;
+const NAMED_COLOURS = new Set([
+  "red", "blue", "green", "yellow", "purple", "pink", "orange", "black", "white",
+  "grey", "gray", "teal", "cyan", "indigo", "violet", "brown", "silver", "gold",
+]);
+
+/** One `property: value` pair, from CSS or from a JS/StyleX object. */
+export function normaliseDeclaration(rawProp, rawValue, { source = "css", rootFontSize = 16 } = {}) {
+  const prop = kebab(String(rawProp).trim());
+  const canonical = CSS_PROPERTY.get(prop);
+  if (!canonical) return [];
+
+  const out = [];
+  for (const part of splitValues(rawValue)) {
+    const token = tokenRef(part);
+    if (token) { out.push(decl(canonical, { token, raw: part, source: source === "css" ? "var" : source })); continue; }
+
+    if (canonical === PROP.COLOR) {
+      const lower = part.toLowerCase();
+      if (NEUTRAL.has(lower)) { out.push(decl(canonical, { raw: part, source })); continue; }
+      if (COLOUR_LITERAL.test(part) || NAMED_COLOURS.has(lower)) {
+        out.push(decl(canonical, { raw: part, source }));
+      }
+      continue;
+    }
+
+    if (canonical === PROP.SHADOW || canonical === PROP.FONT) {
+      out.push(decl(canonical, { raw: part, source }));
+      continue;
+    }
+
+    const px = toPx(part, { rootFontSize });
+    if (px !== null || NEUTRAL.has(part.toLowerCase())) {
+      out.push(decl(canonical, { px, raw: part, source }));
+    }
+  }
+  return out;
+}
+
+/**
+ * Parse a block of CSS text into declarations, keeping the line number.
+ *
+ * Declarations are found ANYWHERE on the line, not just at its start. The first
+ * version anchored to line-start and silently read nothing from `.a { color: red }`
+ * — a whole class of minified, nested and single-line CSS, invisible. That is
+ * the module's own failure mode arriving one level down, which is why the
+ * fixtures in rules.mjs are deliberately written single-line.
+ */
+export function normaliseCss(text, { rootFontSize = 16 } = {}) {
+  const out = [];
+  text.split("\n").forEach((line, i) => {
+    // Strip comments; a `@media`/`@import` prelude declares nothing itself.
+    const clean = line.replace(/\/\*.*?\*\//g, "");
+
+    // A declaration follows the line start, a `{`, or a `;`. Requiring one of
+    // those is what keeps `https://x` and `a:hover {` from parsing as values.
+    for (const m of clean.matchAll(/(?:^|[{;])\s*(--[\w-]+|[a-zA-Z-]+)\s*:\s*([^;{}]+)/g)) {
+      const [, prop, value] = m;
+      // A custom property DEFINITION is the dictionary being written, not a use
+      // of it. `--color-surface: #0b0d10` in System A's console is the
+      // correct way to run a second palette and must not be reported as
+      // a bespoke colour, or the mechanism becomes unusable.
+      if (prop.startsWith("--")) continue;
+      for (const d of normaliseDeclaration(prop, value, { source: "css", rootFontSize })) {
+        out.push({ ...d, line: i + 1 });
+      }
+    }
+  });
+  return out;
+}
+
+/**
+ * Tailwind / cva utility classes.
+ *
+ * System C's whole component layer is `cva("... rounded-md h-10 px-4 ...")`,
+ * so without this the normaliser sees an entire design system as opaque strings.
+ *
+ * Semantic utilities that resolve through a CSS variable — `bg-primary`,
+ * `text-muted-foreground`, the shadcn convention — are TOKENISED, which is the
+ * subtle and important case. `bg-primary` is a dictionary reference spelled as
+ * a class; treating it as a bespoke colour would report a correctly-built
+ * shadcn component as 100% violations and the rule would be switched off within
+ * a day.
+ */
+const SEMANTIC_COLOUR_WORDS = new Set([
+  "primary", "secondary", "destructive", "muted", "accent", "popover", "card",
+  "background", "foreground", "border", "input", "ring", "success", "warning",
+  "danger", "surface", "canvas", "raised", "inset", "faint",
+]);
+
+export function normaliseUtilities(classString, { spacingStep = TAILWIND_SPACING_STEP } = {}) {
+  const out = [];
+  // Interpolations carry no literal class; System A strips them for
+  // the same reason — `${active ? "a" : "b"}` is not a spelling we can read.
+  const cleaned = String(classString).replace(/\$\{[^}]*\}/g, " ");
+
+  for (const raw of cleaned.split(/\s+/)) {
+    if (!raw) continue;
+    // Drop variant prefixes: `hover:`, `md:`, `dark:`, `focus-visible:`.
+    const cls = raw.replace(/^(?:[\w-]+:)+/, "");
+    if (!cls) continue;
+
+    // Arbitrary values are always literal by definition: `rounded-[7px]`.
+    const arb = cls.match(/^([\w-]+?)-\[(.+)\]$/);
+    if (arb) {
+      const [, prefix, value] = arb;
+      const canonical = utilityProperty(prefix);
+      if (canonical) {
+        out.push(decl(canonical, {
+          px: toPx(value), raw: cls, source: "tailwind",
+          // The value is right there in the class, so this is read, not assumed.
+        }));
+      }
+      continue;
+    }
+
+    let m;
+    if ((m = cls.match(/^rounded(?:-(\w+))?$/))) {
+      const key = m[1] ?? "DEFAULT";
+      if (key in TAILWIND_RADIUS) {
+        out.push(decl(PROP.RADIUS, {
+          px: TAILWIND_RADIUS[key], raw: cls, source: "tailwind",
+          confidence: "assumed", scaleHint: "tailwind default borderRadius scale",
+        }));
+      } else {
+        // `rounded-card` — a project-defined semantic radius, i.e. tokenised.
+        out.push(decl(PROP.RADIUS, { token: `radius.${key}`, raw: cls, source: "tailwind" }));
+      }
+      continue;
+    }
+
+    if ((m = cls.match(/^text-(\w+)$/))) {
+      const key = m[1];
+      if (key in TAILWIND_TEXT) {
+        out.push(decl(PROP.TYPE, {
+          px: TAILWIND_TEXT[key], raw: cls, source: "tailwind",
+          confidence: "assumed", scaleHint: "tailwind default fontSize scale",
+        }));
+      } else if (SEMANTIC_COLOUR_WORDS.has(key) || key.endsWith("foreground")) {
+        out.push(decl(PROP.COLOR, { token: `color.${key}`, raw: cls, source: "tailwind" }));
+      }
+      continue;
+    }
+
+    // `bg-red-500` / `text-red-500` / `border-blue-200`: a palette colour chosen
+    // at the call site. This is the shape System B's `no-arbitrary-color` targets.
+    if ((m = cls.match(/^(bg|text|border|fill|stroke|ring|outline)-([a-z]+)-(\d{2,3})$/))) {
+      out.push(decl(PROP.COLOR, { raw: cls, source: "tailwind" }));
+      continue;
+    }
+
+    if ((m = cls.match(/^(bg|border|ring|fill|stroke|outline)-([\w-]+)$/))) {
+      const word = m[2].replace(/\/\d+$/, "");
+      if (SEMANTIC_COLOUR_WORDS.has(word) || word.endsWith("foreground")) {
+        out.push(decl(PROP.COLOR, { token: `color.${word}`, raw: cls, source: "tailwind" }));
+      } else if (NAMED_COLOURS.has(word) || /^\[?#/.test(word)) {
+        out.push(decl(PROP.COLOR, { raw: cls, source: "tailwind" }));
+      }
+      continue;
+    }
+
+    if ((m = cls.match(/^-?(p|m|gap|space)([xytrbl])?-(\d+(?:\.\d+)?)$/))) {
+      out.push(decl(PROP.SPACE, {
+        px: parseFloat(m[3]) * spacingStep, raw: cls, source: "tailwind",
+        confidence: "assumed", scaleHint: `tailwind spacing step ${spacingStep}px`,
+      }));
+      continue;
+    }
+
+    if ((m = cls.match(/^shadow(?:-(\w+))?$/))) {
+      const key = m[1] ?? "DEFAULT";
+      if (key !== "none") out.push(decl(PROP.SHADOW, { raw: cls, source: "tailwind" }));
+      continue;
+    }
+  }
+  return out;
+}
+
+function utilityProperty(prefix) {
+  if (prefix === "rounded") return PROP.RADIUS;
+  if (prefix === "text") return PROP.TYPE;
+  if (prefix === "shadow") return PROP.SHADOW;
+  if (/^-?(p|m|gap|space)[xytrbl]?$/.test(prefix)) return PROP.SPACE;
+  if (/^(bg|border|fill|stroke|ring|outline)$/.test(prefix)) return PROP.COLOR;
+  return null;
+}
+
+/**
+ * A source file, whatever it is written in.
+ *
+ * Walks CSS declarations, JS/StyleX style objects, and class strings in one
+ * pass, so a caller never has to know which idiom a repository uses — which is
+ * the entire point, since two of our three repositories use more than one.
+ */
+export function normaliseSource(text, { filename = "", rootFontSize = 16, spacingStep = TAILWIND_SPACING_STEP } = {}) {
+  const isStyleSheet = /\.(css|scss)$/.test(filename);
+  if (isStyleSheet) return normaliseCss(text, { rootFontSize });
+
+  const out = [];
+  text.split("\n").forEach((line, i) => {
+    const at = (ds) => ds.forEach((d) => out.push({ ...d, line: i + 1 }));
+
+    /**
+     * Ranges of this line already accounted for.
+     *
+     * The first version ran the `className=` matcher and the bare-string matcher
+     * independently, so every class inside a className attribute was counted
+     * TWICE — `className="rounded-lg p-4 bg-red-500"` produced six findings
+     * instead of three, and every headline number built on Tailwind source was
+     * roughly double the truth.
+     *
+     * That is the exact failure this product exists to prevent, arriving in our
+     * own measurement: a number that is confidently wrong, in the direction that
+     * makes the tool look more useful. Claiming ranges is the fix, and the
+     * double-count test below is what stops it coming back.
+     */
+    const claimed = [];
+    const overlaps = (start, end) => claimed.some(([s, e]) => start < e && end > s);
+    const claim = (start, end) => claimed.push([start, end]);
+
+    // `className="..."` / `class="..."`.
+    for (const m of line.matchAll(/(?:className|class)\s*=\s*[{"'`]([^"'`}]*)/g)) {
+      claim(m.index, m.index + m[0].length);
+      at(normaliseUtilities(m[1], { spacingStep }));
+    }
+    // A quoted run of three or more utility-looking words. cva() and clsx()
+    // arguments are not attached to a className, so without this the whole
+    // shadcn variant table is invisible — but anything already claimed above is
+    // the same string seen twice.
+    for (const m of line.matchAll(/["'`]([a-z0-9-]+(?:\s+[a-z0-9:./[\]-]+){2,})["'`]/gi)) {
+      if (overlaps(m.index, m.index + m[0].length)) continue;
+      if (/\b(rounded|text-|bg-|p-|px-|py-|m-|gap-|border|shadow|flex|grid|h-|w-)/.test(m[1])) {
+        claim(m.index, m.index + m[0].length);
+        at(normaliseUtilities(m[1], { spacingStep }));
+      }
+    }
+
+    // Style objects: `borderRadius: 8`, `padding: "16px"`, `color: colors.ink`.
+    for (const m of line.matchAll(/([A-Za-z][\w$]*)\s*:\s*("[^"]*"|'[^']*'|`[^`]*`|[\w$.()#%-]+)/g)) {
+      const value = m[2].replace(/^["'`]|["'`]$/g, "");
+      at(normaliseDeclaration(m[1], value, { source: "object", rootFontSize }));
+    }
+
+    // Imperative DOM styling — `el.style.background = "red"`, `setProperty(...)`.
+    for (const m of line.matchAll(/\.style\.([A-Za-z][\w$]*)\s*=\s*["'`]([^"'`]*)["'`]/g)) {
+      at(normaliseDeclaration(m[1], m[2], { source: "object", rootFontSize }));
+    }
+  });
+  return out;
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@weatherboard/gyde-design",
+  "version": "0.3.0",
+  "private": false,
+  "description": "Scaffolds a design system into a product repository, then keeps auditing it.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Another-Iteration/gyde.git",
+    "directory": "packages/design"
+  },
+  "bin": {
+    "gyde-design": "./cli.mjs"
+  },
+  "exports": {
+    ".": "./index.mjs",
+    "./workspace.mjs": "./workspace.mjs",
+    "./normalise.mjs": "./normalise.mjs",
+    "./rules.mjs": "./rules.mjs",
+    "./scan.mjs": "./scan.mjs",
+    "./tokens.mjs": "./tokens.mjs",
+    "./boundaries.mjs": "./boundaries.mjs",
+    "./ratchet.mjs": "./ratchet.mjs",
+    "./emit.mjs": "./emit.mjs",
+    "./catalogue.mjs": "./catalogue.mjs",
+    "./agentdocs.mjs": "./agentdocs.mjs",
+    "./upgrade.mjs": "./upgrade.mjs",
+    "./usage.mjs": "./usage.mjs",
+    "./wiring.mjs": "./wiring.mjs",
+    "./clientboundary.mjs": "./clientboundary.mjs",
+    "./props.mjs": "./props.mjs",
+    "./docdrift.mjs": "./docdrift.mjs",
+    "./compound.mjs": "./compound.mjs",
+    "./markup.mjs": "./markup.mjs",
+    "./adoption.mjs": "./adoption.mjs",
+    "./tailwind.mjs": "./tailwind.mjs",
+    "./migration.mjs": "./migration.mjs",
+    "./stylex.mjs": "./stylex.mjs",
+    "./enforcement.mjs": "./enforcement.mjs"
+  },
+  "files": [
+    "*.mjs",
+    "!*.test.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test *.test.mjs",
+    "prepublishOnly": "npm test && node ./scripts/check-tarball.mjs"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}