tempest-react-sdk 0.26.1 → 0.28.0

package/bin/lib/doctor/doctor.e2e.test.mjs

@@ -0,0 +1,246 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+const CLI = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "tempest.mjs");
+
+let root;
+
+beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "tempest-doctor-"));
+});
+
+afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+});
+
+/** Write a file under the fixture, creating parent directories. */
+function write(rel, contents) {
+    const path = join(root, rel);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, typeof contents === "string" ? contents : JSON.stringify(contents));
+}
+
+/** Fake an installed package so `installedVersion` finds it. */
+function installed(name, version, extra = {}) {
+    write(`node_modules/${name}/package.json`, { name, version, ...extra });
+}
+
+/**
+ * Run the real CLI in the fixture directory.
+ *
+ * A subprocess rather than an imported function on purpose: `doctor` reads
+ * `process.cwd()` and reports through the exit code, and the exit code is the part
+ * that matters most — it decides whether a project "fails" the audit. Only running
+ * it the way a user does tests that.
+ */
+function doctor() {
+    const result = spawnSync(process.execPath, [CLI, "doctor"], {
+        cwd: root,
+        encoding: "utf8",
+        env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: "0" },
+    });
+    return { code: result.status, out: `${result.stdout}${result.stderr}` };
+}
+
+/** A plain, healthy React + Vite app that has never heard of the SDK. */
+function thirdPartyApp() {
+    write("package.json", {
+        name: "app-de-terceiro",
+        type: "module",
+        dependencies: { react: "^19.0.0", "react-dom": "^19.0.0" },
+        devDependencies: { vite: "^7.0.0", "@vitejs/plugin-react": "^5.0.0", eslint: "^9.0.0" },
+    });
+    write("tsconfig.json", {
+        compilerOptions: { strict: true, jsx: "react-jsx", moduleResolution: "bundler" },
+    });
+    write(
+        "vite.config.ts",
+        'import { defineConfig } from "vite";\nexport default defineConfig({});',
+    );
+    write("src/App.tsx", "export const App = () => null;");
+    write("package-lock.json", "{}");
+    write("eslint.config.js", "export default [];");
+    installed("react", "19.0.0");
+    installed("react-dom", "19.0.0");
+    installed("vite", "7.0.0");
+    installed("@vitejs/plugin-react", "5.0.0");
+    installed("eslint", "9.0.0");
+    installed("prettier", "3.0.0");
+    installed(".bin/eslint", "0.0.0");
+}
+
+describe("tempest doctor — a third-party project that does not use the SDK", () => {
+    beforeEach(thirdPartyApp);
+
+    it("does not fail the audit just for not having the SDK", () => {
+        const { code, out } = doctor();
+        expect(out).toContain("tempest-react-sdk not installed");
+        expect(out).toContain("generic React/Vite health only");
+        expect(code).toBe(0);
+    });
+
+    it("never reports the missing SDK as a problem", () => {
+        const { out } = doctor();
+        expect(out).not.toMatch(/✗.*tempest-react-sdk/);
+    });
+
+    it("drops the SDK's own conventions from the report", () => {
+        const { out } = doctor();
+        // The `@/*` alias and `createViteConfig` are preferences, not health.
+        expect(out).not.toContain('tsconfig "@/*" alias');
+        expect(out).not.toContain("not using createViteConfig");
+        // The stylesheet is only *demanded* of an SDK project; the adoption hint at
+        // the end still mentions it, which is the point of that section.
+        expect(out).not.toContain('add import "tempest-react-sdk/styles.css"');
+    });
+
+    it("does not demand a src/main.tsx it has no reason to expect", () => {
+        const { out } = doctor();
+        expect(out).not.toContain("app entry");
+    });
+
+    it("explains moduleResolution without naming SDK subpaths", () => {
+        write("tsconfig.json", { compilerOptions: { strict: true, jsx: "react-jsx" } });
+        const { out } = doctor();
+        expect(out).toContain("moduleResolution");
+        expect(out).not.toContain("tempest-react-sdk/br");
+        expect(out).toContain("subpath exports");
+    });
+
+    it("closes with how to adopt, so the audit is not a dead end", () => {
+        const { out } = doctor();
+        expect(out).toContain("Adopting the SDK (optional)");
+        expect(out).toContain("npm i tempest-react-sdk");
+        expect(out).toContain("not all-or-nothing");
+    });
+});
+
+describe("tempest doctor — generic findings still surface", () => {
+    it("flags a missing lockfile", () => {
+        thirdPartyApp();
+        rmSync(join(root, "package-lock.json"));
+        expect(doctor().out).toContain("no lockfile");
+    });
+
+    it("flags a missing @vitejs/plugin-react", () => {
+        thirdPartyApp();
+        rmSync(join(root, "node_modules", "@vitejs", "plugin-react"), {
+            recursive: true,
+            force: true,
+        });
+        expect(doctor().out).toContain("@vitejs/plugin-react");
+    });
+
+    it("flags declared dependencies that are not installed", () => {
+        thirdPartyApp();
+        rmSync(join(root, "node_modules", "react"), { recursive: true, force: true });
+        expect(doctor().out).toMatch(/dependency\(ies\) not installed/);
+    });
+
+    it("flags env vars that Vite will not expose", () => {
+        thirdPartyApp();
+        write("src/api.ts", "export const url = import.meta.env.API_URL;");
+        expect(doctor().out).toContain("client env without VITE_ prefix");
+    });
+
+    it("still fails on a genuinely broken project", () => {
+        write("package.json", { name: "broken", dependencies: {} });
+        const { code, out } = doctor();
+        expect(out).toContain("react + react-dom present");
+        expect(code).toBe(1);
+    });
+});
+
+describe("tempest doctor — stylesheets", () => {
+    beforeEach(thirdPartyApp);
+
+    it("says nothing about CSS in a project with no stylesheet", () => {
+        expect(doctor().out).not.toContain("Stylesheets");
+    });
+
+    it("reports a clean sheet as clean", () => {
+        write("src/app.css", ".a {\n    color: red;\n}\n");
+        const { out, code } = doctor();
+        expect(out).toContain("Stylesheets");
+        expect(out).toContain("no CSS problems found");
+        expect(code).toBe(0);
+    });
+
+    it("fails the audit on CSS the browser cannot parse", () => {
+        write("src/app.css", ".a {\n    color: red;\n");
+        const { out, code } = doctor();
+        expect(out).toContain("src/app.css:1");
+        expect(out).toContain("never closed");
+        expect(code).toBe(1);
+    });
+
+    it("warns without failing on CSS that is valid but wrong", () => {
+        write("src/app.css", ".a {\n    bacground-color: red;\n}\n");
+        const { out, code } = doctor();
+        expect(out).toContain("did you mean `background-color`");
+        expect(code).toBe(0);
+    });
+
+    it("points at the fix command when something is auto-fixable", () => {
+        write("src/app.css", ".a {\n    color: red;\n    color: red;\n}\n");
+        const { out } = doctor();
+        expect(out).toMatch(/finding\(s\) are auto-fixable/);
+    });
+
+    it("suggests one global class over repeated local copies", () => {
+        const row = ".row {\n    display: flex;\n    align-items: center;\n    gap: 8px;\n}\n";
+        write("src/A.module.css", row);
+        write("src/B.module.css", row);
+        write("src/C.module.css", row);
+        expect(doctor().out).toContain("one global class beats");
+    });
+});
+
+describe("tempest doctor — a project that does use the SDK", () => {
+    beforeEach(() => {
+        thirdPartyApp();
+        write("package.json", {
+            name: "sdk-app",
+            type: "module",
+            dependencies: {
+                "tempest-react-sdk": "^0.26.1",
+                react: "^19.0.0",
+                "react-dom": "^19.0.0",
+            },
+        });
+        installed("tempest-react-sdk", "0.26.1", { dependencies: { "lucide-react": "^1.26.0" } });
+        installed("lucide-react", "1.26.0");
+    });
+
+    it("checks the SDK's conventions again", () => {
+        write("tsconfig.json", {
+            compilerOptions: { strict: true, jsx: "react-jsx", moduleResolution: "bundler" },
+        });
+        const { out } = doctor();
+        expect(out).toContain('tsconfig "@/*" alias');
+    });
+
+    it("asks for the stylesheet import, which is a real defect without it", () => {
+        write("src/main.tsx", "export const main = 1;");
+        expect(doctor().out).toContain("styles.css");
+    });
+
+    it("omits the adoption hint — it has already adopted", () => {
+        expect(doctor().out).not.toContain("Adopting the SDK (optional)");
+    });
+
+    it("warns when the SDK is installed but undeclared", () => {
+        write("package.json", {
+            name: "sdk-app",
+            dependencies: { react: "^19.0.0", "react-dom": "^19.0.0" },
+        });
+        const { out, code } = doctor();
+        expect(out).toContain("tempest-react-sdk not in dependencies");
+        // Undeclared-but-present is a warning, not a blocking failure.
+        expect(code).toBe(0);
+    });
+});

package/bin/tempest.mjs

@@ -14,6 +14,7 @@ import { fileURLToPath } from "node:url";
 import { aliasImports } from "./lib/alias/index.mjs";
 import { loadTypeScript } from "./lib/alias/typescript.mjs";
 import { readTsconfig } from "./lib/alias/tsconfig.mjs";
+import { analyzeCss, applyCssFixes } from "./lib/css/index.mjs";
 import { checkLucide } from "./lib/doctor/lucide.mjs";
 import { generateRegistry, loadIconTables } from "./lib/icons/generate.mjs";
 import { generate } from "./lib/openapi/generate.mjs";
@@ -250,6 +251,74 @@ const STATEFUL_DEPS = [
     "react-router-dom",
 ];
 
+/**
+ * Doctor rows for the CSS analysis.
+ *
+ * Findings are capped per severity because a report nobody reads to the end is a
+ * report that hides its own first line. The cap is stated, and the pointer to the
+ * uncapped list (`tempest fix --dry-run`) goes with it — a silent truncation
+ * would read as "that is all of them".
+ *
+ * @param {number} [limit] - Findings shown per severity.
+ * @returns {Array<[status: string, label: string, detail?: string]>} Check rows.
+ */
+function cssChecks(limit = 6) {
+    let analysis;
+    try {
+        analysis = analyzeCss({ root: ROOT, targets: ["."], selfDir: SELF_DIR });
+    } catch (err) {
+        return [["warn", "CSS analysis failed", String(err?.message ?? err)]];
+    }
+    if (analysis.stats.files === 0) return [];
+
+    const rows = [["section", "Stylesheets"]];
+    rows.push([
+        "info",
+        `${analysis.stats.files} stylesheet(s) · ${analysis.stats.rules} rules · ${analysis.stats.declarations} declarations`,
+        analysis.tokens.source ? "" : "SDK token table not found — token checks skipped",
+    ]);
+    if (analysis.truncated) {
+        rows.push([
+            "info",
+            "file cap reached",
+            "only the first 600 stylesheets were analyzed — narrow the run with `tempest fix <path> --dry-run`",
+        ]);
+    }
+
+    const status = { error: "fail", warn: "warn", info: "info" };
+    let hidden = 0;
+    for (const severity of ["error", "warn", "info"]) {
+        const group = analysis.findings.filter((f) => f.severity === severity);
+        for (const f of group.slice(0, limit)) {
+            rows.push([status[severity], `${f.file}:${f.line}`, f.message]);
+        }
+        hidden += Math.max(0, group.length - limit);
+    }
+    if (hidden > 0) {
+        rows.push([
+            "info",
+            `${hidden} more CSS finding(s) not shown`,
+            "run `tempest fix --dry-run` for the full list",
+        ]);
+    }
+    if (analysis.findings.length === 0) {
+        rows.push(["ok", "no CSS problems found"]);
+    } else {
+        const fixable = analysis.findings.filter((f) => f.fixable).length;
+        if (fixable > 0) {
+            rows.push([
+                "info",
+                `${fixable} finding(s) are auto-fixable`,
+                "run `tempest fix` — it removes only what is provably dead",
+            ]);
+        }
+    }
+    for (const skip of analysis.skipped.slice(0, 3)) {
+        rows.push(["info", `skipped ${skip.file}`, skip.reason]);
+    }
+    return rows;
+}
+
 function doctor() {
     const checks = [];
     const pkg = readJSON(join(ROOT, "package.json"));
@@ -312,16 +381,45 @@ function doctor() {
     checks.push(["section", "Project"]);
     checks.push(["ok", "package.json found"]);
     const sdkInstalled = installedVersion("tempest-react-sdk");
-    checks.push(
-        deps["tempest-react-sdk"]
-            ? ["ok", "tempest-react-sdk in dependencies", deps["tempest-react-sdk"]]
-            : ["fail", "tempest-react-sdk in dependencies", "npm install tempest-react-sdk"],
-    );
-    checks.push(
-        sdkInstalled
-            ? ["ok", "tempest-react-sdk installed", `v${sdkInstalled}`]
-            : ["fail", "tempest-react-sdk installed", "run npm install"],
-    );
+
+    /**
+     * Whether this project has adopted the SDK.
+     *
+     * When it has not, `doctor` runs in **generic mode**: the checks that only make
+     * sense once you use the SDK (its `@/*` alias, `createViteConfig`, the
+     * `styles.css` import, its optional peers) drop out, and not having the SDK is
+     * reported as information rather than as a defect.
+     *
+     * Without this the tool is useless on the exact project it should help most —
+     * somebody's existing app, being evaluated. It reported two hard failures for the
+     * single fact "you have not installed this yet", exited non-zero, and buried the
+     * findings that *were* actionable (no lockfile, no plugin-react, no linter) among
+     * warnings that were really just the SDK's own conventions.
+     */
+    const usesSdk = Boolean(deps["tempest-react-sdk"] || sdkInstalled);
+
+    if (usesSdk) {
+        checks.push(
+            deps["tempest-react-sdk"]
+                ? ["ok", "tempest-react-sdk in dependencies", deps["tempest-react-sdk"]]
+                : [
+                      "warn",
+                      "tempest-react-sdk not in dependencies",
+                      `installed as v${sdkInstalled} but undeclared — add it to package.json`,
+                  ],
+        );
+        checks.push(
+            sdkInstalled
+                ? ["ok", "tempest-react-sdk installed", `v${sdkInstalled}`]
+                : ["fail", "tempest-react-sdk installed", "run npm install"],
+        );
+    } else {
+        checks.push([
+            "info",
+            "tempest-react-sdk not installed",
+            "checking generic React/Vite health only — `npm i tempest-react-sdk` to adopt it",
+        ]);
+    }
     const reactV = installedVersion("react");
     checks.push(
         deps.react && deps["react-dom"]
@@ -438,11 +536,15 @@ function doctor() {
     if (tsc) {
         checks.push(["section", "TypeScript"]);
         const co = tsc.compilerOptions;
-        checks.push(
-            co.paths?.["@/*"]
-                ? ["ok", 'tsconfig "@/*" alias']
-                : ["warn", 'tsconfig "@/*" alias', 'add "paths": { "@/*": ["./src/*"] }'],
-        );
+        // The `@/*` alias is the SDK's convention, not a health property: a project
+        // that has not adopted the SDK is not wrong for lacking it.
+        if (usesSdk) {
+            checks.push(
+                co.paths?.["@/*"]
+                    ? ["ok", 'tsconfig "@/*" alias']
+                    : ["warn", 'tsconfig "@/*" alias', 'add "paths": { "@/*": ["./src/*"] }'],
+            );
+        }
         const mr = String(co.moduleResolution ?? "").toLowerCase();
         checks.push(
             ["bundler", "node16", "nodenext"].includes(mr)
@@ -450,7 +552,9 @@ function doctor() {
                 : [
                       "warn",
                       `moduleResolution: ${co.moduleResolution ?? "(unset)"}`,
-                      'use "bundler" — otherwise subpath types (tempest-react-sdk/br, /charts…) won\'t resolve',
+                      usesSdk
+                          ? 'use "bundler" — otherwise subpath types (tempest-react-sdk/br, /charts…) won\'t resolve'
+                          : 'use "bundler" — a bundled app needs it for any package that ships subpath exports',
                   ],
         );
         checks.push(
@@ -491,11 +595,21 @@ function doctor() {
     if (!viteCfg) {
         checks.push(["warn", "vite config", "no vite.config.* found"]);
     } else {
-        checks.push(
-            fileIncludes(join(ROOT, viteCfg), "createViteConfig")
-                ? ["ok", `${viteCfg} uses createViteConfig`]
-                : ["warn", `${viteCfg}`, "not using createViteConfig from tempest-react-sdk/vite"],
-        );
+        // `createViteConfig` is a convenience, not a requirement — only worth
+        // mentioning to a project that already uses the SDK, and even then as info.
+        if (usesSdk) {
+            checks.push(
+                fileIncludes(join(ROOT, viteCfg), "createViteConfig")
+                    ? ["ok", `${viteCfg} uses createViteConfig`]
+                    : [
+                          "info",
+                          `${viteCfg}`,
+                          "not using createViteConfig from tempest-react-sdk/vite — optional",
+                      ],
+            );
+        } else {
+            checks.push(["ok", `${viteCfg} found`]);
+        }
         // React plugin is required for JSX/Fast Refresh in a Vite React app.
         checks.push(
             installedVersion("@vitejs/plugin-react")
@@ -508,14 +622,23 @@ function doctor() {
         );
     }
     const entry = firstExisting(["src/main.tsx", "src/main.ts", "src/index.tsx", "src/index.ts"]);
-    if (entry) {
-        checks.push(
-            fileIncludes(join(ROOT, entry), "tempest-react-sdk/styles.css")
-                ? ["ok", `${entry} imports styles.css`]
-                : ["warn", `${entry}`, 'add import "tempest-react-sdk/styles.css"'],
-        );
-    } else {
-        checks.push(["warn", "app entry", "no src/main.tsx found"]);
+    if (usesSdk) {
+        // Without the stylesheet every component renders unstyled, so for an SDK
+        // project this is a real defect. For anyone else the entry's filename is
+        // their business, not ours.
+        if (entry) {
+            checks.push(
+                fileIncludes(join(ROOT, entry), "tempest-react-sdk/styles.css")
+                    ? ["ok", `${entry} imports styles.css`]
+                    : ["warn", `${entry}`, 'add import "tempest-react-sdk/styles.css"'],
+            );
+        } else {
+            checks.push([
+                "warn",
+                "app entry",
+                "none of src/main.tsx, src/main.ts, src/index.tsx, src/index.ts found — cannot verify the styles.css import",
+            ]);
+        }
     }
     // styles.css should be imported once — duplicates re-inject the whole sheet.
     const stylesImports = (src.match(/tempest-react-sdk\/styles\.css/g) ?? []).length;
@@ -527,6 +650,9 @@ function doctor() {
         ]);
     }
 
+    // ── Stylesheets ───────────────────────────────────────────────────────────
+    checks.push(...cssChecks());
+
     // ── Tooling ────────────────────────────────────────────────────────────────
     checks.push(["section", "Tooling"]);
     checks.push(
@@ -600,6 +726,26 @@ function doctor() {
         checks.push(["ok", "client env vars use the VITE_ prefix"]);
     }
 
+    /*
+     * In generic mode, close with what adoption would actually take. A tool that
+     * audits somebody's project and then says nothing about the next step reads as an
+     * ad for a product they cannot find the door to.
+     */
+    if (!usesSdk) {
+        checks.push(["section", "Adopting the SDK (optional)"]);
+        checks.push(["info", "install", "npm i tempest-react-sdk"]);
+        checks.push([
+            "info",
+            "import the stylesheet once, in your entry",
+            'import "tempest-react-sdk/styles.css"',
+        ]);
+        checks.push([
+            "info",
+            "not all-or-nothing",
+            "one component at a time works — the @/* alias, createViteConfig and the scaffold are all optional",
+        ]);
+    }
+
     return report(checks);
 }
 
@@ -668,7 +814,7 @@ function lint(args) {
 }
 
 /** Flags `fix` owns itself; anything else is rejected rather than forwarded. */
-const FIX_FLAGS = new Set(["--no-alias", "--dry-run"]);
+const FIX_FLAGS = new Set(["--no-alias", "--no-css", "--dry-run"]);
 
 /**
  * Print the alias pass result.
@@ -711,6 +857,91 @@ function reportAlias(result, dryRun) {
     );
 }
 
+/** Prefix for a finding line: red for a browser-visible defect, yellow otherwise. */
+function severityMark(severity) {
+    if (severity === "error") return `${c.red}✗${c.reset}`;
+    return severity === "warn" ? `${c.yellow}!${c.reset}` : `${c.cyan}i${c.reset}`;
+}
+
+/**
+ * The CSS pass of `fix`: report what the analysis found, then remove the subset
+ * that is provably dead.
+ *
+ * Findings that need a human are printed in full here rather than capped, because
+ * `--dry-run` is the review surface — `doctor` is the summary, this is the list
+ * you read before letting the tool write. Only the advisory (`info`) tail is
+ * capped, since "this could be a token" scales with the size of the project.
+ *
+ * @param {object} params
+ * @param {string[]} params.targets - Positional paths from the command line.
+ * @param {boolean} params.dryRun
+ * @returns {number} Exit status contribution.
+ */
+function cssPass({ targets, dryRun }) {
+    console.log(
+        `${c.dim}→ css (dedupe declarations · drop dead rules)${dryRun ? " [dry-run]" : ""}${c.reset}`,
+    );
+    let analysis;
+    try {
+        analysis = analyzeCss({ root: ROOT, targets, selfDir: SELF_DIR });
+    } catch (err) {
+        console.log(
+            `  ${c.red}✗ analysis failed${c.reset} ${c.dim}${err?.message ?? err}${c.reset}`,
+        );
+        return 1;
+    }
+    if (analysis.stats.files === 0) {
+        console.log(`  ${c.dim}no stylesheets found${c.reset}`);
+        return 0;
+    }
+
+    const manual = analysis.findings.filter((f) => !f.fixable);
+    const infoLimit = 10;
+    let shownInfo = 0;
+    let hiddenInfo = 0;
+    for (const f of manual) {
+        if (f.severity === "info") {
+            if (shownInfo >= infoLimit) {
+                hiddenInfo += 1;
+                continue;
+            }
+            shownInfo += 1;
+        }
+        console.log(
+            `  [${severityMark(f.severity)}] ${f.file}:${f.line} ${c.dim}${f.message}${c.reset}`,
+        );
+    }
+    if (hiddenInfo > 0) {
+        console.log(`  ${c.dim}…+${hiddenInfo} more suggestion(s)${c.reset}`);
+    }
+
+    const result = applyCssFixes({ analysis, dryRun });
+    for (const file of result.files) {
+        console.log(`  ${file.file} ${c.dim}${file.changes.length}${c.reset}`);
+        for (const change of file.changes) {
+            console.log(`    ${c.dim}${change.line}:${c.reset} ${change.message}`);
+        }
+    }
+    for (const err of result.errors) {
+        console.log(`  ${c.red}✗ ${err.file}${c.reset} ${c.dim}${err.message}${c.reset}`);
+    }
+
+    if (result.total === 0) {
+        console.log(`  ${c.dim}nothing to remove${c.reset}`);
+    } else {
+        const verb = dryRun ? "would remove" : "removed";
+        console.log(
+            `  ${c.green}✓${c.reset} ${verb} ${result.total} dead declaration(s)/rule(s) in ${result.files.length} file(s)`,
+        );
+    }
+    if (analysis.counts.error > 0) {
+        console.log(
+            `  ${c.red}✗ ${analysis.counts.error} CSS syntax error(s)${c.reset} ${c.dim}— those files were not touched; fix them and run again${c.reset}`,
+        );
+    }
+    return result.errors.length || analysis.counts.error ? 1 : 0;
+}
+
 function fix(args) {
     const { flags, paths } = splitArgs(args);
     const unknown = flags.filter((f) => !FIX_FLAGS.has(f));
@@ -730,7 +961,10 @@ function fix(args) {
         reportAlias(result, dryRun);
         aliasStatus = result.status === "error" ? 1 : 0;
     }
-    if (dryRun) return aliasStatus;
+
+    const cssStatus = flags.includes("--no-css") ? 0 : cssPass({ targets, dryRun });
+
+    if (dryRun) return aliasStatus || cssStatus;
 
     console.log(`${c.dim}→ eslint --fix (sort imports · drop unused · tidy whitespace)${c.reset}`);
     const eslintStatus = run(requireBin("eslint"), [...targets, "--fix"]);
@@ -742,7 +976,7 @@ function fix(args) {
     } else {
         console.log(`${c.yellow}! prettier not installed — skipping format pass${c.reset}`);
     }
-    return aliasStatus || eslintStatus || prettierStatus;
+    return aliasStatus || cssStatus || eslintStatus || prettierStatus;
 }
 
 function format(args) {
@@ -878,8 +1112,8 @@ ${c.bold}Usage${c.reset}
 ${c.bold}Commands${c.reset}
   ${c.bold}doctor${c.reset}            Health-check the current project
   ${c.bold}lint${c.reset} [paths]      Run ESLint (report only)
-  ${c.bold}fix${c.reset} [paths]       Alias imports (../ → @/) + ESLint --fix (sort imports, remove
-                    unused, tidy whitespace) + Prettier
+  ${c.bold}fix${c.reset} [paths]       Alias imports (../ → @/) + CSS dead-code removal + ESLint --fix
+                    (sort imports, remove unused, tidy whitespace) + Prettier
   ${c.bold}format${c.reset} [paths]    Prettier --write
   ${c.bold}gen api${c.reset} <src>    Generate Zod schemas + types + service classes from an OpenAPI spec
                     (e.g. tempest gen api http://127.0.0.1:8000/openapi.json --out src/api)
@@ -887,8 +1121,10 @@ ${c.bold}Commands${c.reset}
                     (e.g. tempest gen icons --out src/icons.generated.ts --dir src)
 
 ${c.bold}fix options${c.reset}
-  --dry-run         List the imports that would be rewritten; write nothing
-  --no-alias        Skip the alias pass (ESLint + Prettier only)
+  --dry-run         List every CSS finding and the imports that would be rewritten;
+                    write nothing
+  --no-alias        Skip the alias pass
+  --no-css          Skip the CSS pass (analysis and dead-code removal)
 
 ${c.bold}Options${c.reset}
   -h, --help        Show this help

package/dist/charts/scales.cjs

@@ -0,0 +1,2 @@
+var e=7,t=9,n=3;function r(e){return`var(--tempest-chart-${e})`}function i(e,t,n){if(!Number.isFinite(e))return 0;let r=Math.min(t,n),i=Math.max(t,n);return i===r?.5:Math.min(1,Math.max(0,(e-r)/(i-r)))}function a(e,t){return Math.min(t,Math.max(1,Math.round(e*(t-1))+1))}function o(e){let{min:t,max:n,ordinal:o=!1}=e,s=o?3:1,c=7-s+1;return e=>r(`sequential-${s+a(i(e,t,n),c)-1}`)}function s(e){let{min:t,max:n,center:i=0}=e,o=Math.abs(i-Math.min(t,n)),s=Math.abs(Math.max(t,n)-i);return e=>r(!Number.isFinite(e)||e===i?`diverging-5`:e<i?o===0?`diverging-5`:`diverging-${5-a(Math.min(1,(i-e)/o),4)}`:s===0?`diverging-5`:`diverging-${5+a(Math.min(1,(e-i)/s),4)}`)}function c(e){let t=e===`sequential`?7:9;return Array.from({length:t},(t,n)=>r(`${e}-${n+1}`))}exports.DIVERGING_STEP_COUNT=t,exports.ORDINAL_START_STEP=n,exports.SEQUENTIAL_STEP_COUNT=e,exports.divergingScale=s,exports.scaleSteps=c,exports.sequentialScale=o;
+//# sourceMappingURL=scales.cjs.map

package/dist/charts/scales.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"scales.cjs","names":[],"sources":["../../src/charts/scales.ts"],"sourcesContent":["/** How many steps the sequential token scale has. */\nexport const SEQUENTIAL_STEP_COUNT = 7;\n\n/** How many steps the diverging token scale has, midpoint included. */\nexport const DIVERGING_STEP_COUNT = 9;\n\n/**\n * First sequential step that clears 2:1 against the chart surface.\n *\n * A sequential scale may let its near-zero end recede into the surface — on a\n * heatmap that is exactly what \"almost nothing\" should look like. An **ordinal**\n * scale may not: every step is a discrete mark someone has to see. Starting an\n * ordinal ramp here is the difference.\n */\nexport const ORDINAL_START_STEP = 3;\n\n/** A `var(--tempest-chart-…)` reference, so the value follows the active theme. */\nexport type ChartColorToken = string;\n\n/** Reference a token by name rather than interpolating the string at each call site. */\nfunction token(name: string): ChartColorToken {\n    return `var(--tempest-chart-${name})`;\n}\n\n/**\n * Clamp `value` into `0…1` against a domain, tolerating a reversed or empty one.\n *\n * A zero-width domain (every datum equal) would otherwise divide by zero and paint\n * the whole chart `NaN`; it resolves to the middle of the scale instead, which is\n * the honest reading of \"no variation\".\n */\nfunction normalize(value: number, min: number, max: number): number {\n    if (!Number.isFinite(value)) return 0;\n    const lo = Math.min(min, max);\n    const hi = Math.max(min, max);\n    if (hi === lo) return 0.5;\n    return Math.min(1, Math.max(0, (value - lo) / (hi - lo)));\n}\n\n/** Map a `0…1` position onto `1…steps`, inclusive. */\nfunction stepOf(t: number, steps: number): number {\n    return Math.min(steps, Math.max(1, Math.round(t * (steps - 1)) + 1));\n}\n\nexport interface SequentialScaleOptions {\n    /** Lowest value in the data. */\n    min: number;\n    /** Highest value in the data. */\n    max: number;\n    /**\n     * Keep every step visible against the surface, for discrete ordered marks.\n     *\n     * Off by default: a heatmap *wants* its near-zero cells to recede. Turn it on\n     * for tiers, funnel stages or anything where each step is its own mark.\n     */\n    ordinal?: boolean;\n}\n\n/**\n * Build a magnitude scale over the sequential tokens.\n *\n * Returns `var(--tempest-chart-sequential-N)` rather than a hex string, so a\n * heatmap painted once follows the theme — including dark mode, whose steps are\n * chosen for the dark surface rather than flipped.\n *\n * @example\n * const color = sequentialScale({ min: 0, max: 250 });\n * <rect fill={color(value)} />\n *\n * @param options - The data domain, and whether every step must stay visible.\n * @returns A function from value to a CSS colour reference.\n */\nexport function sequentialScale(\n    options: SequentialScaleOptions,\n): (value: number) => ChartColorToken {\n    const { min, max, ordinal = false } = options;\n    const first = ordinal ? ORDINAL_START_STEP : 1;\n    const span = SEQUENTIAL_STEP_COUNT - first + 1;\n    return (value) => token(`sequential-${first + stepOf(normalize(value, min, max), span) - 1}`);\n}\n\nexport interface DivergingScaleOptions {\n    /** Lowest value in the data. */\n    min: number;\n    /** Highest value in the data. */\n    max: number;\n    /**\n     * The value that means \"no deviation\". Default `0`.\n     *\n     * It is a parameter because the interesting midpoint is often not zero — a\n     * budget variance diverges around the target, not around nothing.\n     */\n    center?: number;\n}\n\n/**\n * Build a polarity scale over the diverging tokens.\n *\n * Each arm is scaled against its **own** distance from the centre, so an asymmetric\n * domain (say −5…+80) still uses the full cool arm for its small negatives. Scaling\n * both arms by the wider one — the easy mistake — would collapse every negative\n * into the step next to the midpoint and hide the sign entirely.\n *\n * @example\n * const color = divergingScale({ min: -12, max: 40 });   // centre 0\n * const budget = divergingScale({ min: 80, max: 130, center: 100 });\n *\n * @param options - The data domain and the neutral centre.\n * @returns A function from value to a CSS colour reference.\n */\nexport function divergingScale(options: DivergingScaleOptions): (value: number) => ChartColorToken {\n    const { min, max, center = 0 } = options;\n    const mid = Math.ceil(DIVERGING_STEP_COUNT / 2);\n    const armSteps = mid - 1;\n    const coolSpan = Math.abs(center - Math.min(min, max));\n    const warmSpan = Math.abs(Math.max(min, max) - center);\n\n    return (value) => {\n        if (!Number.isFinite(value) || value === center) return token(`diverging-${mid}`);\n        if (value < center) {\n            if (coolSpan === 0) return token(`diverging-${mid}`);\n            const t = Math.min(1, (center - value) / coolSpan);\n            // Step 1 is the cool extreme, so a bigger deviation walks toward it.\n            return token(`diverging-${mid - stepOf(t, armSteps)}`);\n        }\n        if (warmSpan === 0) return token(`diverging-${mid}`);\n        const t = Math.min(1, (value - center) / warmSpan);\n        return token(`diverging-${mid + stepOf(t, armSteps)}`);\n    };\n}\n\n/**\n * Every step of a token scale, in order — for rendering a legend.\n *\n * A continuous scale needs a legend showing the ramp with its end labels; without\n * one the reader has no way to turn a colour back into a number.\n *\n * @param kind - Which scale.\n * @returns The token references, lightest/coolest first.\n */\nexport function scaleSteps(kind: \"sequential\" | \"diverging\"): ChartColorToken[] {\n    const count = kind === \"sequential\" ? SEQUENTIAL_STEP_COUNT : DIVERGING_STEP_COUNT;\n    return Array.from({ length: count }, (_, i) => token(`${kind}-${i + 1}`));\n}\n"],"mappings":"AACA,IAAa,EAAwB,EAGxB,EAAuB,EAUvB,EAAqB,EAMlC,SAAS,EAAM,EAA+B,CAC1C,MAAO,uBAAuB,EAAK,EACvC,CASA,SAAS,EAAU,EAAe,EAAa,EAAqB,CAChE,GAAI,CAAC,OAAO,SAAS,CAAK,EAAG,MAAO,GACpC,IAAM,EAAK,KAAK,IAAI,EAAK,CAAG,EACtB,EAAK,KAAK,IAAI,EAAK,CAAG,EAE5B,OADI,IAAO,EAAW,GACf,KAAK,IAAI,EAAG,KAAK,IAAI,GAAI,EAAQ,IAAO,EAAK,EAAG,CAAC,CAC5D,CAGA,SAAS,EAAO,EAAW,EAAuB,CAC9C,OAAO,KAAK,IAAI,EAAO,KAAK,IAAI,EAAG,KAAK,MAAM,GAAK,EAAQ,EAAE,EAAI,CAAC,CAAC,CACvE,CA8BA,SAAgB,EACZ,EACkC,CAClC,GAAM,CAAE,MAAK,MAAK,UAAU,IAAU,EAChC,EAAQ,EAAA,EAA+B,EACvC,EAAA,EAA+B,EAAQ,EAC7C,MAAQ,IAAU,EAAM,cAAc,EAAQ,EAAO,EAAU,EAAO,EAAK,CAAG,EAAG,CAAI,EAAI,GAAG,CAChG,CA+BA,SAAgB,EAAe,EAAoE,CAC/F,GAAM,CAAE,MAAK,MAAK,SAAS,GAAM,EAG3B,EAAW,KAAK,IAAI,EAAS,KAAK,IAAI,EAAK,CAAG,CAAC,EAC/C,EAAW,KAAK,IAAI,KAAK,IAAI,EAAK,CAAG,EAAI,CAAM,EAErD,MAAQ,IACoD,EAApD,CAAC,OAAO,SAAS,CAAK,GAAK,IAAU,EAAqB,cAC1D,EAAQ,EACJ,IAAa,EAAgB,cAGpB,aAAa,EAAM,EAFtB,KAAK,IAAI,GAAI,EAAS,GAAS,CAEF,EAAG,CAAQ,IAElD,IAAa,EAAgB,cAEpB,aAAa,EAAM,EADtB,KAAK,IAAI,GAAI,EAAQ,GAAU,CACF,EAAG,CAAQ,GAT8B,CAWxF,CAWA,SAAgB,EAAW,EAAqD,CAC5E,IAAM,EAAQ,IAAS,aAAA,EAAA,EACvB,OAAO,MAAM,KAAK,CAAE,OAAQ,CAAM,GAAI,EAAG,IAAM,EAAM,GAAG,EAAK,GAAG,EAAI,GAAG,CAAC,CAC5E"}