tempest-react-sdk 0.76.0 → 0.78.0

package/bin/lib/openapi/generate.mjs

@@ -1,6 +1,7 @@
 // OpenAPI 3.x → per-tag { schemas.ts (Zod), types.ts, service.ts (class) }.
 // Pure: takes the parsed spec object, returns a { path: contents } map. No I/O.
-import { refName, zodName, schemaToZod } from "./schema-to-zod.mjs";
+import { assertNoCollision, commentText, toIdentifier, urlTemplate } from "./escape.mjs";
+import { refName, schemaToZod, typeName, zodName } from "./schema-to-zod.mjs";
 
 const HTTP_METHODS = ["get", "post", "put", "patch", "delete"];
 
@@ -20,19 +21,91 @@ function pascal(s) {
     return s.replace(/(^|[^a-zA-Z0-9])([a-zA-Z0-9])/g, (_, _b, ch) => ch.toUpperCase());
 }
 
-/** camelCase method name from operationId or method+path. */
+/**
+ * camelCase method name from operationId or method+path.
+ *
+ * The result only ever holds `[a-zA-Z0-9]`, so it cannot carry code; an
+ * operationId that sanitizes to nothing, or to a leading digit, falls back to
+ * the method+path name and is otherwise prefixed with `_` to stay an identifier.
+ */
 function methodName(op, method, path) {
-    if (op.operationId) {
+    if (typeof op.operationId === "string") {
         const id = op.operationId.replace(/[^a-zA-Z0-9]+(.)?/g, (_, ch) =>
             ch ? ch.toUpperCase() : "",
         );
-        return id.charAt(0).toLowerCase() + id.slice(1);
+        if (/^[a-zA-Z]/.test(id)) return id.charAt(0).toLowerCase() + id.slice(1);
     }
     const parts = path
         .split("/")
         .filter(Boolean)
-        .map((p) => p.replace(/[{}]/g, ""));
-    return method + parts.map((p) => pascal(p)).join("");
+        .map((p) => pascal(p).replace(/[^a-zA-Z0-9]/g, ""));
+    return method + parts.join("");
+}
+
+/**
+ * Member names every generated service class already has: the constructor and the
+ * injected `api` property. An operation whose method name lands on one of them is
+ * deduplicated like any other collision (`constructor2`, `api2`).
+ */
+const CLASS_MEMBERS = ["constructor", "api"];
+
+/**
+ * Names a generated method body uses besides its path parameters: the `body` and
+ * `params` arguments, the `S` schemas import and the `encodeIdSegment` import. A
+ * path parameter that maps to one of them becomes `<name>Param` (`{body}` →
+ * `bodyParam`), so it neither duplicates an argument nor shadows the import.
+ */
+const METHOD_LOCALS = new Set(["body", "params", "S", "encodeIdSegment"]);
+
+/**
+ * Whether a path parameter's schema only ever produces a `string` or a `number` —
+ * the types `encodeIdSegment(id: string | number)` accepts — so the generated call
+ * can pass the argument as is.
+ *
+ * `$ref` chains are followed, and `anyOf`/`oneOf`/single-member `allOf` qualify
+ * when every branch does. `null`, `boolean`, arrays, objects and anything
+ * unrecognised do not.
+ *
+ * @param {object | undefined} schema - The parameter's schema.
+ * @param {Record<string, object>} schemas - `components.schemas`.
+ * @param {number} [depth] - Recursion guard for self-referencing unions.
+ * @returns {boolean} `true` when the TypeScript type is assignable to `string | number`.
+ */
+function isSegmentScalar(schema, schemas, depth = 0) {
+    const node = resolveSchema(schema, schemas);
+    if (!node || typeof node !== "object" || depth > 16) return false;
+    const branches = node.anyOf ?? node.oneOf ?? (node.allOf?.length === 1 ? node.allOf : null);
+    if (branches) return branches.every((b) => isSegmentScalar(b, schemas, depth + 1));
+    if (node.nullable || Array.isArray(node.type)) return false;
+    return node.type === "string" || node.type === "integer" || node.type === "number";
+}
+
+/**
+ * Check every `pattern` in a schema compiles as a JavaScript regex.
+ *
+ * The generated Zod schema builds it with `new RegExp(...)` when the module is
+ * imported, so an invalid one would only surface in the app at runtime — a blank
+ * screen. Failing here names the schema and where in it the pattern sits.
+ *
+ * @param {unknown} node - The schema (sub)node.
+ * @param {string} schema - The component schema name, for the error.
+ * @param {string[]} [at] - Keys from the schema root to `node`.
+ * @throws {Error} When a pattern does not compile.
+ */
+function assertPatterns(node, schema, at = []) {
+    if (!node || typeof node !== "object") return;
+    if (typeof node.pattern === "string") {
+        try {
+            new RegExp(node.pattern);
+        } catch (err) {
+            throw new Error(
+                `OpenAPI schema ${JSON.stringify(schema)} at ${at.join(".") || "(root)"}: pattern ${JSON.stringify(node.pattern)} is not a valid JavaScript regular expression (${err.message}).`,
+            );
+        }
+    }
+    for (const [key, value] of Object.entries(node)) {
+        if (key !== "pattern") assertPatterns(value, schema, [...at, key]);
+    }
 }
 
 /** Collect component-schema names referenced (transitively) by a schema node. */
@@ -58,7 +131,7 @@ function collectRefs(node, schemas, acc = new Set(), seen = new Set()) {
 /** TS type expression for a schema node (uses generated type names for $refs). */
 function tsType(schema) {
     if (!schema || typeof schema !== "object") return "unknown";
-    if (schema.$ref) return refName(schema.$ref);
+    if (schema.$ref) return typeName(refName(schema.$ref));
     if (schema.allOf) return schema.allOf.map(tsType).join(" & ");
     if (schema.anyOf || schema.oneOf) {
         const parts = (schema.anyOf ?? schema.oneOf).map(tsType);
@@ -189,6 +262,10 @@ function bodySchema(op) {
  */
 export function generate(doc) {
     const schemas = doc.components?.schemas ?? {};
+    assertNoCollision(
+        Object.keys(schemas).map((n) => [n, typeName(n)]),
+        "schema names",
+    );
     const groups = new Map(); // slug → { tag, ops: [...] }
 
     for (const [path, item] of Object.entries(doc.paths ?? {})) {
@@ -202,12 +279,17 @@ export function generate(doc) {
         }
     }
 
+    assertNoCollision(
+        [...groups.keys()].map((slug) => [slug, slugIdent(slug)]),
+        "tags (as barrel names)",
+    );
+
     const files = {};
     const tags = [];
 
     for (const { tag, slug, ops } of groups.values()) {
         tags.push(tag);
-        const Class = `${pascal(slug)}Service`;
+        const Class = `${slugIdent(pascal(slug))}Service`;
 
         // 1. Which component schemas does this group touch (transitively)?
         const used = new Set();
@@ -218,6 +300,7 @@ export function generate(doc) {
             if (r) collectRefs(r, schemas, used);
         }
         const { sorted, cyclic } = topoSort(used, schemas);
+        for (const name of sorted) assertPatterns(schemas[name], name);
 
         // 2. schemas.ts
         const schemaLines = sorted.map((name) => {
@@ -231,17 +314,17 @@ export function generate(doc) {
 
         // 3. types.ts
         const typeLines = sorted.map(
-            (name) => `export type ${name} = z.infer<typeof S.${zodName(name)}>;`,
+            (name) => `export type ${typeName(name)} = z.infer<typeof S.${zodName(name)}>;`,
         );
         files[`${slug}/types.ts`] =
             `import type { z } from "zod";\n\nimport * as S from "./schemas";\n\n${typeLines.join("\n")}\n`;
 
         // 4. service.ts
-        const usedNames = new Set();
+        const usedNames = new Set(CLASS_MEMBERS);
         const methods = ops.map(({ method, path, op }) =>
             emitMethod(method, path, op, schemas, usedNames),
         );
-        const usedTypeNames = [...used].sort();
+        const usedTypeNames = [...used].map(typeName).sort();
         const typeImport = usedTypeNames.length
             ? `import type { ${usedTypeNames.join(", ")} } from "./types";\n`
             : "";
@@ -251,11 +334,16 @@ export function generate(doc) {
         const sdkTypes = ["ApiClient"];
         if (body.includes("OffsetPage<")) sdkTypes.push("OffsetPage");
         if (body.includes("CursorPage<")) sdkTypes.push("CursorPage");
+        const sdkValues = body.includes("encodeIdSegment(")
+            ? `import { encodeIdSegment } from "tempest-react-sdk";\n`
+            : "";
         files[`${slug}/service.ts`] =
-            `import type { ${sdkTypes.join(", ")} } from "tempest-react-sdk";\n\n` +
+            `import type { ${sdkTypes.join(", ")} } from "tempest-react-sdk";\n` +
+            sdkValues +
+            "\n" +
             schemaImport +
             typeImport +
-            `\n/** Generated service for the "${tag}" routes. Inject an ApiClient (createApiClient). */\n` +
+            `\n/** Generated service for the "${commentText(tag)}" routes. Inject an ApiClient (createApiClient). */\n` +
             `export class ${Class} {\n` +
             `    constructor(private readonly api: ApiClient) {}\n\n` +
             body +
@@ -287,6 +375,29 @@ function emitMethod(method, path, op, schemas, usedNames = new Set()) {
     }
     usedNames.add(name);
     const pathParams = (op.parameters ?? []).filter((p) => p.in === "path");
+    const where = `${method.toUpperCase()} ${path}`;
+    const paramId = (name) => {
+        const id = toIdentifier(name, "camel", `path parameter in ${where}`);
+        return METHOD_LOCALS.has(id) ? `${id}Param` : id;
+    };
+    const paramIds = new Map(pathParams.map((p) => [p.name, paramId(p.name)]));
+    const segmentArgs = new Map(
+        pathParams.map((p) => {
+            const id = paramIds.get(p.name);
+            const schema = p.schema ?? { type: "string" };
+            return [p.name, isSegmentScalar(schema, schemas) ? id : `${id} as never`];
+        }),
+    );
+    assertNoCollision(
+        [
+            ...[...paramIds],
+            ...(bodySchema(op) ? [["the request body argument", "body"]] : []),
+            ...((op.parameters ?? []).some((p) => p.in === "query")
+                ? [["the query argument", "params"]]
+                : []),
+        ],
+        `method arguments of ${where}`,
+    );
     const queryParams = (op.parameters ?? []).filter((p) => p.in === "query");
     const body = bodySchema(op);
     const resp = successSchema(op);
@@ -299,7 +410,9 @@ function emitMethod(method, path, op, schemas, usedNames = new Set()) {
           : "void";
 
     const args = [];
-    for (const p of pathParams) args.push(`${p.name}: ${tsType(p.schema ?? { type: "string" })}`);
+    for (const p of pathParams) {
+        args.push(`${paramIds.get(p.name)}: ${tsType(p.schema ?? { type: "string" })}`);
+    }
     if (body) args.push(`body: ${tsType(body)}`);
     if (queryParams.length) {
         const q = queryParams
@@ -311,9 +424,7 @@ function emitMethod(method, path, op, schemas, usedNames = new Set()) {
         args.push(`params: { ${q} }`);
     }
 
-    // Interpolate path params into a template literal.
-    const tpl = path.replace(/{([^}]+)}/g, (_, n) => "${" + n + "}");
-    const url = pathParams.length ? `\`${tpl}\`` : JSON.stringify(path);
+    const url = urlTemplate(path, segmentArgs);
 
     const callOpts = [];
     if (body) callOpts.push("body");
@@ -330,7 +441,7 @@ function emitMethod(method, path, op, schemas, usedNames = new Set()) {
     const ret = retType === "void" ? "Promise<void>" : `Promise<${retType}>`;
     const generic = retType === "void" ? "" : `<${retType}>`;
     return (
-        `    /** \`${method.toUpperCase()} ${path}\`${op.summary ? ` — ${op.summary}` : ""} */\n` +
+        `    /** \`${method.toUpperCase()} ${commentText(path)}\`${op.summary ? ` — ${commentText(op.summary)}` : ""} */\n` +
         `    async ${name}(${args.join(", ")}): ${ret} {\n` +
         validation +
         `        return this.api.${method}${generic}(${url}${optsArg});\n` +

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

@@ -122,8 +122,13 @@ describe("generate — FastAPI-style spec", () => {
         // create with Zod input validation
         expect(svc).toContain("S.UserCreateSchema.parse(body);");
         expect(svc).toMatch(/async createUser\(body: UserCreate\): Promise<User>/);
-        // path param interpolation
         expect(svc).toMatch(/async getUser\(id: number\): Promise<User>/);
-        expect(svc).toContain("return this.api.get<User>(`/users/${id}`);");
+    });
+
+    it("wraps every path param in encodeIdSegment — the raw `${id}` this used to pin sent '../../account' to /account with the Bearer (#499, the class #438 closed)", () => {
+        const svc = files["users/service.ts"];
+        expect(svc).not.toContain("`/users/${id}`");
+        expect(svc).toContain("return this.api.get<User>(`/users/${encodeIdSegment(id)}`);");
+        expect(svc).toContain('import { encodeIdSegment } from "tempest-react-sdk";');
     });
 });

package/bin/lib/openapi/schema-to-zod.mjs

@@ -1,14 +1,53 @@
 // JSON Schema (OpenAPI 3.0/3.1 subset) → Zod expression source string.
 // Pure + deterministic so the generated output is stable and testable.
 
-/** Convert a $ref like "#/components/schemas/User" to its schema name ("User"). */
+import { toIdentifier } from "./escape.mjs";
+
+/**
+ * Convert a $ref like "#/components/schemas/User" to its spec schema name
+ * ("User"). This is the lookup key into `components.schemas`, not yet an
+ * identifier: pass it through {@link typeName} before emitting it.
+ */
 export function refName(ref) {
     return ref.slice(ref.lastIndexOf("/") + 1);
 }
 
-/** The generated Zod const name for a schema name (e.g. "User" → "UserSchema"). */
+/**
+ * Names the generated files declare, import or rely on as globals next to the
+ * schema types: the SDK types and the `encodeIdSegment` value `service.ts`
+ * imports, the `z` and `S` imports, and the `Promise` / `Record` globals the
+ * emitted signatures use. A schema with one of these names would collide with
+ * the import or shadow the global.
+ */
+export const GENERATED_NAMES = new Set([
+    "ApiClient",
+    "CursorPage",
+    "OffsetPage",
+    "Promise",
+    "Record",
+    "S",
+    "encodeIdSegment",
+    "z",
+]);
+
+/**
+ * The TypeScript type name for a spec schema name (`user.Response` →
+ * `UserResponse`; a valid identifier is kept as is). A name in
+ * {@link GENERATED_NAMES} gets a `_` prefix (`Promise` → `_Promise`).
+ *
+ * @throws {Error} When the name has nothing to build an identifier from.
+ */
+export function typeName(name) {
+    const id = toIdentifier(name, "pascal", "schema name");
+    return GENERATED_NAMES.has(id) ? `_${id}` : id;
+}
+
+/**
+ * The generated Zod const name for a spec schema name
+ * (`User` → `UserSchema`, `user.Response` → `UserResponseSchema`).
+ */
 export function zodName(name) {
-    return `${name}Schema`;
+    return `${typeName(name)}Schema`;
 }
 
 function isNullable(schema) {
@@ -77,7 +116,7 @@ export function schemaToZod(schema, resolveRef = (ref) => zodName(refName(ref)))
             if (typeof schema.minLength === "number") e += `.min(${schema.minLength})`;
             if (typeof schema.maxLength === "number") e += `.max(${schema.maxLength})`;
             if (typeof schema.pattern === "string")
-                e += `.regex(/${schema.pattern.replace(/\//g, "\\/")}/)`;
+                e += `.regex(new RegExp(${JSON.stringify(schema.pattern)}))`;
             return withModifiers(e, schema);
         }
         case "integer":

package/bin/tempest-gen.test.mjs

@@ -0,0 +1,188 @@
+import { spawnSync } from "node:child_process";
+import {
+    existsSync,
+    mkdirSync,
+    mkdtempSync,
+    readdirSync,
+    readFileSync,
+    rmSync,
+    symlinkSync,
+    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");
+
+const SPEC = {
+    openapi: "3.0.0",
+    info: { title: "t", version: "1" },
+    paths: {
+        "/users": {
+            get: {
+                tags: ["users"],
+                operationId: "listUsers",
+                responses: { 200: { description: "ok" } },
+            },
+        },
+    },
+};
+
+/**
+ * Every file under `dir`, relative, sorted — `[]` when nothing was written.
+ *
+ * @param {string} dir - Absolute folder.
+ * @returns {string[]}
+ */
+function filesUnder(dir) {
+    return readdirSync(dir, { recursive: true }).sort();
+}
+
+describe("tempest gen api / gen icons — write containment (#484)", () => {
+    let cwd;
+    let outside;
+
+    beforeEach(() => {
+        cwd = mkdtempSync(join(tmpdir(), "tempest-gen-cli-"));
+        outside = mkdtempSync(join(tmpdir(), "tempest-gen-outside-"));
+        mkdirSync(join(cwd, "src"));
+        writeFileSync(join(cwd, "spec.json"), JSON.stringify(SPEC));
+    });
+
+    afterEach(() => {
+        rmSync(cwd, { recursive: true, force: true });
+        rmSync(outside, { recursive: true, force: true });
+    });
+
+    /**
+     * Run the `tempest` CLI in the temporary project.
+     *
+     * @param {string[]} args - CLI arguments.
+     * @returns {{ status: number | null, out: string }}
+     */
+    function tempest(...args) {
+        const result = spawnSync(process.execPath, [CLI, ...args], { cwd, encoding: "utf8" });
+        return { status: result.status, out: result.stdout + result.stderr };
+    }
+
+    it("gen api still writes into a regular src/api", () => {
+        const { status } = tempest("gen", "api", "spec.json");
+        expect(status).toBe(0);
+        expect(existsSync(join(cwd, "src", "api", "users", "service.ts"))).toBe(true);
+    });
+
+    it("gen api refuses a src/api that is a symlink leaving the project", () => {
+        symlinkSync(outside, join(cwd, "src", "api"));
+
+        const { status, out } = tempest("gen", "api", "spec.json");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/src\/api is a symlink/);
+        expect(filesUnder(outside)).toEqual([]);
+    });
+
+    it("gen api refuses a symlinked --out even when it points inside the project", () => {
+        mkdirSync(join(cwd, "elsewhere"));
+        symlinkSync(join(cwd, "elsewhere"), join(cwd, "src", "api"));
+
+        const { status, out } = tempest("gen", "api", "spec.json");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/symlink/);
+        expect(filesUnder(join(cwd, "elsewhere"))).toEqual([]);
+    });
+
+    it("gen api refuses a dangling symlink, which writeFile would follow and create", () => {
+        symlinkSync(join(outside, "not-yet"), join(cwd, "src", "api"));
+
+        const { status, out } = tempest("gen", "api", "spec.json");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/symlink/);
+        expect(existsSync(join(outside, "not-yet"))).toBe(false);
+    });
+
+    it("gen api refuses a symlinked route-group folder below --out, before writing anything", () => {
+        mkdirSync(join(cwd, "src", "api"));
+        symlinkSync(outside, join(cwd, "src", "api", "users"));
+
+        const { status, out } = tempest("gen", "api", "spec.json");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/src\/api\/users is a symlink/);
+        expect(filesUnder(outside)).toEqual([]);
+        expect(filesUnder(join(cwd, "src", "api"))).toEqual(["users"]);
+    });
+
+    it("gen api refuses a generated file that is a symlink", () => {
+        mkdirSync(join(cwd, "src", "api"));
+        const victim = join(outside, "victim.ts");
+        writeFileSync(victim, "SENTINEL");
+        symlinkSync(victim, join(cwd, "src", "api", "index.ts"));
+
+        const { status, out } = tempest("gen", "api", "spec.json");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/src\/api\/index\.ts is a symlink/);
+        expect(readFileSync(victim, "utf8")).toBe("SENTINEL");
+    });
+
+    it("gen api refuses an --out whose existing ancestor is a symlink leaving the project", () => {
+        symlinkSync(outside, join(cwd, "gen"));
+
+        const { status, out } = tempest("gen", "api", "spec.json", "--out", "gen/api");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/outside the project/);
+        expect(filesUnder(outside)).toEqual([]);
+    });
+
+    it("gen api refuses an --out outside the project", () => {
+        const { status, out } = tempest("gen", "api", "spec.json", "--out", outside);
+        expect(status).toBe(1);
+        expect(out).toMatch(/outside the project/);
+        expect(filesUnder(outside)).toEqual([]);
+    });
+
+    it("gen icons refuses a src/icons.generated.ts that is a symlink", () => {
+        const victim = join(outside, "victim.ts");
+        writeFileSync(victim, "SENTINEL");
+        symlinkSync(victim, join(cwd, "src", "icons.generated.ts"));
+
+        const { status, out } = tempest("gen", "icons");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/src\/icons\.generated\.ts is a symlink/);
+        expect(readFileSync(victim, "utf8")).toBe("SENTINEL");
+    });
+
+    it("gen icons refuses a dangling symlink at the output", () => {
+        symlinkSync(join(outside, "not-yet.ts"), join(cwd, "src", "icons.generated.ts"));
+
+        const { status, out } = tempest("gen", "icons");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/symlink/);
+        expect(existsSync(join(outside, "not-yet.ts"))).toBe(false);
+    });
+
+    it("gen icons refuses an --out whose folder is a symlink leaving the project", () => {
+        symlinkSync(outside, join(cwd, "gen"));
+
+        const { status, out } = tempest("gen", "icons", "--out", "gen/icons.ts");
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/gen is a symlink/);
+        expect(filesUnder(outside)).toEqual([]);
+    });
+
+    it("gen icons refuses an --out outside the project", () => {
+        const { status, out } = tempest("gen", "icons", "--out", join(outside, "icons.ts"));
+        expect(status).toBe(1);
+        expect(out).toMatch(/outside the project/);
+        expect(filesUnder(outside)).toEqual([]);
+    });
+});