basalt-ui 1.21.0 → 1.23.0

package/dist/cli/index.js

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import {
   existsSync,
@@ -14,9 +15,11 @@ import {
   checkSource,
   DEFAULT_GUARD_CONFIG,
   GENERATED_HEADER_LINE,
+  findAllowAnnotations,
   guardKindRemedy,
   GUARD_RULES,
   guardWaiverHint,
+  neutralizeAllowAnnotation,
   TOKENS_ONLY_DISABLED_KINDS,
   unmatchedExemptPatterns
 } from "../guard/index.js";
@@ -157,6 +160,16 @@ function hasBasaltProject(dir) {
     return false;
   }
 }
+function descendantProjects(cwd, depth = 2) {
+  if (depth === 0) return [];
+  const out = [];
+  for (const name of subdirNames(cwd, { skipDotDirs: true })) {
+    const dir = resolve(cwd, name);
+    if (hasBasaltProject(dir)) out.push(dir);
+    else out.push(...descendantProjects(dir, depth - 1));
+  }
+  return out;
+}
 function resolveProjectDir(cwd) {
   const override = process.env["BASALT_CWD"];
   if (override !== void 0 && override.length > 0) {
@@ -164,7 +177,8 @@ function resolveProjectDir(cwd) {
     return { dir, relocatedFrom: dir === cwd ? null : cwd, ambiguous: null };
   }
   if (hasBasaltProject(cwd)) return { dir: cwd, relocatedFrom: null, ambiguous: null };
-  const candidates = collectWorkspacePackages(cwd).packages.filter((pkg) => pkg.dir !== cwd && hasBasaltProject(pkg.dir)).map((pkg) => pkg.dir);
+  const declared = collectWorkspacePackages(cwd).packages.filter((pkg) => pkg.dir !== cwd && hasBasaltProject(pkg.dir)).map((pkg) => pkg.dir);
+  const candidates = declared.length > 0 ? declared : descendantProjects(cwd);
   if (candidates.length === 1) {
     return { dir: candidates[0], relocatedFrom: cwd, ambiguous: null };
   }
@@ -219,6 +233,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(
@@ -229,7 +250,7 @@ function checkTheme(invocationCwd = process.cwd(), flags = []) {
   const project = resolveProjectDir(invocationCwd);
   if (project.ambiguous !== null) {
     console.error(
-      `\u2716 basalt-ui check-theme: 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.`
+      `\u2716 basalt-ui check-theme: no basalt config at ${invocationCwd}, and ${project.ambiguous.length} packages below it 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;
   }
@@ -329,7 +350,9 @@ function checkTheme(invocationCwd = process.cwd(), flags = []) {
 `);
   }
   const presentKinds = [...new Set(findings.map((f) => f.kind))].toSorted();
-  const waiverHints = [...new Set(findings.map((f) => guardWaiverHint(f.relPath)))].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(
@@ -338,20 +361,89 @@ 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 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;
@@ -363,6 +455,7 @@ basalt-ui check-theme --audit-allows \u2014 ${cwd}
   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) {
@@ -375,31 +468,60 @@ basalt-ui check-theme --audit-allows \u2014 ${cwd}
     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);
+    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 site = `  ${rel}:${index + 1}`.padEnd(52);
+      const label = `  ${rel}:${site.line}`.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))) {
+        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(
-          `${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}`
+          `${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}`
         );
-      } else {
-        dead++;
-        waiverLines.push(`${site} SUPPRESSES NOTHING \u2014 dead, delete it${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 = [];
@@ -452,7 +574,11 @@ 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).`
+${live} live, ${dead} dead, ${outOfReach} unjudgeable, ${unaccountable} unaccountable (reported as theme-allow-unscoped by a normal run).`
+  );
+  const includes = cfg.include ?? [];
+  lines.push(
+    `Scope: the ${scanned.length} file(s) check-theme scans \u2014 everything under basalt.roots (${resolveRoots(cfg).join(", ")}), plus each root's sibling index.html and public/ tree, ` + (includes.length === 0 ? "plus anything named in basalt.include (none). " : `plus basalt.include (${includes.join(", ")}). `) + "A waiver in a file none of those reach is not audited \u2014 widen roots, or name it in basalt.include, or accept that nothing polices that file."
   );
   if (dead > 0) {
     lines.push(
@@ -746,6 +872,16 @@ function migrateLegacyOxfmt(cwd, pkgRoot, manifest) {
   const shipped = readSource(pkgRoot, "configs/oxfmt.json");
   if (shipped !== null && onDisk === shipped) unlinkSync(legacyAbs);
 }
+const DESIGN_VERSION_LINE = /^(> Managed by basalt-ui) \(\d+\.\d+\.\d+\)\./m;
+function migrateDesignVersionLine(cwd) {
+  const dest = resolve(cwd, "DESIGN.md");
+  const onDisk = readIfExists(dest);
+  if (onDisk === null || !DESIGN_VERSION_LINE.test(onDisk)) return;
+  writeFileEnsuringDir(
+    dest,
+    onDisk.replace(DESIGN_VERSION_LINE, "$1 \u2014 run `basalt-ui doctor` for the version.")
+  );
+}
 function writeFileEnsuringDir(abs, content) {
   mkdirSync(dirname(abs), { recursive: true });
   writeFileSync(abs, content);
@@ -969,6 +1105,38 @@ function inspectLefthookSeam(repoRoot) {
   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");
   const raw = readIfExists(abs);
@@ -1131,15 +1299,60 @@ 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 syncFlags = opts.flags ?? [];
+  if (conflictingProfileFlags(syncFlags)) {
+    console.error("basalt-ui sync: --tokens-only and --framework are alternatives \u2014 pass one.");
+    return 1;
+  }
+  const project = resolveProjectDir(invocationCwd);
+  if (project.ambiguous !== null) {
+    console.error(
+      `\u2716 basalt-ui sync: no basalt config at ${invocationCwd}, and ${project.ambiguous.length} packages below it 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 (declaredProfile(readBasaltConfig(cwd), syncFlags) === "tokens-only") {
+    console.log(
+      `basalt-ui sync: ${MANIFEST_PATH}: n/a \u2014 a tokens-only consumer has no scaffold to reconcile. The token layer is refreshed by re-running \`basalt-ui tokens:css\`, and \`tokens:css --check\` is its drift gate. Pass --framework to force the full profile.`
+    );
+    return 0;
+  }
+  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);
+  if (!opts.check) {
+    migrateLegacyOxfmt(cwd, ctx.pkgRoot, manifest);
+    migrateDesignVersionLine(cwd);
+  }
   const peers = resolvePeerFlags(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;
@@ -1151,10 +1364,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;
     }
@@ -1172,8 +1387,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(
@@ -1222,7 +1438,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):");
@@ -1454,7 +1670,7 @@ function doctor(invocationCwd = process.cwd(), flags = []) {
       `
 basalt-ui doctor \u2014 ${invocationCwd}
 
-  \u2716 no basalt config at ${invocationCwd}, and ${project.ambiguous.length} workspace packages carry one (${project.ambiguous.map((d) => relativePosix(invocationCwd, d)).join(", ")}) \u2014 run doctor from one of them, or set BASALT_CWD to pick.
+  \u2716 no basalt config at ${invocationCwd}, and ${project.ambiguous.length} packages below it carry one (${project.ambiguous.map((d) => relativePosix(invocationCwd, d)).join(", ")}) \u2014 run doctor from one of them, or set BASALT_CWD to pick.
 
 1 hard failure(s), 0 warning(s).
 `
@@ -1630,22 +1846,30 @@ basalt-ui doctor \u2014 ${cwd}
     }
   }
   const repoRoot = findRepoRoot(cwd);
-  const lefthookSeam = profile === "tokens-only" ? { kind: "n/a" } : inspectLefthookSeam(repoRoot);
+  const lefthookGate = profile === "tokens-only" ? { kind: "n/a" } : inspectLefthookGate(repoRoot);
   const lefthookCorrect = shippedAssetPath(install, repoRoot, "configs/lefthook.yml");
-  if (lefthookSeam.kind === "n/a") {
+  if (lefthookGate.kind === "n/a") {
     pass("lefthook-preset: n/a \u2014 a tokens-only consumer wires its own hooks");
-  } else if (lefthookSeam.kind === "no-file") {
+  } else if (lefthookGate.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 (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 (lefthookSeam.kind === "broken") {
+  } else if (lefthookGate.kind === "extends-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}".`
+      `${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 {
-    pass(`${lefthookSeam.file} extends the shipped lefthook preset (${lefthookSeam.entry})`);
+    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)) {
@@ -2017,7 +2241,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 [--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.";
+const USAGE = "Usage: basalt-ui <init [--with-router] [--with-query] [--merge-lint] |\n                  sync [--force] [--check] [--tokens-only|--framework] |\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\nsync [--force] [--check] [--tokens-only|--framework]\n  Refreshes an EXISTING install; it never creates one (that is init). A tokens-only consumer\n  has no scaffold to reconcile, so sync reports n/a and exits 0 there \u2014 as doctor does.\n\ncheck-theme / doctor / sync all resolve their project the same way: they honour BASALT_CWD, and\nrelocate to the single package below the cwd carrying a basalt config when invoked from a repo\nroot that has none \u2014 several carrying one is ambiguous and exits 1 in ALL THREE.\n--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")) {
@@ -2032,7 +2256,10 @@ function run(argv, cwd = process.cwd()) {
         mergeLint: flags.includes("--merge-lint")
       });
     case "sync":
-      return sync({ force: flags.includes("--force"), check: flags.includes("--check") }, cwd);
+      return sync(
+        { force: flags.includes("--force"), check: flags.includes("--check"), flags },
+        cwd
+      );
     case "check-theme":
       return checkTheme(cwd, flags);
     case "check-coverage":

package/dist/cli/shipped-versions.test.d.ts

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

package/dist/cli/shipped-versions.test.d.ts.map

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

package/dist/guard/index.d.ts

@@ -28,6 +28,17 @@ export type UnmatchedExemptPattern = {
  * 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 oxlint plugin's rule ids. Not guard kinds — they can never suppress a `checkSource` finding —
+ * but they ARE valid ids in a `theme-allow`, so an annotation scoped to one of them must parse as
+ * accountable rather than be reported as unscoped. Kept as a literal list because the plugin is a
+ * standalone `.js` file this module must not import (see the plugin's own header).
+ *
+ * Exported for `check-theme --audit-allows`: an annotation naming one of these is outside the
+ * guard's reach, and judging it needs a `oxlint` run rather than a `checkSource` one. Keep in step
+ * with the plugin's own `KNOWN_RULE_IDS`; `configs/oxlint-plugin.test.ts` asserts the two agree.
+ */
+export declare const PLUGIN_RULE_IDS: ReadonlySet<string>;
 /**
  * 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`
@@ -262,4 +273,60 @@ export declare function guardWaiverHint(relPath: string): string;
  * if (findings.some((f) => f.kind === 'raw-hex')) { ... }
  */
 export declare function checkSource(text: string, relPath: string, cfg: GuardConfig): Finding[];
+/**
+ * One `theme-allow` annotation as WRITTEN, classified by whose reach its ids fall in.
+ *
+ * `guardKinds` is what `checkSource` can judge by re-running itself with the annotation
+ * neutralized. `pluginRules` is what only an `oxlint` run can judge. `unknownRules` names no rule
+ * at all. All three empty with `bare: true` is the legacy blanket form.
+ */
+export type AllowAnnotationSite = {
+    /** 1-based line the annotation is written on. */
+    readonly line: number;
+    /** `'file'` for the `theme-allow-file` declaration form, `'line'` otherwise. */
+    readonly scope: 'line' | 'file';
+    /** Every id the annotation names that resolves to a real rule, `basalt/` prefix stripped. */
+    readonly rules: readonly string[];
+    /** The subset of `rules` `checkSource` owns. */
+    readonly guardKinds: readonly GuardKind[];
+    /** The subset of `rules` the oxlint plugin owns — outside `checkSource`'s reach. */
+    readonly pluginRules: readonly string[];
+    /** Words that occupied the id slot but name no rule. Their presence makes the parse fail closed. */
+    readonly unknownRules: readonly string[];
+    /** A written reason follows the ids. */
+    readonly hasReason: boolean;
+    /** The legacy blanket form — no ids at all, known or unknown. Only covers anything at line scope. */
+    readonly bare: boolean;
+    /** The source line, verbatim. */
+    readonly text: string;
+};
+/**
+ * Every allow annotation in one file, with the ids it names classified by reach.
+ *
+ * Pure, and it shares `collectAllowAnnotations` with {@link checkSource} — so a caller enumerating
+ * annotations sees exactly the set the scan honours, rather than a second regex that can drift from
+ * it. `--audit-allows` carried such a mirror and it was already one alternation behind.
+ *
+ * A file-scoped declaration appears once, at the line it is written on.
+ *
+ * @example
+ * for (const site of findAllowAnnotations(text, rel, cfg)) {
+ *   if (site.pluginRules.length > 0) probeWithOxlint(neutralizeAllowAnnotation(text, site.line, cfg))
+ * }
+ */
+export declare function findAllowAnnotations(text: string, relPath: string, cfg: GuardConfig): AllowAnnotationSite[];
+/** The token a neutralized annotation is rewritten to. Shares no substring with `theme-allow`. */
+export declare const NEUTRALIZED_ALLOW_TOKEN = "basalt-audit-neutralized";
+/**
+ * `text` with the allow token on ONE (1-based) line rewritten to {@link NEUTRALIZED_ALLOW_TOKEN},
+ * leaving every other annotation intact.
+ *
+ * The probe half of an audit: re-scan the result and the findings that appear are exactly what that
+ * one annotation suppresses. Shipped rather than left to each caller so the guard probe and the
+ * oxlint probe neutralize identically — a `--audit-allows` verdict that differs between the two
+ * halves by a substitution detail is worse than no verdict.
+ *
+ * A line with no token comes back unchanged.
+ */
+export declare function neutralizeAllowAnnotation(text: string, line: number, cfg: GuardConfig): string;
 //# sourceMappingURL=index.d.ts.map

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;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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guard/index.ts"],"names":[],"mappings":"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"}