tempest-react-sdk 0.31.1 → 0.32.1

package/bin/lib/design/index.test.mjs

@@ -0,0 +1,129 @@
+import { mkdirSync, mkdtempSync, 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 { analyzeDesign } from "./index.mjs";
+
+let root;
+
+function write(relative, contents) {
+    const full = join(root, relative);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, contents);
+}
+
+beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "tempest-design-"));
+});
+
+afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+});
+
+describe("analyzeDesign", () => {
+    it("reports nothing for a well-shaped project", () => {
+        write(
+            "src/features/orders/OrderRow.tsx",
+            [
+                "interface OrderRowProps {",
+                "  code: string;",
+                "}",
+                "",
+                "/** One row. */",
+                "export function OrderRow({ code }: OrderRowProps) {",
+                "  return <span>{code}</span>;",
+                "}",
+            ].join("\n"),
+        );
+        const result = analyzeDesign({ root });
+        expect(result.findings).toEqual([]);
+        expect(result.stats.files).toBe(1);
+        expect(result.counts.warn).toBe(0);
+    });
+
+    it("reports findings with project-relative paths", () => {
+        write(
+            "src/pages/List.tsx",
+            "export function List() {\n  fetch('/api');\n  return null;\n}",
+        );
+        const result = analyzeDesign({ root });
+        expect(result.findings).toHaveLength(1);
+        expect(result.findings[0].file).toBe(join("src", "pages", "List.tsx"));
+        expect(result.findings[0].code).toBe("fetch-in-component");
+    });
+
+    it("walks app/ as well as src/", () => {
+        write("app/Widget.tsx", "export function Widget() {\n  fetch('/x');\n  return null;\n}");
+        expect(analyzeDesign({ root }).findings.map((f) => f.code)).toEqual(["fetch-in-component"]);
+    });
+
+    it("ignores declaration files and generated code", () => {
+        write("src/types.d.ts", "export type Any = any;");
+        write("src/icons.generated.ts", "export const icons = { a: 1 as any };");
+        write("src/generated/api.ts", "export const client = {} as any;");
+        const result = analyzeDesign({ root });
+        expect(result.stats.files).toBe(0);
+        expect(result.findings).toEqual([]);
+    });
+
+    it("reports statistics over the files it read", () => {
+        write("src/a.ts", "export const a = 1;\nexport const b = 2;");
+        write("src/b.ts", "export const c = 3;");
+        const result = analyzeDesign({ root });
+        expect(result.stats.files).toBe(2);
+        expect(result.stats.codeLines).toBe(3);
+        expect(result.stats.largest.lines).toBe(2);
+    });
+
+    it("collects waivers with their reasons", () => {
+        write(
+            "src/Crop.tsx",
+            [
+                "/**",
+                " * Cropper.",
+                " *",
+                " * @tempest-limits file-lines — drag, zoom and canvas export share one",
+                " * piece of geometry state.",
+                " */",
+                "export function Crop() {",
+                ...Array.from({ length: 200 }, (_, i) => `  const v${i} = ${i};`),
+                "  return null;",
+                "}",
+            ].join("\n"),
+        );
+        const result = analyzeDesign({ root });
+        expect(result.findings.map((f) => f.code)).not.toContain("file-lines");
+        expect(result.waivers).toEqual([
+            {
+                file: "src/Crop.tsx",
+                code: "file-lines",
+                reason: expect.stringContaining("geometry state"),
+            },
+        ]);
+    });
+
+    it("sorts warnings before info", () => {
+        write("src/a.tsx", "export function A() {\n  fetch('/x');\n  return null;\n}");
+        write("src/a.test.ts", "const mock = {} as any;");
+        const result = analyzeDesign({ root });
+        expect(result.findings.map((f) => f.severity)).toEqual(["warn", "info"]);
+    });
+
+    it("flags truncation when the file cap is reached", () => {
+        for (let i = 0; i < 5; i += 1) write(`src/f${i}.ts`, "export const v = 1;");
+        const result = analyzeDesign({ root, maxFiles: 2 });
+        expect(result.stats.files).toBe(2);
+        expect(result.truncated).toBe(true);
+    });
+
+    it("returns empty stats when there is nothing to read", () => {
+        const result = analyzeDesign({ root });
+        expect(result.stats).toEqual({
+            files: 0,
+            codeLines: 0,
+            medianLines: 0,
+            largest: null,
+        });
+    });
+});

package/bin/lib/design/markers.mjs

@@ -0,0 +1,76 @@
+// The escape hatch. A limit you can never exceed stops being a default and
+// becomes a reason to silence the tool, so exceeding one is allowed — out loud.
+//
+//   /**
+//    * Interactive image cropper.
+//    *
+//    * @tempest-limits file-lines — pointer drag, wheel zoom, aspect clamping and
+//    * canvas export share one piece of geometry state.
+//    */
+//
+// The rule id (or `*`) says what is waived; the text after it says why. A marker
+// with no reason is itself reported: an unexplained waiver is the thing this is
+// meant to prevent.
+
+/** Minimum characters of prose that count as an actual reason. */
+const MIN_REASON = 12;
+
+/**
+ * Parse every `@tempest-limits` marker out of a file's comment text.
+ *
+ * @param {string} commentText - Comment text from `maskSource`.
+ * @returns {{ waived: Set<string>, reasons: Map<string, string>, unexplained: string[] }}
+ *   `waived` holds the rule ids (possibly `*`); `reasons` maps id → reason;
+ *   `unexplained` lists ids whose marker carried no usable reason.
+ */
+export function parseMarkers(commentText) {
+    const waived = new Set();
+    const reasons = new Map();
+    const unexplained = [];
+
+    const re = /@tempest-limits\s+([\w-]+(?:\s*,\s*[\w-]+)*|\*)([^\n]*(?:\n\s*\*(?!\/)[^\n]*)*)/g;
+    let match;
+    while ((match = re.exec(commentText))) {
+        const ids = match[1]
+            .split(",")
+            .map((id) => id.trim())
+            .filter(Boolean);
+        const reason = cleanReason(match[2] ?? "");
+        for (const id of ids) {
+            waived.add(id);
+            if (reason.length >= MIN_REASON) reasons.set(id, reason);
+            else unexplained.push(id);
+        }
+    }
+
+    return { waived, reasons, unexplained };
+}
+
+/**
+ * Strip the JSDoc furniture from the text trailing a marker: leading dashes or
+ * colon, and the `*` that opens each continuation line.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+function cleanReason(raw) {
+    return raw
+        .split("\n")
+        .map((line) => line.replace(/^\s*\*\s?/, ""))
+        .join(" ")
+        .replace(/^\s*[—–\-:]+\s*/, "")
+        .replace(/\*\/\s*$/, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+
+/**
+ * Whether a rule is waived for a file.
+ *
+ * @param {{ waived: Set<string> }} markers
+ * @param {string} code
+ * @returns {boolean}
+ */
+export function isWaived(markers, code) {
+    return markers.waived.has("*") || markers.waived.has(code);
+}

package/bin/lib/design/markers.test.mjs

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+
+import { maskSource } from "./mask.mjs";
+import { isWaived, parseMarkers } from "./markers.mjs";
+
+const markersOf = (source) => parseMarkers(maskSource(source).commentText);
+
+describe("parseMarkers", () => {
+    it("waives one rule and keeps its reason", () => {
+        const markers = markersOf(
+            [
+                "/**",
+                " * Interactive image cropper.",
+                " *",
+                " * @tempest-limits file-lines — drag, zoom and canvas export share one",
+                " * piece of geometry state.",
+                " */",
+            ].join("\n"),
+        );
+        expect(isWaived(markers, "file-lines")).toBe(true);
+        expect(markers.reasons.get("file-lines")).toContain("geometry state");
+        expect(markers.unexplained).toEqual([]);
+    });
+
+    it("waives several rules from one marker", () => {
+        const markers = markersOf(
+            "// @tempest-limits file-lines, function-lines: the state machine is one unit",
+        );
+        expect(isWaived(markers, "file-lines")).toBe(true);
+        expect(isWaived(markers, "function-lines")).toBe(true);
+        expect(isWaived(markers, "props-count")).toBe(false);
+    });
+
+    it("waives everything with a star", () => {
+        const markers = markersOf("// @tempest-limits * — vendored file, regenerated by a script");
+        expect(isWaived(markers, "anything-at-all")).toBe(true);
+    });
+
+    it("reports a marker with no reason", () => {
+        const markers = markersOf("// @tempest-limits file-lines");
+        expect(markers.unexplained).toEqual(["file-lines"]);
+        expect(markers.reasons.size).toBe(0);
+    });
+
+    it("reports a marker whose reason is too short to be one", () => {
+        const markers = markersOf("// @tempest-limits props-count — big");
+        expect(markers.unexplained).toEqual(["props-count"]);
+    });
+
+    it("finds nothing in a file without markers", () => {
+        const markers = markersOf("/** Just a component. */");
+        expect(markers.waived.size).toBe(0);
+        expect(markers.unexplained).toEqual([]);
+    });
+
+    it("ignores a marker written inside a string, not a comment", () => {
+        const markers = markersOf('const help = "@tempest-limits file-lines — not a comment";');
+        expect(markers.waived.size).toBe(0);
+    });
+});

package/bin/lib/design/mask.mjs

@@ -0,0 +1,209 @@
+// Blank out comments, string literals and regex bodies while keeping every byte
+// offset and newline in place. Every other rule in this folder runs on the mask
+// instead of the raw source, which is what stops the two loudest classes of
+// false positive: a brace inside a string ("}") breaking the body scan, and the
+// word `any` inside a doc comment being reported as a type.
+//
+// A `/` starts a regex only when the previous meaningful character is one that
+// cannot end an expression. That is the standard heuristic; it keeps JSX
+// (`</div>`) and division (`a / b`) out of regex state.
+
+const REGEX_PRECEDERS = new Set(["(", ",", "=", ":", "[", "!", "&", "|", "?", "{", "}", ";", "+"]);
+
+/** Last non-whitespace character before `index`, or "" at the start of input. */
+function previousMeaningful(source, index) {
+    for (let i = index - 1; i >= 0; i -= 1) {
+        if (!/\s/.test(source[i])) return source[i];
+    }
+    return "";
+}
+
+/**
+ * Replace comment bodies, string contents and regex bodies with spaces.
+ *
+ * Newlines are preserved everywhere, including inside block comments and
+ * template literals, so a line number computed on the mask is the line number in
+ * the original file. Template-literal `${…}` holes stay as code, since that is
+ * where real expressions live.
+ *
+ * @param {string} source - Raw file contents.
+ * @returns {{ masked: string, commentText: string }} The mask, plus the comment
+ *   text that was removed (some rules — `@ts-ignore`, the limits marker — only
+ *   exist in comments).
+ */
+export function maskSource(source) {
+    const out = new Array(source.length);
+    let comments = "";
+    let i = 0;
+    /** Depth of `${` holes per nested template literal. */
+    const templates = [];
+
+    const blank = (from, to) => {
+        for (let k = from; k < to; k += 1) out[k] = source[k] === "\n" ? "\n" : " ";
+    };
+
+    while (i < source.length) {
+        const ch = source[i];
+        const next = source[i + 1];
+
+        if (ch === "/" && next === "/") {
+            const end = source.indexOf("\n", i);
+            const stop = end === -1 ? source.length : end;
+            comments += `${source.slice(i, stop)}\n`;
+            blank(i, stop);
+            i = stop;
+            continue;
+        }
+
+        if (ch === "/" && next === "*") {
+            const end = source.indexOf("*/", i + 2);
+            const stop = end === -1 ? source.length : end + 2;
+            comments += `${source.slice(i, stop)}\n`;
+            blank(i, stop);
+            i = stop;
+            continue;
+        }
+
+        if (ch === '"' || ch === "'") {
+            let k = i + 1;
+            while (k < source.length && source[k] !== ch) {
+                if (source[k] === "\\") k += 1;
+                if (source[k] === "\n") break;
+                k += 1;
+            }
+            out[i] = ch;
+            blank(i + 1, k);
+            out[k] = source[k] === ch ? ch : source[k] === "\n" ? "\n" : " ";
+            i = k + 1;
+            continue;
+        }
+
+        if (ch === "`") {
+            out[i] = "`";
+            i += 1;
+            let start = i;
+            while (i < source.length) {
+                if (source[i] === "\\") {
+                    i += 2;
+                    continue;
+                }
+                if (source[i] === "$" && source[i + 1] === "{") {
+                    blank(start, i);
+                    out[i] = " ";
+                    out[i + 1] = "{";
+                    templates.push(1);
+                    i += 2;
+                    let depth = 1;
+                    while (i < source.length && depth > 0) {
+                        const inner = maskHole(source, i, out);
+                        depth += inner.delta;
+                        i = inner.next;
+                        if (depth === 0) break;
+                    }
+                    templates.pop();
+                    start = i;
+                    continue;
+                }
+                if (source[i] === "`") break;
+                i += 1;
+            }
+            blank(start, i);
+            if (i < source.length) out[i] = "`";
+            i += 1;
+            continue;
+        }
+
+        if (ch === "/" && REGEX_PRECEDERS.has(previousMeaningful(source, i))) {
+            let k = i + 1;
+            let inClass = false;
+            while (k < source.length && source[k] !== "\n") {
+                if (source[k] === "\\") {
+                    k += 2;
+                    continue;
+                }
+                if (source[k] === "[") inClass = true;
+                else if (source[k] === "]") inClass = false;
+                else if (source[k] === "/" && !inClass) break;
+                k += 1;
+            }
+            out[i] = "/";
+            blank(i + 1, k);
+            if (k < source.length && source[k] === "/") out[k] = "/";
+            i = k + 1;
+            continue;
+        }
+
+        out[i] = ch;
+        i += 1;
+    }
+
+    for (let k = 0; k < source.length; k += 1) {
+        if (out[k] === undefined) out[k] = source[k] === "\n" ? "\n" : " ";
+    }
+    return { masked: out.join(""), commentText: comments };
+}
+
+/**
+ * Copy one character of a template-literal `${…}` hole into the mask, reporting
+ * how it changes brace depth. Nested strings and comments inside the hole are not
+ * re-masked here — a hole deep enough to need that is rare, and treating its
+ * braces literally keeps the scan terminating.
+ *
+ * @param {string} source
+ * @param {number} index
+ * @param {string[]} out - Mask being built, mutated in place.
+ * @returns {{ delta: number, next: number }}
+ */
+function maskHole(source, index, out) {
+    const ch = source[index];
+    out[index] = ch === "\n" ? "\n" : ch;
+    if (ch === "{") return { delta: 1, next: index + 1 };
+    if (ch === "}") return { delta: -1, next: index + 1 };
+    return { delta: 0, next: index + 1 };
+}
+
+/**
+ * Count lines that carry code: non-blank after masking. Comment-only and blank
+ * lines do not count, matching `max-lines` with `skipComments` + `skipBlankLines`
+ * — the ESLint setting the docs recommend.
+ *
+ * @param {string} masked - Output of {@link maskSource}.
+ * @returns {number}
+ */
+export function countCodeLines(masked) {
+    let count = 0;
+    for (const line of masked.split("\n")) {
+        if (line.trim().length > 0) count += 1;
+    }
+    return count;
+}
+
+/** 1-based line number of a character offset. */
+export function lineAt(text, offset) {
+    let line = 1;
+    for (let i = 0; i < offset && i < text.length; i += 1) {
+        if (text[i] === "\n") line += 1;
+    }
+    return line;
+}
+
+/**
+ * Index of the delimiter matching the one at `open`, or -1 when unbalanced.
+ *
+ * @param {string} masked
+ * @param {number} open - Offset of the opening delimiter.
+ * @param {string} openCh
+ * @param {string} closeCh
+ * @returns {number}
+ */
+export function matchPair(masked, open, openCh, closeCh) {
+    let depth = 0;
+    for (let i = open; i < masked.length; i += 1) {
+        if (masked[i] === openCh) depth += 1;
+        else if (masked[i] === closeCh) {
+            depth -= 1;
+            if (depth === 0) return i;
+        }
+    }
+    return -1;
+}

package/bin/lib/design/mask.test.mjs

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+
+import { countCodeLines, lineAt, maskSource, matchPair } from "./mask.mjs";
+
+describe("maskSource", () => {
+    it("blanks line and block comments while keeping newlines", () => {
+        const { masked, commentText } = maskSource("const a = 1; // note\n/* two\nlines */\nb;");
+        expect(masked).toContain("const a = 1;");
+        expect(masked).not.toContain("note");
+        expect(masked.split("\n")).toHaveLength(4);
+        expect(commentText).toContain("note");
+        expect(commentText).toContain("two");
+    });
+
+    it("blanks string contents but keeps the quotes", () => {
+        const { masked } = maskSource('const s = "a } b";');
+        expect(masked).toMatch(/const s = "\s+";/);
+        expect(masked).not.toContain("}");
+    });
+
+    it("keeps template holes as code and blanks the literal text", () => {
+        const { masked } = maskSource("const s = `x ${ value } y`;");
+        expect(masked).toContain("value");
+        expect(masked).not.toContain("x ");
+    });
+
+    it("blanks a regex body so its braces do not unbalance the scan", () => {
+        const { masked } = maskSource('const re = /a{2}"/g;');
+        expect(masked).not.toContain("{2}");
+        expect(masked).not.toContain('"');
+    });
+
+    it("does not treat JSX closing slashes as a regex", () => {
+        const { masked } = maskSource("const el = <div>{value}</div>;");
+        expect(masked).toContain("value");
+        expect(masked).toContain("</div>");
+    });
+
+    it("does not let an unterminated string swallow the rest of the file", () => {
+        const { masked } = maskSource('const broken = "oops\nconst after = 1;');
+        expect(masked).toContain("const after = 1;");
+    });
+});
+
+describe("countCodeLines", () => {
+    it("counts only lines with code left after masking", () => {
+        const { masked } = maskSource("a;\n\n// comment\nb;\n/* block\nmore */\nc;\n");
+        expect(countCodeLines(masked)).toBe(3);
+    });
+});
+
+describe("lineAt", () => {
+    it("is 1-based", () => {
+        expect(lineAt("a\nb\nc", 0)).toBe(1);
+        expect(lineAt("a\nb\nc", 2)).toBe(2);
+        expect(lineAt("a\nb\nc", 4)).toBe(3);
+    });
+});
+
+describe("matchPair", () => {
+    it("finds the matching delimiter across nesting", () => {
+        const text = "f({ a: { b: 1 } })";
+        expect(matchPair(text, 1, "(", ")")).toBe(text.length - 1);
+    });
+
+    it("returns -1 when unbalanced", () => {
+        expect(matchPair("f({", 1, "(", ")")).toBe(-1);
+    });
+});