@oj-module/cli 0.1.17 → 0.1.21

package/src/contract/__tests__/check-api.test.ts

@@ -0,0 +1,74 @@
+import type { OpenApiDoc } from "../openapi-ir";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { checkApi } from "../check";
+import { runApi } from "../run";
+
+let dir: string;
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "ojm-check-"));
+});
+afterEach(() => {
+	rmSync(dir, { recursive: true, force: true });
+});
+
+const DOC: OpenApiDoc = {
+	openapi: "3.1.0",
+	paths: {
+		"/v1/api/wiki/collections/{id}": {
+			get: {
+				operationId: "wiki_collections__id__get",
+				tags: ["wiki"],
+				parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
+				responses: {
+					200: {
+						"description": "OK",
+						"x-oj-response-enforced": false,
+						"content": { "application/json": { schema: { type: "object", required: ["code", "msg", "data"], properties: { code: { type: "integer" }, msg: { type: "string" }, data: { type: "string" } } } } },
+					},
+				},
+			},
+		},
+	},
+};
+
+describe("checkApi 消费 openapi.json（新口径 Task #5）", () => {
+	it("__client 缺失 → artifact-stale 报错", async () => {
+		writeFileSync(join(dir, "openapi.json"), JSON.stringify(DOC));
+		const { violations } = await checkApi({ cwd: dir });
+		expect(violations.some(v => v.kind === "artifact-stale")).toBe(true);
+	});
+
+	it("ojm api 生成后重跑 --check → 无 artifact-stale", async () => {
+		writeFileSync(join(dir, "openapi.json"), JSON.stringify(DOC));
+		mkdirSync(join(dir, "web/src/wiki/__client"), { recursive: true });
+		await runApi({ cwd: dir, openapi: "openapi.json" });
+		const { violations } = await checkApi({ cwd: dir });
+		expect(violations.filter(v => v.kind === "artifact-stale").length).toBe(0);
+	});
+});
+
+describe("checkApi 豁免清单（D12/F19）覆盖契约→handler 侧", () => {
+	it("豁免模块的根级路由（route=\"/\" 但 handler .route 为模块名）不误报 route-params-mismatch", async () => {
+		// 模拟 api/.ojm-api-exempt.json 豁免 notifications 模块：oj 为根级兜底端点
+		// 生成 /api/notifications（route 推导为 "/"），而 handler 落在 api/src/notifications
+		// 模块根（实际 .route 即模块名 notifications）——两侧表示不同但线径一致，历史上误报
+		// route-params-mismatch；修复后「契约→handler」侧同样按豁免跳过。
+		writeFileSync(join(dir, "openapi.json"), JSON.stringify({
+			openapi: "3.1.0",
+			paths: {
+				"/v1/api/notifications": {
+					get: { operationId: "notifications_get", tags: ["notifications"], responses: { 200: { description: "OK" } } },
+				},
+			},
+		} satisfies OpenApiDoc));
+		mkdirSync(join(dir, "api/src/notifications"), { recursive: true });
+		writeFileSync(join(dir, "api/src/notifications/api.ts"), "export default { async get() { json.ok([]); } };\n");
+		mkdirSync(join(dir, "api"), { recursive: true });
+		writeFileSync(join(dir, "api/.ojm-api-exempt.json"), JSON.stringify({ modules: ["notifications"], paths: [] }));
+		const { violations } = await checkApi({ cwd: dir });
+		expect(violations.some(v => v.kind === "route-params-mismatch")).toBe(false);
+	});
+});

package/src/contract/__tests__/emit-client.test.ts

@@ -0,0 +1,132 @@
+import type { OpenApiDoc } from "../openapi-ir";
+import { describe, expect, it } from "vitest";
+import { emitClient } from "../emit-client";
+import { irFromOpenapi } from "../openapi-ir";
+
+const DOC: OpenApiDoc = {
+	openapi: "3.1.0",
+	paths: {
+		"/v1/api/wiki/collections/{id}": {
+			get: {
+				"operationId": "wiki_collections__id__get",
+				"tags": ["wiki"],
+				"x-oj-file": "wiki/collections/_id_/api.ts",
+				"parameters": [
+					{ name: "id", in: "path", required: true, schema: { type: "integer", minimum: 1 } },
+					{ name: "page", in: "query", required: false, schema: { type: "integer", minimum: 1 } },
+				],
+				"responses": {
+					200: {
+						"description": "OK",
+						"x-oj-response-enforced": false,
+						"content": {
+							"application/json": {
+								schema: {
+									type: "object",
+									required: ["code", "msg", "data"],
+									properties: {
+										code: { type: "integer" },
+										msg: { type: "string" },
+										data: {
+											type: "object",
+											required: ["list", "total"],
+											properties: {
+												list: { type: "array", items: { type: "object", properties: { id: { type: "integer" } } } },
+												total: { type: "integer", minimum: 0 },
+											},
+										},
+									},
+								},
+							},
+						},
+					},
+				},
+			},
+		},
+		"/v1/api/wiki/collections": {
+			post: {
+				operationId: "wiki_collections_post",
+				tags: ["wiki"],
+				requestBody: {
+					required: true,
+					content: {
+						"application/json": {
+							schema: {
+								type: "object",
+								required: ["title"],
+								additionalProperties: false,
+								properties: { title: { type: "string", maxLength: 80 }, tag: { type: ["string", "null"] } },
+							},
+						},
+					},
+				},
+				responses: { 200: { description: "OK" } },
+			},
+		},
+	},
+};
+
+function emit() {
+	const ir = irFromOpenapi(DOC, { base: "/v1/api" });
+	return emitClient(ir, { target: "module", module: "wiki" });
+}
+
+describe("emitClient (module target)", () => {
+	const { "api.ts": apiTs, "api.schemas.ts": schemasTs } = emit();
+
+	it("aPI_PREFIX / MODULE_PREFIX 用 JSON 字符串字面量（注入安全）", () => {
+		expect(apiTs).toContain("export const API_PREFIX = \"/wiki\";");
+		expect(apiTs).toContain("export const MODULE_PREFIX = \"/wiki\";");
+	});
+
+	it("端点函数名 camelCase", () => {
+		expect(apiTs).toContain("export async function wikiCollectionsIdGet(");
+	});
+
+	it("信封解包到强类型 data（PascalCase 返回类型名）", () => {
+		expect(apiTs).toContain("env.data as WikiCollectionsIdGetData");
+		expect(apiTs).toContain("Promise<WikiCollectionsIdGetData>");
+	});
+
+	it("dEV 下对 data 做 safeParse 校验（契约违例兜底）", () => {
+		expect(apiTs).toContain("schemas[\"wikiCollectionsIdGet\"].data.safeParse(data)");
+	});
+
+	it("客户端不含 z.regex（pattern 不进运行时）", () => {
+		expect(apiTs).not.toContain("z.regex");
+	});
+
+	it("api.schemas.ts 用 JSON 字符串字面量作端点键", () => {
+		expect(schemasTs).toContain("\"wikiCollectionsIdGet\":");
+		expect(schemasTs).toContain("\"wikiCollectionsPost\":");
+	});
+
+	it("params id → z.number().int().min(1)；body tag 类型数组 → .nullable()", () => {
+		expect(schemasTs).toContain("\"id\": z.number().int().min(1)");
+		expect(schemasTs).toContain("\"tag\": z.string().nullable().optional()");
+	});
+
+	it("body additionalProperties:false → .strict()", () => {
+		expect(schemasTs).toContain("}).strict()");
+	});
+});
+
+describe("emitClient 注入安全：模块名含特殊字符不破坏源码", () => {
+	it("module 名含 -/$ 时 MODULE_PREFIX/工厂名仍走字符串字面量（API_PREFIX 取 IR wirePrefix）", () => {
+		const ir = irFromOpenapi(DOC, { base: "/v1/api" });
+		const { "api.ts": apiTs } = emitClient(ir, { target: "module", module: "weird-name" });
+		// module 选项只影响 MODULE_PREFIX 与 create<Module>Client 名
+		expect(apiTs).toContain("export const MODULE_PREFIX = \"/weird-name\";");
+		expect(apiTs).toContain("export function createWeirdNameClient(");
+		// 前缀均为字符串字面量，无裸插值
+		expect(apiTs).not.toContain("MODULE_PREFIX = /weird-name;");
+		// API_PREFIX 取自 IR 的 wirePrefix（/wiki），与 module 选项无关
+		expect(apiTs).toContain("export const API_PREFIX = \"/wiki\";");
+	});
+});
+
+describe("emitClient 空 IR 报错", () => {
+	it("iR 为空抛错（无端点无需生成）", () => {
+		expect(() => emitClient([], { target: "module", module: "x" })).toThrow();
+	});
+});

package/src/contract/__tests__/emit-jsonschema-zod.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import { emitZodFromJsonSchema } from "../emit-jsonschema-zod";
+
+describe("emitZodFromJsonSchema", () => {
+	it("object：required 无 .optional()，其余 .optional()，additionalProperties:false→.strict()", () => {
+		expect(emitZodFromJsonSchema({
+			type: "object",
+			required: ["title"],
+			additionalProperties: false,
+			properties: { title: { type: "string", maxLength: 80 }, remark: { type: "string", nullable: true } },
+		}, "x")).toBe(
+			"z.object({\n\t\"title\": z.string().max(80),\n\t\"remark\": z.string().nullable().optional()\n}).strict()",
+		);
+	});
+
+	it("类型数组 [\"string\",\"null\"] → .nullable()", () => {
+		expect(emitZodFromJsonSchema({ type: ["string", "null"] }, "x")).toBe("z.string().nullable()");
+	});
+
+	it("类型数组 [\"string\",\"number\"]（oj 翻 z.union）→ z.union([z.string(), z.number()])", () => {
+		// oj 把 z.union([z.string(), z.number()]) 翻成类型数组，codegen 必须兜住（映射表补充）
+		expect(emitZodFromJsonSchema({ type: ["string", "number"] }, "x")).toBe("z.union([z.string(), z.number()])");
+	});
+
+	it("类型数组多实类型 + null → z.union(...).nullable()", () => {
+		expect(emitZodFromJsonSchema({ type: ["string", "number", "null"] }, "x"))
+			.toBe("z.union([z.string(), z.number()]).nullable()");
+	});
+
+	it("pattern 不进 z.regex，仅发 // @oj-warn 注释（ReDoS + 跨语言漂移防护）", () => {
+		const out = emitZodFromJsonSchema({ type: "string", pattern: "^[a-z]+$" }, "x");
+		expect(out).toContain("// @oj-warn: pattern=");
+		expect(out).not.toContain("z.regex");
+	});
+
+	it("default 不射 .default()，仅发 // @oj-note 注释", () => {
+		const out = emitZodFromJsonSchema({ type: "integer", default: 0 }, "x");
+		expect(out).toContain("@oj-note: default=0");
+		expect(out).not.toContain(".default(");
+	});
+
+	it("数值 enum → z.union([z.literal...])；字符串 enum → z.enum", () => {
+		// enum 是独立基础类型（zod v4 无 z.number().enum()/z.string().enum()，
+		// 挂在 typed base 后是运行期 TypeError 根因）——故作为 base 整体返回
+		expect(emitZodFromJsonSchema({ type: "integer", enum: [0, 1, 2] }, "x"))
+			.toBe("z.union([z.literal(0), z.literal(1), z.literal(2)])");
+		expect(emitZodFromJsonSchema({ type: "string", enum: ["a", "b"] }, "x"))
+			.toBe("z.enum([\"a\", \"b\"])");
+	});
+
+	it("required 项不在 properties 中 → 不抛错、跳过缺失键", () => {
+		expect(emitZodFromJsonSchema({ type: "object", required: ["ghost"], properties: { a: { type: "string" } } }, "x"))
+			.toBe("z.object({\n\t\"a\": z.string().optional()\n})");
+	});
+
+	it("注入安全：属性名经 JSON.stringify 成字符串字面量键，无裸模板插值", () => {
+		// 拼接构造含 ${
+		// 的键名：字面量里写 ${ 会触发 no-template-curly-in-string
+		const nastyKey = ["a", "$", "{b}"].join("");
+		const out = emitZodFromJsonSchema({ type: "object", properties: { "`": { type: "string" }, [nastyKey]: { type: "string" }, "*/": { type: "string" } } }, "x");
+		expect(out).toMatch(/"a\$\{b\}":/);
+		expect(out).toMatch(/"`":/);
+	});
+
+	it("白名单外关键字 fail-fast", () => {
+		expect(() => emitZodFromJsonSchema({ type: "string", format: "email" } as never, "x")).toThrow();
+	});
+
+	it("array：items + minItems/maxItems", () => {
+		expect(emitZodFromJsonSchema({ type: "array", minItems: 1, maxItems: 20, items: { type: "string", pattern: "^[a-z]+$" } }, "x"))
+			.toBe("z.array(// @oj-warn: pattern=\"^[a-z]+$\" 为 Rust regex，未在前端执行（跨语言语义漂移/ReDoS 风险）\n\tz.string()).min(1).max(20)");
+	});
+
+	it("object nullable → .strict().nullable()（补齐标量外的 nullable 缺口）", () => {
+		expect(emitZodFromJsonSchema({ type: "object", nullable: true, additionalProperties: false, properties: { a: { type: "string" } } }, "x"))
+			.toBe("z.object({\n\t\"a\": z.string().optional()\n}).strict().nullable()");
+	});
+
+	it("array nullable → z.array(...).nullable()", () => {
+		expect(emitZodFromJsonSchema({ type: "array", nullable: true, items: { type: "integer" } }, "x"))
+			.toBe("z.array(z.number().int()).nullable()");
+	});
+
+	it("additionalProperties:true → .catchall(z.unknown())（任意额外键放行）", () => {
+		expect(emitZodFromJsonSchema({ type: "object", additionalProperties: true, properties: { a: { type: "string" } } }, "x"))
+			.toBe("z.object({\n\t\"a\": z.string().optional()\n}).catchall(z.unknown())");
+	});
+
+	it("additionalProperties:schema → .catchall(emitZod(schema))（额外键须符合子 schema）", () => {
+		expect(emitZodFromJsonSchema({ type: "object", additionalProperties: { type: "string", maxLength: 8 }, properties: { a: { type: "string" } } }, "x"))
+			.toBe("z.object({\n\t\"a\": z.string().optional()\n}).catchall(z.string().max(8))");
+	});
+});

package/src/contract/__tests__/mock.test.ts

@@ -0,0 +1,56 @@
+import type { OpenApiDoc } from "../openapi-ir";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { loadContractMocks, resolveMock } from "../mock";
+
+let dir: string;
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "ojm-mock-"));
+});
+afterEach(() => {
+	rmSync(dir, { recursive: true, force: true });
+});
+
+const DOC: OpenApiDoc = {
+	openapi: "3.1.0",
+	paths: {
+		"/v1/api/wiki/collections/{id}": {
+			get: {
+				operationId: "wiki_collections__id__get",
+				tags: ["wiki"],
+				parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
+				responses: {
+					200: {
+						"description": "OK",
+						"x-oj-response-enforced": false,
+						"content": { "application/json": { schema: { type: "object", required: ["code", "msg", "data"], properties: { code: { type: "integer" }, msg: { type: "string" }, data: { type: "object", required: ["title"], properties: { title: { type: "string", maxLength: 10 }, count: { type: "integer", minimum: 1 } } } } } } },
+					},
+				},
+			},
+		},
+	},
+};
+
+describe("dev mock 消费 openapi.json（新口径 Task #6）", () => {
+	it("loadContractMocks 由 openapi.json 装载路由，data 为 JSON Schema", async () => {
+		writeFileSync(join(dir, "openapi.json"), JSON.stringify(DOC));
+		const routes = await loadContractMocks(dir);
+		expect(routes.length).toBe(1);
+		expect(routes[0].method).toBe("GET");
+		expect(routes[0].pattern).toBe("/wiki/collections/{id}");
+		expect((routes[0].data as Record<string, unknown>).type).toBe("object");
+	});
+
+	it("resolveMock 用 JSON Schema 生成示例 data（满足 maxLength/minimum 约束）", async () => {
+		writeFileSync(join(dir, "openapi.json"), JSON.stringify(DOC));
+		const routes = await loadContractMocks(dir);
+		const fn = resolveMock([], routes, "GET", "/wiki/collections/5");
+		expect(fn).toBeTypeOf("function");
+		const res = fn!() as { code: number, msg: string, data: { title: string, count: number } };
+		expect(res.code).toBe(0);
+		expect(res.data.title.length).toBeLessThanOrEqual(10);
+		expect(res.data.count).toBeGreaterThanOrEqual(1);
+	});
+});

package/src/contract/__tests__/openapi-ir.test.ts

@@ -0,0 +1,137 @@
+import type { OpenApiDoc } from "../openapi-ir";
+import { describe, expect, it } from "vitest";
+import { camelCaseOperationId, irFromOpenapi } from "../openapi-ir";
+
+const DOC: OpenApiDoc = {
+	openapi: "3.1.0",
+	paths: {
+		"/v1/api/wiki/collections/{id}": {
+			get: {
+				"operationId": "wiki_collections__id__get",
+				"tags": ["wiki"],
+				"x-oj-file": "wiki/collections/_id_/api.ts",
+				"parameters": [
+					{ name: "id", in: "path", required: true, schema: { type: "integer", minimum: 1 } },
+					{ name: "page", in: "query", required: false, schema: { type: "integer", minimum: 1 } },
+				],
+				"responses": {
+					200: {
+						"description": "OK",
+						"x-oj-response-enforced": false,
+						"content": {
+							"application/json": {
+								schema: {
+									type: "object",
+									required: ["code", "msg", "data"],
+									properties: {
+										code: { type: "integer" },
+										msg: { type: "string" },
+										data: {
+											type: "object",
+											required: ["list", "total"],
+											properties: {
+												list: { type: "array", items: { type: "object", properties: { id: { type: "integer" } } } },
+												total: { type: "integer", minimum: 0 },
+											},
+										},
+									},
+								},
+							},
+						},
+					},
+				},
+			},
+		},
+		"/v1/api/wiki/collections": {
+			post: {
+				operationId: "wiki_collections_post",
+				tags: ["wiki"],
+				requestBody: {
+					required: true,
+					content: {
+						"application/json": {
+							schema: {
+								type: "object",
+								required: ["title"],
+								additionalProperties: false,
+								properties: { title: { type: "string", maxLength: 80 } },
+							},
+						},
+					},
+				},
+				responses: { 200: { description: "OK" } },
+			},
+		},
+		"/v1/api/wiki/plain": {
+			get: {
+				operationId: "wiki_plain_get",
+				tags: ["wiki"],
+				responses: { 200: { description: "OK" } },
+			},
+		},
+	},
+};
+
+describe("camelCaseOperationId", () => {
+	it("折叠 __ 路径参数边界为单一 camelCase", () => {
+		expect(camelCaseOperationId("wiki_collections__id__get")).toBe("wikiCollectionsIdGet");
+		expect(camelCaseOperationId("notification_notifications_get")).toBe("notificationNotificationsGet");
+	});
+});
+
+describe("irFromOpenapi", () => {
+	const ir = irFromOpenapi(DOC, { base: "/v1/api" });
+
+	it("剥 base 前缀、取模块、camelCase 命名", () => {
+		const ep = ir.find(e => e.name === "wikiCollectionsIdGet")!;
+		expect(ep.route).toBe("/collections/{id}");
+		expect(ep.apiPrefix).toBe("/wiki");
+		expect(ir.find(e => e.name === "wikiCollectionsPost")).toBeDefined();
+	});
+
+	it("params/query 按 in 通道合并，required 收集到数组", () => {
+		const ep = ir.find(e => e.name === "wikiCollectionsIdGet")!;
+		expect(ep.paramsSchema).toEqual({
+			type: "object",
+			required: ["id"],
+			properties: { id: { type: "integer", minimum: 1 } },
+		});
+		expect(ep.querySchema).toEqual({
+			type: "object",
+			required: [],
+			properties: { page: { type: "integer", minimum: 1 } },
+		});
+		expect(ep.paramNames).toEqual(["id"]);
+	});
+
+	it("requestBody → bodySchema", () => {
+		const ep = ir.find(e => e.name === "wikiCollectionsPost")!;
+		expect(ep.bodySchema).toEqual({
+			type: "object",
+			required: ["title"],
+			additionalProperties: false,
+			properties: { title: { type: "string", maxLength: 80 } },
+		});
+	});
+
+	it("带 x-oj-response-enforced 的端点解包 data，无 response 的端点 dataSchema=undefined", () => {
+		const withResp = ir.find(e => e.name === "wikiCollectionsIdGet")!;
+		expect(withResp.dataSchema).toEqual({
+			type: "object",
+			required: ["list", "total"],
+			properties: {
+				list: { type: "array", items: { type: "object", properties: { id: { type: "integer" } } } },
+				total: { type: "integer", minimum: 0 },
+			},
+		});
+		const plain = ir.find(e => e.name === "wikiPlainGet")!;
+		expect(plain.dataSchema).toBeUndefined();
+		expect(plain.raw).toBe(false);
+	});
+
+	it("base 缺省时从 path + module 反推，route 仍为模块相对", () => {
+		const ir2 = irFromOpenapi(DOC);
+		const ep = ir2.find(e => e.name === "wikiCollectionsIdGet")!;
+		expect(ep.route).toBe("/collections/{id}");
+	});
+});

package/src/contract/__tests__/run-api.test.ts

@@ -0,0 +1,67 @@
+import type { OpenApiDoc } from "../openapi-ir";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { runApi } from "../run";
+
+let dir: string;
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "ojm-run-"));
+});
+afterEach(() => {
+	rmSync(dir, { recursive: true, force: true });
+});
+
+const DOC: OpenApiDoc = {
+	openapi: "3.1.0",
+	paths: {
+		"/v1/api/wiki/collections/{id}": {
+			get: {
+				operationId: "wiki_collections__id__get",
+				tags: ["wiki"],
+				parameters: [{ name: "id", in: "path", required: true, schema: { type: "integer" } }],
+				responses: {
+					200: {
+						"description": "OK",
+						"x-oj-response-enforced": false,
+						"content": { "application/json": { schema: { type: "object", required: ["code", "msg", "data"], properties: { code: { type: "integer" }, msg: { type: "string" }, data: { type: "string" } } } } },
+					},
+				},
+			},
+		},
+		"/v1/api/user/profile": {
+			get: {
+				operationId: "user_profile_get",
+				tags: ["user"],
+				responses: { 200: { description: "OK" } },
+			},
+		},
+	},
+};
+
+describe("runApi 消费 openapi.json（新口径 Task #4）", () => {
+	it("按模块分组生成 web/src/<模块>/__client/{api.ts,api.schemas.ts}", async () => {
+		writeFileSync(join(dir, "openapi.json"), JSON.stringify(DOC));
+		const result = await runApi({ cwd: dir, openapi: "openapi.json" });
+		expect(result.contracts).toBe(2);
+
+		const wikiApi = join(dir, "web/src/wiki/__client/api.ts");
+		const wikiSchemas = join(dir, "web/src/wiki/__client/api.schemas.ts");
+		const userApi = join(dir, "web/src/user/__client/api.ts");
+		expect(existsSync(wikiApi)).toBe(true);
+		expect(existsSync(wikiSchemas)).toBe(true);
+		expect(existsSync(userApi)).toBe(true);
+
+		expect(readFileSync(wikiApi, "utf8")).toContain("export async function wikiCollectionsIdGet(");
+		expect(readFileSync(wikiSchemas, "utf8")).toContain("\"wikiCollectionsIdGet\":");
+		// 幂等：第二次无变化应跳过
+		const result2 = await runApi({ cwd: dir, openapi: "openapi.json" });
+		expect(result2.written.length).toBe(0);
+		expect(result2.skipped.length).toBeGreaterThan(0);
+	});
+
+	it("无 openapi.json 且无 contract.ts → 报错指引", async () => {
+		await expect(runApi({ cwd: dir })).rejects.toThrow(/openapi\.json/);
+	});
+});