@oj-module/cli 0.1.17 → 0.1.20

package/src/contract/check.ts

@@ -1,20 +1,23 @@
+import type { HandlerRow } from "./handler-scan";
 import type { IrEndpoint } from "./ir";
+import type { OpenApiDoc } from "./openapi-ir";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
-import ts from "typescript";
 import { readOjAnonymousPaths } from "../oj-config";
 import { emitClient } from "./emit-client";
-import { emitOpenapiYaml, emitRoutesJson } from "./emit-meta";
 import { planStubWrites } from "./emit-stub";
+import { handlerAbs, implementedRouteKeys, pathKey, scanHandlerFile, VERB_OF, walkApiFiles } from "./handler-scan";
 import { splitRoute, wirePrefixOf } from "./ir";
-import { artifactPaths, discoverContracts, irOf } from "./run";
+import { irFromOpenapi } from "./openapi-ir";
+import { findOpenapiJson, groupIrByModule } from "./run";
 
 /**
  * AC-D10：`ojm api --check` 三重校验（纯对账不写盘）——
  * ① 生成物同步：内存重生成 vs 磁盘逐字节 diff（含 stub 待更新）
  * ② route 双向对账：AST 扫 oj api.ts（default 导出方法名 + 语句起始 `.route = "..."` 赋值）
  *    vs 契约路由表：未实现 warn / 未登记 error / 参数段不一致 error
- * ③ routes.js diff：release 路由表（oj build 产物）vs routes.json；无 dist 给提示不判违规
+ * ③ routes.js diff：release 路由表（oj build 产物，api/dist 下各模块的 routes.js）vs openapi.json
+ *   契约路由表；无 dist 给提示不判违规
  *
  * 原则：check 永不修文件——修复动作永远由人执行（重跑 ojm api / 补 handler / oj build）。
  */
@@ -104,226 +107,6 @@ function matchExemptPath(routePath: string, p: string): boolean {
 	return routePath === p || routePath.startsWith(`${p}/`);
 }
 
-/**
- * oj 方法名 → HTTP 动词（emit-stub 的反向映射）。
- * 注意**不含 options**：契约运行时故意不表达 OPTIONS（预检请求由 fetch/CORS 层处理，
- * 见 runtime/contract 的方法白名单）——oj 树里的 options handler 因此永不进对账表
- * （不会被误报「未登记」）；routes.js 的 options 行经下方 parseRoutesJs 的
- * 大写回落归一，同样不误报 drift。
- */
-const VERB_OF: Record<string, IrEndpoint["method"]> = {
-	get: "GET",
-	post: "POST",
-	put: "PUT",
-	del: "DELETE",
-	patch: "PATCH",
-	head: "HEAD",
-};
-
-/** oj v0.1.64 嵌套上限（与 oj 内省一致）；超出即 oj 启动报错，checker 不深追 */
-const MAX_GROUP_DEPTH = 4;
-
-interface HandlerRow {
-	/** HTTP 动词 */
-	method: IrEndpoint["method"]
-	/** 目录镜像相对 api/src 的路径段（含模块段），如 "order/item" */
-	dir: string
-	/** 语句起始 `.route = "..."` 字面量（无则目录镜像直达） */
-	tail?: string
-	/** v0.1.64：点分 handler 链（"cccc.get"；顶层动词即方法名） */
-	chain: string
-	/** v0.1.64：组前缀解析后的有效路由全路径（base 相对、无前导 /；绝对 .route 即其自身） */
-	full: string
-	filePath: string
-}
-
-/** `a` / `a.b` 形式的属性访问 → 点分名；其余（调用/元素访问）→ undefined */
-function dottedNameOf(node: ts.Expression): string | undefined {
-	if (ts.isIdentifier(node))
-		return node.text;
-	if (ts.isPropertyAccessExpression(node)) {
-		const base = dottedNameOf(node.expression);
-		return base ? `${base}.${node.name.text}` : undefined;
-	}
-	return undefined;
-}
-
-/**
- * 语句起始的 `<路径>.route = "字面量"`（路径可为点分：`cccc.post.route`，运行时即
- * `cccc.post` 函数对象的 `.route`——与 oj 内省读 `fn.route` 同源）。空串视同未挂
- * （oj 口径）。oj build 只认顶层标准赋值，这里同口径且放宽到点分左值。
- */
-function collectRouteDecls(sf: ts.SourceFile): Map<string, string> {
-	const routes = new Map<string, string>();
-	for (const stmt of sf.statements) {
-		if (!ts.isExpressionStatement(stmt) || !ts.isBinaryExpression(stmt.expression))
-			continue;
-		const expr = stmt.expression;
-		if (expr.operatorToken.kind !== ts.SyntaxKind.EqualsToken)
-			continue;
-		if (!ts.isPropertyAccessExpression(expr.left) || expr.left.name.text !== "route")
-			continue;
-		if (!ts.isStringLiteral(expr.right) || expr.right.text === "")
-			continue;
-		const path = dottedNameOf(expr.left.expression);
-		if (path)
-			routes.set(path, expr.right.text);
-	}
-	return routes;
-}
-
-/** 顶层 `const x = { ... }` 对象字面量表：嵌套组经标识符引用时的解析依据 */
-function collectObjectDecls(sf: ts.SourceFile): Map<string, ts.ObjectLiteralExpression> {
-	const decls = new Map<string, ts.ObjectLiteralExpression>();
-	for (const stmt of sf.statements) {
-		if (!ts.isVariableStatement(stmt))
-			continue;
-		for (const decl of stmt.declarationList.declarations) {
-			if (ts.isIdentifier(decl.name) && decl.initializer && ts.isObjectLiteralExpression(decl.initializer))
-				decls.set(decl.name.text, decl.initializer);
-		}
-	}
-	return decls;
-}
-
-/** verb 键 → 实现函数名（供 `.route` 语句按函数名查找；内联写法回落键名） */
-function implNameOf(prop: ts.ObjectLiteralElementLike): string | undefined {
-	if (ts.isShorthandPropertyAssignment(prop))
-		return prop.name.text;
-	if (ts.isMethodDeclaration(prop) && prop.name)
-		return prop.name.getText();
-	if (ts.isPropertyAssignment(prop)) {
-		if (ts.isIdentifier(prop.name) && ts.isIdentifier(prop.initializer))
-			return prop.initializer.text;
-		if (prop.name)
-			return prop.name.getText();
-	}
-	return undefined;
-}
-
-/** 非 verb 键 → 子组对象字面量（内联或经标识符解析）；函数/数组/基元 → undefined */
-function groupValueOf(prop: ts.ObjectLiteralElementLike, decls: Map<string, ts.ObjectLiteralExpression>): ts.ObjectLiteralExpression | undefined {
-	if (ts.isPropertyAssignment(prop)) {
-		if (ts.isObjectLiteralExpression(prop.initializer))
-			return prop.initializer;
-		if (ts.isIdentifier(prop.initializer))
-			return decls.get(prop.initializer.text);
-		return undefined;
-	}
-	if (ts.isShorthandPropertyAssignment(prop))
-		return decls.get(prop.name.text);
-	return undefined;
-}
-
-/** default 导出对象：内联字面量或标识符（`export default api`） */
-function defaultExportObject(sf: ts.SourceFile, decls: Map<string, ts.ObjectLiteralExpression>): ts.ObjectLiteralExpression | undefined {
-	for (const stmt of sf.statements) {
-		if (!ts.isExportAssignment(stmt) || stmt.isExportEquals)
-			continue;
-		if (ts.isObjectLiteralExpression(stmt.expression))
-			return stmt.expression;
-		if (ts.isIdentifier(stmt.expression))
-			return decls.get(stmt.expression.text);
-	}
-	return undefined;
-}
-
-/** 相对路由按层前缀解析（绝对 `/` 开头即根级）；与 oj 内省 resolve 同规则 */
-function resolveRoute(own: string, prefix: string): string {
-	return own.startsWith("/") ? own : (prefix ? `${prefix}/${own}` : own);
-}
-
-/** 有效路由全路径（base 相对、无前导 /）：绝对 .route 取其自身，否则目录镜像 + 相对尾 */
-function fullPathOf(dir: string, tail: string | undefined): string {
-	if (tail?.startsWith("/"))
-		return tail.replace(/^\//, "");
-	return [dir, tail].filter(Boolean).join("/");
-}
-
-/**
- * AST 扫单个 api.ts（v0.1.64 起支持嵌套 handler 组）：
- * default 导出对象的键——verb 键（函数）即端点；非 verb 键（普通对象）即子组，
- * 递归展开（上限 4 层，路径环守卫）。组级 `.route` 作整组默认前缀，动词自身
- * `.route` 优先覆盖；文件层（`const api = {...}; api.route = ...`）同为默认前缀。
- * 非 verb 键挂函数/数组/基元是 oj 判别红线（启动即报错），此处按「不当路由」跳过。
- */
-export function scanHandlerFile(filePath: string, apiSrcDir: string): HandlerRow[] {
-	const text = readFileSync(filePath, "utf8");
-	const sf = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-	const routes = collectRouteDecls(sf);
-	const decls = collectObjectDecls(sf);
-	const relDir = relative(apiSrcDir, dirname(filePath)).split(sep).join("/");
-	const rows: HandlerRow[] = [];
-	const seen = new Set<ts.Node>();
-
-	const walk = (obj: ts.ObjectLiteralExpression, chainPrefix: string, routePrefix: string, depth: number): void => {
-		if (depth > MAX_GROUP_DEPTH || seen.has(obj))
-			return;
-		seen.add(obj);
-		for (const prop of obj.properties) {
-			const name = (prop.name && ts.isIdentifier(prop.name)) ? prop.name.text : undefined;
-			if (!name)
-				continue;
-			const chain = chainPrefix ? `${chainPrefix}.${name}` : name;
-			if (VERB_OF[name]) {
-				const fnName = implNameOf(prop) ?? name;
-				const own = routes.get(chain) ?? routes.get(fnName);
-				// 无自身 .route → 继承本层前缀（根层即目录镜像）；与 oj 内省同规则
-				const tail = own === undefined
-					? (routePrefix || undefined)
-					: resolveRoute(own, routePrefix);
-				rows.push({
-					method: VERB_OF[name],
-					dir: relDir,
-					tail,
-					chain,
-					full: fullPathOf(relDir, tail),
-					filePath,
-				});
-			}
-			else {
-				const child = groupValueOf(prop, decls);
-				if (!child)
-					continue; // 函数/数组/基元：oj 红线，checker 不当路由
-				const own = routes.get(chain);
-				const childPrefix = own === undefined
-					? (routePrefix ? `${routePrefix}/${name}` : name)
-					: resolveRoute(own, routePrefix);
-				walk(child, chain, childPrefix, depth + 1);
-			}
-		}
-		seen.delete(obj);
-	};
-
-	const root = defaultExportObject(sf, decls);
-	if (root) {
-		// 文件层 .route：default 导出为标识符时，该标识符的 .route 语句即整文件默认前缀
-		let filePrefix = "";
-		for (const stmt of sf.statements) {
-			if (ts.isExportAssignment(stmt) && !stmt.isExportEquals && ts.isIdentifier(stmt.expression)) {
-				const own = routes.get(stmt.expression.text);
-				if (own !== undefined)
-					filePrefix = resolveRoute(own, "");
-			}
-		}
-		walk(root, "", filePrefix, 1);
-	}
-	return rows;
-}
-
-function walkApiFiles(dir: string, out: string[] = []): string[] {
-	if (!existsSync(dir))
-		return out;
-	for (const entry of readdirSync(dir, { withFileTypes: true })) {
-		const p = join(dir, entry.name);
-		if (entry.isDirectory())
-			walkApiFiles(p, out);
-		else if (entry.name === "api.ts" || entry.name === "api.js")
-			out.push(p);
-	}
-	return out;
-}
-
 /** ws.ts / ws.js（目录内放即产生一条 WS 路由，文件名必须小写——oj 0.1.5 约定） */
 function walkWsFiles(dir: string, out: string[] = []): string[] {
 	if (!existsSync(dir))
@@ -366,9 +149,6 @@ function checkWsAnonymous(wsFiles: string[], apiSrcDir: string, configPath: stri
 		}));
 }
 
-/** 对账键（方法 + 全路径） */
-const pathKey = (method: string, path: string) => `${method} ${path}`;
-
 /** 路径段（去空串，忽略前导 /） */
 const pathSegs = (p: string) => p.split("/").filter(Boolean);
 /** 静态前缀：首个参数段（{...}）之前的路径段 */
@@ -378,14 +158,6 @@ function staticPrefixOf(p: string): string {
 	return segs.slice(0, i === -1 ? segs.length : i).join("/");
 }
 
-/**
- * handler 的有效 wire 全路径（带前导 /）：绝对 `.route` 即其自身；相对尾巴 = `/` + full。
- * 用于与契约 contractAbs（wirePrefix + route）对齐比对。
- */
-function handlerAbs(h: HandlerRow): string {
-	return h.tail?.startsWith("/") ? h.tail : `/${h.full}`;
-}
-
 /**
  * ② route 双向对账：契约路由表 vs AST 扫描的 handler 表（D12/F19：豁免降级）。
  *
@@ -411,6 +183,14 @@ function reconcileRoutes(contractIr: IrEndpoint[], handlers: HandlerRow[], exemp
 
 	const claimed = new Set<HandlerRow>();
 	for (const ep of contractIr) {
+		// D12/F19：豁免模块/路径在「契约→handler」侧同样降级——否则 openapi.json 含豁免
+		// 模块（oj 照常为其生成 path）时，根级模块路由（route="/" 但 handler .route 为
+		// 模块名）会误报 route-params-mismatch。整模块/路径前缀命中即跳过本端点全部核对。
+		const epModule = ep.apiPrefix.replace(/^\//, "");
+		if (exemption.modules.includes(epModule))
+			continue;
+		if (exemption.paths.some(p => matchExemptPath(ep.fullPath, p)))
+			continue;
 		const { dir } = splitRoute(ep.route);
 		const dirFull = `${ep.apiPrefix.replace(/^\//, "")}${dir ? `/${dir}` : ""}`;
 		const ojFull = `${ep.apiPrefix.replace(/^\//, "")}${ep.route}`.replace(/\/+/g, "/");
@@ -487,70 +267,58 @@ function parseRoutesJs(text: string): { method: string, pattern: string }[] {
 	return rows;
 }
 
+/**
+ * 新口径（Task #5）：以 openapi.json 为事实源做 --check。
+ * - ① 生成物同步：仅核对 `web/src/<模块>/__client/{api.ts,api.schemas.ts}`（routes.json/openapi.yaml
+ *   已废弃，openapi.json 即权威，ojm 不再自产）。
+ * - ② route 双向对账复用 `uniDevIr`（与旧口径同源 `IrEndpoint` 形状，reconcileRoutes 不变）。
+ * - stub 计划：openapi IR 同样喂 `planStubWrites`（handler 骨架生成；`.schema` 由开发者手写，不注入）。
+ */
+async function checkFromOpenapi(openapiPath: string, cwd: string, _exemption: ApiExemption): Promise<{ violations: CheckViolation[], uniDevIr: IrEndpoint[] }> {
+	const doc = JSON.parse(readFileSync(openapiPath, "utf8")) as OpenApiDoc;
+	const ir = irFromOpenapi(doc);
+	const violations: CheckViolation[] = [];
+	for (const [module, eps] of groupIrByModule(ir)) {
+		const client = emitClient(eps, { target: "module", module });
+		const clientDir = join(cwd, "web/src", module, "__client");
+		for (const [file, content] of [["api.ts", client["api.ts"]], ["api.schemas.ts", client["api.schemas.ts"]]] as const) {
+			const p = join(clientDir, file);
+			if (!existsSync(p) || readFileSync(p, "utf8") !== content)
+				violations.push({ level: "error", kind: "artifact-stale", message: `[ojm-api] 生成物过期或缺失：${relative(cwd, p)}——请重跑 ojm api 使其与 openapi.json 同步。`, filePath: p });
+		}
+	}
+	const apiSrcDir = join(cwd, "api/src");
+	if (existsSync(apiSrcDir)) {
+		const stubWrites = await planStubWrites(ir, { apiSrcDir, implemented: implementedRouteKeys(apiSrcDir) });
+		for (const w of stubWrites) {
+			if (w.action === "create")
+				violations.push({ level: "error", kind: "artifact-stale", message: `[ojm-api] stub 缺失：${relative(cwd, w.filePath)}——请重跑 ojm api 生成。`, filePath: w.filePath });
+			else if (w.action === "update" && !w.prefixUpgrade)
+				violations.push({ level: "error", kind: "artifact-stale", message: `[ojm-api] stub 待随契约更新：${relative(cwd, w.filePath)}——请重跑 ojm api。`, filePath: w.filePath });
+		}
+	}
+	return { violations, uniDevIr: ir };
+}
+
 /** ojm api --check 主入口。opts.exempt 为可选豁免清单路径（覆盖默认 api/.ojm-api-exempt.json） */
 export async function checkApi(opts: { cwd: string, exempt?: string }): Promise<CheckResult> {
 	const exemption = loadExemption(opts);
-	const contracts = discoverContracts(opts.cwd);
-	if (contracts.length === 0) {
-		throw new Error(`[ojm-api] ${opts.cwd} 下没有发现契约文件——默认发现：api/src/*/contract.ts（uni-dev）与 web/src/*/client/contract.ts（纯前端）。存量工程请迁移：modules/ → web/、模块内 api/ → client/。`);
-	}
+	const openapiPath = findOpenapiJson(opts.cwd);
 	const violations: CheckViolation[] = [];
 	const hints: string[] = [];
 	const uniDevIr: IrEndpoint[] = [];
 
-	for (const found of contracts) {
-		const ir = await irOf(found, opts.cwd);
-		if (found.kind === "uni-dev")
-			uniDevIr.push(...ir);
-
-		// ① 生成物同步：内存重生成 vs 磁盘逐字节
-		const paths = artifactPaths(found, opts.cwd);
-		const client = emitClient(ir, { target: "module", module: found.module });
-		const expected: [string, string][] = [
-			[paths.client, client["api.ts"]],
-			[paths.schemas, client["api.schemas.ts"]],
-			[paths.routes, emitRoutesJson(ir)],
-			[paths.openapi, emitOpenapiYaml(ir, { title: `${found.module} api`, version: "0.0.0" })],
-		];
-		for (const [p, content] of expected) {
-			if (!existsSync(p) || readFileSync(p, "utf8") !== content) {
-				violations.push({
-					level: "error",
-					kind: "artifact-stale",
-					message: `[ojm-api] 生成物过期或缺失：${relative(opts.cwd, p)}——请重跑 ojm api 使其与契约同步。`,
-					filePath: p,
-				});
-			}
-		}
-		// stub 生成物：缺失（create）与待更新（update，指纹匹配但契约已变）都属过期。
-		// 纯指纹头前缀升级（旧 ram-api:stub → 新 ojm-api:stub，正文未变）不算过期：
-		// 存量工程升级后首次 --check 不应因改名误报（R2 平滑升级）。
-		if (found.kind === "uni-dev") {
-			const stubWrites = await planStubWrites(ir, { apiSrcDir: join(opts.cwd, "api/src") });
-			for (const w of stubWrites) {
-				if (w.action === "create") {
-					violations.push({
-						level: "error",
-						kind: "artifact-stale",
-						message: `[ojm-api] stub 缺失：${relative(opts.cwd, w.filePath)}——请重跑 ojm api 生成。`,
-						filePath: w.filePath,
-					});
-					continue;
-				}
-				if (w.action === "update" && !w.prefixUpgrade) {
-					violations.push({
-						level: "error",
-						kind: "artifact-stale",
-						message: `[ojm-api] stub 待随契约更新：${relative(opts.cwd, w.filePath)}——请重跑 ojm api。`,
-						filePath: w.filePath,
-					});
-				}
-			}
-		}
+	if (openapiPath) {
+		const r = await checkFromOpenapi(openapiPath, opts.cwd, exemption);
+		violations.push(...r.violations);
+		uniDevIr.push(...r.uniDevIr);
+	}
+	else {
+		throw new Error(`[ojm-api] ${opts.cwd} 下未发现 openapi.json——请先运行 oj v0.1.73 的 \`oj openapi -c config -d api/src -b /api -o openapi.json\` 生成（OpenAPI 3.1，含全部模块）。\`ojm api --check\` 的单一事实源即 openapi.json，不再消费旧 contract.ts。`);
 	}
 
 	// ② route 双向对账（仅 uni-dev——oj 树存在才有意义）
-	if (contracts.some(c => c.kind === "uni-dev")) {
+	if (existsSync(join(opts.cwd, "api/src"))) {
 		const apiSrcDir = join(opts.cwd, "api/src");
 		const handlers = walkApiFiles(apiSrcDir).flatMap(f => scanHandlerFile(f, apiSrcDir));
 		violations.push(...reconcileRoutes(uniDevIr, handlers, exemption));
@@ -579,19 +347,24 @@ export async function checkApi(opts: { cwd: string, exempt?: string }): Promise<
 		hints.push("[ojm-api] 未发现 api/dist/**/routes.js——release 路由表对账跳过；发布前请先 oj build 再跑 ojm api --check。");
 	}
 	else {
-		const contractRows = uniDevIr.map(ep => ({ method: ep.method, pattern: ep.fullPath.replace(/^\//, "") }));
+		// 尾斜杠规范化：契约侧 fullPath 对「模块根路径」带尾斜杠（stripBase 的
+		// `rel || "/"`：如 notifications 模块的 GET / → fullPath "/notifications/"），
+		// 而 oj 产出的 routes.js pattern 无尾斜杠（"notifications"）——直接比键必然误报。
+		const normPattern = (p: string) => p.replace(/^\/+/, "").replace(/\/+$/, "");
+		const contractRows = uniDevIr.map(ep => ({ method: ep.method, pattern: normPattern(ep.fullPath) }));
+		const distRowsNorm = distRows.map(r => ({ method: r.method, pattern: normPattern(r.pattern) }));
 		const keyOf = (r: { method: string, pattern: string }) => `${r.method} ${r.pattern}`;
 		const contractSet = new Set(contractRows.map(keyOf));
-		const distSet = new Set(distRows.map(keyOf));
-		const missingInDist = [...contractSet].filter(r => !distSet.has(r));
-		// D12/F19：dist 行命中豁免（整模块或路径前缀）→ 不报 "dist 多"
+		const distSet = new Set(distRowsNorm.map(keyOf));
+		// D12/F19：行命中豁免（整模块或路径前缀）→ 两个方向都不报（dist 缺 / dist 多）
 		const isExemptRow = (r: { method: string, pattern: string }) => {
 			const mod = moduleOf(r.pattern);
 			const hitModule = exemption.modules.includes(mod);
 			const hitPath = exemption.paths.some(p => matchExemptPath(`/${r.pattern}`, p));
 			return hitModule || hitPath;
 		};
-		const extraInDist = distRows
+		const missingInDist = contractRows.filter(r => !distSet.has(keyOf(r))).filter(r => !isExemptRow(r)).map(keyOf);
+		const extraInDist = distRowsNorm
 			.filter(r => !contractSet.has(keyOf(r)))
 			.filter(r => !isExemptRow(r))
 			.map(keyOf);

package/src/contract/emit-client.ts

@@ -1,5 +1,6 @@
 import type { IrEndpoint } from "./ir";
-import { emitSchemaSource, keyOf } from "./emit-schema";
+import type { JsonSchema } from "./openapi-ir";
+import { emitZodFromJsonSchema } from "./emit-jsonschema-zod";
 import { wirePrefixOf } from "./ir";
 
 /**
@@ -40,6 +41,12 @@ function pascalModuleName(module: string): string {
 	return module.split("-").map(pascal).join("");
 }
 
+/** 对象键发射：合法标识符原样，其余 JSON 引号化（与 emit-stub 示例值同款） */
+const IDENT = /^[a-z_$][\w$]*$/i;
+function keyOf(name: string): string {
+	return IDENT.test(name) ? name : JSON.stringify(name);
+}
+
 function slotsOf(ep: IrEndpoint): Slot[] {
 	const slots: Slot[] = [];
 	if (ep.paramNames.length > 0)
@@ -65,7 +72,8 @@ function urlTemplate(ep: IrEndpoint, prefix: string): string {
 			return seg;
 		const isCatchAll = seg.startsWith("{*");
 		const key = seg.replace(/^\{\*?/, "").replace(/\}$/, "");
-		const expr = `${prefix}params.${key}`;
+		// 参数段名一律 JSON.stringify 成字符串字面量索引（防止段名含特殊字符破坏源码）
+		const expr = `${prefix}params[${JSON.stringify(key)}]`;
 		return isCatchAll
 			? `\${String(${expr}).split("/").map(encodeURIComponent).join("/")}`
 			: `\${encodeURIComponent(String(${expr}))}`;
@@ -87,10 +95,10 @@ function emitTypes(ep: IrEndpoint): string[] {
 			continue;
 		}
 		// 请求槽用 z.input（带 .default() 的字段入参可选）；data 用 z.infer（输出型）
-		lines.push(`export type ${pascal(ep.name)}${SLOT_TYPE_SUFFIX[slot]} = z.input<(typeof schemas)["${ep.name}"]["${slot}"]>;`);
+		lines.push(`export type ${pascal(ep.name)}${SLOT_TYPE_SUFFIX[slot]} = z.input<(typeof schemas)[${JSON.stringify(ep.name)}][${JSON.stringify(slot)}]>;`);
 	}
 	if (ep.dataSchema)
-		lines.push(`export type ${pascal(ep.name)}Data = z.infer<(typeof schemas)["${ep.name}"]["data"]>;`);
+		lines.push(`export type ${pascal(ep.name)}Data = z.infer<(typeof schemas)[${JSON.stringify(ep.name)}]["data"]>;`);
 	return lines;
 }
 
@@ -102,7 +110,7 @@ function emitFormType(ep: IrEndpoint): string {
 	const form = ep.form!;
 	const members: string[] = [];
 	if (form.fieldsSchema)
-		members.push(`\tfields: z.input<(typeof schemas)["${ep.name}"]["form"]>`);
+		members.push(`\tfields: z.input<(typeof schemas)[${JSON.stringify(ep.name)}]["form"]>`);
 	if (form.files.length) {
 		const files = form.files
 			.map(f => `${keyOf(f.name)}${f.required ? "" : "?"}: ${f.multiple ? "Array<File | Blob>" : "File | Blob"}`)
@@ -199,7 +207,7 @@ function emitEndpoint(ep: IrEndpoint): string {
 		? `
 		if (import.meta.env.DEV) {
 			const { schemas } = await import("./api.schemas");
-			const r = schemas.${ep.name}.data.safeParse(data);
+			const r = schemas[${JSON.stringify(ep.name)}].data.safeParse(data);
 			if (!r.success)
 				throw new ContractApiError(-1, \`[契约违例] ${ep.name} 响应与契约不符：\${r.error.issues.map(i => \`\${i.path.join(".") || "(root)"}: \${i.message}\`).join("; ")}\`);
 		}`
@@ -226,10 +234,10 @@ function emitPrelude(target: "module" | "internal", module?: string, endpointNam
 		? `let req: ScopedRequestLike | undefined;
 
 /** 线上 API 前缀（ojm api 从契约抽取，唯一真源，勿手改）：请求基址 + 前缀登记用 */
-export const API_PREFIX = "${wirePrefix ?? `/${module}`}";
+export const API_PREFIX = ${JSON.stringify(wirePrefix ?? `/${module}`)};
 
 /** 认领身份前缀（契约 apiPrefix，字面等于模块目录名）：跨模块认领护栏对比基准 */
-export const MODULE_PREFIX = "/${module}";
+export const MODULE_PREFIX = ${JSON.stringify(`/${module}`)};
 
 /**
  * 模块 entry 的 onInit 里一行创建（构造即 install）：完成 apiPrefix 登记 +
@@ -309,19 +317,19 @@ function emitSchemas(ir: IrEndpoint[], target: "module" | "internal"): string {
 			// raw 端点也保留请求槽（params/query/body 类型引用此处 schema）；
 			// 仅 data 槽与 raw 互斥（定义期已拦截 data+raw）
 			if (ep.paramsSchema)
-				slots.push(`\t\tparams: ${emitSchemaSource(ep.paramsSchema)},`);
+				slots.push(`\t\tparams: ${emitZodFromJsonSchema(ep.paramsSchema as JsonSchema, `${ep.name}.params`)},`);
 			if (ep.querySchema)
-				slots.push(`\t\tquery: ${emitSchemaSource(ep.querySchema)},`);
+				slots.push(`\t\tquery: ${emitZodFromJsonSchema(ep.querySchema as JsonSchema, `${ep.name}.query`)},`);
 			if (ep.bodySchema)
-				slots.push(`\t\tbody: ${emitSchemaSource(ep.bodySchema)},`);
+				slots.push(`\t\tbody: ${emitZodFromJsonSchema(ep.bodySchema as JsonSchema, `${ep.name}.body`)},`);
 			// form 槽只发射文本部件（files 是二进制，无 schema）；api.ts 的 Form 类型据此推导
 			if (ep.form?.fieldsSchema)
-				slots.push(`\t\tform: ${emitSchemaSource(ep.form.fieldsSchema)},`);
+				slots.push(`\t\tform: ${emitZodFromJsonSchema(ep.form.fieldsSchema as JsonSchema, `${ep.name}.form`)},`);
 			if (!ep.raw && ep.dataSchema)
-				slots.push(`\t\tdata: ${emitSchemaSource(ep.dataSchema)},`);
+				slots.push(`\t\tdata: ${emitZodFromJsonSchema(ep.dataSchema as JsonSchema, `${ep.name}.data`)},`);
 			if (slots.length === 0)
 				return "";
-			return `\t${ep.name}: {\n${slots.join("\n")}\n\t},`;
+			return `\t${JSON.stringify(ep.name)}: {\n${slots.join("\n")}\n\t},`;
 		})
 		.filter(Boolean);
 
@@ -338,7 +346,7 @@ ${entries.join("\n")}
 /** 发射双产物：api.ts（类型 + 请求函数 + 工厂）与 api.schemas.ts（DEV 校验 schema） */
 export function emitClient(ir: IrEndpoint[], opts: { target: "module" | "internal", module?: string }): { "api.ts": string, "api.schemas.ts": string } {
 	if (ir.length === 0)
-		throw new Error("[ojm-api] client 发射失败：IR 为空——契约文件里没有 defineApi 端点，无需生成。");
+		throw new Error("[ojm-api] client 发射失败：IR 为空——openapi.json 里没有任何端点（operationId + tags），无需生成；请检查 \`oj openapi\` 产物。");
 	if (opts.target === "module" && !opts.module) {
 		throw new Error(
 			"[ojm-api] client 发射失败：module 目标需要模块名——"