tempest-react-sdk 0.76.0 → 0.78.0

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

@@ -188,3 +188,53 @@ describe("tempest fix --extract-css", () => {
         expect(readFileSync(join(root, "src/index.css"), "utf8")).not.toContain(".u-row");
     });
 });
+
+describe("tempest fix — files outside the project are skipped out loud", () => {
+    let outside;
+
+    beforeEach(() => {
+        outside = mkdtempSync(join(tmpdir(), "tempest-fix-outside-"));
+    });
+
+    afterEach(() => {
+        rmSync(outside, { recursive: true, force: true });
+    });
+
+    it("the CSS pass prints how many sheets it skipped", () => {
+        const before = ".a {\n    color: red;\n    color: red;\n}\n";
+        writeFileSync(join(outside, "a.css"), before);
+        symlinkSync(outside, join(root, "src"), "dir");
+
+        const { out } = fix(["src"]);
+
+        expect(out).toContain("! 1 arquivo(s) fora do projeto (symlink) — pulados");
+        expect(readFileSync(join(outside, "a.css"), "utf8")).toBe(before);
+    });
+
+    it("the alias pass prints how many files it skipped", () => {
+        const typescript = dirname(
+            createRequire(import.meta.url).resolve("typescript/package.json"),
+        );
+        mkdirSync(join(root, "node_modules"));
+        symlinkSync(typescript, join(root, "node_modules", "typescript"), "dir");
+        write(
+            "tsconfig.json",
+            JSON.stringify({ compilerOptions: { paths: { "@/*": ["./src/*"] } } }),
+        );
+        const before = 'import { b } from "../b";\nexport const a = b;\n';
+        mkdirSync(join(outside, "sub"));
+        writeFileSync(join(outside, "b.ts"), "export const b = 1;\n");
+        writeFileSync(join(outside, "sub", "a.ts"), before);
+        symlinkSync(outside, join(root, "src"), "dir");
+
+        const result = spawnSync(process.execPath, [CLI, "fix", "--no-css"], {
+            cwd: root,
+            encoding: "utf8",
+            env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: "0" },
+        });
+        const out = `${result.stdout}${result.stderr}`;
+
+        expect(out).toContain("! 2 arquivo(s) fora do projeto (symlink) — pulados");
+        expect(readFileSync(join(outside, "sub", "a.ts"), "utf8")).toBe(before);
+    });
+});

package/bin/lib/css/index.mjs

@@ -1,6 +1,11 @@
 // 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 {
+    collectStylesheets,
+    customPropertiesInSources,
+    looksMinified,
+    OUTSIDE_PROJECT,
+} from "./collect.mjs";
 export { countBySeverity, finding, SEVERITY, sortFindings } from "./findings.mjs";
 export { fixCss } from "./fix.mjs";
 export {

package/bin/lib/fs/contain.mjs

@@ -0,0 +1,50 @@
+// Where a CLI write really lands. Every pass that writes into the user's project
+// (`gen *`, `fix`'s alias and CSS passes) asks these before touching a path, so a
+// symlink planted in a cloned repository cannot carry a write out of it.
+import { lstatSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, sep } from "node:path";
+
+/**
+ * `lstat` that answers `null` for a missing path instead of throwing.
+ *
+ * @param {string} path - Absolute path.
+ * @returns {import("node:fs").Stats | null}
+ */
+export function lstatOrNull(path) {
+    try {
+        return lstatSync(path);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Whether `path` lands inside `root` once symlinks are resolved.
+ *
+ * Resolves the nearest ancestor that exists through `realpath`, so `../x`, an
+ * absolute path and an ancestor that is a symlink to somewhere else
+ * (`src/components -> /elsewhere`) are all seen where they really land. The walk
+ * stops at the nearest ancestor `lstat` sees, so a dangling symlink on the way is
+ * not skipped over: its `realpath` throws and the path counts as outside, since
+ * `mkdir` or `writeFile` would create whatever the link names.
+ *
+ * @param {string} root - Project root.
+ * @param {string} path - Absolute path, existing or about to be created.
+ * @returns {boolean}
+ */
+export function landsInside(root, path) {
+    let existing = path;
+    while (lstatOrNull(existing) === null && dirname(existing) !== existing) {
+        existing = dirname(existing);
+    }
+    let real;
+    let realRoot;
+    try {
+        real = realpathSync(existing);
+        realRoot = realpathSync(root);
+    } catch {
+        return false;
+    }
+    const rel = relative(realRoot, real);
+    return !(rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel));
+}

package/bin/lib/icons/generate.mjs

@@ -14,19 +14,44 @@ const NAME_PATTERNS = [
 const SOURCE_FILE = /\.[cm]?[jt]sx?$/;
 const SKIP_DIRS = new Set(["node_modules", "dist", "build", "coverage"]);
 
+/**
+ * The two catalogue modules `loadIconTables` reads, relative to `dist/`.
+ *
+ * Both are pure data (`export { e as iconNames }`, `export { e as iconAliases }`)
+ * with no import of their own, which `scripts/check-dist-guards.mjs` asserts
+ * after every build.
+ */
+export const ICON_TABLE_MODULES = {
+    names: "icons/generated/icon-names.js",
+    aliases: "icons/generated/aliases.js",
+};
+
 /**
  * Read the slug tables out of the installed SDK build.
  *
  * Deliberately reads `dist/` rather than embedding a copy: the CLI must agree with
  * the `<Icon>` the app actually renders, and both come from the same install.
  *
+ * It imports the two catalogue modules directly instead of the `dist/icons.js`
+ * barrel. Since 0.63.0 every component module imports its own stylesheet, and the
+ * barrel reaches `<IconPicker>` and its `.css`: in plain Node — which is how the
+ * `tempest` bin runs — that import died with `ERR_UNKNOWN_FILE_EXTENSION ".css"`
+ * and `gen icons` failed in every installed app (#485). Registering the
+ * `/node-css-loader` hooks would also have worked, but it changes module loading
+ * for the whole CLI process to read two arrays, and the barrel would still pull
+ * React and the component graph just to list slugs; the data modules need
+ * neither.
+ *
  * @param {string} selfDir - Directory holding this CLI (`bin/`).
  * @returns {Promise<{ known: Set<string>, aliases: Record<string, string> }>}
  */
 export async function loadIconTables(selfDir) {
-    const dist = join(selfDir, "..", "dist", "icons.js");
-    const mod = await import(pathToFileURL(dist).href);
-    return { known: new Set(mod.iconNames), aliases: mod.iconAliases };
+    const dist = join(selfDir, "..", "dist");
+    const [names, aliases] = await Promise.all([
+        import(pathToFileURL(join(dist, ICON_TABLE_MODULES.names)).href),
+        import(pathToFileURL(join(dist, ICON_TABLE_MODULES.aliases)).href),
+    ]);
+    return { known: new Set(names.iconNames), aliases: aliases.iconAliases };
 }
 
 /**

package/bin/lib/icons/generate.test.mjs

@@ -1,6 +1,8 @@
+import { spawnSync } from "node:child_process";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 import { iconAliases, iconNames } from "@/icons";
@@ -123,3 +125,57 @@ describe("renderRegistry — reserved names", () => {
         expect(out).toContain(`"infinity": InfinityIcon,`);
     });
 });
+
+describe("loadIconTables in plain Node (#485)", () => {
+    let pkg;
+
+    beforeEach(() => {
+        pkg = mkdtempSync(join(tmpdir(), "tempest-icon-tables-"));
+    });
+
+    afterEach(() => {
+        rmSync(pkg, { recursive: true, force: true });
+    });
+
+    /**
+     * Lay out a package the way `npm pack` ships it: a `dist/icons.js` barrel that
+     * imports a stylesheet, as every component module has since 0.63.0, next to the
+     * two pure data modules. Vitest would load the `.css` on its own, so the call
+     * runs in a child `node` with no loader — exactly how the `tempest` bin runs.
+     */
+    function loadInPlainNode() {
+        const dist = join(pkg, "dist");
+        mkdirSync(join(dist, "icons", "generated"), { recursive: true });
+        mkdirSync(join(pkg, "bin"));
+        writeFileSync(join(dist, "icons", "IconPicker.css"), ".a{color:red}");
+        writeFileSync(
+            join(dist, "icons.js"),
+            'import "./icons/IconPicker.css";\nexport const iconNames = [];\nexport const iconAliases = {};\n',
+        );
+        writeFileSync(
+            join(dist, "icons", "generated", "icon-names.js"),
+            'var e = ["check", "house"];\nexport { e as iconNames };\n',
+        );
+        writeFileSync(
+            join(dist, "icons", "generated", "aliases.js"),
+            'var e = { home: "house" };\nexport { e as iconAliases };\n',
+        );
+        const generator = join(dirname(fileURLToPath(import.meta.url)), "generate.mjs");
+        const script = `const { loadIconTables } = await import(${JSON.stringify(generator)});
+const t = await loadIconTables(${JSON.stringify(join(pkg, "bin"))});
+console.log(JSON.stringify({ known: [...t.known], aliases: t.aliases }));`;
+        return spawnSync(process.execPath, ["--input-type=module", "-e", script], {
+            encoding: "utf8",
+        });
+    }
+
+    it("reads the tables without importing a stylesheet", () => {
+        const result = loadInPlainNode();
+        expect(result.stderr).not.toMatch(/ERR_UNKNOWN_FILE_EXTENSION/);
+        expect(result.status).toBe(0);
+        expect(JSON.parse(result.stdout)).toEqual({
+            known: ["check", "house"],
+            aliases: { home: "house" },
+        });
+    });
+});

package/bin/lib/openapi/escape.mjs

@@ -0,0 +1,224 @@
+/**
+ * Context-aware escaping for text copied from an OpenAPI document into generated
+ * TypeScript.
+ *
+ * The spec is input the developer does not control — a partner API, a shared
+ * backend, a document fetched over the network — and the generated files are
+ * imported by the app. Every spec string therefore reaches the output through one
+ * of these functions, chosen by the syntactic position it lands in:
+ *
+ * - identifier position (schema names, path parameters) → {@link toIdentifier},
+ *   which maps a name that is not a TypeScript identifier (`user-id`,
+ *   `user.Response`) to one that is. The mapped name only ever appears in
+ *   identifier position; wherever the name matters at runtime — the URL
+ *   placeholder, an object key — the spec's original is used, escaped. Two
+ *   names that map to the same identifier are refused by
+ *   {@link assertNoCollision}, never silently merged;
+ * - string position → `JSON.stringify` at the call site;
+ * - doc comment → {@link commentText};
+ * - URL template literal → {@link urlTemplate}.
+ */
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+/**
+ * Words that parse as an identifier but cannot name a type alias, a `const` or a
+ * parameter in a generated module. Ported from the ECMAScript reserved words,
+ * `eval` and `arguments` (which strict mode — every class body — forbids as a
+ * binding), and the TypeScript predefined type names that `type X = ...`
+ * rejects.
+ */
+export const RESERVED_WORDS = new Set([
+    "any",
+    "arguments",
+    "await",
+    "bigint",
+    "boolean",
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "continue",
+    "debugger",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "enum",
+    "eval",
+    "export",
+    "extends",
+    "false",
+    "finally",
+    "for",
+    "function",
+    "if",
+    "implements",
+    "import",
+    "in",
+    "instanceof",
+    "interface",
+    "let",
+    "never",
+    "new",
+    "null",
+    "number",
+    "object",
+    "package",
+    "private",
+    "protected",
+    "public",
+    "return",
+    "static",
+    "string",
+    "super",
+    "switch",
+    "symbol",
+    "this",
+    "throw",
+    "true",
+    "try",
+    "typeof",
+    "undefined",
+    "unknown",
+    "var",
+    "void",
+    "while",
+    "with",
+    "yield",
+]);
+
+/**
+ * Map a spec name to a valid, non-reserved TypeScript identifier.
+ *
+ * A name that already is one is returned unchanged, so a spec that generated
+ * fine before keeps generating the same code. Otherwise the name is split into
+ * its alphanumeric words and joined in `camel` case (parameters: `user-id` →
+ * `userId`) or `pascal` case (schemas and types: `user.Response` →
+ * `UserResponse`). A reserved word, or a rebuilt name that starts with a digit
+ * or is reserved, gets a `_` prefix (`string` → `_string`, `2fa` → `_2fa`). Only `[A-Za-z0-9_$]`
+ * survives, so no spec text can reach the output through this path.
+ *
+ * @param {unknown} name - The spec string about to land in identifier position.
+ * @param {"camel"|"pascal"} style - Case for a name that has to be rebuilt.
+ * @param {string} what - What the name is, for the error ("schema name").
+ * @returns {string} The identifier.
+ * @throws {Error} When the name has no alphanumeric character to build one from.
+ */
+export function toIdentifier(name, style, what) {
+    if (typeof name === "string" && IDENTIFIER.test(name)) {
+        return RESERVED_WORDS.has(name) ? `_${name}` : name;
+    }
+    const words = typeof name === "string" ? (name.match(/[A-Za-z0-9]+/g) ?? []) : [];
+    if (words.length === 0) {
+        throw new Error(
+            `OpenAPI ${what} ${JSON.stringify(name)} has no letter or digit to build a TypeScript identifier from. Rename it in the spec.`,
+        );
+    }
+    const joined = words
+        .map((w, i) =>
+            i === 0 && style === "camel"
+                ? w.charAt(0).toLowerCase() + w.slice(1)
+                : w.charAt(0).toUpperCase() + w.slice(1),
+        )
+        .join("");
+    return /^[0-9]/.test(joined) || RESERVED_WORDS.has(joined) ? `_${joined}` : joined;
+}
+
+/**
+ * Throw when two entries map to the same identifier.
+ *
+ * Compared per entry, not per name: a path parameter literally called `body`
+ * maps to itself and still collides with the `body` argument, which a
+ * name-versus-mapped-name comparison would miss.
+ *
+ * @param {Iterable<[string, string]>} entries - `[label, identifier]` pairs; the
+ *   label is the spec's original name, or a description of a generated name.
+ * @param {string} what - What the names are, for the error ("schema names").
+ * @throws {Error} Listing both labels and the identifier they share.
+ */
+export function assertNoCollision(entries, what) {
+    const seen = new Map();
+    for (const [label, id] of entries) {
+        if (seen.has(id)) {
+            throw new Error(
+                `OpenAPI ${what} ${JSON.stringify(seen.get(id))} and ${JSON.stringify(label)} both map to the TypeScript identifier "${id}". Rename one of them in the spec.`,
+            );
+        }
+        seen.set(id, label);
+    }
+}
+
+/**
+ * Make spec text safe inside a `/** ... *\/` block comment.
+ *
+ * Line terminators collapse to a space, so the text cannot start a new line of
+ * the comment, and every `*\/` is broken as `*\\/` so it cannot close it.
+ *
+ * @param {unknown} text - The spec text (tag, summary, path).
+ * @returns {string} The neutralized single-line text.
+ */
+export function commentText(text) {
+    return String(text)
+        .replace(/[\r\n\u2028\u2029]+/g, " ")
+        .replace(/\*\//g, "*\\/");
+}
+
+/**
+ * Escape a static fragment for the inside of a template literal.
+ *
+ * @param {string} text - Literal text from the path.
+ * @returns {string} The text with `\`, `` ` `` and `${` escaped.
+ */
+function templateText(text) {
+    return text.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+}
+
+/**
+ * Build the URL expression for an operation path.
+ *
+ * Static segments are escaped for the template literal; each `{name}` placeholder
+ * is matched by the spec's original name against the declared path parameters
+ * and becomes `${encodeIdSegment(identifier)}`, the variable that parameter was
+ * mapped to passed through the SDK's segment encoder (`{user-id}` →
+ * `${encodeIdSegment(userId)}`). A path without placeholders is emitted as a
+ * JSON string literal.
+ *
+ * The encoder is what keeps a runtime value inside its own segment: interpolated
+ * raw, `"../../account"` turned `DELETE /api/comments/{id}` into
+ * `DELETE /account` carrying the Bearer, and `"7?role=admin"` injected a query
+ * string (#499 — the class #438 closed for the data provider). Encoded, `/`, `?`,
+ * `#` and `%` stay in the segment, and `null`, `undefined`, `""`, `"."` and
+ * `".."` throw before the request is built.
+ *
+ * @param {string} path - The OpenAPI path key ("/users/{user-id}").
+ * @param {Map<string, string>} declared - Original name → argument expression of
+ *   each of the operation's `in: "path"` params: the identifier, or the
+ *   identifier with a type assertion when its type is wider than
+ *   `encodeIdSegment` accepts.
+ * @returns {string} A TypeScript expression evaluating to the URL.
+ * @throws {Error} When a placeholder is not a declared path parameter — there is
+ *   no variable it could safely map to.
+ */
+export function urlTemplate(path, declared) {
+    if (declared.size === 0) return JSON.stringify(path);
+    let out = "";
+    let last = 0;
+    for (const match of path.matchAll(/\{([^}]*)\}/g)) {
+        const name = match[1];
+        if (!declared.has(name)) {
+            throw new Error(
+                `OpenAPI path ${JSON.stringify(path)}: placeholder ${JSON.stringify(name)} is not a declared path parameter.`,
+            );
+        }
+        out +=
+            templateText(path.slice(last, match.index)) +
+            "${encodeIdSegment(" +
+            declared.get(name) +
+            ")}";
+        last = match.index + match[0].length;
+    }
+    out += templateText(path.slice(last));
+    return "`" + out + "`";
+}

package/bin/lib/openapi/generate.encode.test.mjs

@@ -0,0 +1,120 @@
+import ts from "typescript";
+import { describe, expect, it } from "vitest";
+
+import { encodeIdSegment } from "../../../src/data";
+import { createApiClient } from "../../../src/http";
+import { generate } from "./generate.mjs";
+
+const BASE = "https://api.example.test";
+
+/**
+ * Transpile one generated `service.ts` and load it as CommonJS, resolving
+ * `tempest-react-sdk` to the SDK's real source — so the call goes through the
+ * genuine `encodeIdSegment` and `createApiClient`, not a stub of either.
+ *
+ * @param {string} source - The generated `service.ts` contents.
+ * @returns {Record<string, unknown>} The module's exports.
+ */
+function load(source) {
+    const { outputText } = ts.transpileModule(source, {
+        compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022 },
+    });
+    const module = { exports: {} };
+    const require = (id) => {
+        if (id === "tempest-react-sdk") return { encodeIdSegment };
+        throw new Error(`unexpected import ${id}`);
+    };
+    new Function("exports", "require", "module", outputText)(module.exports, require, module);
+    return module.exports;
+}
+
+/**
+ * Generate a one-route `comments` service (`GET`/`DELETE /api/comments/{id}`)
+ * bound to a real `ApiClient` whose `fetcher` records every request.
+ *
+ * @param {object} [schema] - The `id` path parameter's schema.
+ * @param {string} [baseURL] - The client's base URL.
+ * @returns {{ service: Record<string, Function>, seen: string[], source: string }}
+ */
+function commentsService(schema = { type: "string" }, baseURL = BASE) {
+    const op = (operationId) => ({
+        operationId,
+        tags: ["comments"],
+        parameters: [{ name: "id", in: "path", required: true, schema }],
+        responses: { 204: { description: "x" } },
+    });
+    const { files } = generate({
+        openapi: "3.1.0",
+        info: { title: "t", version: "1" },
+        paths: { "/api/comments/{id}": { get: op("getComment"), delete: op("deleteComment") } },
+    });
+    const source = files["comments/service.ts"];
+    const seen = [];
+    const api = createApiClient({
+        baseURL,
+        getToken: () => "DUMMY_TOKEN",
+        fetcher: async (url, init) => {
+            seen.push(`${init?.method ?? "GET"} ${String(url)}`);
+            return new Response(null, { status: 204 });
+        },
+    });
+    const { CommentsService } = load(source);
+    return { service: new CommentsService(api), seen, source };
+}
+
+describe("generate — path params are encoded into one segment (#499, as #438 did for the data provider)", () => {
+    it.each([
+        ["../../account", "..%2F..%2Faccount"],
+        ["../x", "..%2Fx"],
+        ["%2e%2e/%2e%2e/account", "%252e%252e%2F%252e%252e%2Faccount"],
+        ["7?a=b", "7%3Fa%3Db"],
+        ["7?role=admin", "7%3Frole%3Dadmin"],
+        ["7#x", "7%23x"],
+    ])("a hostile id %j stays one segment under /api/comments", async (id, segment) => {
+        const { service, seen } = commentsService();
+        await service.deleteComment(id);
+        expect(seen).toEqual([`DELETE ${BASE}/api/comments/${segment}`]);
+    });
+
+    it("a base URL prefix cannot be escaped with extra dot-segments", async () => {
+        const { service, seen } = commentsService({ type: "string" }, `${BASE}/v1`);
+        await service.deleteComment("../../../account");
+        expect(seen).toEqual([`DELETE ${BASE}/v1/api/comments/..%2F..%2F..%2Faccount`]);
+    });
+
+    it.each(["", ".", ".."])("the dot-segment id %j throws before any request", async (id) => {
+        const { service, seen } = commentsService();
+        await expect(service.deleteComment(id)).rejects.toThrow(TypeError);
+        expect(seen).toEqual([]);
+    });
+
+    it("null and undefined from an untyped caller throw instead of becoming a literal segment", async () => {
+        const { service, seen } = commentsService();
+        await expect(service.getComment(null)).rejects.toThrow(TypeError);
+        await expect(service.getComment(undefined)).rejects.toThrow(TypeError);
+        expect(seen).toEqual([]);
+    });
+
+    it("a numeric id is still sent as its decimal segment", async () => {
+        const { service, seen, source } = commentsService({ type: "integer" });
+        expect(source).toContain("async getComment(id: number): Promise<void>");
+        await service.getComment(7);
+        expect(seen).toEqual([`GET ${BASE}/api/comments/7`]);
+    });
+
+    it.each([
+        ["a boolean", { type: "boolean" }, true, "true"],
+        ["an array", { type: "array", items: { type: "string" } }, ["a", "b/c"], "a%2Cb%2Fc"],
+        ["a nullable string", { type: ["string", "null"] }, "a/b", "a%2Fb"],
+    ])("%s path param is encoded too", async (_kind, schema, value, segment) => {
+        const { service, seen } = commentsService(schema);
+        await service.getComment(value);
+        expect(seen).toEqual([`GET ${BASE}/api/comments/${segment}`]);
+    });
+
+    it("a nullable path param still rejects null at runtime", async () => {
+        const { service, seen } = commentsService({ type: ["string", "null"] });
+        await expect(service.getComment(null)).rejects.toThrow(TypeError);
+        expect(seen).toEqual([]);
+    });
+});