@godxjp/ui 19.6.0 → 20.1.0

package/scripts/ui-audit.mjs

@@ -9,13 +9,22 @@ import { readdirSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, join, relative } from "node:path";
 
 const CWD = process.cwd();
+const SELF = (() => {
+  try {
+    return JSON.parse(readFileSync(join(CWD, "package.json"), "utf8")).name === "@godxjp/ui";
+  } catch {
+    return false;
+  }
+})();
 const args = process.argv.slice(2);
 const asJson = args.includes("--format") && args[args.indexOf("--format") + 1] === "json";
 const quiet = args.includes("--quiet");
 const dirArgs = args.filter((a) => !a.startsWith("--") && a !== "json");
 const SCAN_DIRS = dirArgs.length
   ? dirArgs
-  : ["resources/js/components", "resources/js/pages", "resources/js/layouts"];
+  : SELF
+    ? ["src", "docs"]
+    : ["resources/js/components", "resources/js/pages", "resources/js/layouts"];
 
 const PALETTE =
   "red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|gray|grey|slate|zinc|neutral|stone";
@@ -29,7 +38,29 @@ const EMOJI = /\p{Extended_Pictographic}/u;
 const EMOJI_FLAG = /\p{Regional_Indicator}/u;
 
 /**
- * @type {{id:string, severity:'error'|'warn', test:RegExp, message:string, standard?:string, exempt?:RegExp}[]}
+ * The attribute run of a JSX OPEN TAG, for rules that must see the whole element rather than one
+ * class name. Two things a plain `[^>]*` gets wrong, both of them the "green because it measured
+ * nothing" shape:
+ *
+ *  1. `[^>]` stops at the `>` of an arrow function, so `<Button onClick={() => go()} size="icon">`
+ *     was invisible while the identical `<Button size="icon" onClick={() => go()}>` was flagged.
+ *     A rule that depends on ATTRIBUTE ORDER is a rule an author flips by moving a prop — the same
+ *     defect `no-hand-rolled-surface` had with CLASS order. `(?:=>[^>]*)*` lets the run step over
+ *     an arrow and keep going; the tag's own `>` still ends it.
+ *  2. The scanner below feeds rules ONE LINE at a time, and prettier wraps any element wider than
+ *     printWidth onto several lines. Every rule anchored on `<Tag …>` therefore only ever saw
+ *     single-line elements. Rules carrying `spansElement: true` are matched against the whole file
+ *     instead (line number derived from the match offset), so wrapping no longer hides a violation.
+ */
+const ATTRS = String.raw`(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|=>|[^>"'])*`;
+
+/**
+ * @type {{id:string, severity:'error'|'warn', test:RegExp, message:string, standard?:string,
+ *         exempt?:RegExp, classOnly?:boolean}[]}
+ *
+ * `classOnly` marks a rule whose pattern is a CLASS NAME (`gap-3`, `bg-red-500`, `pr-4`). Those are
+ * matched against the class-expression mask (see `classExpressionsOnly`), never the raw line, so
+ * product copy, an i18n value or a JSX text node that merely spells a utility is not a finding.
  *
  * `exempt` is an optional SECOND escape a rule may declare, matched against the ORIGINAL (un-blanked)
  * line or the one above it. `ui-audit-disable-line <id>` silences any rule; an `exempt` marker is for
@@ -45,6 +76,7 @@ const EMOJI_FLAG = /\p{Regional_Indicator}/u;
 const RULES = [
   {
     id: "no-utility-spacing",
+    classOnly: true,
     scope: "consumer",
     severity: "error",
     // Any Tailwind spacing step on the consumer's own markup. Arbitrary values ([13px]) have their
@@ -70,18 +102,38 @@ const RULES = [
     severity: "warn",
     // rounded + border/bg on the consumer's own element = a fake Card / Badge / Avatar / ListRow
     // that drifts from the real ones (a 38px account pill beside 32px controls).
-    test: /className=(?:"[^"]*|'[^']*|\{`[^`]*)\brounded(?:-(?:full|sm|md|lg|xl|2xl))?\b[^"'`]*\b(?:border|bg-)/,
+    //
+    // ORDER-INDEPENDENT, and it has to be: the old single regex required `rounded` to appear
+    // BEFORE `border`/`bg-`, so the identical element passed or failed depending on how the
+    // classes happened to be sorted — and prettier's Tailwind plugin sorts them. A `bg-current …
+    // rounded-full` dot was clean, `prettier --write` reordered it to `rounded-full bg-current`,
+    // and the warning appeared with no source change. A rule a formatter can flip is a rule
+    // nobody can trust.
+    test: (line) => {
+      const m = line.match(/className=(?:"([^"]*)"|'([^']*)'|\{`([^`]*)`)/);
+      if (!m) return false;
+      const cls = m[1] ?? m[2] ?? m[3] ?? "";
+      // A MARKER is not a surface. `size-1` is 4px — a dot, a pip, a status bead. The primitives
+      // this rule points at (Card, Badge, Avatar, ListRow, Descriptions, EmptyState) all start at
+      // control height, so none of them can express one, and flagging it sends the reader looking
+      // for a component that does not exist. The cut-off is `size-2` / 8px: below that there is no
+      // room for the padding and type that make something a surface.
+      if (/\b(?:size|[wh])-(?:0\.5|1|1\.5|2)\b/.test(cls)) return false;
+      return /\brounded(?:-(?:full|sm|md|lg|xl|2xl))?\b/.test(cls) && /\b(?:border|bg-)/.test(cls);
+    },
     message:
       "Hand-rolled surface (rounded + border/bg) — use Card, Badge, Avatar, ListRow, Descriptions or EmptyState so height, padding and radius come from the tokens (docs/CONSUMER-RULES.md §4).",
   },
   {
     id: "no-space-xy",
+    classOnly: true,
     severity: "error",
     test: /\bspace-[xy]-\d/,
     message: "Use <Stack>/<Inline> with gap, not space-x/y-* (rules §5).",
   },
   {
     id: "no-raw-palette-color",
+    classOnly: true,
     severity: "error",
     test: new RegExp(
       `\\b(bg|text|border|ring|fill|stroke|from|to|via|divide|outline)-(${PALETTE})-\\d`,
@@ -92,11 +144,15 @@ const RULES = [
   {
     id: "status-tone-not-variant",
     severity: "error",
+    spansElement: true,
     // Only the tone-driven status components (Badge/Tag/StatCard) are wrong here — they expose a
     // `tone` prop and reserve `variant` for STRUCTURE (default|secondary|outline). Button, Alert,
     // DropdownMenuItem, ContextMenuItem, AlertDialog etc. legitimately use `variant` for emphasis,
     // so they must NOT be flagged.
-    test: /<(?:Badge|Tag|StatCard)\b[^>]*\bvariant=["'](?:success|warning|destructive|info|neutral)["']/,
+    test: new RegExp(
+      `<(?:Badge|Tag|StatCard)\\b${ATTRS}\\bvariant=["'](?:success|warning|destructive|info|neutral)["']`,
+      "g",
+    ),
     message:
       "Badge/Tag/StatCard status uses tone, not variant (variant is structural: default|secondary|outline). Use tone='success|warning|destructive|info|neutral'.",
   },
@@ -110,12 +166,18 @@ const RULES = [
   {
     id: "value-callback-on-value-change",
     severity: "error",
-    test: /<(?:Checkbox\.Group|Upload|Cascader|TreeSelect|Transfer|SearchSelect|DatePicker|DateRangePicker|TimePicker|ColorPicker|LocalePicker|TimezonePicker|DateFormatPicker|TimeFormatPicker)\b[^>]*\bonChange=/,
+    spansElement: true,
+    test: new RegExp(
+      "<(?:Checkbox\\.Group|Upload|Cascader|TreeSelect|Transfer|Select|SearchSelect|DatePicker|" +
+        `DateRangePicker|TimePicker|ColorPicker|LocalePicker|TimezonePicker|DateFormatPicker|TimeFormatPicker)\\b${ATTRS}\\bonChange=`,
+      "g",
+    ),
     message:
       "Abstract value components use onValueChange, not onChange. Reserve onChange for DOM events.",
   },
   {
     id: "no-arbitrary-hex",
+    classOnly: true,
     severity: "error",
     test: /(bg|text|border|ring|fill|stroke|from|to|via)-\[#[0-9a-fA-F]{3,8}\]/,
     message: "No hardcoded hex colors in className; use design-system tokens (rules §4).",
@@ -125,6 +187,7 @@ const RULES = [
   // (they start with a letter), so token-driven values stay legal (rules §4–§5).
   {
     id: "no-arbitrary-spacing",
+    classOnly: true,
     severity: "error",
     test: /\b(p|px|py|pt|pb|pl|pr|pe|ps|m|mx|my|mt|mb|ml|mr|me|ms|gap|gap-x|gap-y|inset|inset-x|inset-y|top|right|bottom|left)-\[-?\.?\d/,
     message:
@@ -132,6 +195,7 @@ const RULES = [
   },
   {
     id: "no-arbitrary-size",
+    classOnly: true,
     severity: "error",
     // `min-w-[…]` / `min-h-[…]` are allowed: a MINIMUM dimension is the legit responsive
     // pattern (horizontal-scroll tables `<Table className="min-w-[720px]">`, collapse
@@ -143,6 +207,7 @@ const RULES = [
   },
   {
     id: "no-arbitrary-typography",
+    classOnly: true,
     severity: "error",
     test: /\b(text|leading|tracking|font)-\[-?\.?\d/,
     message:
@@ -150,6 +215,7 @@ const RULES = [
   },
   {
     id: "no-arbitrary-radius",
+    classOnly: true,
     severity: "error",
     test: /\brounded(?:-[a-z]+)?-\[-?\.?\d/,
     message: "No arbitrary radius (rounded-[6px]…). Use rounded-sm/md/lg radius tokens (rules §4).",
@@ -188,6 +254,7 @@ const RULES = [
   },
   {
     id: "no-raw-select",
+    scope: "consumer-control",
     severity: "error",
     test: /<select[\s>]/,
     message: "Use <Select> from @godxjp/ui, not a raw <select> (rules §3).",
@@ -200,18 +267,22 @@ const RULES = [
   },
   {
     id: "no-raw-textarea",
+    scope: "consumer-control",
     severity: "warn",
     test: /<textarea[\s>]/,
     message: "Use <Textarea> from @godxjp/ui, not a raw <textarea> (rules §3).",
   },
   {
     id: "no-raw-input",
+    scope: "consumer-control",
     severity: "error",
-    test: /<input[\s>]/,
+    spansElement: true,
+    test: new RegExp(`<input\\b(?!${ATTRS}\\btype=["']hidden["'])${ATTRS}>`, "g"),
     message: "Use <Input> from @godxjp/ui, not a raw <input> (rules §3).",
   },
   {
     id: "no-raw-button",
+    scope: "consumer-control",
     severity: "error",
     test: /<button[\s>]/,
     message: "Use <Button> from @godxjp/ui, not a raw <button> (rules §3).",
@@ -219,12 +290,14 @@ const RULES = [
   {
     id: "card-manual-padding",
     severity: "error",
-    test: /<Card\b[^>]*\bp-[1-9]/,
+    spansElement: true,
+    test: new RegExp(`<Card\\b${ATTRS}\\bp-[1-9]`, "g"),
     message:
       "Don't hand-roll padding on <Card> (className='p-4'…) — wrap the body in <CardContent>. (p-0 for a full-bleed table is fine.)",
   },
   {
     id: "no-dark-color-override",
+    classOnly: true,
     severity: "warn",
     test: /\bdark:(bg|text|border|ring|fill|stroke)-/,
     message: "Don't add dark: color overrides — semantic tokens already adapt (rules §4).",
@@ -232,7 +305,8 @@ const RULES = [
   {
     id: "manual-field-error",
     severity: "warn",
-    test: /<p[^>]*className="[^"]*text-(xs|sm)[^"]*text-destructive/,
+    spansElement: true,
+    test: new RegExp(`<p${ATTRS}className="[^"]*text-(?:xs|sm)[^"]*text-destructive`, "g"),
     message:
       "Field errors should use <FormField error=…>, not a hand-rolled <p> (rules §1). OK only for checkbox/radio groups.",
   },
@@ -245,6 +319,7 @@ const RULES = [
   },
   {
     id: "raw-white-black",
+    classOnly: true,
     severity: "warn",
     test: /\b(bg|text|border)-(white|black)\b/,
     message:
@@ -270,10 +345,12 @@ const RULES = [
   },
   {
     id: "no-physical-direction",
+    classOnly: true,
     severity: "warn",
     // Physical-edge utilities break RTL. Logical equivalents: ms-/me-/ps-/pe-, start-/end-,
     // text-start/end, border-s/e, rounded-s/e. `-mx-`/`-px-` (both edges) are RTL-safe → not matched.
-    test: /\b-?(ml|mr|pl|pr|left|right)-(?:\d|\[|auto|px|full)|\b(?:rounded-[tb]?[lr]|border-[lr]|text-(?:left|right))\b/,
+    exempt: /rtl-ignore:\s*\S.{10,}/,
+    test: /(?<![\w-])-?(ml|mr|pl|pr|left|right)-(?:\d|\[|auto|px|full)|(?<![\w-])(?:rounded-[tb]?[lr]|border-[lr]|text-(?:left|right))\b/,
     standard: "W3C CSS Logical Properties & Values L1 · WCAG 2.2 (1.3.2 / reflow)",
     message:
       "Use LOGICAL direction utilities for RTL safety: ms-/me-/ps-/pe-, start-/end-, text-start/end, border-s/e, rounded-s/e — not physical ml-/mr-/pl-/pr-/left-/right-/text-left|right.",
@@ -281,9 +358,13 @@ const RULES = [
   {
     id: "icon-button-needs-name",
     severity: "warn",
+    spansElement: true,
     // An icon-only Button (size="icon") with no author-supplied accessible name. A combobox/icon
     // button's name is computed from author (aria-label / aria-labelledby / title), not glyph content.
-    test: /<Button\b(?=[^>]*\bsize=["']icon["'])(?![^>]*\b(?:aria-label|aria-labelledby|title)=)[^>]*>/,
+    test: new RegExp(
+      `<Button\\b(?=${ATTRS}\\bsize=["']icon["'])(?!${ATTRS}\\b(?:aria-label|aria-labelledby|title)=)${ATTRS}>`,
+      "g",
+    ),
     standard: "WCAG 2.2 SC 4.1.2 · 1.1.1 · WAI-ARIA 1.2",
     message:
       "Icon-only <Button size=\"icon\"> needs an accessible name — add aria-label={t('…')}. The icon is decorative (aria-hidden); the name comes from the author, not the glyph.",
@@ -291,7 +372,8 @@ const RULES = [
   {
     id: "img-needs-alt",
     severity: "warn",
-    test: /<img\b(?![^>]*\balt=)[^>]*>/,
+    spansElement: true,
+    test: new RegExp(`<img\\b(?!${ATTRS}\\balt=)${ATTRS}>`, "g"),
     standard: "WCAG 2.2 SC 1.1.1 · HTML Living Standard (WHATWG)",
     message:
       'Every <img> needs an alt attribute (alt="" for purely decorative images). Prefer the <Avatar>/<AspectRatio> primitives for product imagery.',
@@ -306,9 +388,14 @@ const RULES = [
   },
   {
     id: "hardcoded-currency",
+    matches: currencyMatches,
     severity: "warn",
     // A currency glyph glued to an interpolation in JSX text: `>¥{amount}` / `>{x}円`.
-    test: /(?:>[\s]*[¥$€£₫]\s*\{)|(?:\}\s*円)/,
+    spansElement: true,
+    test: new RegExp(
+      `<(?:[A-Za-z][\\w.:]*(?:\\s${ATTRS})?)?(?<!=)>[^<>{}]*[¥$€£₫]\\s*\\{|\\}\\s*円\\s*</`,
+      "g",
+    ),
     standard: "ISO 4217 · ECMA-402 Intl.NumberFormat",
     message:
       "Don't hand-format currency (¥{amount}). Use Intl.NumberFormat(locale, { style: 'currency', currency }) — ISO 4217 code drives the symbol and minor units per locale.",
@@ -339,7 +426,12 @@ const RULES = [
     id: "no-em-dash-in-copy",
     severity: "warn",
     // Em-dash (U+2014) in JSX text — the reference design uses the middot `·` for JP/EN pairs and calm copy.
-    test: /[A-Za-z0-9぀-ヿ一-鿿]\s*—\s*[A-Za-z0-9぀-ヿ一-鿿]/,
+    spansElement: true,
+    test: new RegExp(
+      `<(?:[A-Za-z][\\w.:]*(?:\\s${ATTRS})?)?>[^<>]*[A-Za-z0-9぀-ヿ一-鿿]\\s*—\\s*[A-Za-z0-9぀-ヿ一-鿿]|` +
+        String.raw`\b(?:label|title|placeholder|description|aria-label)=["'][^"']*[A-Za-z0-9぀-ヿ一-鿿]\s*—\s*[A-Za-z0-9぀-ヿ一-鿿][^"']*["']`,
+      "g",
+    ),
     standard: "@godxjp/ui reference-design typography (best-ux) · Unicode punctuation",
     message:
       "No em-dash (—) in product copy. Use a middot `·` for JP/EN label pairs, or restructure into two calm sentences. Keep copy factual and quiet.",
@@ -423,6 +515,128 @@ function stripComments(src) {
   return out;
 }
 
+/** End index (inclusive) of the string / template literal opening at `i`. `${…}` is stepped over as
+ *  a brace group, so a quote nested inside an interpolation never closes the template early. */
+function endOfString(src, i) {
+  const quote = src[i];
+  for (let j = i + 1; j < src.length; j++) {
+    const c = src[j];
+    if (c === "\\") j++;
+    else if (quote === "`" && c === "$" && src[j + 1] === "{") {
+      const close = matchBracket(src, j + 1);
+      if (close < 0) return src.length - 1;
+      j = close;
+    } else if (c === quote) return j;
+  }
+  return src.length - 1;
+}
+
+/** End index (inclusive) of the bracket group opening at `i`, or -1 when it never closes. */
+function matchBracket(src, i) {
+  const CLOSER = { "{": "}", "[": "]", "(": ")" };
+  const stack = [CLOSER[src[i]]];
+  for (let j = i + 1; j < src.length; j++) {
+    const c = src[j];
+    if (c === '"' || c === "'" || c === "`") j = endOfString(src, j);
+    else if (CLOSER[c]) stack.push(CLOSER[c]);
+    else if (c === stack[stack.length - 1]) {
+      stack.pop();
+      if (stack.length === 0) return j;
+    }
+  }
+  return -1;
+}
+
+/** The value that starts at `i`: a literal or bracket group in full, otherwise the rest of the line
+ *  (`= base + " p-2"`, a ternary) — enough to see the classes, never the next statement. */
+function valueEnd(src, i) {
+  const c = src[i];
+  if (c === '"' || c === "'" || c === "`") return endOfString(src, i);
+  if (c === "{" || c === "[" || c === "(") {
+    const close = matchBracket(src, i);
+    return close < 0 ? src.length - 1 : close;
+  }
+  const nl = src.indexOf("\n", i);
+  return nl < 0 ? src.length - 1 : nl - 1;
+}
+
+/** A call that BUILDS a class list — its arguments are classes wherever they are written. */
+const CLASS_HELPER = /(?<![\w$.])(?:cn|clsx|classnames|classNames|cx|cva|tv|twMerge|twJoin)\s*\(/g;
+/** `className={…}` / `wrapperClass = "…"` / `const flexGapClass: Record<…> = {…}` — an assignment
+ *  (JSX attribute, variable, default) whose NAME says class. The optional `: …` is a type annotation. */
+const CLASS_ASSIGN = /(?<![\w$.])([A-Za-z_$][\w$]*)\s*(?::[^=;\n]*?)?=(?!=)\s*/g;
+/** `className: "…"` — the same, written as an object key (a DataTable column, a slots map). */
+const CLASS_KEY = /(?<![\w$.])([A-Za-z_$][\w$]*)\s*:\s*/g;
+/**
+ * The names a class list is actually bound to, as a SUFFIX so every prefix works: `className`,
+ * `rowClassName`, `baseClass`, `cellClasses` — plus the three conventional aliases for a class MAP,
+ * `statusStyles` / `badgeVariants` / `toneVariant`, which are how a palette of class strings is
+ * written when it is not inside `cva()`. A class list bound to a name outside this set (`const map =
+ * { … }`) is NOT scanned — that is the cost of the mask, and the reason the set errs wide.
+ */
+const CLASS_NAMED = /(?:class(?:es|name|names)?|styles?|variants?)$/i;
+
+/**
+ * Blank everything that is NOT a class expression, keeping newlines so line numbers stay true.
+ *
+ * The `classOnly` rules are plain regexes over source text, so before this pass any line that merely
+ * CONTAINED a utility-shaped word was reported: product copy, an i18n value, a test fixture, a JSX
+ * text node (`<Text>văn bản JSX nhắc gap-3</Text>`). The bar is zero errors, so a false positive is
+ * not a nuisance — it blocks the review. What survives the mask is the three places a class can
+ * actually be written: a class-named binding's value, a class-named object key's value, and the
+ * arguments of a class-building helper. The NAME stays inside the region, so rules that anchor on
+ * `className="` keep matching.
+ */
+function classExpressionsOnly(src) {
+  const keep = new Uint8Array(src.length);
+  const mark = (from, to) => {
+    for (let i = Math.max(from, 0); i <= Math.min(to, src.length - 1); i++) keep[i] = 1;
+  };
+  for (const m of src.matchAll(CLASS_HELPER)) {
+    const close = matchBracket(src, m.index + m[0].length - 1);
+    mark(m.index, close < 0 ? src.length - 1 : close);
+  }
+  for (const pattern of [CLASS_ASSIGN, CLASS_KEY]) {
+    for (const m of src.matchAll(pattern)) {
+      if (!CLASS_NAMED.test(m[1])) continue;
+      mark(m.index, valueEnd(src, m.index + m[0].length));
+    }
+  }
+  const out = Array.from(src, (c, i) => (keep[i] || c === "\n" ? c : " "));
+  return out.join("");
+}
+
+/** `ui-audit-disable-begin <rule> — <why>` … `ui-audit-disable-end <rule>`: ONE marker for a whole
+ *  region instead of one per line (prettier wrapping a 24-item literal used to cost 24 identical
+ *  comments, so the formatter was being bent to satisfy the linter). The reason is MANDATORY — a
+ *  marker without `— <12+ chars>` is ignored and the finding stands, so an opt-out always says why.
+ *  A block that is never closed runs to the end of the file. */
+const DISABLE_BEGIN = /ui-audit-disable-begin\s+([a-z][a-z0-9-]*)\s*[—:]\s*(\S[^\n]{11,})/;
+const DISABLE_END = /ui-audit-disable-end\s+([a-z][a-z0-9-]*)/;
+
+/** @returns {(ruleId: string, lineIndex: number) => boolean} */
+function blockSuppressions(lines) {
+  /** @type {Map<string, {from:number, to:number}[]>} */
+  const ranges = new Map();
+  /** @type {Map<string, number>} */
+  const open = new Map();
+  const close = (ruleId, to) => {
+    const from = open.get(ruleId);
+    open.delete(ruleId);
+    if (!ranges.has(ruleId)) ranges.set(ruleId, []);
+    ranges.get(ruleId).push({ from, to });
+  };
+  lines.forEach((line, i) => {
+    const begin = DISABLE_BEGIN.exec(line);
+    if (begin && !open.has(begin[1])) open.set(begin[1], i);
+    const end = DISABLE_END.exec(line);
+    if (end && open.has(end[1])) close(end[1], i);
+  });
+  for (const ruleId of [...open.keys()]) close(ruleId, lines.length - 1);
+  return (ruleId, lineIndex) =>
+    (ranges.get(ruleId) ?? []).some((r) => lineIndex >= r.from && lineIndex <= r.to);
+}
+
 /** A finding is suppressed by `ui-audit-disable-line <rule>` on the same line, or
  *  `ui-audit-disable-next-line <rule>` on the line above (explicit rule id required). */
 function isSuppressed(ruleId, sameLine, prevLine) {
@@ -473,19 +687,52 @@ function walk(dir, acc = []) {
   return acc;
 }
 
+/** Match real JSX text after a balanced opening tag, including props with comparisons. */
+function* currencyMatches(source) {
+  for (const opening of source.matchAll(/<(?:[A-Za-z][\w.:]*\b|(?=>))/g)) {
+    const end = jsxOpeningEnd(source, opening.index);
+    const text = source.slice(end + 1).match(/^[^<>{}]*[¥$€£₫]\s*\{/);
+    if (text) yield { 0: source.slice(opening.index, end + 1) + text[0], index: opening.index };
+  }
+  yield* source.matchAll(/\}\s*円\s*</g);
+}
+
+/** Find the tag boundary without confusing a comparison, callback or string for markup. */
+function jsxOpeningEnd(source, start) {
+  let braces = 0;
+  let quote = "";
+  for (let i = start + 1; i < source.length; i++) {
+    const char = source[i];
+    if (quote) {
+      if (char === "\\") i++;
+      else if (char === quote) quote = "";
+    } else if (char === '"' || char === "'" || char === "`") quote = char;
+    else if (char === "{") braces++;
+    else if (char === "}") braces--;
+    else if (char === ">" && braces === 0) return i;
+  }
+  return source.length;
+}
+
 // Structural: a <Card> (without p-0) whose first child is body content rather than a Card
 // sub-component sits FLUSH (no padding). Per-line regexes can't see across lines, so this is a
 // whole-file pass. The body must be wrapped in <CardContent> (titles in <CardHeader>).
-const CARD_FLUSH =
-  /<Card(?![^>]*\bp-0\b)(?:\s[^>]*)?>\s*<(?!CardContent|CardHeader|CardCover|CardFooter|CardBar|\/Card)/g;
+const CARD_FLUSH = new RegExp(
+  `<Card(?!${ATTRS}\\bp-0\\b)(?:\\s${ATTRS})?>\\s*<(?!CardContent|CardHeader|CardCover|CardFooter|CardBar|\\/Card)`,
+  "g",
+);
 
 // Structural: a bare <label>/<Label> paired with a TEXT control (its sibling) instead of a
 // <FormField>. FormField OWNS the label↔control association (htmlFor/id), aria-describedby/
 // error wiring, AND the field rhythm (label gap + field spacing) — a hand-rolled Label+Input
 // loses all of it (the cramped login-form failure mode). Checkbox/Radio/Switch use Field/Label
 // legitimately, so they are NOT matched. Whole-file pass (the pair spans lines).
-const BARE_FIELD =
-  /<(?:label|Label)\b[^>]*>[\s\S]{0,240}?<\/(?:label|Label)>\s*<(?:Input|Select|Textarea|NumberInput|SearchInput|SearchSelect|DatePicker|DateRangePicker|TimePicker|MonthPicker|MonthRangePicker|Cascader|TreeSelect|input)\b/g;
+const BARE_FIELD = new RegExp(
+  `<(?:label|Label)\\b${ATTRS}>[\\s\\S]{0,240}?</(?:label|Label)>\\s*` +
+    "<(?:Input|Select|Textarea|NumberInput|SearchInput|SearchSelect|DatePicker|DateRangePicker|" +
+    "TimePicker|MonthPicker|MonthRangePicker|Cascader|TreeSelect|input)\\b",
+  "g",
+);
 
 // Two <Card> siblings written back to back at the same indentation with nothing between them.
 // Direct children of PageContainer are spaced by the page; anywhere else they touch.
@@ -496,29 +743,50 @@ const SIBLING_CARDS = /^([ \t]*)<\/Card>\s*\n\1<Card\b/gm;
  * utilities are the design system itself (that is where `flex`/`gap-*` are supposed to live), so
  * those rules are skipped when the CWD package is @godxjp/ui — unless `--consumer` forces them.
  */
-const SELF = (() => {
-  try {
-    return JSON.parse(readFileSync(join(CWD, "package.json"), "utf8")).name === "@godxjp/ui";
-  } catch {
-    return false;
-  }
-})();
+
 const ACTIVE_RULES =
   SELF && !args.includes("--consumer") ? RULES.filter((r) => r.scope !== "consumer") : RULES;
 
 const findings = [];
+let filesScanned = 0;
 for (const dir of SCAN_DIRS) {
   for (const file of walk(isAbsolute(dir) ? dir : join(CWD, dir))) {
     const rel = relative(CWD, file);
+    // Framework test support is executable fixture markup, not a shipped product screen.
+    if (SELF && !args.includes("--consumer") && rel.startsWith("src/test/")) continue;
+    filesScanned += 1;
+    // A primitive implements native controls; asking Input to render Input recurses.
+    // Consumer applications and executable docs still receive these composition checks.
+    const fileRules =
+      SELF && !args.includes("--consumer") && rel.startsWith("src/components/")
+        ? ACTIVE_RULES.filter((rule) => rule.scope !== "consumer-control")
+        : ACTIVE_RULES;
     const content = readFileSync(file, "utf8");
     const origLines = content.split("\n");
     const scanContent = stripComments(content); // comments blanked; strings + line numbers kept
     const scanLines = scanContent.split("\n");
+    // `classOnly` rules read this instead — everything but a real class expression blanked.
+    const classLines = classExpressionsOnly(scanContent).split("\n");
+    const inDisabledBlock = blockSuppressions(origLines);
+    /** Both opt-outs, by line index: the per-line markers and the reason-carrying block. */
+    const suppressed = (ruleId, i) =>
+      isSuppressed(ruleId, origLines[i], origLines[i - 1]) || inDisabledBlock(ruleId, i);
+    const isJsx = file.endsWith(".tsx");
+    // This compiler output intentionally resolves CSS variables to email-safe literals.
+    // gen-email-tokens.mjs --check verifies it against its canonical token sources.
+    const compiledEmailTokens =
+      SELF &&
+      rel === "src/email/tokens.generated.ts" &&
+      content.startsWith("// AUTO-GENERATED by scripts/gen-email-tokens.mjs");
     scanLines.forEach((line, i) => {
-      for (const rule of ACTIVE_RULES) {
+      for (const rule of fileRules) {
+        if (!isJsx && rule.scope === "consumer-control") continue;
+        if (compiledEmailTokens && rule.id === "no-off-scale-token-value") continue;
+        if (rule.spansElement) continue; // matched over the whole file below, not line by line
+        const target = rule.classOnly ? (classLines[i] ?? "") : line;
         if (
-          rule.test.test(line) &&
-          !isSuppressed(rule.id, origLines[i], origLines[i - 1]) &&
+          (typeof rule.test === "function" ? rule.test(target) : rule.test.test(target)) &&
+          !suppressed(rule.id, i) &&
           !isExempt(rule, origLines[i], origLines[i - 1])
         ) {
           findings.push({
@@ -533,10 +801,39 @@ for (const dir of SCAN_DIRS) {
         }
       }
     });
+    // Element-spanning rules: matched against the WHOLE file, because a JSX element prettier wrapped
+    // over five lines is invisible to a line-by-line scan. Same offset→line-number idiom as the
+    // block rules below.
+    for (const rule of fileRules) {
+      if (!rule.spansElement || !isJsx) continue;
+      for (const match of rule.matches
+        ? rule.matches(scanContent)
+        : scanContent.matchAll(rule.test)) {
+        // A comparison `>` inside a JSX prop is not the end of its opening tag.
+        if (
+          (rule.id === "hardcoded-currency" || rule.id === "no-em-dash-in-copy") &&
+          match[0].startsWith("<") &&
+          jsxOpeningEnd(scanContent, match.index) >= match.index + match[0].length
+        )
+          continue;
+        const lineNo = scanContent.slice(0, match.index).split("\n").length;
+        if (suppressed(rule.id, lineNo - 1)) continue;
+        if (isExempt(rule, origLines[lineNo - 1], origLines[lineNo - 2])) continue;
+        findings.push({
+          file: rel,
+          line: lineNo,
+          rule: rule.id,
+          severity: rule.severity,
+          standard: rule.standard,
+          message: rule.message,
+          snippet: match[0].replace(/\s+/g, " ").slice(0, 120),
+        });
+      }
+    }
+    if (!isJsx) continue;
     for (const match of scanContent.matchAll(CARD_FLUSH)) {
       const lineNo = scanContent.slice(0, match.index).split("\n").length;
-      if (isSuppressed("card-needs-content", origLines[lineNo - 1], origLines[lineNo - 2]))
-        continue;
+      if (suppressed("card-needs-content", lineNo - 1)) continue;
       findings.push({
         file: rel,
         line: lineNo,
@@ -553,8 +850,7 @@ for (const dir of SCAN_DIRS) {
     ) {
       for (const match of scanContent.matchAll(SIBLING_CARDS)) {
         const lineNo = scanContent.slice(0, match.index).split("\n").length + 1;
-        if (isSuppressed("sibling-cards-need-flex", origLines[lineNo - 1], origLines[lineNo - 2]))
-          continue;
+        if (suppressed("sibling-cards-need-flex", lineNo - 1)) continue;
         findings.push({
           file: rel,
           line: lineNo,
@@ -568,10 +864,7 @@ for (const dir of SCAN_DIRS) {
     }
     for (const match of scanContent.matchAll(BARE_FIELD)) {
       const lineNo = scanContent.slice(0, match.index).split("\n").length;
-      if (
-        isSuppressed("bare-control-needs-formfield", origLines[lineNo - 1], origLines[lineNo - 2])
-      )
-        continue;
+      if (suppressed("bare-control-needs-formfield", lineNo - 1)) continue;
       findings.push({
         file: rel,
         line: lineNo,
@@ -589,7 +882,28 @@ for (const dir of SCAN_DIRS) {
 const errors = findings.filter((f) => f.severity === "error");
 const warnings = findings.filter((f) => f.severity === "warn");
 
-if (asJson) {
+// A run that opened NO file is not a clean run. The default SCAN_DIRS are a consumer's
+// `resources/js/{components,pages,layouts}`; `walk()` swallows ENOENT and returns [], so in any
+// tree without that layout — this repo included — `pnpm audit` printed
+// "✓ No UI-standardization violations found." and exited 0 having read nothing at all.
+if (filesScanned === 0) {
+  const message =
+    `ui-audit scanned 0 files — none of [${SCAN_DIRS.join(", ")}] exists (or all were filtered). ` +
+    `Pass the directories to scan, e.g. \`node scripts/ui-audit.mjs src docs\`. ` +
+    `Reporting a clean audit without opening a file is not a result.`;
+  if (asJson) {
+    process.stdout.write(
+      JSON.stringify({ summary: null, error: message, findings: [] }, null, 2) + "\n",
+    );
+  } else {
+    console.error(`✗ ${message}`);
+  }
+  process.exitCode = 2;
+}
+
+if (filesScanned === 0) {
+  // already reported above
+} else if (asJson) {
   process.stdout.write(
     JSON.stringify(
       { summary: { errors: errors.length, warnings: warnings.length }, findings },
@@ -622,4 +936,4 @@ if (asJson) {
 }
 
 // See the note above --rules: exitCode, so a large JSON report drains fully.
-process.exitCode = errors.length > 0 ? 1 : 0;
+if (filesScanned > 0) process.exitCode = errors.length > 0 ? 1 : 0;