basalt-ui 1.20.0 → 1.22.0

package/dist/cli/index.js

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import {
   existsSync,
@@ -14,12 +15,33 @@ import {
   checkSource,
   DEFAULT_GUARD_CONFIG,
   GENERATED_HEADER_LINE,
+  findAllowAnnotations,
+  guardKindRemedy,
   GUARD_RULES,
-  TOKENS_ONLY_DISABLED_KINDS
+  guardWaiverHint,
+  neutralizeAllowAnnotation,
+  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 +111,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 ".";
@@ -219,6 +222,13 @@ function appShellFiles(rootAbs) {
   out.push(...walkSourceFiles(resolve(appDir, "public")));
   return out;
 }
+const PLAIN_JSON_HINT_PATH = "manifest.json";
+function waiverHintFor(relPath, profile) {
+  if (profile !== "tokens-only" || !relPath.endsWith(".webmanifest")) {
+    return guardWaiverHint(relPath);
+  }
+  return `${guardWaiverHint(PLAIN_JSON_HINT_PATH)} (basaltAppPlugin would emit the file instead, but it needs basalt's Vite/React layer, which a tokens-only consumer has opted out of.)`;
+}
 function checkTheme(invocationCwd = process.cwd(), flags = []) {
   if (conflictingProfileFlags(flags)) {
     console.error(
@@ -265,7 +275,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 +296,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 +338,11 @@ 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) => waiverHintFor(f.relPath, profile)))
+  ].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 +350,232 @@ function checkTheme(invocationCwd = process.cwd(), flags = []) {
   }
   return errors.length > 0 ? 1 : 0;
 }
+function findingKey(f) {
+  return `${f.relPath}:${f.line}:${f.kind}`;
+}
+function resolveToolBin(dir, name) {
+  let current = dir;
+  for (; ; ) {
+    const candidate = resolve(current, "node_modules/.bin", name);
+    if (existsSync(candidate)) return candidate;
+    const parent = resolve(current, "..");
+    if (parent === current) break;
+    current = parent;
+  }
+  const probe = spawnSync(name, ["--version"], { stdio: "ignore", timeout: 1e4 });
+  return probe.error === void 0 && probe.status === 0 ? name : null;
+}
+function diagnosticCounts(diagnostics, filename) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const d of diagnostics) {
+    if (d.filename !== filename) continue;
+    const code = typeof d.code === "string" ? d.code : "";
+    const rule = /^basalt\((.+)\)$/.exec(code)?.[1];
+    if (rule === void 0) continue;
+    const line = d.labels?.[0]?.span?.line;
+    const key = `${typeof line === "number" ? line : 0}:${rule}`;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return counts;
+}
+function probePluginRules(cwd, guardCfg, probes, sources) {
+  if (probes.length === 0) return /* @__PURE__ */ new Map();
+  const bin = resolveToolBin(cwd, "oxlint");
+  if (bin === null) return null;
+  const written = [];
+  const probePaths = /* @__PURE__ */ new Map();
+  try {
+    for (const probe of probes) {
+      const probed = neutralizeAllowAnnotation(sources.get(probe.rel) ?? "", probe.line, guardCfg);
+      const dot = probe.rel.lastIndexOf(".");
+      const rel = dot === -1 ? `${probe.rel}.basalt-audit-${probe.slot}` : `${probe.rel.slice(0, dot)}.basalt-audit-${probe.slot}${probe.rel.slice(dot)}`;
+      const abs = resolve(cwd, rel);
+      if (existsSync(abs)) continue;
+      writeFileSync(abs, probed, "utf8");
+      written.push(abs);
+      probePaths.set(probe.slot, rel);
+    }
+    if (probePaths.size === 0) return null;
+    const targets = [...new Set(probes.map((p) => p.rel)), ...probePaths.values()];
+    const run2 = spawnSync(bin, ["--format=json", "--no-error-on-unmatched-pattern", ...targets], {
+      cwd,
+      encoding: "utf8",
+      timeout: 12e4,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    if (run2.error !== void 0 || typeof run2.stdout !== "string") return null;
+    let diagnostics;
+    try {
+      diagnostics = JSON.parse(run2.stdout).diagnostics ?? [];
+    } catch {
+      return null;
+    }
+    const verdicts = /* @__PURE__ */ new Map();
+    for (const probe of probes) {
+      const probeRel = probePaths.get(probe.slot);
+      if (probeRel === void 0) continue;
+      const before = diagnosticCounts(diagnostics, probe.rel);
+      const after = diagnosticCounts(diagnostics, probeRel);
+      const revealed = [];
+      for (const [key, count] of after) {
+        if (count <= (before.get(key) ?? 0)) continue;
+        const [line = "", rule = ""] = key.split(":");
+        revealed.push(`${rule}@${line}`);
+      }
+      verdicts.set(probe.slot, revealed.toSorted());
+    }
+    return verdicts;
+  } finally {
+    for (const abs of written) {
+      try {
+        unlinkSync(abs);
+      } catch {
+      }
+    }
+  }
+}
+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 pluginProbes = [];
+  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])
+    );
+    for (const site of findAllowAnnotations(text, rel, guardCfg)) {
+      const revealed = checkSource(
+        neutralizeAllowAnnotation(text, site.line, guardCfg),
+        rel,
+        guardCfg
+      ).filter((f) => f.kind !== "theme-allow-unscoped" && !baselineKeys.has(findingKey(f))).map((f) => `${f.kind}@${f.line}`);
+      const note = unscopedAt.get(site.line);
+      if (note !== void 0) unaccountable++;
+      const label = `  ${rel}:${site.line}`.padEnd(52);
+      const suffix = note === void 0 ? "" : ` [${note}]`;
+      if (revealed.length > 0) {
+        live++;
+        waiverLines.push(`${label} suppresses ${[...new Set(revealed)].join(", ")}${suffix}`);
+        continue;
+      }
+      if (site.pluginRules.length > 0 && site.guardKinds.length === 0) {
+        pluginProbes.push({
+          slot: waiverLines.length,
+          rel,
+          line: site.line,
+          ids: site.pluginRules,
+          site: label,
+          suffix
+        });
+        waiverLines.push("");
+        continue;
+      }
+      if (site.guardKinds.length === 0 && site.unknownRules.length > 0) {
+        outOfReach++;
+        waiverLines.push(
+          `${label} scoped to ${site.unknownRules.join(", ")} \u2014 names no guard kind and no plugin rule, so this audit cannot judge it (most likely a typo, which theme-allow-unscoped reports)${suffix}`
+        );
+        continue;
+      }
+      dead++;
+      waiverLines.push(`${label} SUPPRESSES NOTHING \u2014 dead, delete it${suffix}`);
+    }
+  }
+  const pluginVerdicts = probePluginRules(cwd, guardCfg, pluginProbes, sources);
+  for (const probe of pluginProbes) {
+    const revealed = pluginVerdicts?.get(probe.slot);
+    if (revealed === void 0) {
+      outOfReach++;
+      waiverLines[probe.slot] = `${probe.site} scoped to ${probe.ids.join(", ")} \u2014 an oxlint plugin rule, and oxlint could not be run here, so this audit cannot judge it${probe.suffix}`;
+      continue;
+    }
+    if (revealed.length > 0) {
+      live++;
+      waiverLines[probe.slot] = `${probe.site} suppresses ${revealed.join(", ")} (oxlint)${probe.suffix}`;
+      continue;
+    }
+    dead++;
+    waiverLines[probe.slot] = `${probe.site} SUPPRESSES NOTHING \u2014 dead, delete it (proved by re-running oxlint over the file with this annotation neutralized)${probe.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} unjudgeable, ${unaccountable} unaccountable (reported as theme-allow-unscoped by a normal run).`
+  );
+  lines.push(
+    `Scope: the ${scanned.length} file(s) check-theme scans under basalt.roots (${resolveRoots(cfg).join(", ")}). A waiver outside them is not audited \u2014 widen roots to cover it, or accept that nothing polices that file.`
+  );
+  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 +770,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 +944,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 +1041,79 @@ 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 };
+}
+const LEFTHOOK_GUARD_RUN = /^\s*run:\s*.*\bcheck-theme\b/m;
+function lefthookDump(repoRoot) {
+  const localBin = resolve(repoRoot, "node_modules/.bin/lefthook");
+  const bin = existsSync(localBin) ? localBin : "lefthook";
+  try {
+    const result = spawnSync(bin, ["dump"], {
+      cwd: repoRoot,
+      encoding: "utf8",
+      timeout: 1e4,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    if (result.error !== void 0 || result.status !== 0) return null;
+    return result.stdout;
+  } catch {
+    return null;
+  }
+}
+function inspectLefthookGate(repoRoot) {
+  const seam = inspectLefthookSeam(repoRoot);
+  if (seam.kind === "no-file") return { kind: "no-file" };
+  if (seam.kind === "ok") return { kind: "extends-ok", file: seam.file, entry: seam.entry };
+  if (seam.kind === "broken") {
+    return { kind: "extends-broken", file: seam.file, entry: seam.entry };
+  }
+  const dump = lefthookDump(repoRoot);
+  if (dump !== null) {
+    return LEFTHOOK_GUARD_RUN.test(dump) ? { kind: "wired", file: seam.file, proof: "dump" } : { kind: "absent", file: seam.file };
+  }
+  const raw = readIfExists(resolve(repoRoot, seam.file)) ?? "";
+  if (LEFTHOOK_GUARD_RUN.test(raw)) return { kind: "wired", file: seam.file, proof: "config" };
+  return { kind: "advisory", file: seam.file };
 }
 function mergeOxlintExtends(cwd, presetPath) {
   const abs = resolve(cwd, ".oxlintrc.json");
@@ -744,7 +1121,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 +1146,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 +1210,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.`);
   }
@@ -921,7 +1277,38 @@ function readOxlintPresetPlugins(pkgRoot) {
     return [];
   }
 }
-function sync(opts = {}, cwd = process.cwd()) {
+function findManifestAbove(dir) {
+  let current = resolve(dir, "..");
+  for (; ; ) {
+    if (existsSync(resolve(current, MANIFEST_PATH))) return current;
+    const parent = resolve(current, "..");
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+function sync(opts = {}, invocationCwd = process.cwd()) {
+  const project = resolveProjectDir(invocationCwd);
+  if (project.ambiguous !== null) {
+    console.error(
+      `\u2716 basalt-ui sync: no basalt config at ${invocationCwd}, and ${project.ambiguous.length} workspace packages carry one (${project.ambiguous.map((d) => relativePosix(invocationCwd, d)).join(", ")}) \u2014 run it from one of them, or set BASALT_CWD to pick.`
+    );
+    return 1;
+  }
+  const cwd = project.dir;
+  if (project.relocatedFrom !== null) {
+    console.log(
+      `basalt-ui sync: no basalt config at ${project.relocatedFrom} \u2014 running in ${relativePosix(project.relocatedFrom, cwd)}, where it lives.`
+    );
+  }
+  if (!existsSync(resolve(cwd, MANIFEST_PATH))) {
+    const elsewhere = findManifestAbove(cwd);
+    const wouldWrite = managedFiles(resolvePeerFlags(cwd, {}), resolvePlacement(cwd)).length;
+    console.error(
+      `\u2716 basalt-ui sync: no ${MANIFEST_PATH} at ${cwd} \u2014 refusing to scaffold. \`sync\` refreshes an EXISTING basalt install; creating one is \`basalt-ui init\`'s decision, and continuing here would write ${wouldWrite} managed file(s) into this directory.` + (elsewhere === null ? " No manifest exists at any ancestor either \u2014 run `basalt-ui init` here if this package really is meant to be a consumer." : ` This repo's install is at ${relativePosix(cwd, elsewhere)} (${elsewhere}) \u2014 run sync there, or set BASALT_CWD to it.`)
+    );
+    return 1;
+  }
+  const rootsState = reconcileRoots(cwd, { write: opts.check !== true });
   const ctx = renderContext(cwd);
   const manifest = readManifest(cwd);
   if (!opts.check) migrateLegacyOxfmt(cwd, ctx.pkgRoot, manifest);
@@ -929,6 +1316,7 @@ function sync(opts = {}, cwd = process.cwd()) {
   const placement = resolvePlacement(cwd);
   const files = managedFiles(peers, placement);
   let updated = 0;
+  let created = 0;
   let recreated = 0;
   let skippedDrift = 0;
   let staleForCheck = 0;
@@ -940,10 +1328,12 @@ function sync(opts = {}, cwd = process.cwd()) {
       missingSources.push(file.source);
       continue;
     }
+    const tracked = manifest.files[file.dest] !== void 0;
     if (file.mode === "seed") {
       if (state.current === null && !opts.check) {
         manifest.files[file.dest] = writeUnit(file, cwd, state.desired);
-        recreated++;
+        if (tracked) recreated++;
+        else created++;
       }
       continue;
     }
@@ -961,8 +1351,9 @@ function sync(opts = {}, cwd = process.cwd()) {
     staleForCheck++;
     if (opts.check) continue;
     manifest.files[file.dest] = writeUnit(file, cwd, state.desired);
-    if (kind === "missing") recreated++;
-    else updated++;
+    if (kind !== "missing") updated++;
+    else if (tracked) recreated++;
+    else created++;
   }
   if (!placement.isPackageRepoRoot) {
     console.log(
@@ -977,6 +1368,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:");
@@ -994,7 +1402,7 @@ function sync(opts = {}, cwd = process.cwd()) {
   writeFileEnsuringDir(resolve(cwd, MANIFEST_PATH), `${JSON.stringify(manifest, null, 2)}
 `);
   console.log(
-    `basalt-ui sync: ${updated} updated, ${recreated} recreated, ${skippedDrift} skipped (drift).`
+    `basalt-ui sync: ${updated} updated, ${created} created, ${recreated} recreated, ${skippedDrift} skipped (drift).`
   );
   if (driftLines.length > 0) {
     console.log("Locally-edited files were skipped (run with --force to overwrite):");
@@ -1380,15 +1788,53 @@ 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 lefthookGate = profile === "tokens-only" ? { kind: "n/a" } : inspectLefthookGate(repoRoot);
+  const lefthookCorrect = shippedAssetPath(install, repoRoot, "configs/lefthook.yml");
+  if (lefthookGate.kind === "n/a") {
+    pass("lefthook-preset: n/a \u2014 a tokens-only consumer wires its own hooks");
+  } else if (lefthookGate.kind === "no-file") {
+    pass(`lefthook-preset: n/a \u2014 no lefthook config at ${repoRoot}`);
+  } else if (lefthookGate.kind === "extends-ok") {
+    pass(`${lefthookGate.file} extends the shipped lefthook preset (${lefthookGate.entry})`);
+  } else if (lefthookGate.kind === "wired") {
+    pass(
+      `lefthook-preset: ${lefthookGate.file} does not extend the shipped preset, but a pre-commit command runs check-theme directly \u2014 the gate exists (read from ` + (lefthookGate.proof === "dump" ? "`lefthook dump`, so extends/include/root: are all resolved)." : "the config text; `lefthook dump` was not runnable here, so an `include:` or a remote config was not consulted).")
+    );
+  } else if (lefthookGate.kind === "extends-broken") {
+    fail(
+      `${lefthookGate.file} extends "${lefthookGate.entry}", which does not exist (${resolve(repoRoot, lefthookGate.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 if (lefthookGate.kind === "absent") {
+    warn(
+      `${lefthookGate.file}: \`lefthook dump\` resolves the merged config and NO pre-commit command runs check-theme \u2014 the theme guard is not gating commits. Either add "extends: [${lefthookCorrect}]", or add your own command running \`bunx basalt-ui check-theme\` (with \`root:\` if it must run in a subdirectory).`
+    );
+  } else {
+    warn(
+      `${lefthookGate.file} names no basalt gate and \`lefthook dump\` could not be run here, so this check cannot tell a missing gate from one wired through an \`include:\` or a remote config it never read \u2014 treat it as advisory. If the guard really is unwired, add "extends: [${lefthookCorrect}]" or your own command running \`bunx basalt-ui check-theme\`.`
+    );
+  }
   const publicDir = resolve(cwd, "public");
   if (profile === "framework" && existsSync(publicDir)) {
     const iconFiles = [
@@ -1541,10 +1987,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 +2169,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 +2205,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")) {