tempest-react-sdk 0.27.0 → 0.28.1

package/README.md

@@ -31,6 +31,7 @@ The goal is to start every new React frontend with the same opinionated foundati
   - [CSS import](#css-import)
 - [What's inside](#whats-inside)
 - [Scaffold a new app](#scaffold-a-new-app)
+- [Project CLI — `tempest` (doctor, fix, CSS analysis)](#project-cli--tempest)
 - [App foundation (routing, state, providers, Vite)](#app-foundation)
 - [Architecture overview](#architecture-overview)
 - [Quickstart — wiring the app providers](#quickstart--wiring-the-app-providers)
@@ -341,6 +342,29 @@ Each generated file demonstrates one SDK capability. Full walkthrough: **[scaffo
 
 ---
 
+## Project CLI — `tempest`
+
+The package ships a second `bin`, **`tempest`**, for day-to-day project health — it needs no config and works on any React + Vite app, SDK or not:
+
+```bash
+npx tempest doctor           # health-check: deps, TypeScript, Vite, tooling, env, CSS
+npx tempest fix              # relative imports → @/ · dead CSS · ESLint --fix · Prettier
+npx tempest fix --dry-run    # the full report, writing nothing
+npx tempest lint             # ESLint, report only
+npx tempest gen api <spec>   # Zod schemas + types + service classes from OpenAPI
+npx tempest gen icons        # static icon registry from the slugs your source uses
+```
+
+**CSS is analyzed too** — ESLint does not read `.css` and Prettier only reformats it, so broken CSS normally goes through untouched. `doctor` and `fix` parse every stylesheet (CSS Modules included) and report:
+
+- **syntax the browser silently drops** — a missing `;` that swallows the next declarations, `color: ;`, an unclosed block, an unterminated comment or string;
+- **valid CSS that is still wrong** — a declaration the next one kills, a selector declared twice, `bacground-color`, `@medai`, a `--tempest-*` token that does not exist, a `var()` nobody defines and that has no fallback;
+- **when a global class beats the repeated local one** — the same declaration block in N CSS Modules, including the cases `utilities.css` already covers (`.tempest-row`, `.tempest-stack`, …). CSS Modules cannot see this for you: scoping makes the duplication invisible by design.
+
+`tempest fix` removes only what is provably dead (a declaration repeated with the identical value, a rule that repeats an earlier one exactly, an empty rule in a plain sheet) — always the **earlier** copy, since CSS is last-wins. Everything else is reported and left to you. Details: **[CLI docs (PT)](https://mauriciobenjamin700.github.io/tempest-react-sdk/cli/)** · **[EN](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/cli/)**.
+
+---
+
 ## App foundation
 
 Beyond UI blocks, the SDK ships an opinionated **application foundation** so every Tempest frontend wires Vite, routing, state and cache the same way. These are also what the scaffold above generates.
@@ -1081,7 +1105,7 @@ export function PushToggle() {
   const push = usePushSubscription({
     vapidPublicKey: import.meta.env.VITE_VAPID_PUBLIC_KEY,
     onSubscribe: (subscription) => api.post("/webpush/subscribe", { body: subscription }),
-    onUnsubscribe: () => api.delete("/webpush/my"),
+    onUnsubscribe: (sub) => api.delete("/webpush/subscribe", { body: { endpoint: sub.endpoint } }),
   });
 
   if (!push.supported) return <p>Push não suportado neste navegador.</p>;
@@ -1106,7 +1130,7 @@ import { WebPushClient } from "tempest-react-sdk";
 const push = new WebPushClient({
   vapidPublicKey: VAPID_PUBLIC_KEY,
   onSubscribe: (sub) => api.post("/webpush/subscribe", { body: sub }),
-  onUnsubscribe: () => api.delete("/webpush/my"),
+  onUnsubscribe: (sub) => api.delete("/webpush/subscribe", { body: { endpoint: sub.endpoint } }),
 });
 
 await push.subscribe();

package/bin/lib/css/analyze.mjs

@@ -0,0 +1,149 @@
+// The whole CSS analysis in one call: collect, parse, diagnose per file,
+// diagnose across files. `doctor` renders the summary, `fix` applies the subset
+// that is provably safe, and both read the same result — there is no second
+// implementation that can disagree with the first.
+import { readFileSync, writeFileSync } from "node:fs";
+import { relative } from "node:path";
+
+import { collectStylesheets, customPropertiesInSources, looksMinified } from "./collect.mjs";
+import { countBySeverity, sortFindings } from "./findings.mjs";
+import { fixCss } from "./fix.mjs";
+import { parseCss } from "./parse.mjs";
+import { repetitionFindings } from "./repetition.mjs";
+import { analyzeParsed, definedCustomProperties } from "./semantic.mjs";
+import { loadTokens } from "./tokens.mjs";
+
+/**
+ * Analyze every stylesheet under `targets`.
+ *
+ * @param {object} params
+ * @param {string} params.root - Project root.
+ * @param {string[]} [params.targets] - Positional paths from the command line.
+ * @param {string} params.selfDir - Directory of the running CLI, to locate the token table.
+ * @param {number} [params.maxFiles]
+ * @returns {{
+ *   sheets: Array<{ path: string, file: string, text: string, isModule: boolean, parsed: object }>,
+ *   findings: Array<object>,
+ *   groups: Array<object>,
+ *   skipped: Array<{ file: string, reason: string }>,
+ *   truncated: boolean,
+ *   counts: { error: number, warn: number, info: number },
+ *   stats: { files: number, rules: number, declarations: number },
+ *   tokens: { source: string | null, names: Set<string>, byValue: Map<string, string[]>, utilities: Set<string> },
+ * }}
+ */
+export function analyzeCss({ root, targets = ["."], selfDir, maxFiles }) {
+    const tokens = loadTokens({ root, selfDir });
+    const collected = collectStylesheets({ root, targets, maxFiles });
+    const skipped = collected.skipped.map((s) => ({
+        file: relative(root, s.path),
+        reason: s.reason,
+    }));
+
+    const sheets = [];
+    for (const path of collected.files) {
+        let text;
+        try {
+            text = readFileSync(path, "utf8");
+        } catch (err) {
+            skipped.push({ file: relative(root, path), reason: String(err?.message ?? err) });
+            continue;
+        }
+        if (looksMinified(text)) {
+            skipped.push({ file: relative(root, path), reason: "minified" });
+            continue;
+        }
+        sheets.push({
+            path,
+            file: relative(root, path),
+            text,
+            isModule: path.endsWith(".module.css"),
+            parsed: parseCss(text),
+        });
+    }
+
+    const definedVars = new Set(tokens.names);
+    for (const sheet of sheets) {
+        for (const name of definedCustomProperties(sheet.parsed)) definedVars.add(name);
+    }
+    if (sheets.length > 0) {
+        for (const name of customPropertiesInSources({ root })) definedVars.add(name);
+    }
+
+    const findings = [];
+    let rules = 0;
+    let declarations = 0;
+    for (const sheet of sheets) {
+        findings.push(
+            ...analyzeParsed({
+                file: sheet.file,
+                parsed: sheet.parsed,
+                tokens,
+                definedVars,
+                isModule: sheet.isModule,
+            }),
+        );
+        for (const block of sheet.parsed.blocks) {
+            if (block.kind === "rule") rules += 1;
+            declarations += block.decls.length;
+        }
+    }
+
+    const repetition = repetitionFindings({ sheets, utilities: tokens.utilities });
+    findings.push(...repetition.findings);
+
+    const sorted = sortFindings(findings);
+    return {
+        sheets,
+        findings: sorted,
+        groups: repetition.groups,
+        skipped,
+        truncated: collected.truncated,
+        counts: countBySeverity(sorted),
+        stats: { files: sheets.length, rules, declarations },
+        tokens,
+    };
+}
+
+/**
+ * Apply the safe subset of the analysis to disk.
+ *
+ * A sheet with a syntax error is left untouched — `fixCss` refuses it, because an
+ * offset taken from a sheet the parser had to guess its way through is not an
+ * offset worth splicing. Fix the error, run again.
+ *
+ * @param {object} params
+ * @param {ReturnType<typeof analyzeCss>} params.analysis
+ * @param {boolean} [params.dryRun] - Report the edits without writing them.
+ * @returns {{
+ *   files: Array<{ file: string, changes: Array<{ code: string, line: number, message: string }> }>,
+ *   total: number,
+ *   errors: Array<{ file: string, message: string }>,
+ * }}
+ */
+export function applyCssFixes({ analysis, dryRun = false }) {
+    const files = [];
+    const errors = [];
+    let total = 0;
+
+    for (const sheet of analysis.sheets) {
+        const result = fixCss({
+            text: sheet.text,
+            parsed: sheet.parsed,
+            isModule: sheet.isModule,
+        });
+        if (result.changes.length === 0) continue;
+        if (!dryRun) {
+            try {
+                writeFileSync(sheet.path, result.text);
+            } catch (err) {
+                errors.push({ file: sheet.file, message: String(err?.message ?? err) });
+                continue;
+            }
+        }
+        files.push({ file: sheet.file, changes: result.changes });
+        total += result.changes.length;
+    }
+
+    return { files, total, errors };
+}

package/bin/lib/css/analyze.test.mjs

@@ -0,0 +1,136 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { analyzeCss, applyCssFixes } from "./analyze.mjs";
+
+let root;
+const SELF_DIR = join(dirname(new URL(import.meta.url).pathname), "..", "..");
+
+/** Write a file inside the fixture project, creating its directory. */
+function write(rel, text) {
+    const full = join(root, rel);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, text);
+    return full;
+}
+
+const analyze = (targets = ["."]) => analyzeCss({ root, targets, selfDir: SELF_DIR });
+const codesFor = (analysis, file) =>
+    analysis.findings.filter((f) => f.file === file).map((f) => f.code);
+
+beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "tempest-css-"));
+});
+
+afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+});
+
+describe("analyzeCss — collection", () => {
+    it("reports nothing when the project has no stylesheet", () => {
+        const analysis = analyze();
+        expect(analysis.stats.files).toBe(0);
+        expect(analysis.findings).toEqual([]);
+    });
+
+    it("walks the project and reports paths relative to the root", () => {
+        write("src/a.css", ".a { color: red; color: red; }\n");
+        const analysis = analyze();
+        expect(analysis.stats).toMatchObject({ files: 1, rules: 1, declarations: 2 });
+        expect(analysis.findings[0].file).toBe(join("src", "a.css"));
+    });
+
+    it("skips node_modules, dist and other generated trees", () => {
+        write("node_modules/pkg/x.css", ".a {}\n");
+        write("dist/x.css", ".a {}\n");
+        write("coverage/x.css", ".a {}\n");
+        write("src/x.css", ".a { color: red; }\n");
+        expect(analyze().stats.files).toBe(1);
+    });
+
+    it("skips a minified sheet and says so", () => {
+        write("src/vendor.min.css", ".a{color:red}\n");
+        const analysis = analyze();
+        expect(analysis.stats.files).toBe(0);
+        expect(analysis.skipped[0]).toMatchObject({ reason: "minified" });
+    });
+
+    it("honors a single-file target", () => {
+        write("src/a.css", ".a { color: red; color: red; }\n");
+        write("src/b.css", ".b { color: red; color: red; }\n");
+        const analysis = analyze([join("src", "a.css")]);
+        expect(analysis.stats.files).toBe(1);
+    });
+
+    it("sorts findings error → warn → info", () => {
+        write("src/a.css", ".a {\n    color: ;\n}\n.b {\n    color: red;\n    color: red;\n}\n");
+        const severities = analyze().findings.map((f) => f.severity);
+        expect(severities).toEqual(["error", "warn"]);
+        expect(analyze().counts).toMatchObject({ error: 1, warn: 1 });
+    });
+});
+
+describe("analyzeCss — project-wide knowledge", () => {
+    it("accepts a custom property defined in another stylesheet", () => {
+        write("src/tokens.css", ":root {\n    --brand: #123456;\n}\n");
+        write("src/use.css", ".a {\n    color: var(--brand);\n}\n");
+        expect(codesFor(analyze(), join("src", "use.css"))).toEqual([]);
+    });
+
+    it("accepts a custom property only the TypeScript sets", () => {
+        write("src/app.ts", 'el.style.setProperty("--row-height", "40px");\n');
+        write("src/use.css", ".a {\n    height: var(--row-height);\n}\n");
+        expect(codesFor(analyze(), join("src", "use.css"))).toEqual([]);
+    });
+
+    it("still flags a variable nothing anywhere defines", () => {
+        write("src/use.css", ".a {\n    height: var(--nowhere);\n}\n");
+        expect(codesFor(analyze(), join("src", "use.css"))).toEqual(["undefined-var"]);
+    });
+
+    it("finds a block repeated across CSS Modules", () => {
+        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);
+        const codes = analyze().findings.map((f) => f.code);
+        expect(codes).toContain("global-candidate");
+    });
+});
+
+describe("applyCssFixes", () => {
+    it("writes the deduped sheet and reports each change", () => {
+        const file = write("src/a.css", ".a {\n    color: red;\n    color: red;\n}\n.gone {\n}\n");
+        const result = applyCssFixes({ analysis: analyze() });
+        expect(result.total).toBe(2);
+        expect(result.files[0].changes.map((c) => c.code)).toEqual([
+            "duplicate-declaration",
+            "empty-rule",
+        ]);
+        expect(readFileSync(file, "utf8")).toBe(".a {\n    color: red;\n}\n");
+    });
+
+    it("writes nothing on a dry run", () => {
+        const before = ".a {\n    color: red;\n    color: red;\n}\n";
+        const file = write("src/a.css", before);
+        const result = applyCssFixes({ analysis: analyze(), dryRun: true });
+        expect(result.total).toBe(1);
+        expect(readFileSync(file, "utf8")).toBe(before);
+    });
+
+    it("leaves a sheet with a syntax error untouched", () => {
+        const before = ".a {\n    color: red;\n    color: red;\n";
+        const file = write("src/a.css", before);
+        const result = applyCssFixes({ analysis: analyze() });
+        expect(result.total).toBe(0);
+        expect(readFileSync(file, "utf8")).toBe(before);
+    });
+
+    it("is idempotent — a second run finds nothing to do", () => {
+        write("src/a.css", ".a {\n    color: red;\n    color: red;\n}\n");
+        applyCssFixes({ analysis: analyze() });
+        expect(applyCssFixes({ analysis: analyze() }).total).toBe(0);
+    });
+});

package/bin/lib/css/collect.mjs

@@ -0,0 +1,152 @@
+// Find the stylesheets to analyze — and, just as important, the ones to leave
+// alone: a vendored or already-minified sheet is not the author's code, and
+// reporting 400 findings in `normalize.min.css` buries the two that are theirs.
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const SKIP_DIRS = new Set([
+    "node_modules",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    "public",
+    "vendor",
+    ".git",
+    ".vite",
+    ".next",
+    ".turbo",
+    ".cache",
+]);
+
+/** Above this size a stylesheet is treated as generated, not authored. */
+const MAX_BYTES = 512 * 1024;
+
+/** Cap on files opened, so `tempest doctor` stays fast on a huge tree. */
+const MAX_FILES = 600;
+
+/** True when a sheet looks minified: few newlines for a lot of bytes. */
+export function looksMinified(text) {
+    if (text.length < 2000) return false;
+    const lines = text.split("\n").length;
+    return text.length / lines > 400;
+}
+
+/**
+ * Collect the project's own `.css` files.
+ *
+ * @param {object} params
+ * @param {string} params.root - Project root; relative targets resolve against it.
+ * @param {string[]} [params.targets] - Positional paths from the command line.
+ * @param {number} [params.maxFiles]
+ * @returns {{ files: string[], skipped: Array<{ path: string, reason: string }>, truncated: boolean }}
+ */
+export function collectStylesheets({ root, targets = ["."], maxFiles = MAX_FILES }) {
+    const files = new Set();
+    const skipped = [];
+    let truncated = false;
+
+    const consider = (path) => {
+        if (!path.endsWith(".css") || files.has(path)) return;
+        if (files.size >= maxFiles) {
+            truncated = true;
+            return;
+        }
+        let size;
+        try {
+            size = statSync(path).size;
+        } catch {
+            return;
+        }
+        if (size > MAX_BYTES) {
+            skipped.push({ path, reason: "larger than 512 KB — treated as generated" });
+            return;
+        }
+        if (/\.min\.css$/.test(path)) {
+            skipped.push({ path, reason: "minified" });
+            return;
+        }
+        files.add(path);
+    };
+
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (SKIP_DIRS.has(entry.name)) continue;
+            if (entry.name.startsWith(".") && entry.isDirectory()) continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) walk(full);
+            else if (entry.isFile()) consider(full);
+        }
+    };
+
+    for (const target of targets) {
+        const full = resolve(root, target);
+        let stat;
+        try {
+            stat = statSync(full);
+        } catch {
+            continue;
+        }
+        if (stat.isDirectory()) walk(full);
+        else if (stat.isFile()) consider(full);
+    }
+
+    return { files: [...files].sort((a, b) => a.localeCompare(b)), skipped, truncated };
+}
+
+/**
+ * Custom-property names mentioned anywhere in the project's TS/JS/HTML.
+ *
+ * Without this the "never defined" check reports every token an app sets from
+ * JavaScript — `style.setProperty("--row-height", …)` is how a CSS variable is
+ * meant to be driven at runtime, and calling that a bug would be the loudest
+ * false positive in the tool.
+ *
+ * @param {object} params
+ * @param {string} params.root
+ * @param {number} [params.maxFiles]
+ * @returns {Set<string>}
+ */
+export function customPropertiesInSources({ root, maxFiles = 1500 }) {
+    const found = new Set();
+    const exts = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".html", ".svg"];
+    let budget = maxFiles;
+
+    const walk = (dir) => {
+        if (budget <= 0) return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (budget <= 0) return;
+            if (SKIP_DIRS.has(entry.name)) continue;
+            if (entry.name.startsWith(".") && entry.isDirectory()) continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            if (!exts.some((ext) => entry.name.endsWith(ext))) continue;
+            budget -= 1;
+            let text;
+            try {
+                text = readFileSync(full, "utf8");
+            } catch {
+                continue;
+            }
+            for (const match of text.matchAll(/(--[a-zA-Z][a-zA-Z0-9_-]*)/g)) found.add(match[1]);
+        }
+    };
+
+    walk(root);
+    return found;
+}

package/bin/lib/css/findings.mjs

@@ -0,0 +1,79 @@
+// The finding vocabulary: every code the CSS analysis can emit, and how loud it
+// is. Kept in one table so `doctor`, `fix` and the tests agree on what counts as
+// broken CSS versus a suggestion somebody may reasonably decline.
+//
+// `error` means the browser drops something the author wrote. `warn` means the
+// CSS is valid but a declaration is dead, shadowed or pointing at a name that
+// does not exist. `info` is advice — a token or a shared class that would say
+// the same thing better — and never fails a command.
+
+/** Severity of each finding code. */
+export const SEVERITY = {
+    "unterminated-comment": "error",
+    "unterminated-string": "error",
+    "unterminated-paren": "error",
+    "unclosed-block": "error",
+    "unexpected-brace": "error",
+    "missing-brace": "error",
+    "missing-colon": "error",
+    "missing-property": "error",
+    "missing-semicolon": "error",
+    "empty-value": "error",
+    "empty-selector": "error",
+    "declaration-outside-rule": "error",
+    "unknown-at-rule": "warn",
+    "unknown-property": "warn",
+    "unknown-token": "warn",
+    "undefined-var": "warn",
+    "duplicate-declaration": "warn",
+    "overridden-declaration": "warn",
+    "duplicate-selector": "warn",
+    "duplicate-rule": "warn",
+    "empty-rule": "warn",
+    "hardcoded-token-value": "info",
+    "global-candidate": "info",
+    "utility-candidate": "info",
+};
+
+/**
+ * Build a finding.
+ *
+ * @param {string} code - A key of {@link SEVERITY}.
+ * @param {object} params
+ * @param {string} params.file - Path as it should be reported (project-relative).
+ * @param {number} params.line - 1-based line.
+ * @param {string} params.message - What is wrong, and what to do about it.
+ * @param {boolean} [params.fixable] - Whether `tempest fix` rewrites it.
+ * @param {object} [params.extra] - Extra fields carried through to the reporter.
+ * @returns {{ code: string, severity: string, file: string, line: number, message: string, fixable: boolean }}
+ */
+export function finding(code, { file, line, message, fixable = false, extra = {} }) {
+    return {
+        code,
+        severity: SEVERITY[code] ?? "warn",
+        file,
+        line,
+        message,
+        fixable,
+        ...extra,
+    };
+}
+
+/** Sort findings by severity, then file, then line — the reporting order. */
+export function sortFindings(findings) {
+    const rank = { error: 0, warn: 1, info: 2 };
+    return [...findings].sort(
+        (a, b) =>
+            (rank[a.severity] ?? 3) - (rank[b.severity] ?? 3) ||
+            a.file.localeCompare(b.file) ||
+            a.line - b.line ||
+            a.code.localeCompare(b.code),
+    );
+}
+
+/** Count findings per severity. */
+export function countBySeverity(findings) {
+    const counts = { error: 0, warn: 0, info: 0 };
+    for (const f of findings) counts[f.severity] = (counts[f.severity] ?? 0) + 1;
+    return counts;
+}

package/bin/lib/css/fix.e2e.test.mjs

@@ -0,0 +1,99 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, 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-fix-css-"));
+    writeFileSync(join(root, "package.json"), JSON.stringify({ name: "fixture" }));
+});
+
+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, contents);
+    return path;
+}
+
+/**
+ * Run `tempest fix` in the fixture.
+ *
+ * `--no-alias` keeps the run to the CSS pass: the alias pass needs TypeScript and
+ * a `paths` entry, neither of which this fixture has, and its "skipping" notice
+ * would be the loudest line in the output.
+ */
+function fix(args = []) {
+    const result = spawnSync(process.execPath, [CLI, "fix", "--no-alias", ...args], {
+        cwd: root,
+        encoding: "utf8",
+        env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: "0" },
+    });
+    return { code: result.status, out: `${result.stdout}${result.stderr}` };
+}
+
+describe("tempest fix — the CSS pass", () => {
+    it("removes dead declarations and reports each one", () => {
+        const file = write("src/app.css", ".a {\n    color: red;\n    color: red;\n}\n");
+        const { out } = fix();
+        expect(out).toContain("→ css");
+        expect(out).toContain("removed duplicate `color`");
+        expect(readFileSync(file, "utf8")).toBe(".a {\n    color: red;\n}\n");
+    });
+
+    it("writes nothing under --dry-run", () => {
+        const before = ".a {\n    color: red;\n    color: red;\n}\n";
+        const file = write("src/app.css", before);
+        const { out } = fix(["--dry-run"]);
+        expect(out).toContain("would remove 1");
+        expect(readFileSync(file, "utf8")).toBe(before);
+    });
+
+    it("lists the findings a human has to resolve", () => {
+        write("src/app.css", ".a {\n    color: red;\n    color: blue;\n}\n");
+        const { out } = fix(["--dry-run"]);
+        expect(out).toContain("overrides");
+        expect(out).toContain("nothing to remove");
+    });
+
+    it("refuses to write to a sheet with a syntax error, and exits non-zero", () => {
+        const before = ".a {\n    color: red;\n    color: red;\n";
+        const file = write("src/app.css", before);
+        const { out, code } = fix();
+        expect(out).toContain("CSS syntax error(s)");
+        expect(readFileSync(file, "utf8")).toBe(before);
+        expect(code).toBe(1);
+    });
+
+    it("honors a path argument", () => {
+        const touched = write("src/a.css", ".a {\n    color: red;\n    color: red;\n}\n");
+        const other = write("src/b.css", ".b {\n    color: red;\n    color: red;\n}\n");
+        fix([join("src", "a.css")]);
+        expect(readFileSync(touched, "utf8")).toBe(".a {\n    color: red;\n}\n");
+        expect(readFileSync(other, "utf8")).toContain("color: red;\n    color: red;");
+    });
+
+    it("skips the pass entirely with --no-css", () => {
+        const before = ".a {\n    color: red;\n    color: red;\n}\n";
+        const file = write("src/app.css", before);
+        const { out } = fix(["--no-css", "--dry-run"]);
+        expect(out).not.toContain("→ css");
+        expect(readFileSync(file, "utf8")).toBe(before);
+    });
+
+    it("rejects an unknown flag instead of forwarding it", () => {
+        const { out, code } = fix(["--no-such-flag"]);
+        expect(out).toContain("Unknown flag for fix");
+        expect(code).toBe(1);
+    });
+});