basalt-ui 1.20.0 → 1.21.0

package/dist/cli/index.js

@@ -14,12 +14,31 @@ import {
   checkSource,
   DEFAULT_GUARD_CONFIG,
   GENERATED_HEADER_LINE,
+  guardKindRemedy,
   GUARD_RULES,
-  TOKENS_ONLY_DISABLED_KINDS
+  guardWaiverHint,
+  TOKENS_ONLY_DISABLED_KINDS,
+  unmatchedExemptPatterns
 } from "../guard/index.js";
 import { evaluateGuardHook } from "../guard/guard-hook.js";
 import { RULE_NAMES, SKILL_NAMES, SURFACES, TOKEN_LAYER_BOUNDARY_SURFACES } from "../surfaces.js";
 import { buildPaletteCss, deriveSpacing } from "../tokens/index.js";
+function exemptRulePaths(entry) {
+  if (entry === void 0) return [];
+  return Array.isArray(entry) ? entry : entry.paths;
+}
+function exemptRuleReason(entry) {
+  if (entry === void 0 || Array.isArray(entry)) return null;
+  return entry.reason.trim().length > 0 ? entry.reason.trim() : null;
+}
+function resolveExemptRules(cfg) {
+  if (cfg.exemptRules === void 0) return DEFAULT_GUARD_CONFIG.exemptRules;
+  const out = {};
+  for (const [kind, entry] of Object.entries(cfg.exemptRules)) {
+    out[kind] = exemptRulePaths(entry);
+  }
+  return out;
+}
 const DEFAULT_ROOT = "src";
 const DEFAULT_ROOTS = [DEFAULT_ROOT];
 function resolveRoots(cfg) {
@@ -89,25 +108,6 @@ function walkSourceFiles(dir, out = []) {
   }
   return out;
 }
-const GUARD_KIND_EXPLANATIONS = {
-  "raw-hex": "raw-hex: route color through VX.* / the Mantine theme instead of a hardcoded hex literal.",
-  "raw-color-fn": "raw-color-fn: route color through VX.* / the Mantine theme instead of a hardcoded rgb()/hsl() literal.",
-  "off-identity-accent": "off-identity-accent: use blue/gray or a status hue (red/green/orange/yellow) instead.",
-  "raw-spacing": "raw-spacing: use the spacing scale token instead of a raw literal.",
-  "raw-radius": "raw-radius: use the radius scale token instead of a raw literal.",
-  "raw-surface": "raw-surface: use `VX.surface.*` / a `radius` token / `var(--vx-radius-card)` instead of an inline border/radius/shadow.",
-  "card-with-border": "card-with-border: `withBorder` on a Card/Paper double-draws the edge \u2014 card depth is `--vx-shadow-card`, which already bakes a 1px ring into the shadow. Drop the prop.",
-  "off-system-surface-var": "off-system-surface-var: raw Mantine ramp step bypasses the basalt surface tokens \u2014 use VX.surface.* / --vx-surface-* (border/panel/subtle/bg) instead.",
-  "raw-html-layout": "raw-html-layout: raw HTML element with inline layout/surface styling \u2014 use a Mantine layout primitive (Box/Flex/Grid/Stack/Group).",
-  "inline-spacing": "inline-spacing: inline spacing literal \u2014 use the Mantine spacing prop/token (p/m/gap with xs..xl).",
-  "inline-display": "inline-display: use <Flex>/<Grid>/<Group> instead of an inline display:flex/grid.",
-  "raw-visx-axis": "raw-visx-axis: raw <AxisLeft>/<AxisBottom>/<AxisRight> in a chart file \u2014 use AxisLeftNumeric / AxisBottomDate / AxisRightNumeric from the charts primitives.",
-  "raw-motion-value": "raw-motion-value: hardcoded duration/spring/ease in `transition={{...}}` \u2014 use MOTION_DURATION / MOTION_SPRING / MOTION_EASE_STANDARD instead.",
-  "unframed-chart": "unframed-chart: hand-rolled ChartLegend built from an inline array literal \u2014 pass a derived legend (deriveLegend(series)), or compose ChartFrame, which derives it for you.",
-  "raw-form-control": "raw-form-control: raw <input>/<select>/<textarea> bypasses the entire theme \u2014 use TextInput / NumberInput / Select / Textarea from @mantine/core.",
-  "sub-16-input-font": "sub-16-input-font: fontSize below 16 on a form control is dead code against the `!important` iOS floor in styles.css \u2014 drop the override or be honest about 16px.",
-  "raw-font-family": "raw-font-family: route the font stack through createBasaltTheme(overrides, { fonts }) / the --basalt-font-sans|head|mono vars instead of a hardcoded fontFamily literal."
-};
 function relativePosix(fromDir, toPath) {
   const rel = relative(fromDir, toPath).replace(/\\/g, "/");
   if (rel === "") return ".";
@@ -265,7 +265,7 @@ function checkTheme(invocationCwd = process.cwd(), flags = []) {
     rawFormControl: cfg.rawFormControl ?? DEFAULT_GUARD_CONFIG.rawFormControl,
     sub16InputFont: cfg.sub16InputFont ?? DEFAULT_GUARD_CONFIG.sub16InputFont,
     allowComment: "theme-allow",
-    exemptRules: cfg.exemptRules ?? DEFAULT_GUARD_CONFIG.exemptRules,
+    exemptRules: resolveExemptRules(cfg),
     severity: cfg.severity ?? DEFAULT_GUARD_CONFIG.severity,
     ...profile === "tokens-only" ? { profile: "tokens-only" } : {}
   };
@@ -286,6 +286,12 @@ function checkTheme(invocationCwd = process.cwd(), flags = []) {
     }
     return 1;
   }
+  if (flags.includes("--audit-allows")) return auditAllows(cwd, cfg, guardCfg, scanned);
+  for (const unmatched of unmatchedExemptPatterns(guardCfg, scanned)) {
+    console.error(
+      `\u26A0 basalt-ui check-theme: "basalt.exemptRules" entry ${unmatched.kind}: "${unmatched.pattern}" ` + (unmatched.reason === "unknown-kind" ? "names no guard kind \u2014 it exempts nothing at all (a typo, or a kind that was renamed)." : "matched none of the scanned files \u2014 it suppresses nothing, and reads as coverage in a config review while enforcing as much as an empty object.")
+    );
+  }
   if (findings.length === 0) {
     console.log("\u2713 Theme guard: no off-palette colors.");
     return 0;
@@ -322,14 +328,9 @@ function checkTheme(invocationCwd = process.cwd(), flags = []) {
     report(errors, `\u2716 Theme guard: ${errors.length} off-palette / off-identity violation(s)
 `);
   }
-  const presentKinds = new Set(findings.map((f) => f.kind));
-  const explanations = Object.keys(GUARD_KIND_EXPLANATIONS).filter((kind) => presentKinds.has(kind)).map((kind) => GUARD_KIND_EXPLANATIONS[kind]);
-  const fixLine = [
-    "Fix:",
-    ...explanations,
-    "Add a `theme-allow` comment for a deliberate exception."
-  ];
-  console.error(fixLine.join(" "));
+  const presentKinds = [...new Set(findings.map((f) => f.kind))].toSorted();
+  const waiverHints = [...new Set(findings.map((f) => guardWaiverHint(f.relPath)))].toSorted();
+  console.error(["Fix:", ...presentKinds.map(guardKindRemedy), ...waiverHints].join(" "));
   if (findings.some((f) => SERIES_MODULE_HINT_RE.test(f.relPath))) {
     console.error(
       'Hint: if a flagged file IS your palette/series source, exempt it via "basalt": { "exempt": ["<path>"] } in package.json.'
@@ -337,6 +338,130 @@ function checkTheme(invocationCwd = process.cwd(), flags = []) {
   }
   return errors.length > 0 ? 1 : 0;
 }
+const AUDIT_NEUTRALIZED_TOKEN = "basalt-audit-neutralized";
+function findingKey(f) {
+  return `${f.relPath}:${f.line}:${f.kind}`;
+}
+const AUDIT_ANNOTATION_PREFIX = /(?:^|\/\/|\/\*|<!--|^\s*\*)\s*$/;
+function annotationRuleIds(rest) {
+  const head = (rest.replace(/^-file\b/, "").split(/—|–|:|\s-\s/)[0] ?? "").trim();
+  return head.split(",").map((word) => word.trim().replace(/^basalt\//, "")).filter((word) => /^[a-z][a-z0-9-]*$/.test(word));
+}
+function isAllowAnnotationLine(line, token) {
+  const at = line.indexOf(token);
+  if (at === -1) return false;
+  if (line.includes(`"basalt:${token}`)) return true;
+  return AUDIT_ANNOTATION_PREFIX.test(line.slice(0, at));
+}
+function auditAllows(cwd, cfg, guardCfg, scanned) {
+  const token = guardCfg.allowComment;
+  const lines = [`
+basalt-ui check-theme --audit-allows \u2014 ${cwd}
+`];
+  let dead = 0;
+  let live = 0;
+  let outOfReach = 0;
+  let unaccountable = 0;
+  const waiverLines = [];
+  const sources = /* @__PURE__ */ new Map();
+  for (const rel of scanned) sources.set(rel, readFileSync(resolve(cwd, rel), "utf8"));
+  for (const rel of scanned) {
+    const text = sources.get(rel) ?? "";
+    if (!text.includes(token)) continue;
+    const baseline = checkSource(text, rel, guardCfg);
+    const baselineKeys = new Set(
+      baseline.filter((f) => f.kind !== "theme-allow-unscoped").map(findingKey)
+    );
+    const unscopedAt = new Map(
+      baseline.filter((f) => f.kind === "theme-allow-unscoped").map((f) => [f.line, f.token])
+    );
+    const fileLines = text.split("\n");
+    for (const [index, line] of fileLines.entries()) {
+      if (!isAllowAnnotationLine(line ?? "", token)) continue;
+      const probe = [...fileLines];
+      probe[index] = (line ?? "").replaceAll(token, AUDIT_NEUTRALIZED_TOKEN);
+      const revealed = checkSource(probe.join("\n"), rel, guardCfg).filter((f) => f.kind !== "theme-allow-unscoped" && !baselineKeys.has(findingKey(f))).map((f) => `${f.kind}@${f.line}`);
+      const note = unscopedAt.get(index + 1);
+      if (note !== void 0) unaccountable++;
+      const site = `  ${rel}:${index + 1}`.padEnd(52);
+      const suffix = note === void 0 ? "" : ` [${note}]`;
+      const ids = annotationRuleIds((line ?? "").slice((line ?? "").indexOf(token) + token.length));
+      if (revealed.length > 0) {
+        live++;
+        waiverLines.push(`${site} suppresses ${[...new Set(revealed)].join(", ")}${suffix}`);
+      } else if (ids.length > 0 && !ids.some((id) => Object.hasOwn(GUARD_RULES, id))) {
+        outOfReach++;
+        waiverLines.push(
+          `${site} scoped to ${ids.join(", ")} \u2014 not a check-theme kind, so this audit cannot judge it (an oxlint plugin rule, or a typo theme-allow-unscoped would report)${suffix}`
+        );
+      } else {
+        dead++;
+        waiverLines.push(`${site} SUPPRESSES NOTHING \u2014 dead, delete it${suffix}`);
+      }
+    }
+  }
+  lines.push(`${token} annotations (${waiverLines.length}):`);
+  lines.push(...waiverLines.length === 0 ? ["  (none)"] : waiverLines);
+  const exemptLines = [];
+  let exemptCount = 0;
+  const declared = Object.entries(cfg.exemptRules ?? {});
+  if (declared.length > 0) {
+    const baselineKeys = /* @__PURE__ */ new Set();
+    for (const rel of scanned) {
+      for (const f of checkSource(sources.get(rel) ?? "", rel, guardCfg))
+        baselineKeys.add(findingKey(f));
+    }
+    for (const [kind, entry] of declared) {
+      const reason = exemptRuleReason(entry);
+      for (const pattern of exemptRulePaths(entry)) {
+        exemptCount++;
+        const probeCfg = {
+          ...guardCfg,
+          exemptRules: {
+            ...guardCfg.exemptRules,
+            [kind]: exemptRulePaths(entry).filter((p) => p !== pattern)
+          }
+        };
+        const revealed = /* @__PURE__ */ new Set();
+        for (const rel of scanned) {
+          for (const f of checkSource(sources.get(rel) ?? "", rel, probeCfg)) {
+            if (!baselineKeys.has(findingKey(f))) revealed.add(f.relPath);
+          }
+        }
+        const site = `  ${kind}: "${pattern}"`.padEnd(52);
+        const why = reason === null ? " [no reason recorded]" : ` \u2014 ${reason}`;
+        if (revealed.size === 0) {
+          dead++;
+          const unmatched = unmatchedExemptPatterns(guardCfg, scanned).find(
+            (u) => u.kind === kind && u.pattern === pattern
+          );
+          exemptLines.push(
+            `${site} SUPPRESSES NOTHING \u2014 ` + (unmatched === void 0 ? "the files it matches have no such finding; delete it" : unmatched.reason === "unknown-kind" ? "it names no guard kind (a typo, or a renamed kind)" : "it matches no scanned file at all") + why
+          );
+        } else {
+          live++;
+          exemptLines.push(
+            `${site} suppresses findings in ${[...revealed].toSorted().join(", ")}${why}`
+          );
+        }
+      }
+    }
+  }
+  lines.push(`
+basalt.exemptRules entries (${exemptCount}):`);
+  lines.push(...exemptLines.length === 0 ? ["  (none)"] : exemptLines);
+  lines.push(
+    `
+${live} live, ${dead} dead, ${outOfReach} outside check-theme's reach, ${unaccountable} unaccountable (reported as theme-allow-unscoped by a normal run).`
+  );
+  if (dead > 0) {
+    lines.push(
+      "A dead waiver is not harmless: it is an exception nobody re-checked, and it will silently cover the next real finding on that line."
+    );
+  }
+  console.log(lines.join("\n"));
+  return dead > 0 ? 1 : 0;
+}
 const BLOCK_BEGIN_PREFIX = "<!-- basalt:begin";
 const BLOCK_END = "<!-- basalt:end -->";
 const MANIFEST_PATH = ".basalt/manifest.json";
@@ -531,9 +656,24 @@ function managedFiles(peers, placement = ROOT_PLACEMENT) {
 # The path is RESOLVED from where basalt-ui actually installed, not assumed at the
 # repo root \u2014 under an isolated linker it lives beside the package that depends on it.
 # Run \`lefthook install\` once: the file is inert until the git hooks are written.
+#
+# NOTE: an extends target WINS on a colliding key \u2014 a \`run:\`/\`glob:\` you write under one of
+# the preset's command names is discarded silently. \`env:\`, \`exclude:\`, \`skip:\` and your own
+# command names merge. See the preset itself for the sanctioned override seams.
 extends:
   - ${ctx.vars.LEFTHOOK_PRESET_PATH.replace(/^\.\//, "")}
-`
+` + // The one seam that has to be RENDERED rather than documented: the preset is read in place
+    // out of node_modules, so it cannot template the resolved bin the way check.yml does. Its
+    // default (`bunx --no-install basalt-ui`) fails loudly rather than fetching a stranger's
+    // copy; this pins it to the local one whenever basalt actually resolved.
+    (ctx.vars.BASALT_BIN.startsWith("bunx ") ? "" : `
+# The theme guard runs the LOCAL bin, not a copy \`bunx\` fetches from npm.
+pre-commit:
+  commands:
+    check-theme:
+      env:
+        BASALT_BIN: ${ctx.vars.BASALT_BIN}
+`)
   };
   const ci = {
     dest: ".github/workflows/check.yml",
@@ -690,6 +830,60 @@ function detectRoots(cwd) {
   }
   return existsSync(resolve(cwd, DEFAULT_ROOT)) ? [DEFAULT_ROOT] : [];
 }
+function rootCovers(root, detected) {
+  const r = root.replace(/\/+$/, "");
+  return detected === r || detected.startsWith(`${r}/`);
+}
+function reconcileRoots(cwd, opts) {
+  const declared = readBasaltConfig(cwd).roots;
+  const detected = detectRoots(cwd);
+  if (declared !== void 0) {
+    const unscanned = detected.filter((d) => !declared.some((r) => rootCovers(r, d)));
+    return { kind: "declared", declared, unscanned };
+  }
+  if (detected.length === 0) return { kind: "undetectable" };
+  if (!opts.write) return { kind: "declared", declared: [], unscanned: detected };
+  const wrote = patchPackageJson(cwd, (pkg) => {
+    const basalt = pkg["basalt"] ?? {};
+    if (basalt["roots"] !== void 0) return false;
+    pkg["basalt"] = { ...basalt, roots: detected };
+    return true;
+  });
+  return wrote ? { kind: "wrote", roots: detected } : { kind: "undetectable" };
+}
+function rootsNotices(state) {
+  if (state.kind === "wrote") {
+    return {
+      log: [
+        `wrote "basalt": { "roots": ${JSON.stringify(state.roots)} } to package.json \u2014 check-theme, the CI oxfmt globs and the default scan exemption all derive from it. Correct it if your sources live elsewhere.`
+      ],
+      error: []
+    };
+  }
+  if (state.kind === "undetectable") {
+    return {
+      log: [],
+      error: [
+        'could not infer "basalt.roots" \u2014 no src/ here and no workspace package with one. Set "basalt": { "roots": [...] } in package.json by hand, or check-theme will fail with "0 files scanned".'
+      ]
+    };
+  }
+  if (state.unscanned.length === 0) return { log: [], error: [] };
+  if (state.declared.length === 0) {
+    return {
+      log: [],
+      error: [
+        `"basalt.roots" is not set \u2014 the guard is running on the built-in default ("${DEFAULT_ROOT}"). This layout suggests ${JSON.stringify(state.unscanned)}; declare it in package.json.`
+      ]
+    };
+  }
+  return {
+    log: [
+      `keeping your "basalt.roots" (${JSON.stringify(state.declared)}) \u2014 never overwritten. The layout also has ${JSON.stringify(state.unscanned)}, which nothing scans; add it if it should be guarded, or leave it if the exclusion is deliberate.`
+    ],
+    error: []
+  };
+}
 function stripJsonc(text) {
   let out = "";
   let inString = false;
@@ -733,10 +927,47 @@ function parseJsonc(text) {
     return null;
   }
 }
-function extendsBasaltPreset(entries) {
-  return Array.isArray(entries) && entries.some(
+function basaltPresetEntry(entries) {
+  if (!Array.isArray(entries)) return null;
+  const match = entries.find(
     (entry) => typeof entry === "string" && entry.endsWith("basalt-ui/configs/oxlint.json")
   );
+  return match ?? null;
+}
+const LEFTHOOK_CONFIG_NAMES = ["lefthook.yml", "lefthook.yaml", ".lefthook.yml", ".lefthook.yaml"];
+function findLefthookConfig(dir) {
+  return LEFTHOOK_CONFIG_NAMES.find((name) => existsSync(resolve(dir, name))) ?? null;
+}
+function yamlUnquote(raw) {
+  return raw.trim().replace(/^['"]|['"]$/g, "");
+}
+function yamlExtendsEntries(text) {
+  const lines = text.split("\n");
+  const out = [];
+  for (const [index, line] of lines.entries()) {
+    const inline = /^extends:\s*\[(.*)\]\s*$/.exec(line ?? "");
+    if (inline !== null) {
+      out.push(...(inline[1] ?? "").split(",").map(yamlUnquote).filter(Boolean));
+      continue;
+    }
+    if (!/^extends:\s*(#.*)?$/.test(line ?? "")) continue;
+    for (const next of lines.slice(index + 1)) {
+      if (/^\s*(#.*)?$/.test(next ?? "")) continue;
+      const item = /^\s*-\s*(.+?)\s*$/.exec(next ?? "");
+      if (item === null) break;
+      out.push(yamlUnquote(item[1] ?? ""));
+    }
+  }
+  return out;
+}
+function inspectLefthookSeam(repoRoot) {
+  const file = findLefthookConfig(repoRoot);
+  if (file === null) return { kind: "no-file" };
+  const raw = readIfExists(resolve(repoRoot, file));
+  if (raw === null) return { kind: "no-file" };
+  const entry = yamlExtendsEntries(raw).find((e) => e.endsWith("basalt-ui/configs/lefthook.yml"));
+  if (entry === void 0) return { kind: "unwired", file };
+  return existsSync(resolve(repoRoot, entry)) ? { kind: "ok", file, entry } : { kind: "broken", file, entry };
 }
 function mergeOxlintExtends(cwd, presetPath) {
   const abs = resolve(cwd, ".oxlintrc.json");
@@ -744,7 +975,7 @@ function mergeOxlintExtends(cwd, presetPath) {
   if (raw === null) return "absent";
   const cfg = parseJsonc(raw);
   if (cfg === null) return "unreadable";
-  if (extendsBasaltPreset(cfg["extends"])) return "already";
+  if (basaltPresetEntry(cfg["extends"]) !== null) return "already";
   if (stripJsonc(raw) !== raw) return "has-comments";
   const existing = Array.isArray(cfg["extends"]) ? cfg["extends"].filter((entry) => typeof entry === "string") : [];
   const merged = "extends" in cfg ? {} : { extends: [presetPath] };
@@ -769,21 +1000,7 @@ function init(cwd = process.cwd(), scaffoldFlags = {}) {
       `\u26A0 basalt-ui init: basalt-ui does not resolve from ${cwd} or any directory above it \u2014 the seeded \`extends\` paths and CI steps are being written against the repo root by assumption. Install basalt-ui here (or at the repo root) and re-run \`basalt-ui init\` so they resolve.`
     );
   }
-  let seededRoots = null;
-  let rootsUndetectable = false;
-  if (readBasaltConfig(cwd).roots === void 0) {
-    const detected = detectRoots(cwd);
-    if (detected.length === 0) {
-      rootsUndetectable = true;
-    } else if (patchPackageJson(cwd, (pkg) => {
-      const basalt = pkg["basalt"] ?? {};
-      if (basalt["roots"] !== void 0) return false;
-      pkg["basalt"] = { ...basalt, roots: detected };
-      return true;
-    })) {
-      seededRoots = detected;
-    }
-  }
+  const rootsState = reconcileRoots(cwd, { write: true });
   const ctx = renderContext(cwd);
   const lintScript = `oxlint . && ${ctx.vars.BASALT_BIN} check-theme`;
   const seededLintScript = patchPackageJson(cwd, (pkg) => {
@@ -847,16 +1064,9 @@ Kept (already present \u2014 basalt did not touch them):`);
     };
     console.log(`basalt-ui init: --merge-lint \u2014 ${mergeMessage[mergeLint]}`);
   }
-  if (seededRoots !== null) {
-    console.log(
-      `basalt-ui init: wrote "basalt": { "roots": ${JSON.stringify(seededRoots)} } to package.json \u2014 check-theme, the CI oxfmt globs and the default scan exemption all derive from it. Correct it if your sources live elsewhere.`
-    );
-  }
-  if (rootsUndetectable) {
-    console.error(
-      '\u26A0 basalt-ui init: could not infer "basalt.roots" \u2014 no src/ here and no workspace package with one. Set "basalt": { "roots": [...] } in package.json by hand, or check-theme will fail with "0 files scanned".'
-    );
-  }
+  const rootsMessages = rootsNotices(rootsState);
+  for (const line of rootsMessages.log) console.log(`basalt-ui init: ${line}`);
+  for (const line of rootsMessages.error) console.error(`\u26A0 basalt-ui init: ${line}`);
   if (seededLintScript) {
     console.log(`basalt-ui init: added the "lint:basalt" script (${lintScript}) to package.json.`);
   }
@@ -922,6 +1132,7 @@ function readOxlintPresetPlugins(pkgRoot) {
   }
 }
 function sync(opts = {}, cwd = process.cwd()) {
+  const rootsState = reconcileRoots(cwd, { write: opts.check !== true });
   const ctx = renderContext(cwd);
   const manifest = readManifest(cwd);
   if (!opts.check) migrateLegacyOxfmt(cwd, ctx.pkgRoot, manifest);
@@ -977,6 +1188,23 @@ function sync(opts = {}, cwd = process.cwd()) {
       `basalt-ui sync: skipped src/query-client.ts (found an existing query client at ${relative(cwd, placement.relocatedQueryClient)}) \u2014 import it from there instead of re-seeding at the original path.`
     );
   }
+  const rootsMessages = rootsNotices(rootsState);
+  for (const line of rootsMessages.log) console.log(`basalt-ui sync: ${line}`);
+  for (const line of rootsMessages.error) console.error(`\u26A0 basalt-ui sync: ${line}`);
+  const install = findBasaltInstall(cwd);
+  const lefthookSeam = inspectLefthookSeam(placement.repoRoot);
+  if (lefthookSeam.kind === "broken") {
+    console.error(
+      `\u26A0 basalt-ui sync: ${lefthookSeam.file} extends "${lefthookSeam.entry}", which does not exist \u2014 lefthook merges a missing extends target into ZERO commands and still exits 0, so there is no pre-commit gate. Repoint it at "${shippedAssetPath(install, placement.repoRoot, "configs/lefthook.yml")}".`
+    );
+  }
+  const oxlintrcRaw = readIfExists(resolve(cwd, ".oxlintrc.json"));
+  const oxlintEntry = oxlintrcRaw === null ? null : basaltPresetEntry(parseJsonc(oxlintrcRaw)?.["extends"]);
+  if (oxlintEntry !== null && !existsSync(resolve(cwd, oxlintEntry))) {
+    console.error(
+      `\u26A0 basalt-ui sync: .oxlintrc.json extends "${oxlintEntry}", which does not exist \u2014 oxlint refuses to start on a missing extends target (\`NotFound\`). Repoint it at "${shippedAssetPath(install, cwd, "configs/oxlint.json")}".`
+    );
+  }
   if (opts.check) {
     if (driftLines.length > 0) {
       console.error("basalt-ui sync --check: locally-drifted managed files:");
@@ -1380,15 +1608,45 @@ basalt-ui doctor \u2014 ${cwd}
         skip(
           ".oxlintrc.json does not parse as JSON/JSONC \u2014 cannot tell whether it extends the preset"
         );
-      } else if (extendsBasaltPreset(parsed["extends"])) {
-        pass(".oxlintrc.json extends the shipped basalt-ui oxlint preset");
       } else {
-        fail(
-          `.oxlintrc.json does NOT extend the shipped preset \u2014 every basalt/* design rule is off and oxlint reports green without them. Add "extends": ["${shippedAssetPath(install, cwd, "configs/oxlint.json")}"], or re-run \`basalt-ui init --merge-lint\` to splice it in.`
-        );
+        const entry = basaltPresetEntry(parsed["extends"]);
+        const correct = shippedAssetPath(install, cwd, "configs/oxlint.json");
+        if (entry === null) {
+          fail(
+            `.oxlintrc.json does NOT extend the shipped preset \u2014 every basalt/* design rule is off and oxlint reports green without them. Add "extends": ["${correct}"], or re-run \`basalt-ui init --merge-lint\` to splice it in.`
+          );
+        } else if (!existsSync(resolve(cwd, entry)) && entry === correct && install.dir !== null) {
+          fail(
+            `.oxlintrc.json extends "${entry}", which does not exist (${resolve(cwd, entry)}) \u2014 basalt-ui resolves there but ships no \`configs/oxlint.json\` at that path, so oxlint refuses to start (\`NotFound\`) and nothing is linted. Reinstall basalt-ui.`
+          );
+        } else if (!existsSync(resolve(cwd, entry))) {
+          fail(
+            `.oxlintrc.json extends "${entry}", which does not exist (${resolve(cwd, entry)}) \u2014 oxlint refuses to start on a missing extends target (\`NotFound\`), so nothing is linted at all. Repoint it at "${correct}", where basalt-ui actually resolves.`
+          );
+        } else {
+          pass(`.oxlintrc.json extends the shipped basalt-ui oxlint preset (${entry})`);
+        }
       }
     }
   }
+  const repoRoot = findRepoRoot(cwd);
+  const lefthookSeam = profile === "tokens-only" ? { kind: "n/a" } : inspectLefthookSeam(repoRoot);
+  const lefthookCorrect = shippedAssetPath(install, repoRoot, "configs/lefthook.yml");
+  if (lefthookSeam.kind === "n/a") {
+    pass("lefthook-preset: n/a \u2014 a tokens-only consumer wires its own hooks");
+  } else if (lefthookSeam.kind === "no-file") {
+    pass(`lefthook-preset: n/a \u2014 no lefthook config at ${repoRoot}`);
+  } else if (lefthookSeam.kind === "unwired") {
+    warn(
+      `${lefthookSeam.file} does not extend the shipped lefthook preset \u2014 the oxlint / oxfmt / check-theme pre-commit jobs are not wired. Add "extends: [${lefthookCorrect}]" to it.`
+    );
+  } else if (lefthookSeam.kind === "broken") {
+    fail(
+      `${lefthookSeam.file} extends "${lefthookSeam.entry}", which does not exist (${resolve(repoRoot, lefthookSeam.entry)}) \u2014 lefthook merges a missing extends target into ZERO commands and still exits 0, so this repo has no pre-commit gate and \`lefthook dump\` looks clean. Repoint it at "${lefthookCorrect}".`
+    );
+  } else {
+    pass(`${lefthookSeam.file} extends the shipped lefthook preset (${lefthookSeam.entry})`);
+  }
   const publicDir = resolve(cwd, "public");
   if (profile === "framework" && existsSync(publicDir)) {
     const iconFiles = [
@@ -1541,10 +1799,14 @@ function generatedHeader(version, command, flags) {
 }
 function normalizeColorFunctions(css) {
   return css.replace(/\b(rgba?|hsla?)\(([^()]*)\)/g, (_match, fn, args) => {
-    const parts = args.split(",").map((part) => part.trim());
+    const parts = args.split(",").map((part) => normalizeCssNumber(part.trim()));
     return `${fn}(${parts.join(", ")})`;
   });
 }
+function normalizeCssNumber(arg) {
+  if (!/^\d+\.\d+$/.test(arg)) return arg;
+  return arg.replace(/\.?0+$/, "");
+}
 const SCHEME_CLASS_SENTINEL = "data-basalt-scheme-class";
 function emitGeneratedCss(content, flags, cwd, command) {
   const out = flagValue(flags, "--out");
@@ -1719,7 +1981,7 @@ async function guardHook(cwd = process.cwd()) {
     rawFormControl: cfg.rawFormControl ?? DEFAULT_GUARD_CONFIG.rawFormControl,
     sub16InputFont: cfg.sub16InputFont ?? DEFAULT_GUARD_CONFIG.sub16InputFont,
     allowComment: "theme-allow",
-    exemptRules: cfg.exemptRules ?? DEFAULT_GUARD_CONFIG.exemptRules,
+    exemptRules: resolveExemptRules(cfg),
     severity: cfg.severity ?? DEFAULT_GUARD_CONFIG.severity,
     // Same detection check-theme uses: the hook must never block an edit over advice the app
     // cannot take ("use @mantine/core's Select") in a repo with no Mantine.
@@ -1755,7 +2017,7 @@ async function guardHook(cwd = process.cwd()) {
   }
   return 0;
 }
-const USAGE = "Usage: basalt-ui <init [--with-router] [--with-query] [--merge-lint] | sync [--force] [--check] |\n                  check-theme | check-coverage | info [--json] | doctor [--tokens-only|--framework] |\n                  guard-hook | tokens:css | fonts:css | help>\n\ntokens:css [--out <path>] [--check] [--selector-attribute <attr> | --selector-class <class>]\n           [--light-class <class>] [--dark-value <v>] [--light-value <v>]\n           [--default-scheme <dark|light|none>] [--media-fallback] [--only <core|all>]\n           [--no-legacy-aliases]\n  Emit the --vx-* stylesheet (stdout unless --out). Defaults reproduce basalt-ui/tokens.css.\n  --selector-class emits `:root.dark` instead of an attribute selector (the Tailwind convention).\n  --check writes nothing and exits 1 when --out differs from what would be emitted (a CI gate).\n  --no-legacy-aliases drops the deprecated camelCase spellings (--vx-accentFill and friends),\n  which are emitted by default as aliases of the canonical kebab-case names.\n\nfonts:css [--out <path>] [--check]\n  Emit the shipped --basalt-font-* stacks as plain CSS \u2014 the typeface half of the token layer,\n  otherwise reachable only by importing styles.css.\n\ndoctor [--tokens-only|--framework]\n  Auto-detects a tokens-only consumer (no manifest + no @mantine/core) and checks only what\n  applies. A check that cannot RUN is reported as SKIPPED and exits non-zero.\n\ncheck-theme / doctor honour BASALT_CWD, and relocate to the single workspace package carrying a\nbasalt config when invoked from a repo root that has none \u2014 several carrying one is ambiguous\nand exits 1 in BOTH. --tokens-only and --framework are alternatives; passing both is an error.\n\nEvery subcommand accepts --help / -h to print this message and exit without running.";
+const USAGE = "Usage: basalt-ui <init [--with-router] [--with-query] [--merge-lint] | sync [--force] [--check] |\n                  check-theme [--audit-allows] | check-coverage | info [--json] |\n                  doctor [--tokens-only|--framework] | guard-hook | tokens:css | fonts:css | help>\n\ncheck-theme [--tokens-only|--framework] [--audit-allows]\n  --audit-allows reports instead of scanning: every `theme-allow` annotation and every\n  `basalt.exemptRules` entry, with what each one still suppresses \u2014 proved by re-running the\n  guard with that one waiver neutralized, not by reading its text. Exits 1 on a waiver that\n  suppresses nothing (dead), which is what makes it usable as a CI gate.\n\ntokens:css [--out <path>] [--check] [--selector-attribute <attr> | --selector-class <class>]\n           [--light-class <class>] [--dark-value <v>] [--light-value <v>]\n           [--default-scheme <dark|light|none>] [--media-fallback] [--only <core|all>]\n           [--no-legacy-aliases]\n  Emit the --vx-* stylesheet (stdout unless --out). Defaults reproduce basalt-ui/tokens.css.\n  --selector-class emits `:root.dark` instead of an attribute selector (the Tailwind convention).\n  --check writes nothing and exits 1 when --out differs from what would be emitted (a CI gate).\n  --no-legacy-aliases drops the deprecated camelCase spellings (--vx-accentFill and friends),\n  which are emitted by default as aliases of the canonical kebab-case names.\n\nfonts:css [--out <path>] [--check]\n  Emit the shipped --basalt-font-* stacks as plain CSS \u2014 the typeface half of the token layer,\n  otherwise reachable only by importing styles.css.\n\ndoctor [--tokens-only|--framework]\n  Auto-detects a tokens-only consumer (no manifest + no @mantine/core) and checks only what\n  applies. A check that cannot RUN is reported as SKIPPED and exits non-zero.\n\ncheck-theme / doctor honour BASALT_CWD, and relocate to the single workspace package carrying a\nbasalt config when invoked from a repo root that has none \u2014 several carrying one is ambiguous\nand exits 1 in BOTH. --tokens-only and --framework are alternatives; passing both is an error.\n\nEvery subcommand accepts --help / -h to print this message and exit without running.";
 function run(argv, cwd = process.cwd()) {
   const [cmd, ...flags] = argv;
   if (cmd === "help" || cmd === "--help" || cmd === "-h" || flags.includes("--help") || flags.includes("-h")) {

package/dist/cli/waiver-audit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=waiver-audit.test.d.ts.map

package/dist/cli/waiver-audit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"waiver-audit.test.d.ts","sourceRoot":"","sources":["../../src/cli/waiver-audit.test.ts"],"names":[],"mappings":""}

package/dist/guard/index.d.ts

@@ -8,6 +8,26 @@ import type { Finding, GuardConfig, GuardKind, GuardSeverity } from './types.js'
 export type { Finding, GuardConfig, GuardKind, GuardSeverity };
 /** Shared default config — CLI and tests import this to avoid duplication. */
 export declare const DEFAULT_GUARD_CONFIG: GuardConfig;
+/** One `exemptRules` entry that suppressed nothing, and why — see {@link unmatchedExemptPatterns}. */
+export type UnmatchedExemptPattern = {
+    readonly kind: string;
+    readonly pattern: string;
+    readonly reason: 'unknown-kind' | 'no-match';
+};
+/**
+ * Every `exemptRules` entry that matched no scanned file, so a run can say so instead of passing.
+ *
+ * An exemption is a claim ("this rule does not apply here"), and a claim that resolves to nothing is
+ * not harmless — it reads as coverage in a config review while enforcing exactly as much as an empty
+ * object. rollhook's `["public/site.webmanifest"]` was correct, matched nothing under the
+ * segments-only matcher, and reported no diagnostic; the finding it was written for kept failing the
+ * build with the config sitting right there looking like the answer. A silent no-op exemption is the
+ * same false-green family as a guard that reports green while enforcing nothing.
+ *
+ * Called once per run by the CLI with every relative path it scanned. Kind keys are checked too: a
+ * typo'd kind name is an exemption for a rule that does not exist.
+ */
+export declare function unmatchedExemptPatterns(cfg: GuardConfig, scannedRelPaths: readonly string[]): UnmatchedExemptPattern[];
 /**
  * The exact first line of every stylesheet the CLI emits — the contract between `basalt-ui
  * tokens:css` / `fonts:css` and this scanner, and the single source of truth for it (`src/cli`
@@ -178,13 +198,13 @@ export declare const GUARD_RULES: {
     readonly 'theme-allow-unscoped': {
         readonly kind: "theme-allow-unscoped";
         readonly pattern: RegExp;
-        readonly message: "theme-allow without a usable rule id and a reason. Write `theme-allow <rule-id> — <why>`: the id scopes the exception to that one kind (a bare comment waives EVERY kind on the line, including ones added later), and the reason is what makes it reviewable in a diff. An id that names no rule is a typo, not a blanket waiver — it suppresses nothing.";
+        readonly message: "theme-allow without a usable rule id and a reason. Write `theme-allow <rule-id> — <why>`: the id scopes the exception to that one kind (a bare comment waives EVERY kind on the line, including ones added later), and the reason is what makes it reviewable in a diff. An id that names no rule is a typo, not a blanket waiver — it suppresses nothing. `theme-allow-file <rule-id> — <why>` declares the whole file, and must name its ids: a bare one waives nothing.";
     };
     readonly 'surface-shadow-override': {
         readonly kind: "surface-shadow-override";
         readonly pattern: RegExp;
         readonly enabled: (cfg: GuardConfig) => boolean;
-        readonly message: "Token-composed boxShadow that REPLACES card depth — a card whose shadow drops --vx-shadow-card is the one card in the app with no depth. Compose with it (`${VX.shadowCard}, <your ring>`) rather than instead of it.";
+        readonly message: "Token-composed boxShadow that REPLACES surface depth — a card whose shadow drops --vx-shadow-card is the one card in the app with no depth. Compose with the depth token for its tier (`${VX.shadowCard}, <your ring>`; a fixed/floating surface wants --vx-shadow-overlay) rather than instead of it.";
     };
     readonly 'css-raw-surface': {
         readonly kind: "css-raw-surface";
@@ -206,6 +226,31 @@ export declare const GUARD_RULES: {
         readonly message: "Raw font-size literal — route through VX.text.* (numbers) / --vx-text-* (CSS), or the Mantine fz token. Same rule the oxlint plugin enforces as basalt/no-raw-font-size; this is the half a check-theme-only CI can see.";
     };
 };
+/**
+ * The one-line remedy for `kind`, as a report reads it: `raw-hex: Route color through VX.* / …`.
+ *
+ * The registry has always carried a remedy per kind; `check-theme`'s `Fix:` epilogue read a
+ * hand-duplicated subset instead, and the subset was missing every kind added at 1.20.0. Since all
+ * five of those ship `warn` under grace, the findings whose whole argument is "this looks correct
+ * and is not" arrived with no argument at all — just "add a `theme-allow`", which reads as advice to
+ * waive. Sourcing the epilogue from here retires the duplicate rather than extending it.
+ */
+export declare function guardKindRemedy(kind: GuardKind): string;
+/**
+ * How to waive a finding **in this file's syntax** — the closer a report prints under `Fix:`.
+ *
+ * `check-theme` printed one closer for every file class, and from 1.20.0 (when the scan reached
+ * `.webmanifest` / `.json`) it prescribed a `theme-allow` comment to files that cannot hold a
+ * comment. Two consumers read that, found no route, and fell back to a blanket `exemptRules` entry —
+ * the un-reviewable shape the release was spent retiring.
+ *
+ * A manifest gets the sharper answer first, because a hex there can never be *right*: a manifest
+ * cannot reference a CSS custom property, so the value is a hand-copy of a token that drifts the day
+ * the palette moves (which is exactly what both consumers found — two dead colours). The remedy is
+ * to stop hand-writing the file: `basaltAppPlugin` emits it from `SURFACE.bg`. The annotation is the
+ * fallback for a manifest basalt does not generate.
+ */
+export declare function guardWaiverHint(relPath: string): string;
 /**
  * Scan ONE file's text for theme-guard violations. Pure: same (text, relPath, cfg) → same Finding[].
  * No FS, no walk, no console. The 3 dynamic regexes (forbiddenAccent, spacing, radius) are derived

package/dist/guard/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guard/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE7E,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,CAAA;AAuW9D,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,EAAE,WAoBlC,CAAA;AAuVD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,gGACwD,CAAA;AA8F1F;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,SAAS,CAqB5D,CAAA;AA2NF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;gCA0BL,WAAW;;;;;;;gCAcX,WAAW;;;;;gCAMX,WAAW;;;;;;;gCAaX,WAAW;;;;;;;gCAQX,WAAW;;;;;;gCAOX,WAAW;;;;;;;gCASX,WAAW;;;;;;gCAOX,WAAW;;;;;;;gCAaX,WAAW;;;;;;gCAMX,WAAW;;;;;;;gCAaX,WAAW;;;;;;;gCAUX,WAAW;;;;;;;gCAUX,WAAW;;;;;;;gCASX,WAAW;;;;;;;gCASX,WAAW;;;;;;;gCAUX,WAAW;;;;;;;;;;;;gCAgBX,WAAW;;;;;;gCAOX,WAAW;;;;;;;gCASX,WAAW;;;;;;;;;CAWmB,CAAA;AAUjD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,EAAE,CAyVtF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guard/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE7E,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,CAAA;AAyb9D,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,EAAE,WAoBlC,CAAA;AAmJD,sGAAsG;AACtG,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,UAAU,CAAA;CAC7C,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,WAAW,EAChB,eAAe,EAAE,SAAS,MAAM,EAAE,GACjC,sBAAsB,EAAE,CAc1B;AA8WD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,gGACwD,CAAA;AA8F1F;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,SAAS,CAqB5D,CAAA;AA2NF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;gCA0BL,WAAW;;;;;;;gCAcX,WAAW;;;;;gCAMX,WAAW;;;;;;;gCAaX,WAAW;;;;;;;gCAQX,WAAW;;;;;;gCAOX,WAAW;;;;;;;gCASX,WAAW;;;;;;gCAOX,WAAW;;;;;;;gCAaX,WAAW;;;;;;gCAMX,WAAW;;;;;;;gCAaX,WAAW;;;;;;;gCAUX,WAAW;;;;;;;gCAUX,WAAW;;;;;;;gCASX,WAAW;;;;;;;gCASX,WAAW;;;;;;;gCAUX,WAAW;;;;;;;;;;;;gCAgBX,WAAW;;;;;;gCAOX,WAAW;;;;;;;gCASX,WAAW;;;;;;;;;CAWmB,CAAA;AAEjD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAEvD;AAKD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAgBvD;AAUD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,EAAE,CA0XtF"}