tempest-react-sdk 0.77.0 → 0.79.0

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

@@ -1,4 +1,11 @@
-import { describe, it, expect } from "vitest";
+// @vitest-environment node
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { ESLint } from "eslint";
+import ts from "typescript";
+import { describe, expect, it } from "vitest";
+
 import { generate } from "./generate.mjs";
 
 const SPEC = {
@@ -122,8 +129,268 @@ 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";');
+    });
+});
+
+const TEMPLATE = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "template");
+const OUT = join(TEMPLATE, "src", "__generated_api__");
+
+/**
+ * The `create-tempest-app` template's own compiler options, read from
+ * `template/tsconfig.json` so the check follows the template when it changes:
+ * `strict`, `noUnusedLocals`, `noUnusedParameters`, `verbatimModuleSyntax`.
+ * `types` is dropped because `vite/client` is not installed at the repo root, and
+ * `paths` because nothing generated uses the alias.
+ *
+ * @returns {import("typescript").CompilerOptions}
+ */
+function templateCompilerOptions() {
+    const { config } = ts.readConfigFile(join(TEMPLATE, "tsconfig.json"), ts.sys.readFile);
+    const { types: _types, paths: _paths, ...json } = config.compilerOptions;
+    const { options, errors } = ts.convertCompilerOptionsFromJson(json, TEMPLATE);
+    expect(errors).toEqual([]);
+    return options;
+}
+
+/**
+ * Type-check the whole generator output as an app scaffolded by
+ * `create-tempest-app` would: every group and the root barrel, under the
+ * template's compiler options. Files live in a virtual `template/src/` folder so
+ * `zod` resolves from the repository's `node_modules`; `tempest-react-sdk` is a
+ * stub with the types and the `encodeIdSegment` value the generator imports.
+ *
+ * @param {Record<string, string>} files - The generator output.
+ * @returns {string[]} `file: TSxxxx message` for every diagnostic.
+ */
+function templateTsc(files) {
+    const virtual = new Map(Object.entries(files).map(([f, text]) => [join(OUT, f), text]));
+    virtual.set(
+        join(OUT, "node_modules", "tempest-react-sdk", "index.d.ts"),
+        [
+            "type Call = <T = unknown>(url: string, opts?: { body?: unknown; params?: Record<string, string | number | boolean | undefined | null> }) => Promise<T>;",
+            "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 = templateCompilerOptions();
+    const host = ts.createCompilerHost(options);
+    const readFile = host.readFile.bind(host);
+    const fileExists = host.fileExists.bind(host);
+    const directoryExists = host.directoryExists?.bind(host);
+    const getSourceFile = host.getSourceFile.bind(host);
+    host.readFile = (f) => virtual.get(f) ?? readFile(f);
+    host.fileExists = (f) => virtual.has(f) || fileExists(f);
+    host.directoryExists = (d) => d.startsWith(OUT) || (directoryExists?.(d) ?? true);
+    host.getSourceFile = (f, lang) =>
+        virtual.has(f) ? ts.createSourceFile(f, virtual.get(f), lang) : getSourceFile(f, lang);
+    const roots = Object.keys(files).map((f) => join(OUT, f));
+    return ts
+        .getPreEmitDiagnostics(ts.createProgram(roots, options, host))
+        .map(
+            (d) =>
+                `${d.file ? d.file.fileName.slice(OUT.length + 1) : "(global)"}: TS${d.code} ${ts.flattenDiagnosticMessageText(d.messageText, " ")}`,
+        );
+}
+
+let eslint;
+
+/**
+ * Lint the generator output with the template's `eslint.config.js`, as `npm run
+ * lint` in a scaffolded app would. Warnings count too: a scaffolded app should
+ * not open on a yellow lint run because of a generated file.
+ *
+ * @param {Record<string, string>} files - The generator output.
+ * @returns {Promise<string[]>} `file line:col rule` for every message.
+ */
+async function templateLint(files) {
+    eslint ??= new ESLint({
+        cwd: TEMPLATE,
+        overrideConfigFile: join(TEMPLATE, "eslint.config.js"),
+    });
+    const out = [];
+    for (const [file, text] of Object.entries(files)) {
+        const [result] = await eslint.lintText(text, { filePath: join(OUT, file) });
+        for (const m of result.messages) out.push(`${file} ${m.line}:${m.column} ${m.ruleId}`);
+    }
+    return out;
+}
+
+const ref = (name) => ({ $ref: `#/components/schemas/${name}` });
+const json = (schema) => ({ content: { "application/json": { schema } } });
+
+/**
+ * One spec that puts a `$ref` in every position the generator reads, plus a group
+ * with no schema at all. Measured on `main` before #504/#505 under the template's
+ * `tsc` and ESLint, it produced:
+ *
+ * | Position | Failure before the fix |
+ * | --- | --- |
+ * | path param `$ref` reached by nothing else (the #504 repro, own test below) | TS2304 `Cannot find name 'Kind'` — the type was neither imported nor emitted into `types.ts` |
+ * | query param `$ref` (`sort`) | no error, but typed `string`: the enum name was narrowed away |
+ * | response-only group | `S` imported unused — TS6133 and `unused-imports/no-unused-imports` |
+ * | page envelope / nested schema | `ItemPage` and `Owner` imported unused into `service.ts` |
+ * | `OffsetPage` + `CursorPage` together | `simple-import-sort/imports` (pushed in that order) |
+ * | group without schema | `z` / `S` unused in `schemas.ts`/`types.ts`, double blank line in `service.ts`, extra blank lines at EOF (`no-multiple-empty-lines`) |
+ * | every `types.ts` | `import * as S` used only in `typeof` — `@typescript-eslint/consistent-type-imports` |
+ * | every `index.ts` + root barrel | `simple-import-sort/exports` |
+ *
+ * Header parameters and path-item-level `parameters` are not read by the
+ * generator at all, so they cannot produce an import.
+ */
+const EVERY_POSITION = {
+    openapi: "3.1.0",
+    components: {
+        schemas: {
+            Kind: { type: "string", enum: ["a", "b"] },
+            Sort: { type: "string", enum: ["asc", "desc"] },
+            Code: { type: "integer" },
+            Owner: { type: "object", properties: { name: { type: "string" } } },
+            Item: {
+                type: "object",
+                required: ["id"],
+                properties: { id: { type: "integer" }, owner: ref("Owner") },
+            },
+            ItemCreate: { type: "object", properties: { kind: ref("Kind") } },
+            ItemPage: {
+                type: "object",
+                properties: {
+                    items: { type: "array", items: ref("Item") },
+                    total: { type: "integer" },
+                    pages: { type: "integer" },
+                    size: { type: "integer" },
+                },
+            },
+            ItemFeed: {
+                type: "object",
+                properties: {
+                    items: { type: "array", items: ref("Item") },
+                    next_cursor: { type: "string", nullable: true },
+                    has_more: { type: "boolean" },
+                },
+            },
+        },
+    },
+    paths: {
+        "/items/{kind}": {
+            get: {
+                tags: ["items"],
+                operationId: "list_by_kind",
+                parameters: [
+                    { name: "kind", in: "path", required: true, schema: ref("Kind") },
+                    { name: "sort", in: "query", schema: ref("Sort") },
+                    { name: "codes", in: "query", schema: { type: "array", items: ref("Code") } },
+                    { name: "X-Trace", in: "header", schema: ref("Code") },
+                ],
+                responses: { 200: json({ type: "array", items: ref("Item") }) },
+            },
+        },
+        "/items": {
+            get: {
+                tags: ["items"],
+                operationId: "page",
+                responses: { 200: json(ref("ItemPage")) },
+            },
+            post: {
+                tags: ["items"],
+                operationId: "create_many",
+                requestBody: json({ type: "array", items: ref("ItemCreate") }),
+                responses: { 201: json(ref("Item")) },
+            },
+        },
+        "/feed": {
+            get: {
+                tags: ["items"],
+                operationId: "feed",
+                responses: { 200: json(ref("ItemFeed")) },
+            },
+        },
+        "/reports": {
+            get: {
+                tags: ["reports"],
+                responses: { 200: json({ type: "array", items: ref("Item") }) },
+            },
+        },
+        "/ping": { get: { tags: ["health"], responses: { 200: { description: "ok" } } } },
+    },
+};
+
+describe("generate — output passes the create-tempest-app template's tsc and ESLint (#504, #505)", () => {
+    const { files } = generate(EVERY_POSITION);
+
+    it("a path parameter typed by a $ref imports and declares the type it names (#504)", () => {
+        const minimal = generate({
+            openapi: "3.1.0",
+            components: { schemas: { Kind: { type: "string", enum: ["a", "b"] } } },
+            paths: {
+                "/items/{kind}": {
+                    get: {
+                        tags: ["items"],
+                        operationId: "get_item",
+                        parameters: [
+                            { name: "kind", in: "path", required: true, schema: ref("Kind") },
+                        ],
+                        responses: { 200: { description: "ok" } },
+                    },
+                },
+            },
+        }).files;
+        expect(minimal["items/service.ts"]).toContain("async getItem(kind: Kind): Promise<void>");
+        expect(minimal["items/service.ts"]).toContain('import type { Kind } from "./types";');
+        expect(minimal["items/types.ts"]).toContain("export type Kind = ");
+        expect(minimal["items/schemas.ts"]).toContain(
+            'export const KindSchema = z.enum(["a", "b"]);',
+        );
+        expect(templateTsc(minimal)).toEqual([]);
+    });
+
+    it("a query parameter typed by a scalar $ref keeps its name instead of being narrowed to string", () => {
+        const svc = files["items/service.ts"];
+        expect(svc).toContain('params: { "sort"?: Sort; "codes"?: string }');
+        expect(svc).toMatch(/import type \{[^}]*\bSort\b[^}]*\} from "\.\/types";/);
+    });
+
+    it("service.ts imports only the types its signatures name, and S only when a body is validated", () => {
+        expect(files["items/service.ts"]).toContain(
+            'import type { Item, ItemCreate, Kind, Sort } from "./types";',
+        );
+        expect(files["items/service.ts"]).not.toContain('import * as S from "./schemas";');
+        expect(files["reports/service.ts"]).not.toContain("./schemas");
+        expect(files["items/service.ts"]).toContain(
+            'import type { ApiClient, CursorPage, OffsetPage } from "tempest-react-sdk";',
+        );
+    });
+
+    it("a group without any schema imports neither z nor S and has no double blank line (#505)", () => {
+        expect(files["health/schemas.ts"]).toBe("export {};\n");
+        expect(files["health/types.ts"]).toBe("export {};\n");
+        expect(files["health/service.ts"]).not.toMatch(/\n\n\n/);
+        expect(files["health/service.ts"]).toMatch(
+            /^import type \{ ApiClient \} from "tempest-react-sdk";\n\n\/\*\*/,
+        );
+    });
+
+    it("type-checks under the template's tsconfig (strict, noUnusedLocals, verbatimModuleSyntax)", () => {
+        expect(templateTsc(files)).toEqual([]);
+    });
+
+    it("lints clean under the template's eslint.config.js, warnings included", async () => {
+        expect(await templateLint(files)).toEqual([]);
+    });
+
+    it("the FastAPI-style spec above passes both too", async () => {
+        const out = generate(SPEC).files;
+        expect(out["users/service.ts"]).toContain('import * as S from "./schemas";');
+        expect(templateTsc(out)).toEqual([]);
+        expect(await templateLint(out)).toEqual([]);
     });
 });

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

@@ -14,9 +14,10 @@ export function refName(ref) {
 
 /**
  * Names the generated files declare, import or rely on as globals next to the
- * schema types: the SDK types `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.
+ * 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",
@@ -25,6 +26,7 @@ export const GENERATED_NAMES = new Set([
     "Promise",
     "Record",
     "S",
+    "encodeIdSegment",
     "z",
 ]);
 

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