basalt-ui 1.21.0 → 1.22.0

package/configs/oxlint-plugin.test.ts

@@ -44,6 +44,13 @@ beforeEach(() => {
       },
     }),
   )
+  // `shadow-basalt-export` and `ai-sdk-major` both scope through `isBasaltScopedFile`, so a fixture
+  // repo with NO manifest is out of scope for both and every other assertion here would pass
+  // vacuously. Written per-test by the `ai-sdk-major` block, which needs its own `ai` pin.
+  writeFileSync(
+    resolve(dir, 'package.json'),
+    JSON.stringify({ name: 'fixture', version: '0.0.0', dependencies: { 'basalt-ui': '^1.21.0' } }),
+  )
 })
 
 afterEach(() => {
@@ -918,6 +925,115 @@ describe('basalt/shadow-basalt-export', () => {
     expect(code).toBe(0)
     expect(rules).not.toContain('shadow-basalt-export')
   })
+
+  // The scoping fix, mirroring `ai-sdk-major`'s. obsidian's `packages/obsidian-vault-core` is
+  // React-free, carries no basalt-ui dependency, and sits outside the root's declared
+  // `basalt.roots` — so it CANNOT import the export it was told it had forked. The rule reported
+  // `SlugTracker` there anyway, because it was the one rule in this file that never asked.
+  it('does NOT flag a package that does not depend on basalt-ui at all', () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ name: 'standalone' }))
+    const { code, rules } = run(`export function EmptyState() { return null }\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('shadow-basalt-export')
+  })
+
+  it('does NOT flag a file outside a declared basalt.roots', () => {
+    writeFileSync(
+      resolve(dir, 'package.json'),
+      JSON.stringify({
+        basalt: { roots: ['packages/ui/src'] },
+        devDependencies: { 'basalt-ui': '^1.21.0' },
+      }),
+    )
+    expect(
+      run(`export function EmptyState() { return null }\n`, 'packages/core/src/a.tsx').rules,
+    ).not.toContain('shadow-basalt-export')
+    // …and the declared root is still policed, so the narrowing costs no real coverage.
+    expect(
+      run(`export function EmptyState() { return null }\n`, 'packages/ui/src/a.tsx').rules,
+    ).toContain('shadow-basalt-export')
+  })
+
+  // The second half: a PascalCase name is not a component. The nine-barrel widening pulled every
+  // PascalCase value export into range, and a bare-PascalCase test then matched a plain data class
+  // (obsidian's `SlugTracker` — the same NAME basalt's `./content` exports, and nothing else).
+  it('does NOT flag a plain class that merely shares a name', () => {
+    const { code, rules } = run(`export class SlugTracker {}\n`, 'slug.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('shadow-basalt-export')
+  })
+
+  it('DOES still flag a legacy class component (one that extends)', () => {
+    const { rules } = run(`export class EmptyState extends Component {}\n`)
+    expect(rules).toContain('shadow-basalt-export')
+  })
+
+  it('does NOT flag a non-function binding that shares a name', () => {
+    const { code, rules } = run(`export const EmptyState = { label: 'none' }\n`, 'consts.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('shadow-basalt-export')
+  })
+
+  it('DOES still flag a memo/forwardRef-wrapped component', () => {
+    expect(run(`export const EmptyState = memo(() => null)\n`).rules).toContain(
+      'shadow-basalt-export',
+    )
+    expect(run(`export const EmptyState = React.forwardRef(() => null)\n`).rules).toContain(
+      'shadow-basalt-export',
+    )
+  })
+})
+
+// ── theme-allow comment shapes (the plugin half of the annotation contract) ───
+
+// The prefix rule has had three holes found in three rounds, so every comment shape a consumer
+// actually writes is pinned here — and the guard's copy is pinned identically in
+// `src/guard/check-source.test.ts`. The two must agree on what an annotation IS.
+describe('theme-allow comment shapes', () => {
+  const flags = (source: string): boolean => run(source).rules.has('no-raw-font-size')
+
+  it.each([
+    [
+      'own line //',
+      `// theme-allow no-raw-font-size — deliberate\nexport const C = <Text fz={10} />\n`,
+    ],
+    [
+      'trailing //',
+      `export const C = <Text fz={10} /> // theme-allow no-raw-font-size — deliberate\n`,
+    ],
+    [
+      'trailing block',
+      `export const C = <Text fz={10} /* theme-allow no-raw-font-size — deliberate */ />\n`,
+    ],
+    [
+      'JSX expression comment',
+      `export const C = () => (\n  <div>\n    {/* theme-allow no-raw-font-size — deliberate */}\n    <Text fz={10} />\n  </div>\n)\n`,
+    ],
+    [
+      'JSX expression comment, token on its own wrapped line',
+      `export const C = () => (\n  <div>\n    {/*\n      theme-allow no-raw-font-size — deliberate */}\n    <Text fz={10} />\n  </div>\n)\n`,
+    ],
+    [
+      'block gutter',
+      `/**\n * theme-allow no-raw-font-size — deliberate\n */\nexport const C = <Text fz={10} />\n`,
+    ],
+    [
+      'docblock opener',
+      `/** theme-allow no-raw-font-size — deliberate */\nexport const C = <Text fz={10} />\n`,
+    ],
+  ])('%s waives', (_name, source) => {
+    expect(flags(source as string)).toBe(false)
+  })
+
+  // The false NEGATIVE the prefix rule exists to close: prose that MENTIONS the token is not an
+  // annotation. linewatch documented its own waivers in a docblock and disarmed the file.
+  it('prose that merely mentions the token does not waive', () => {
+    expect(
+      flags(
+        `// each chart here needs a theme-allow no-raw-font-size eventually\nexport const C = <Text fz={10} />\n`,
+      ),
+    ).toBe(true)
+  })
 })
 
 // ── hand-rolled-shell ────────────────────────────────────────────────────────

package/dist/cli/index.d.ts

@@ -358,8 +358,14 @@ type SyncOptions = {
  * - `--check` makes NO writes; exits non-zero if any managed file is out-of-date or locally drifted
  *   (a CI freshness gate), exit 0 when all current.
  * - `--force` overwrites locally-drifted files instead of skipping them.
+ *
+ * Runs against `resolveProjectDir(cwd)`, exactly as `check-theme` and `doctor` do — and then
+ * REFUSES rather than scaffolding when the resolved project has no manifest. See
+ * {@link findManifestAbove} for the failure that bought this: `sync` is the drift refresh and
+ * `init` is the scaffold, so placing twenty files on a cwd that was never a consumer is a decision
+ * `sync` does not get to make silently.
  */
-export declare function sync(opts?: SyncOptions, cwd?: string): number;
+export declare function sync(opts?: SyncOptions, invocationCwd?: string): number;
 /**
  * Assert the 8 SURFACES invariants against the live SURFACES + GUARD_RULES + plugin.json.
  * Returns 0 when all pass; 1 when any fail (console.error each failure).

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

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

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";
@@ -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(
@@ -329,7 +339,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 +350,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 +444,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,30 +457,59 @@ 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);
@@ -452,7 +563,10 @@ 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).`
+  );
+  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(
@@ -969,6 +1083,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,7 +1277,37 @@ 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);
@@ -1140,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;
@@ -1151,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;
     }
@@ -1172,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(
@@ -1222,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):");
@@ -1630,22 +1810,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)) {

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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"}