tempest-react-sdk 0.77.0 → 0.79.0

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

@@ -180,13 +180,23 @@ function templateText(text) {
  *
  * 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 `${identifier}`, the variable that parameter was mapped to
- * (`{user-id}` → `${userId}`). A path without placeholders is emitted as a JSON
- * string literal.
+ * 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 → identifier of each of
- *   the operation's `in: "path"` params.
+ * @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.
@@ -202,7 +212,11 @@ export function urlTemplate(path, declared) {
                 `OpenAPI path ${JSON.stringify(path)}: placeholder ${JSON.stringify(name)} is not a declared path parameter.`,
             );
         }
-        out += templateText(path.slice(last, match.index)) + "${" + declared.get(name) + "}";
+        out +=
+            templateText(path.slice(last, match.index)) +
+            "${encodeIdSegment(" +
+            declared.get(name) +
+            ")}";
         last = match.index + match[0].length;
     }
     out += templateText(path.slice(last));

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([]);
+    });
+});

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

@@ -6,6 +6,7 @@ import vm from "node:vm";
 import ts from "typescript";
 import { describe, expect, it } from "vitest";
 
+import { encodeIdSegment } from "../../../src/data";
 import { generate } from "./generate.mjs";
 
 const require = createRequire(import.meta.url);
@@ -14,7 +15,9 @@ const require = createRequire(import.meta.url);
  *
  * The context gets its own `globalThis`, so any `globalThis.PWNED_*` an injected
  * statement sets lands on `context` and the test can read it back. `zod` is the
- * real package; `./schemas` resolves to the module evaluated before it.
+ * real package, `tempest-react-sdk` exposes the real `encodeIdSegment` every path
+ * parameter goes through (#499); `./schemas` resolves to the module evaluated
+ * before it.
  *
  * @param {string} source - The generated `.ts` contents.
  * @param {object} context - The VM context shared by the group's files.
@@ -33,7 +36,8 @@ function evaluate(source, context, modules) {
     const module = { exports: {} };
     const localRequire = (id) => {
         if (id in modules) return modules[id];
-        if (id === "zod" || id === "tempest-react-sdk") return id === "zod" ? require("zod") : {};
+        if (id === "zod") return require("zod");
+        if (id === "tempest-react-sdk") return { encodeIdSegment };
         throw new Error(`unexpected import ${id}`);
     };
     vm.runInContext(`(function (exports, require, module) {\n${outputText}\n})`, context)(
@@ -398,7 +402,7 @@ const REPO = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
  *
  * Files live in a virtual folder under the repository so `zod` resolves from its
  * `node_modules`; `tempest-react-sdk` is swapped for a stub with the three types
- * the generator imports from it.
+ * and the `encodeIdSegment` value the generator imports from it.
  *
  * @param {Record<string, string>} files - The generator output.
  * @param {string} slug - The group folder.
@@ -409,7 +413,7 @@ function typecheck(files, slug) {
     const virtual = new Map(
         ["schemas.ts", "types.ts", "service.ts"].map((f) => [
             join(root, f),
-            files[`${slug}/${f}`].replace('from "tempest-react-sdk"', 'from "./sdk"'),
+            files[`${slug}/${f}`].replaceAll('from "tempest-react-sdk"', 'from "./sdk"'),
         ]),
     );
     virtual.set(
@@ -419,6 +423,7 @@ function typecheck(files, slug) {
             "export type ApiClient = { get: Call; post: Call; put: Call; patch: Call; delete: Call };",
             "export type OffsetPage<T> = { items: T[]; total: number };",
             "export type CursorPage<T> = { items: T[]; next_cursor: string | null };",
+            "export declare function encodeIdSegment(id: string | number): string;",
         ].join("\n"),
     );
     const options = {
@@ -451,11 +456,11 @@ const JSON_BODY = (ref) => ({
 const JSON_OK = (ref) => ({ 200: JSON_BODY(ref) });
 
 describe("generate — names that collide with what the generator itself declares", () => {
-    it("a path parameter named body, params or S is renamed, not duplicated or shadowing", async () => {
+    it("a path parameter named body, params, S or encodeIdSegment is renamed, not duplicated or shadowing", async () => {
         const { files } = generate(
             spec(
                 {
-                    "/a/{body}/{params}/{S}": {
+                    "/a/{body}/{params}/{S}/{encodeIdSegment}": {
                         post: {
                             tags: ["t"],
                             operationId: "send",
@@ -463,6 +468,7 @@ describe("generate — names that collide with what the generator itself declare
                                 { name: "body", in: "path", required: true },
                                 { name: "params", in: "path", required: true },
                                 { name: "S", in: "path", required: true },
+                                { name: "encodeIdSegment", in: "path", required: true },
                                 { name: "q", in: "query" },
                             ],
                             requestBody: JSON_BODY("Req"),
@@ -479,8 +485,11 @@ describe("generate — names that collide with what the generator itself declare
         const mod = evaluate(files["t/service.ts"], context, { "./schemas": S });
         const calls = [];
         const api = { post: async (url, opts) => calls.push({ url, opts }) };
-        await new mod.TService(api).send("b", "p", "s", { k: 1 }, { q: "x" });
-        expect(calls).toEqual([{ url: "/a/b/p/s", opts: { body: { k: 1 }, params: { q: "x" } } }]);
+        await new mod.TService(api).send("b", "p", "s", "e/x", { k: 1 }, { q: "x" });
+        expect(files["t/service.ts"]).toContain("${encodeIdSegment(encodeIdSegmentParam)}");
+        expect(calls).toEqual([
+            { url: "/a/b/p/s/e%2Fx", opts: { body: { k: 1 }, params: { q: "x" } } },
+        ]);
     });
 
     it("an operationId of constructor or api becomes a distinct method", async () => {
@@ -541,7 +550,16 @@ describe("generate — names that collide with what the generator itself declare
                 size: { type: "integer" },
             },
         };
-        const names = ["ApiClient", "OffsetPage", "CursorPage", "Promise", "Record", "z", "S"];
+        const names = [
+            "ApiClient",
+            "OffsetPage",
+            "CursorPage",
+            "Promise",
+            "Record",
+            "z",
+            "S",
+            "encodeIdSegment",
+        ];
         const paths = Object.fromEntries(
             names.map((n, i) => [
                 `/n${i}`,
@@ -556,10 +574,21 @@ describe("generate — names that collide with what the generator itself declare
                 },
             },
         };
+        paths["/p/{id}"] = {
+            get: {
+                tags: ["t"],
+                parameters: [{ name: "id", in: "path", required: true }],
+                responses: OK,
+            },
+        };
         const schemas = Object.fromEntries(names.map((n) => [n, { type: "object" }]));
         schemas.Page = page;
         const { files } = generate(spec(paths, schemas));
         expect(files["t/service.ts"]).toContain("OffsetPage<_Promise>");
+        expect(files["t/service.ts"]).toContain(
+            'import { encodeIdSegment } from "tempest-react-sdk";',
+        );
+        expect(files["t/types.ts"]).toContain("export type _encodeIdSegment =");
         expect(typecheck(files, "t")).toEqual([]);
     });