basalt-ui 1.28.0 → 1.29.1

package/dist/cli/audit-allows.d.ts

@@ -0,0 +1,24 @@
+import type { GuardConfig } from '../guard/index.js';
+import type { BasaltConfig } from './index.js';
+/**
+ * `check-theme --audit-allows` — list every active waiver and prove, per waiver, whether it still
+ * suppresses anything.
+ *
+ * The accountability release shipped `theme-allow-unscoped`, which reports a waiver that names no
+ * rule — but a waiver that is perfectly well written and covers a finding that no longer exists is
+ * invisible to it, and to everything else. Two consumers found five of those by hand, by editing
+ * the token out and re-running the guard. This is that method, automated: for each annotation the
+ * file is re-checked with THAT occurrence neutralized, and the findings that appear are exactly
+ * what it suppresses. Nothing is inferred from the annotation's text, so the audit cannot disagree
+ * with the scan — it IS the scan, run twice.
+ *
+ * `basalt.exemptRules` entries are audited the same way, one pattern at a time. That also answers
+ * the question the key could never answer for itself: a pattern that matches no scanned file (a
+ * real relative path, say, where the matcher takes whole path SEGMENTS) suppresses nothing and is
+ * reported as dead rather than passing silently.
+ *
+ * Exit 1 when anything is dead, so it can be wired into CI as a gate. A waiver nobody re-checks is
+ * how a rule quietly stops applying to the file that needed the exception most.
+ */
+export declare function auditAllows(cwd: string, cfg: BasaltConfig, guardCfg: GuardConfig, scanned: string[]): number;
+//# sourceMappingURL=audit-allows.d.ts.map

package/dist/cli/audit-allows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-allows.d.ts","sourceRoot":"","sources":["../../src/cli/audit-allows.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAW,WAAW,EAAa,MAAM,UAAU,CAAA;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAmB,MAAM,SAAS,CAAA;AAqJ5D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,MAAM,EAAE,GAChB,MAAM,CAqLR"}

package/dist/cli/audit-allows.js

@@ -0,0 +1,240 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  checkSource,
+  findAllowAnnotations,
+  neutralizeAllowAnnotation,
+  unmatchedExemptPatterns
+} from "../guard/index.js";
+import { exemptRulePaths, exemptRuleReason, resolveRoots } from "./index.js";
+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 run = spawnSync(bin, ["--format=json", "--no-error-on-unmatched-pattern", ...targets], {
+      cwd,
+      encoding: "utf8",
+      timeout: 12e4,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    if (run.error !== void 0 || typeof run.stdout !== "string") return null;
+    let diagnostics;
+    try {
+      diagnostics = JSON.parse(run.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).`
+  );
+  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(
+      "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;
+}
+export {
+  auditAllows
+};

package/dist/cli/check-theme.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Theme guard — thin FS walker over the headless `../guard` core. Reads BasaltConfig, builds a
+ * GuardConfig, walks roots, calls checkSource per file, collects Finding[], groups/reports, returns
+ * 0 (clean) / 1 (violations). A `theme-allow` comment exempts a line.
+ *
+ * Runs against `resolveProjectDir(cwd)`, not `cwd` — see that type's doc for why a root-invoked
+ * hook or CI step has to find the package the config lives in rather than scan nothing and pass.
+ */
+export declare function checkTheme(invocationCwd?: string, flags?: readonly string[]): number;
+//# sourceMappingURL=check-theme.d.ts.map

package/dist/cli/check-theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-theme.d.ts","sourceRoot":"","sources":["../../src/cli/check-theme.ts"],"names":[],"mappings":"AA8BA;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,aAAa,GAAE,MAAsB,EACrC,KAAK,GAAE,SAAS,MAAM,EAAO,GAC5B,MAAM,CA2JR"}

package/dist/cli/check-theme.js

@@ -0,0 +1,139 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  checkSource,
+  DEFAULT_GUARD_CONFIG,
+  guardKindRemedy,
+  TOKENS_ONLY_DISABLED_KINDS,
+  unmatchedExemptPatterns
+} from "../guard/index.js";
+import { auditAllows } from "./audit-allows.js";
+import {
+  conflictingProfileFlags,
+  declaredProfile,
+  DEFAULT_ROOTS,
+  readBasaltConfig,
+  resolveExemptRules,
+  resolveProjectDir,
+  resolveRoots,
+  scannableFiles,
+  SERIES_MODULE_HINT_RE,
+  waiverHintFor
+} from "./index.js";
+function checkTheme(invocationCwd = process.cwd(), flags = []) {
+  if (conflictingProfileFlags(flags)) {
+    console.error(
+      "basalt-ui check-theme: --tokens-only and --framework are alternatives \u2014 pass one."
+    );
+    return 1;
+  }
+  const project = resolveProjectDir(invocationCwd);
+  const cwd = project.dir;
+  if (project.relocatedFrom !== null) {
+    console.log(
+      `basalt-ui check-theme: BASALT_CWD relocated from ${project.relocatedFrom} to ${cwd}.`
+    );
+  }
+  const cfg = readBasaltConfig(cwd);
+  const roots = resolveRoots(cfg);
+  const profile = declaredProfile(cfg, flags);
+  if (profile === "tokens-only") {
+    console.log(
+      `basalt-ui check-theme: tokens-only profile \u2014 ${TOKENS_ONLY_DISABLED_KINDS.size} Mantine-coupled kinds are off; the color and typography kinds still apply. Pass --framework to force the full set.`
+    );
+  }
+  const guardCfg = {
+    spacingSteps: cfg.spacingSteps ?? DEFAULT_GUARD_CONFIG.spacingSteps,
+    rawRadius: cfg.rawRadius ?? DEFAULT_GUARD_CONFIG.rawRadius,
+    forbiddenAccents: cfg.forbiddenAccents ?? DEFAULT_GUARD_CONFIG.forbiddenAccents,
+    mantineShadeIndex: cfg.mantineShadeIndex ?? DEFAULT_GUARD_CONFIG.mantineShadeIndex,
+    rawSurface: cfg.rawSurface ?? DEFAULT_GUARD_CONFIG.rawSurface,
+    cardWithBorder: cfg.cardWithBorder ?? DEFAULT_GUARD_CONFIG.cardWithBorder,
+    offSystemSurfaceVar: cfg.offSystemSurfaceVar ?? DEFAULT_GUARD_CONFIG.offSystemSurfaceVar,
+    rawHtmlLayout: cfg.rawHtmlLayout ?? DEFAULT_GUARD_CONFIG.rawHtmlLayout,
+    inlineSpacing: cfg.inlineSpacing ?? DEFAULT_GUARD_CONFIG.inlineSpacing,
+    inlineDisplay: cfg.inlineDisplay ?? DEFAULT_GUARD_CONFIG.inlineDisplay,
+    rawVisxAxis: cfg.rawVisxAxis ?? DEFAULT_GUARD_CONFIG.rawVisxAxis,
+    rawMotionValue: cfg.rawMotionValue ?? DEFAULT_GUARD_CONFIG.rawMotionValue,
+    chartMissingAriaLabel: cfg.chartMissingAriaLabel ?? DEFAULT_GUARD_CONFIG.chartMissingAriaLabel,
+    rawFormControl: cfg.rawFormControl ?? DEFAULT_GUARD_CONFIG.rawFormControl,
+    sub16InputFont: cfg.sub16InputFont ?? DEFAULT_GUARD_CONFIG.sub16InputFont,
+    allowComment: "theme-allow",
+    exemptRules: resolveExemptRules(cfg),
+    severity: cfg.severity ?? DEFAULT_GUARD_CONFIG.severity,
+    ...profile === "tokens-only" ? { profile: "tokens-only" } : {}
+  };
+  const findings = [];
+  const scanned = scannableFiles(cwd, cfg);
+  for (const rel of scanned) {
+    findings.push(...checkSource(readFileSync(resolve(cwd, rel), "utf8"), rel, guardCfg));
+  }
+  if (scanned.length === 0) {
+    if (cfg.roots === void 0) {
+      console.error(
+        `\u2716 basalt-ui check-theme: 0 files scanned \u2014 no "basalt.roots" configured in package.json, and the built-in default roots (${DEFAULT_ROOTS.join(", ")}) matched zero files. Set "basalt": { "roots": [...] } in package.json to point at your source directories.`
+      );
+    } else {
+      console.error(
+        `\u2716 basalt-ui check-theme: 0 files scanned \u2014 the configured "basalt.roots" (${roots.join(", ")}) matched zero files. Check the paths in "basalt.roots" in package.json.`
+      );
+    }
+    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;
+  }
+  const errors = findings.filter((f) => f.severity === "error");
+  const warnings = findings.filter((f) => f.severity === "warn");
+  const report = (group, heading) => {
+    const byFile = /* @__PURE__ */ new Map();
+    for (const f of group) {
+      const list = byFile.get(f.relPath) ?? [];
+      list.push(f);
+      byFile.set(f.relPath, list);
+    }
+    console.error(heading);
+    for (const [file, vs] of [...byFile].toSorted()) {
+      console.error(file);
+      for (const v of vs.toSorted((a, b) => a.line - b.line)) {
+        console.error(`  ${String(v.line).padStart(4)}  ${v.kind.padEnd(22)} ${v.text}`);
+      }
+      console.error("");
+    }
+  };
+  if (warnings.length > 0) {
+    report(
+      warnings,
+      // Deliberately neutral about WHY a kind is a warning. Two origins reach this block — a kind
+      // in its grace minor, and a consumer's own `basalt.severity` override — and the finding
+      // doesn't carry which. Promising promotion next minor would be wrong for the second.
+      `\u26A0 Theme guard: ${warnings.length} warning(s) \u2014 reported, not fatal. A kind warns while it is in its grace minor, or because \`basalt.severity\` turned it down; fix on your own schedule.
+`
+    );
+  }
+  if (errors.length > 0) {
+    report(errors, `\u2716 Theme guard: ${errors.length} off-palette / off-identity violation(s)
+`);
+  }
+  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.'
+    );
+  }
+  return errors.length > 0 ? 1 : 0;
+}
+export {
+  checkTheme
+};

package/dist/cli/doctor.d.ts

@@ -0,0 +1,47 @@
+export type DoctorResult = {
+    /** Number of hard failures (exit non-zero). */
+    hardFailures: number;
+    /** Number of warnings (informational only). */
+    warnings: number;
+    /**
+     * Number of checks that could not RUN (as opposed to ran and passed). Counted separately and
+     * exits non-zero on its own: under bun's isolated linker `doctor` used to drop two of its five
+     * checks and still print "All checks passed", which is the same false-green this whole surface
+     * exists to remove. A check that cannot run is not a check that passed.
+     */
+    skipped: number;
+};
+/**
+ * Check a consumer repo's basalt integration and print a pass/warn report.
+ *
+ * Narrowed to what a single-directory-scoped run can actually verify — no workspace-glob walking,
+ * no ascend/descend project discovery (see {@link resolveProjectDir}). Four checks, numbered in
+ * the order they run and print:
+ *
+ * Hard failures (exit non-zero):
+ *   1. `.basalt/manifest.json` exists (`basalt-ui init` was run).
+ *   2. `oxlint-preset` ("rules in sync"): the consumer's `.oxlintrc.json` extends the shipped
+ *      preset AND that path resolves. `init` keeps an existing config, so the framework's whole
+ *      lint half can be silently off — one repo carried six real violations invisibly across five
+ *      minors this way.
+ *   4. `ai-major-parity`: within THIS package.json, `dependencies`/`devDependencies`/
+ *      `peerDependencies` agree on the `ai` package's major. `basalt/ai-sdk-major` (the oxlint
+ *      plugin rule) already catches this per linted FILE against its nearest package.json; this
+ *      check exists for the shape a lint run cannot see — a package whose own manifest asks its
+ *      dependents for one major while it itself runs another. A detected skew is exempt-able via
+ *      `basalt.aiMajorSkewReason` (a non-empty reason string, not a bare `true`); missing or
+ *      invalid still hard-fails as if the key were absent. A declared reason when the majors
+ *      already agree warns that the exemption is stale.
+ *
+ * Warning (non-fatal):
+ *   3. `lefthook-preset` ("lefthook wired"): a pre-commit command runs `check-theme`, read from
+ *      `lefthook dump --format json` (resolves `extends`/`include`/`root:` the way lefthook itself
+ *      does — see {@link inspectLefthookGate}). No lefthook config at all is a pass (a consumer may
+ *      gate elsewhere); a config that resolves but wires no guard command warns; a config lefthook
+ *      dump could not read at all (binary missing, or the dump failed) warns and says so, rather
+ *      than inventing a verdict.
+ *
+ * Returns the exit code: 0 = all good, 1 = one or more hard failures.
+ */
+export declare function doctor(invocationCwd?: string, flags?: string[]): number;
+//# sourceMappingURL=doctor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AA0BA,MAAM,MAAM,YAAY,GAAG;IACzB,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAA;IACpB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AA8DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,MAAM,CAAC,aAAa,GAAE,MAAsB,EAAE,KAAK,GAAE,MAAM,EAAO,GAAG,MAAM,CAsM1F"}

package/dist/cli/doctor.js

@@ -0,0 +1,197 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  MANIFEST_PATH,
+  basaltBinCommand,
+  basaltPresetEntry,
+  conflictingProfileFlags,
+  declaredProfile,
+  findBasaltInstall,
+  findRepoRoot,
+  inspectLefthookGate,
+  parseJsonc,
+  readBasaltConfig,
+  readIfExists,
+  resolveProjectDir,
+  shippedAssetPath
+} from "./index.js";
+import { findManifestAbove, parentInstallAdvice } from "./sync.js";
+function majorOf(range) {
+  if (typeof range !== "string") return null;
+  const match = range.match(/\d+/);
+  return match === null ? null : Number(match[0]);
+}
+const AI_MAJOR_FIELDS = ["dependencies", "devDependencies", "peerDependencies"];
+function aiMajorsAt(dir) {
+  const raw = readIfExists(resolve(dir, "package.json"));
+  if (raw === null) return {};
+  try {
+    const pkg = JSON.parse(raw);
+    const out = {};
+    for (const field of AI_MAJOR_FIELDS) {
+      const major = majorOf(pkg[field]?.["ai"]);
+      if (major !== null) out[field] = major;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+function resolveAiMajorSkewReason(cfg) {
+  const raw = cfg.aiMajorSkewReason;
+  if (raw === void 0) return { reason: null, presentButInvalid: false };
+  if (typeof raw === "string" && raw.trim().length > 0) {
+    return { reason: raw, presentButInvalid: false };
+  }
+  return { reason: null, presentButInvalid: true };
+}
+function doctor(invocationCwd = process.cwd(), flags = []) {
+  if (conflictingProfileFlags(flags)) {
+    console.error("basalt-ui doctor: --tokens-only and --framework are alternatives \u2014 pass one.");
+    return 1;
+  }
+  const project = resolveProjectDir(invocationCwd);
+  const cwd = project.dir;
+  const cfg = readBasaltConfig(cwd);
+  const result = { hardFailures: 0, warnings: 0, skipped: 0 };
+  const lines = [`
+basalt-ui doctor \u2014 ${cwd}
+`];
+  function pass(msg) {
+    lines.push(`  \u2713 ${msg}`);
+  }
+  function warn(msg) {
+    lines.push(`  \u26A0 ${msg}`);
+    result.warnings++;
+  }
+  function fail(msg) {
+    lines.push(`  \u2716 ${msg}`);
+    result.hardFailures++;
+  }
+  if (project.relocatedFrom !== null) {
+    lines.push(`  \u2192 BASALT_CWD relocated from ${project.relocatedFrom} to ${cwd}.
+`);
+  }
+  const profile = declaredProfile(cfg, flags);
+  if (profile === "tokens-only") {
+    lines.push(
+      "  profile: tokens-only \u2014 checking the token layer only. `basalt-ui init` is NOT the fix\n  here, it places a Mantine doctrine you have no use for. Pass --framework to force the\n  full profile.\n"
+    );
+  }
+  const manifestAbs = resolve(cwd, MANIFEST_PATH);
+  const manifestExists = existsSync(manifestAbs);
+  const parentInstall = manifestExists ? null : findManifestAbove(cwd);
+  if (profile === "tokens-only") {
+    pass(`${MANIFEST_PATH}: n/a \u2014 a tokens-only consumer has no scaffold to reconcile`);
+  } else if (manifestExists) {
+    pass(`${MANIFEST_PATH} exists`);
+  } else if (parentInstall !== null) {
+    fail(
+      `${MANIFEST_PATH} missing here, but this is not an unscaffolded consumer. ${parentInstallAdvice(cwd, parentInstall, "doctor")} \`basalt-ui init\` is NOT the fix: it would scaffold a SECOND consumer beside the real one.`
+    );
+  } else {
+    fail(`${MANIFEST_PATH} missing \u2014 run \`basalt-ui init\` to scaffold the consumer repo`);
+  }
+  const install = findBasaltInstall(cwd);
+  if (profile === "tokens-only") {
+    pass("oxlint-preset: n/a \u2014 the shipped preset is a Mantine/React preset");
+  } else {
+    const oxlintrcRaw = readIfExists(resolve(cwd, ".oxlintrc.json"));
+    if (oxlintrcRaw === null) {
+      fail(
+        ".oxlintrc.json missing \u2014 the shipped oxlint preset (the basalt/* design rules) is not active. " + (parentInstall === null ? "Run `basalt-ui init` to seed it." : `${parentInstallAdvice(cwd, parentInstall, "doctor")} The preset is seeded once, at the install \u2014 not per package.`)
+      );
+    } else {
+      const parsed = parseJsonc(oxlintrcRaw);
+      if (parsed === null) {
+        fail(
+          ".oxlintrc.json does not parse as JSON/JSONC \u2014 cannot tell whether it extends the preset"
+        );
+      } else {
+        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))) {
+          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 === "wired") {
+    pass(`${lefthookGate.file}: \`lefthook dump\` shows a pre-commit command running check-theme.`);
+  } 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. Add "extends: [${lefthookCorrect}]", or your own command running \`${basaltBinCommand(install, cwd)} check-theme\`.`
+    );
+  } else {
+    warn(
+      `${lefthookGate.file}: \`lefthook dump\` could not be run or parsed here (lefthook may not be installed) \u2014 treat this check as advisory. Verify by running \`lefthook dump\` yourself.`
+    );
+  }
+  const aiMajors = aiMajorsAt(cwd);
+  const aiEntries = AI_MAJOR_FIELDS.filter((field) => aiMajors[field] !== void 0).map(
+    (field) => ({ field, major: aiMajors[field] })
+  );
+  const { reason: aiMajorSkewReason, presentButInvalid: aiMajorSkewReasonInvalid } = resolveAiMajorSkewReason(cfg);
+  if (aiEntries.length > 0) {
+    const distinctMajors = new Set(aiEntries.map((entry) => entry.major));
+    if (distinctMajors.size > 1) {
+      const summary = aiEntries.map((entry) => `${entry.field}@ai${entry.major}`).join(", ");
+      if (aiMajorSkewReason !== null) {
+        pass(
+          `ai package major version mismatch within this package.json: ${summary} \u2014 exempted via basalt.aiMajorSkewReason: "${aiMajorSkewReason}"`
+        );
+      } else if (aiMajorSkewReasonInvalid) {
+        fail(
+          `ai package major version mismatch within this package.json: ${summary} \u2014 basalt.aiMajorSkewReason is present but is not a non-empty string (a bare \`true\` is not accepted); the exemption must carry a written reason.`
+        );
+      } else {
+        fail(`ai package major version mismatch within this package.json: ${summary}`);
+      }
+    } else {
+      const [major] = distinctMajors;
+      if (aiMajorSkewReason !== null) {
+        warn(
+          `basalt.aiMajorSkewReason ("${aiMajorSkewReason}") is declared but the ai package major already agrees within this package.json (ai@${major}) \u2014 the exemption is no longer needed and can be deleted.`
+        );
+      } else {
+        pass(`ai package major is consistent within this package.json (ai@${major})`);
+      }
+    }
+  } else {
+    pass("ai-major-parity: this package.json declares no ai dependency \u2014 nothing to compare");
+  }
+  lines.push("");
+  if (result.hardFailures === 0 && result.warnings === 0) {
+    lines.push("All checks passed.");
+  } else {
+    const parts = [];
+    if (result.hardFailures > 0) parts.push(`${result.hardFailures} hard failure(s)`);
+    parts.push(`${result.warnings} warning(s)`);
+    lines.push(`${parts.join(", ")}.`);
+  }
+  lines.push("");
+  if (result.hardFailures > 0) {
+    console.error(lines.join("\n"));
+    return 1;
+  }
+  console.log(lines.join("\n"));
+  return 0;
+}
+export {
+  doctor
+};