tempest-react-sdk 0.27.0 → 0.28.0

package/bin/lib/css/fix.mjs

@@ -0,0 +1,138 @@
+// The `tempest fix` CSS pass. Removes only what is provably dead:
+//
+//   1. a declaration repeated with the identical value in the same rule,
+//   2. a rule that repeats an earlier one declaration for declaration,
+//   3. an empty rule in a plain stylesheet.
+//
+// Nothing here changes what the browser computes. The **earlier** copy is always
+// the one removed, because CSS is last-wins: dropping the later one would change
+// the result whenever something in between touches the same property.
+//
+// Everything else the analysis finds — an override with a different value, a
+// misspelled property, a repeated block that wants to be a global class — is
+// reported and left alone. Guessing which of two conflicting values the author
+// meant is not a fix, it is a coin flip inside somebody's design.
+import { declSignature, ruleKey } from "./semantic.mjs";
+
+/**
+ * Grow a removal range to swallow the leading indentation and the trailing
+ * whitespace, so deleting a declaration leaves neither a blank indented line nor
+ * a double space where it used to sit on a one-line rule.
+ *
+ * @param {string} text
+ * @param {number} start
+ * @param {number} end
+ * @returns {{ start: number, end: number }}
+ */
+function expandRange(text, start, end) {
+    let from = start;
+    while (from > 0 && (text[from - 1] === " " || text[from - 1] === "\t")) from -= 1;
+    if (from > 0 && text[from - 1] !== "\n") from = start;
+
+    let to = end;
+    while (to < text.length && (text[to] === " " || text[to] === "\t")) to += 1;
+    if (text[to] === "\r") to += 1;
+    if (text[to] === "\n") to += 1;
+
+    return { start: from, end: to };
+}
+
+/**
+ * Compute the edits for one stylesheet.
+ *
+ * @param {object} params
+ * @param {string} params.text - Original file contents.
+ * @param {ReturnType<import("./parse.mjs").parseCss>} params.parsed
+ * @param {boolean} [params.isModule] - CSS Module: empty rules are kept.
+ * @returns {{ text: string, changes: Array<{ code: string, line: number, message: string }> }}
+ */
+export function fixCss({ text, parsed, isModule = false }) {
+    if (parsed.errors.length > 0) return { text, changes: [] };
+
+    const edits = [];
+    const changes = [];
+    const byKey = new Map();
+
+    for (const block of parsed.blocks) {
+        const removable = block.end !== null && block.start < block.end;
+
+        if (block.kind === "rule" && removable) {
+            const key = ruleKey(block);
+            const previous = byKey.get(key);
+            if (
+                previous &&
+                block.decls.length > 0 &&
+                declSignature(block) === declSignature(previous.block) &&
+                previous.removable
+            ) {
+                edits.push({ ...expandRange(text, previous.block.start, previous.block.end) });
+                changes.push({
+                    code: "duplicate-rule",
+                    line: previous.block.line,
+                    message: `removed \`${previous.block.prelude}\` — line ${block.line} repeats it exactly`,
+                });
+            }
+            byKey.set(key, { block, removable });
+        }
+
+        if (block.decls.length === 0 && block.children === 0 && !isModule && removable) {
+            edits.push({ ...expandRange(text, block.start, block.end) });
+            changes.push({
+                code: "empty-rule",
+                line: block.line,
+                message: `removed empty rule \`${block.prelude}\``,
+            });
+            continue;
+        }
+
+        const lastByProp = new Map();
+        for (const decl of block.decls) {
+            const prop = decl.prop.toLowerCase();
+            const value = decl.value.replace(/\s+/g, " ").toLowerCase();
+            const previous = lastByProp.get(prop);
+            if (previous && previous.value === value) {
+                edits.push({ ...expandRange(text, previous.decl.start, previous.decl.end) });
+                changes.push({
+                    code: "duplicate-declaration",
+                    line: previous.decl.line,
+                    message: `removed duplicate \`${prop}\` — line ${decl.line} declares the same value`,
+                });
+            }
+            lastByProp.set(prop, { decl, value });
+        }
+    }
+
+    if (edits.length === 0) return { text, changes: [] };
+
+    const applied = dropOverlaps(edits);
+    let out = text;
+    for (const edit of applied) out = out.slice(0, edit.start) + out.slice(edit.end);
+
+    return {
+        text: out,
+        changes: changes.sort((a, b) => a.line - b.line),
+    };
+}
+
+/**
+ * Keep the widest non-overlapping edits, ordered back-to-front for splicing.
+ *
+ * A duplicate declaration inside a rule that is itself a duplicate produces two
+ * overlapping removals. The enclosing one wins — dropping the whole rule already
+ * drops the declaration — and applying both would splice at an offset that no
+ * longer exists.
+ *
+ * @param {Array<{ start: number, end: number }>} edits
+ * @returns {Array<{ start: number, end: number }>} Descending by `start`.
+ */
+function dropOverlaps(edits) {
+    const sorted = [...edits].sort((a, b) => a.start - b.start || b.end - a.end);
+    const kept = [];
+    let reach = -1;
+    for (const edit of sorted) {
+        if (edit.start < reach) continue;
+        kept.push(edit);
+        reach = edit.end;
+    }
+    return kept.reverse();
+}

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

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+
+import { fixCss } from "./fix.mjs";
+import { parseCss } from "./parse.mjs";
+
+const fix = (text, isModule = false) => fixCss({ text, parsed: parseCss(text), isModule });
+
+describe("fixCss — duplicate declarations", () => {
+    it("removes the earlier copy and keeps the cascade position of the later one", () => {
+        const { text, changes } = fix(
+            ".a {\n    color: red;\n    padding: 0;\n    color: red;\n}\n",
+        );
+        expect(text).toBe(".a {\n    padding: 0;\n    color: red;\n}\n");
+        expect(changes).toEqual([
+            {
+                code: "duplicate-declaration",
+                line: 2,
+                message: "removed duplicate `color` — line 4 declares the same value",
+            },
+        ]);
+    });
+
+    it("treats values that differ only in whitespace or case as the same", () => {
+        const { text } = fix(".a {\n    color:   RED;\n    color: red;\n}\n");
+        expect(text).toBe(".a {\n    color: red;\n}\n");
+    });
+
+    it("leaves an override with a different value alone", () => {
+        const text = ".a {\n    color: red;\n    color: blue;\n}\n";
+        expect(fix(text).text).toBe(text);
+    });
+
+    it("keeps a declaration that is duplicated in a different rule", () => {
+        const text = ".a { color: red; }\n.b { color: red; }\n";
+        expect(fix(text).text).toBe(text);
+    });
+});
+
+describe("fixCss — duplicate rules", () => {
+    it("removes an exact earlier repeat", () => {
+        const { text, changes } = fix(".a {\n    color: red;\n}\n.a {\n    color: red;\n}\n");
+        expect(text).toBe(".a {\n    color: red;\n}\n");
+        expect(changes[0].code).toBe("duplicate-rule");
+    });
+
+    it("keeps two rules that declare different values", () => {
+        const text = ".a {\n    color: red;\n}\n.a {\n    color: blue;\n}\n";
+        expect(fix(text).text).toBe(text);
+    });
+
+    it("does not merge rules across at-rule contexts", () => {
+        const text =
+            ".a {\n    color: red;\n}\n@media print {\n    .a {\n        color: red;\n    }\n}\n";
+        expect(fix(text).text).toBe(text);
+    });
+
+    it("does not apply an inner and an outer removal that overlap", () => {
+        const { text, changes } = fix(
+            ".a {\n    color: red;\n    color: red;\n}\n.a {\n    color: red;\n    color: red;\n}\n",
+        );
+        expect(text).toBe(".a {\n    color: red;\n}\n");
+        expect(changes.map((c) => c.code)).toContain("duplicate-rule");
+    });
+});
+
+describe("fixCss — empty rules", () => {
+    it("removes an empty rule from a plain sheet", () => {
+        const { text, changes } = fix(".a {\n    color: red;\n}\n.gone {\n}\n");
+        expect(text).toBe(".a {\n    color: red;\n}\n");
+        expect(changes[0].code).toBe("empty-rule");
+    });
+
+    it("keeps an empty rule in a CSS Module", () => {
+        const text = ".marker {\n}\n";
+        expect(fix(text, true).text).toBe(text);
+    });
+
+    it("keeps a rule that only holds nested rules", () => {
+        const text = ".a {\n    &:hover {\n        color: red;\n    }\n}\n";
+        expect(fix(text).text).toBe(text);
+    });
+});
+
+describe("fixCss — refusals", () => {
+    it("refuses to touch a sheet with a syntax error", () => {
+        const text = ".a {\n    color: red;\n    color: red;\n";
+        const { text: out, changes } = fix(text);
+        expect(out).toBe(text);
+        expect(changes).toEqual([]);
+    });
+
+    it("returns the input unchanged when there is nothing to remove", () => {
+        const text = ".a {\n    color: red;\n}\n";
+        const result = fix(text);
+        expect(result.text).toBe(text);
+        expect(result.changes).toEqual([]);
+    });
+
+    it("keeps the comment above a surviving declaration", () => {
+        const { text } = fix(".a {\n    color: red;\n    /* why */\n    color: red;\n}\n");
+        expect(text).toBe(".a {\n    /* why */\n    color: red;\n}\n");
+    });
+
+    it("survives a one-line rule", () => {
+        const { text } = fix(".a { color: red; color: red; }\n");
+        expect(text).toBe(".a { color: red; }\n");
+    });
+});

package/bin/lib/css/index.mjs

@@ -0,0 +1,16 @@
+// Public surface of the CSS analysis used by `tempest doctor` and `tempest fix`.
+export { analyzeCss, applyCssFixes } from "./analyze.mjs";
+export { collectStylesheets, customPropertiesInSources, looksMinified } from "./collect.mjs";
+export { countBySeverity, finding, SEVERITY, sortFindings } from "./findings.mjs";
+export { fixCss } from "./fix.mjs";
+export { maskValue, normalizeSelectors, parseCss, stripComments } from "./parse.mjs";
+export { distance, KNOWN_AT_RULES, KNOWN_PROPERTIES, nearest } from "./properties.mjs";
+export { matchUtility, repetitionFindings } from "./repetition.mjs";
+export {
+    analyzeParsed,
+    declSignature,
+    definedCustomProperties,
+    missingSemicolons,
+    ruleKey,
+} from "./semantic.mjs";
+export { loadTokens, tokenForValue } from "./tokens.mjs";

package/bin/lib/css/parse.mjs

@@ -0,0 +1,398 @@
+// A tolerant CSS scanner: turns a stylesheet into blocks + declarations and
+// records every syntax defect it walks past instead of throwing.
+//
+// Tolerant on purpose. A linter that dies on the first unbalanced brace reports
+// one problem per run, and the file it refuses to read is exactly the file that
+// needs reading. This one keeps scanning: a stray `}` is recorded and the walk
+// continues, so a single pass finds every defect in the sheet.
+//
+// Offsets are kept truthful (every block and declaration carries `start`/`end`)
+// because `tempest fix` splices the original text — it never re-prints the AST,
+// so formatting, comments and author intent survive a fix pass untouched.
+
+/** Number of newlines in a string. */
+function countNewlines(text) {
+    let n = 0;
+    for (let i = 0; i < text.length; i += 1) if (text[i] === "\n") n += 1;
+    return n;
+}
+
+/**
+ * Index of the first character that is neither whitespace nor part of a
+ * comment, so a declaration's reported line points at the declaration and not
+ * at the blank line or the comment above it.
+ *
+ * @param {string} raw
+ * @returns {number} Index into `raw`; `raw.length` when it holds only trivia.
+ */
+function contentStart(raw) {
+    let i = 0;
+    while (i < raw.length) {
+        const ch = raw[i];
+        if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r" || ch === "\f") {
+            i += 1;
+            continue;
+        }
+        if (ch === "/" && raw[i + 1] === "*") {
+            const close = raw.indexOf("*/", i + 2);
+            if (close < 0) return raw.length;
+            i = close + 2;
+            continue;
+        }
+        return i;
+    }
+    return i;
+}
+
+/**
+ * Drop `/* … *\/` comments, keeping everything else byte-for-byte.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+export function stripComments(raw) {
+    let out = "";
+    let i = 0;
+    while (i < raw.length) {
+        if (raw[i] === "/" && raw[i + 1] === "*") {
+            const close = raw.indexOf("*/", i + 2);
+            if (close < 0) break;
+            i = close + 2;
+            out += " ";
+            continue;
+        }
+        if (raw[i] === '"' || raw[i] === "'") {
+            const quote = raw[i];
+            let j = i + 1;
+            while (j < raw.length && raw[j] !== quote) j += raw[j] === "\\" ? 2 : 1;
+            out += raw.slice(i, Math.min(j + 1, raw.length));
+            i = j + 1;
+            continue;
+        }
+        out += raw[i];
+        i += 1;
+    }
+    return out;
+}
+
+/**
+ * Blank out quoted strings and parenthesized groups, so a scan for a delimiter
+ * cannot trip over one that lives inside `url(…)`, `calc(…)` or a string.
+ *
+ * @param {string} value
+ * @returns {string} Same length as `value`, with those spans replaced by spaces.
+ */
+export function maskValue(value) {
+    let out = "";
+    let depth = 0;
+    let quote = null;
+    for (let i = 0; i < value.length; i += 1) {
+        const ch = value[i];
+        if (quote) {
+            out += ch === "\n" ? "\n" : " ";
+            if (ch === quote) quote = null;
+            else if (ch === "\\") {
+                out += " ";
+                i += 1;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            out += " ";
+            continue;
+        }
+        if (ch === "(") {
+            depth += 1;
+            out += " ";
+            continue;
+        }
+        if (ch === ")") {
+            depth = Math.max(0, depth - 1);
+            out += " ";
+            continue;
+        }
+        out += depth > 0 && ch !== "\n" ? " " : ch;
+    }
+    return out;
+}
+
+/** Index of the first `:` outside strings and parens, or -1. */
+function colonIndex(raw) {
+    return maskValue(raw).indexOf(":");
+}
+
+/**
+ * Parse a stylesheet.
+ *
+ * @param {string} text - Raw file contents.
+ * @returns {{
+ *   blocks: Array<{
+ *     kind: "rule" | "at",
+ *     prelude: string,
+ *     context: string[],
+ *     line: number,
+ *     endLine: number | null,
+ *     start: number,
+ *     bodyStart: number,
+ *     end: number | null,
+ *     decls: Array<{ prop: string, value: string, line: number, start: number, end: number }>,
+ *     children: number,
+ *     invalid: boolean,
+ *   }>,
+ *   statements: Array<{ name: string, params: string, line: number }>,
+ *   errors: Array<{ code: string, line: number, text?: string }>,
+ * }}
+ */
+export function parseCss(text) {
+    const blocks = [];
+    const statements = [];
+    const errors = [];
+    const stack = [];
+
+    let i = 0;
+    let line = 1;
+    let bufStart = 0;
+    let bufLine = 1;
+
+    const reset = () => {
+        bufStart = i;
+        bufLine = line;
+    };
+
+    /**
+     * Record a defect, and mark the block it happened inside.
+     *
+     * The mark is what keeps one mistake from being reported as two: a rule whose
+     * only declaration the parser had to reject looks empty afterwards, and
+     * "this rule is dead code" is a lie about a rule that is merely broken.
+     */
+    const pushError = (code, errorLine, text) => {
+        errors.push(
+            text === undefined ? { code, line: errorLine } : { code, line: errorLine, text },
+        );
+        const block = stack[stack.length - 1];
+        if (block) block.invalid = true;
+    };
+
+    const pending = () => {
+        const raw = text.slice(bufStart, i);
+        const offset = contentStart(raw);
+        return {
+            raw,
+            body: stripComments(raw.slice(offset)).trim(),
+            start: bufStart + offset,
+            line: bufLine + countNewlines(raw.slice(0, offset)),
+        };
+    };
+
+    /**
+     * Turn the pending buffer into a declaration (or an at-statement), pushing a
+     * diagnostic when it is neither.
+     */
+    const flushDecl = (end) => {
+        const { body, start, line: declLine } = pending();
+        if (!body) return;
+        if (body.startsWith("@")) {
+            const match = /^@([\w-]+)\s*([\s\S]*)$/.exec(body);
+            statements.push({
+                name: (match?.[1] ?? "").toLowerCase(),
+                params: (match?.[2] ?? "").trim(),
+                line: declLine,
+            });
+            return;
+        }
+        const block = stack[stack.length - 1];
+        if (!block) {
+            pushError("declaration-outside-rule", declLine, body);
+            return;
+        }
+        const colon = colonIndex(body);
+        if (colon < 0) {
+            pushError("missing-colon", declLine, body);
+            return;
+        }
+        const prop = body.slice(0, colon).trim();
+        const value = body.slice(colon + 1).trim();
+        if (!prop) {
+            pushError("missing-property", declLine, body);
+            return;
+        }
+        if (!value) {
+            pushError("empty-value", declLine, prop);
+            return;
+        }
+        block.decls.push({ prop, value, line: declLine, start, end });
+    };
+
+    while (i < text.length) {
+        const ch = text[i];
+
+        if (ch === "\n") {
+            line += 1;
+            i += 1;
+            continue;
+        }
+
+        if (ch === "/" && text[i + 1] === "*") {
+            const close = text.indexOf("*/", i + 2);
+            if (close < 0) {
+                pushError("unterminated-comment", line);
+                line += countNewlines(text.slice(i));
+                i = text.length;
+                continue;
+            }
+            line += countNewlines(text.slice(i, close));
+            i = close + 2;
+            continue;
+        }
+
+        if (ch === '"' || ch === "'") {
+            let j = i + 1;
+            let closed = false;
+            while (j < text.length) {
+                if (text[j] === "\\") {
+                    j += 2;
+                    continue;
+                }
+                if (text[j] === ch) {
+                    closed = true;
+                    break;
+                }
+                if (text[j] === "\n") break;
+                j += 1;
+            }
+            if (!closed) pushError("unterminated-string", line);
+            line += countNewlines(text.slice(i, Math.min(j + 1, text.length)));
+            i = Math.min(j + 1, text.length);
+            continue;
+        }
+
+        if (ch === "(") {
+            let depth = 0;
+            let j = i;
+            let quote = null;
+            while (j < text.length) {
+                const cj = text[j];
+                if (quote) {
+                    if (cj === "\\") j += 1;
+                    else if (cj === quote) quote = null;
+                } else if (cj === '"' || cj === "'") quote = cj;
+                else if (cj === "(") depth += 1;
+                else if (cj === ")") {
+                    depth -= 1;
+                    if (depth === 0) break;
+                }
+                j += 1;
+            }
+            if (depth !== 0) pushError("unterminated-paren", line);
+            line += countNewlines(text.slice(i, Math.min(j + 1, text.length)));
+            i = Math.min(j + 1, text.length);
+            continue;
+        }
+
+        if (ch === "{") {
+            const { body, start, line: preludeLine } = pending();
+            if (!body) pushError("empty-selector", line);
+            const parent = stack[stack.length - 1];
+            if (parent) parent.children += 1;
+            const block = {
+                kind: body.startsWith("@") ? "at" : "rule",
+                prelude: body,
+                context: stack.map((b) => b.prelude),
+                line: preludeLine,
+                endLine: null,
+                start,
+                bodyStart: i + 1,
+                end: null,
+                decls: [],
+                children: 0,
+                invalid: false,
+            };
+            blocks.push(block);
+            stack.push(block);
+            i += 1;
+            reset();
+            continue;
+        }
+
+        if (ch === "}") {
+            flushDecl(i);
+            const block = stack.pop();
+            if (!block) pushError("unexpected-brace", line);
+            else {
+                block.endLine = line;
+                block.end = i + 1;
+            }
+            i += 1;
+            reset();
+            continue;
+        }
+
+        if (ch === ";") {
+            flushDecl(i + 1);
+            i += 1;
+            reset();
+            continue;
+        }
+
+        i += 1;
+    }
+
+    const { body: trailing, line: trailingLine } = pending();
+    if (stack.length > 0) {
+        flushDecl(i);
+        for (const block of stack) {
+            block.invalid = true;
+            errors.push({ code: "unclosed-block", line: block.line });
+        }
+    } else if (trailing.startsWith("@")) {
+        flushDecl(i);
+    } else if (trailing && colonIndex(trailing) >= 0) {
+        errors.push({ code: "declaration-outside-rule", line: trailingLine, text: trailing });
+    } else if (trailing) {
+        errors.push({ code: "missing-brace", line: trailingLine, text: trailing });
+    }
+
+    return { blocks, statements, errors };
+}
+
+/**
+ * Selector list of a rule, normalized so two spellings of the same target
+ * compare equal: whitespace collapsed, combinators spaced, list order sorted
+ * (`.a, .b` and `.b, .a` select the same set).
+ *
+ * @param {string} prelude
+ * @returns {string[]}
+ */
+export function normalizeSelectors(prelude) {
+    return maskCommas(prelude)
+        .map((part) =>
+            part
+                .trim()
+                .replace(/\s*([>+~])\s*/g, " $1 ")
+                .replace(/\s+/g, " "),
+        )
+        .filter(Boolean)
+        .sort();
+}
+
+/**
+ * Split a selector list on top-level commas — a comma inside `:is(a, b)` or
+ * `[title="a,b"]` does not start a new selector.
+ *
+ * @param {string} prelude
+ * @returns {string[]}
+ */
+function maskCommas(prelude) {
+    const mask = maskValue(prelude);
+    const out = [];
+    let last = 0;
+    for (let i = 0; i < mask.length; i += 1) {
+        if (mask[i] !== ",") continue;
+        out.push(prelude.slice(last, i));
+        last = i + 1;
+    }
+    out.push(prelude.slice(last));
+    return out;
+}