@oj-module/cli 0.1.17 → 0.1.20

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

@@ -0,0 +1,209 @@
+import type { JsonSchema } from "./openapi-ir";
+
+/**
+ * JSON Schema（oj `.schema` 白名单子集）→ zod 源码表达式。
+ *
+ * 单一职责（SRP）：只把 openapi.json 里的 JSON Schema 翻成 zod 源码字符串，不碰 IR / 文件 IO。
+ *
+ * 安全铁律（来自安全评审）：
+ * 1. 所有动态字符串（属性名 / enum 值 / default 值 / pattern / 路径）一律 `jsonLit`（JSON.stringify）
+ *    嵌入**普通字符串字面量**，绝不走模板插值——openapi.json 值是任意 JSON 字符串，可含反引号、
+ *    斜杠星、换行、模板插值符，模板插值会破坏产物或注入。
+ * 2. `pattern` 不进运行时 `z.regex`：oj 的 pattern 是 Rust regex（线性引擎），JS `RegExp` 是回溯
+ *    引擎——原样执行既有 ReDoS 灾难性回溯风险，又有 Rust 拒/JS 放行的语义漂移。仅发 `// @oj-warn`
+ *    注释（用 `//` 行注释，pattern 经 JSON.stringify 已是单行转义串，安全）。
+ * 3. `default` 不射 `.default()`：oj 运行期不为缺参补默认值，前端若补会让可选字段变必填、掩盖契约
+ *    漂移。仅发 `// @oj-note` 注释。
+ * 4. 白名单外关键字 fail-fast（绝不静默降级）；`required` 项可不在 `properties` 中（JSON Schema 允许），
+ *    取值前先判存在（缺失键直接跳过）。
+ */
+
+/** oj `.schema` 白名单关键字（openapi-guide §2.6），其余 fail-fast */
+const ALLOWED_KEYWORDS = new Set([
+	"type",
+	"required",
+	"properties",
+	"items",
+	"additionalProperties",
+	"minimum",
+	"maximum",
+	"minLength",
+	"maxLength",
+	"pattern",
+	"enum",
+	"nullable",
+	"minItems",
+	"maxItems",
+	"default",
+]);
+
+/** 任意 JSON 值 → 源码安全字面量（字符串/数字/布尔/null 一律 JSON.stringify） */
+function jsonLit(v: unknown): string {
+	return JSON.stringify(v);
+}
+
+function fail(where: string, msg: string): never {
+	throw new Error(`[ojm-api] openapi→zod 失败（${where}）：${msg}`);
+}
+
+/**
+ * enum → zod 基础表达式：全字符串用 `z.enum([...])`，否则（数值/布尔/混合）用
+ * `z.union([z.literal(...)])`。注意 enum 是**独立基础类型**，绝不能挂在 `z.string()`/
+ * `z.number()` 之后（`z.string().enum()` 在 zod 里不存在）——故此处返回完整表达式，
+ * 由 emitScalar 作为 base 使用，而非作为检查链追加。
+ */
+function emitEnum(values: unknown[], _where: string): string {
+	const allString = values.every(v => typeof v === "string");
+	if (allString)
+		return `z.enum([${values.map(jsonLit).join(", ")}])`;
+	return `z.union([${values.map(v => `z.literal(${jsonLit(v)})`).join(", ")}])`;
+}
+
+/**
+ * JSON Schema type → zod 基础表达式，并**统一**叠加标量约束（min/max）与
+ * nullable（借鉴 json-schema-to-zod 的「基础类型 + 修饰符」结构）。
+ *
+ * 关键修正（对照 json-schema-to-zod 映射表补齐口径内缺口）：
+ * - enum 优先作为 base（见 emitEnum）：挂在 `z.string()` 后（`z.string().enum()`）
+ *   在 zod 里不存在，是运行期 TypeError 根因。
+ * - object/array 也走 base + checks 合并，故 `nullable:true` 对对象/数组同样生效
+ *   （旧实现 object/array 提前 return，导致对象/数组的 nullable 被静默丢弃）。
+ * - pattern/default 仍只发注释（Rust regex 不进运行时 / oj 运行期不补值），不射进 zod。
+ */
+function emitScalar(type: string, schema: JsonSchema, where: string): string {
+	// enum 是独立基础类型（z.enum / z.union），不得追加到 typed base 之后
+	if (Array.isArray(schema.enum))
+		return emitEnumWithNullable(schema.enum, schema, where);
+
+	let base: string;
+	switch (type) {
+		case "string":
+			base = "z.string()";
+			break;
+		case "number":
+			base = "z.number()";
+			break;
+		case "integer":
+			base = "z.number().int()";
+			break;
+		case "boolean":
+			base = "z.boolean()";
+			break;
+		case "null":
+			base = "z.null()";
+			break;
+		case "object":
+			base = emitObject(schema, where);
+			break;
+		case "array":
+			base = emitArray(schema, where);
+			break;
+		default:
+			fail(where, `未知 type "${type}"`);
+	}
+
+	const checks: string[] = [];
+	if (type === "string") {
+		if (typeof schema.minLength === "number")
+			checks.push(`.min(${schema.minLength})`);
+		if (typeof schema.maxLength === "number")
+			checks.push(`.max(${schema.maxLength})`);
+	}
+	else if (type === "number" || type === "integer") {
+		if (typeof schema.minimum === "number")
+			checks.push(`.min(${schema.minimum})`);
+		if (typeof schema.maximum === "number")
+			checks.push(`.max(${schema.maximum})`);
+	}
+	if (schema.nullable === true)
+		checks.push(".nullable()");
+
+	let out = `${base}${checks.join("")}`;
+	// pattern：Rust regex，不进运行时（ReDoS + 语义漂移），仅注释
+	if (typeof schema.pattern === "string")
+		out = `// @oj-warn: pattern=${jsonLit(schema.pattern)} 为 Rust regex，未在前端执行（跨语言语义漂移/ReDoS 风险）\n\t${out}`;
+	// default：oj 运行期不补值，仅文档注释
+	if (schema.default !== undefined)
+		out = `// @oj-note: default=${jsonLit(schema.default)}（oj 不补值，仅文档）\n\t${out}`;
+	return out;
+}
+
+/** enum 基础表达式 + nullable（enum 无法叠加 min/max，仅 nullable 有意义） */
+function emitEnumWithNullable(values: unknown[], schema: JsonSchema, where: string): string {
+	let out = emitEnum(values, where);
+	if (schema.nullable === true)
+		out += ".nullable()";
+	if (typeof schema.pattern === "string")
+		out = `// @oj-warn: pattern=${jsonLit(schema.pattern)} 为 Rust regex，未在前端执行（跨语言语义漂移/ReDoS 风险）\n\t${out}`;
+	if (schema.default !== undefined)
+		out = `// @oj-note: default=${jsonLit(schema.default)}（oj 不补值，仅文档）\n\t${out}`;
+	return out;
+}
+
+/**
+ * object → zod。除 properties/required 外，处理 additionalProperties 三态
+ * （借鉴 json-schema-to-zod 映射）：
+ * - `false` → `.strict()`（仅声明属性，拒额外键）
+ * - `true`  → `.catchall(z.unknown())`（任意额外键放行；对应 oj 未限制额外字段）
+ * - schema  → `.catchall(emitZod(schema))`（额外键须符合该子 schema）
+ * `.strict()` 与 `.catchall()` 在 zod 互斥，三者择一。
+ */
+function emitObject(schema: JsonSchema, where: string): string {
+	const props = (schema.properties ?? {}) as Record<string, JsonSchema>;
+	const required: string[] = Array.isArray(schema.required) ? schema.required : [];
+	const members = Object.entries(props).map(([name, sub]) => {
+		const expr = emitZodFromJsonSchema(sub, `${where}.${name}`);
+		const opt = required.includes(name) ? "" : ".optional()";
+		return `\t${jsonLit(name)}: ${expr}${opt}`;
+	});
+	let out = `z.object({\n${members.join(",\n")}\n})`;
+	const ap = schema.additionalProperties;
+	if (ap === false)
+		out += ".strict()";
+	else if (ap === true)
+		out += ".catchall(z.unknown())";
+	else if (ap && typeof ap === "object")
+		out += `.catchall(${emitZodFromJsonSchema(ap as JsonSchema, `${where}<additionalProperties>`)})`;
+	return out;
+}
+
+function emitArray(schema: JsonSchema, where: string): string {
+	const items = schema.items as JsonSchema | undefined;
+	const itemExpr = items ? emitZodFromJsonSchema(items, `${where}[]`) : "z.unknown()";
+	let out = `z.array(${itemExpr})`;
+	if (typeof schema.minItems === "number")
+		out += `.min(${schema.minItems})`;
+	if (typeof schema.maxItems === "number")
+		out += `.max(${schema.maxItems})`;
+	return out;
+}
+
+/** JSON Schema → zod 源码表达式（如 `z.object({...})`） */
+export function emitZodFromJsonSchema(schema: JsonSchema, where: string): string {
+	if (!schema || typeof schema !== "object")
+		return "z.unknown()";
+	for (const k of Object.keys(schema)) {
+		if (!ALLOWED_KEYWORDS.has(k))
+			fail(where, `不支持的关键字 "${k}"（oj .schema 白名单之外，绝不静默降级）`);
+	}
+	const type = schema.type;
+	if (Array.isArray(type)) {
+		const nonNull = type.filter((t): t is string => t !== "null");
+		// 单实类型 + null = nullable（["string","null"] 标准写法）
+		if (nonNull.length === 1) {
+			const expr = emitScalar(nonNull[0], schema, where);
+			return type.includes("null") ? `${expr}.nullable()` : expr;
+		}
+		// 多实类型（如 oj 把 z.union([z.string(),z.number()]) 翻成 ["string","number"]）：
+		// 映射为 z.union，nullable 叠加在外层。oj 产物确有此形状，codegen 必须兜住。
+		const members = nonNull.map(t => emitScalar(t, schema, where));
+		let out = `z.union([${members.join(", ")}])`;
+		if (type.includes("null"))
+			out += ".nullable()";
+		return out;
+	}
+	if (typeof type === "string")
+		return emitScalar(type, schema, where);
+	// 无 type（仅 enum 等少见情形）：oj 产物总有 type，保守退回 unknown
+	return "z.unknown()";
+}

package/src/contract/emit-oj-schema.ts

@@ -1,17 +1,20 @@
 import type { IrEndpoint } from "./ir";
 
 /**
- * 契约 schema → oj 的 `.schema` 入参契约（oj v0.1.44，手册 §4）。
+ * IR 的 JSON Schema（oj `openapi.json` 白名单子集）→ oj 的 `.schema` 入参契约
+ * （oj v0.1.44，手册 §4）。
  *
- * 这是「一份契约 → 前端 client + 后端入参校验」的最后一环：契约里声明的
+ * 这是「openapi.json → 前端 client + 后端入参校验」的最后一环：契约里声明的
  * query/params/body 不只生成前端类型与校验，也落成后端 handler 的 `.schema`，
  * 由 oj 在 **JS 之前**校验（违反即 400，handler 不执行）。
  *
  * 关键字白名单（oj 侧，白名单外装配期 fail-fast）：
  *   type / required / properties / items / additionalProperties / minimum /
  *   maximum / minLength / maxLength / pattern / enum / nullable / minItems / maxItems
- * 所以发射时必须**主动裁剪**到这个子集——把 `format` / `oneOf` 之类原样写出去，
- * 服务根本起不来。
+ * 所以发射时必须**主动裁剪**到这个子集。
+ *
+ * 输入是 IR 里的 JSON Schema 对象（来自 openapi.json），而非 zod——翻译层退役后
+ * 单一事实源即 openapi.json，本模块只做「JSON Schema 白名单裁剪」这一件事。
  */
 
 /** oj `.schema` 的入参通道（对应 http.params / http.query / http.body） */
@@ -20,189 +23,133 @@ export type OjSchemaChannel = "params" | "query" | "body";
 /** params/query 在 HTTP 里只有字符串形态：只允许扁平标量，array/object 是死契约 */
 const FLAT_SCALARS = new Set(["string", "number", "integer", "boolean", "null"]);
 
-interface ZodDefLike {
-	type?: string
-	shape?: Record<string, unknown>
-	element?: unknown
-	options?: unknown[]
-	innerType?: unknown
-	entries?: Record<string, unknown>
-	values?: unknown[]
-	checks?: { _zod?: { def?: Record<string, unknown> } }[]
-	pattern?: unknown
-}
-
-function defOf(schema: unknown): ZodDefLike | undefined {
-	return (schema as { _zod?: { def?: ZodDefLike } })?._zod?.def;
-}
-
 /** 发射期收集的诊断：降级（约束无法表达）必须说出来，不能静默丢 */
 export interface OjSchemaDiag {
 	warnings: string[]
 }
 
-function typeNameOf(value: unknown): "string" | "number" | "boolean" | "null" {
-	if (typeof value === "string")
-		return "string";
-	if (typeof value === "number")
-		return "number";
-	if (typeof value === "boolean")
-		return "boolean";
-	return "null";
+function numOf(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
 
 /**
- * Rust regex（oj 用）不是 ECMA-262：不支持 lookahead / lookbehind / 反向引用。
+ * Rust regex（oj 用）不是 ECMAScript：不支持 lookahead / lookbehind / 反向引用。
+ * openapi.json 来自 oj 自身时本就合规；但用户手写 openapi.json 可能带 JS 专属写法——
  * 这里在**生成期**拦下，避免把服务拖到装配期才 fail-fast。
  */
-function assertRustCompatiblePattern(pattern: string, where: string): void {
+function assertRustCompatiblePattern(pattern: string, where: string, diag: OjSchemaDiag): void {
 	if (/\(\?[=!]|\(\?<[=!]/.test(pattern)) {
-		throw new Error(
-			`[ojm-api] 契约 ${where} 的 pattern 用了零宽断言（lookahead/lookbehind）：oj 的 pattern 是 Rust regex，不支持——请改写成等价的非断言表达式，或去掉该约束。`,
-		);
+		diag.warnings.push(`${where}：pattern 用了零宽断言（lookahead/lookbehind），oj 的 pattern 是 Rust regex 不支持——已跳过该约束（前端 zod 校验不受影响）。`);
 	}
-	if (/\\[1-9]/.test(pattern)) {
-		throw new Error(
-			`[ojm-api] 契约 ${where} 的 pattern 用了反向引用（\\1…\\9）：oj 的 pattern 是 Rust regex，不支持——请改写。`,
-		);
+	if (/\\\{[1-9]/.test(pattern)) {
+		diag.warnings.push(`${where}：pattern 用了反向引用（\\1…\\9），oj 的 pattern 是 Rust regex 不支持——已跳过。`);
 	}
 }
 
-/** zod 约束 → oj 白名单内的约束键（无法表达的返回 undefined 并记诊断） */
-function constraintsOf(def: ZodDefLike, where: string, diag: OjSchemaDiag): Record<string, unknown> {
-	const out: Record<string, unknown> = {};
-	for (const check of def.checks ?? []) {
-		const cd = check._zod?.def ?? {};
-		switch (cd.check) {
-			case "min_length":
-				out[def.type === "array" ? "minItems" : "minLength"] = cd.minimum;
-				break;
-			case "max_length":
-				out[def.type === "array" ? "maxItems" : "maxLength"] = cd.maximum;
-				break;
-			case "greater_than":
-				out.minimum = cd.inclusive === false ? (cd.value as number) : cd.value;
-				break;
-			case "less_than":
-				out.maximum = cd.inclusive === false ? (cd.value as number) : cd.value;
-				break;
-			case "string_format": {
-				// 两种情况都挂在 string_format 下，必须分开：
-				//  · 内置格式（email/uuid/url…，有 format）：format 不在 oj 白名单（写了服务起不来），
-				//    且其自带 pattern 含零宽断言，Rust regex 也拒——整条跳过。
-				//  · 用户 .regex(re)（无 format、只有 pattern）：可发射，但须是 Rust 兼容写法。
-				//  · 用户 .regex(re)：zod v4 也挂在 string_format 下，但 format 值是字面 "regex"
-				const isUserRegex = cd.format === "regex";
-				if (isUserRegex) {
-					const source = cd.pattern instanceof RegExp ? cd.pattern.source : typeof cd.pattern === "string" ? cd.pattern : undefined;
-					if (source) {
-						assertRustCompatiblePattern(source, where);
-						out.pattern = source;
-					}
-					break;
-				}
-				if (cd.format) {
-					diag.warnings.push(`${where}：z.string().${String(cd.format)}() 的格式约束无法进 oj .schema（白名单无 format），已在后端跳过——需要后端强校验请改用 .regex()（Rust regex 写法）。`);
-					break;
-				}
-				break;
-			}
-			case "number_format":
-				// z.int() / z.number().int() → safeint：oj 侧对应 integer（影响 params/query 的字符串强转）
-				if (cd.format === "safeint" || cd.format === "int")
-					out.type = "integer";
-				else
-					diag.warnings.push(`${where}：number_format "${String(cd.format)}" 无法进 oj .schema，已跳过。`);
-				break;
-			case "multiple_of":
-				diag.warnings.push(`${where}：multipleOf 约束不在 oj .schema 白名单，已跳过。`);
-				break;
-			default:
-				break;
+/** params/query 通道：只允许扁平标量，array/object 是永远无法满足的死契约 */
+function assertFlatScalars(schema: Record<string, unknown> | undefined, where: string): void {
+	if (!schema || schema.type !== "object" || typeof schema.properties !== "object")
+		return;
+	for (const [key, child] of Object.entries(schema.properties as Record<string, unknown>)) {
+		const type = (child as { type?: string }).type;
+		if (type && !FLAT_SCALARS.has(type)) {
+			throw new Error(
+				`[ojm-api] 契约 ${where}.${key}：params/query 通道只允许扁平标量（string/number/integer/boolean/null），收到 "${type}"——`
+				+ "params/query 在 HTTP 里只有字符串形态，声明 array/object 是永远无法满足的死契约（oj 装配期即拒）。",
+			);
 		}
 	}
-	return out;
 }
 
-/** 递归：zod schema → oj `.schema` 片段（裁剪到白名单） */
-function convert(schema: unknown, where: string, diag: OjSchemaDiag): Record<string, unknown> {
-	const def = defOf(schema);
-	if (!def || !def.type)
-		throw new Error(`[ojm-api] 契约 ${where} 不是 zod schema，无法转 oj .schema。`);
+/**
+ * JSON Schema → oj `.schema` 裁剪（递归）。
+ * 返回裁剪后的对象；若整个 schema 无可表达约束返回 undefined。
+ * 类型数组 ["x","null"] → {type:"x", nullable:true}；非单实类型联合（["string","number"]）
+ * → 告警并丢弃该字段（oj 白名单无 oneOf/anyOf，后端不校验，前端 zod 不受影响）。
+ */
+function convert(schema: unknown, where: string, diag: OjSchemaDiag): Record<string, unknown> | undefined {
+	if (!schema || typeof schema !== "object")
+		return undefined;
+	const s = schema as Record<string, unknown>;
+	const out: Record<string, unknown> = {};
 
-	switch (def.type) {
-		case "object": {
-			const properties: Record<string, unknown> = {};
-			const required: string[] = [];
-			for (const [key, child] of Object.entries(def.shape ?? {})) {
-				const childDef = defOf(child);
-				properties[key] = convert(child, `${where}.${key}`, diag);
-				// optional / default 有缺省值 → 非必填；nullable 语义单独用 nullable 表达
-				if (childDef?.type !== "optional" && childDef?.type !== "default")
-					required.push(key);
-			}
-			const out: Record<string, unknown> = { type: "object", properties };
-			if (required.length)
-				out.required = required;
-			return out;
-		}
-		case "array": {
-			const out: Record<string, unknown> = { type: "array", items: convert(def.element, `${where}[]`, diag) };
-			return { ...out, ...constraintsOf(def, where, diag) };
-		}
-		case "enum": {
-			const values = Object.keys(def.entries ?? {});
-			return { type: typeNameOf((def.entries ?? {})[values[0]]), enum: values };
-		}
-		case "literal": {
-			const value = (def.values ?? [])[0];
-			return { type: typeNameOf(value), enum: [value] };
-		}
-		case "union": {
-			// 白名单无 oneOf/anyOf：全字面量联合 → enum 等价表达；否则降级为空约束
-			const options = def.options ?? [];
-			const literals = options.map(opt => defOf(opt)?.values?.[0]).filter(v => v !== undefined);
-			if (literals.length === options.length && literals.length > 0) {
-				return { type: typeNameOf(literals[0]), enum: literals };
-			}
-			diag.warnings.push(`${where}：union 无法进 oj .schema（白名单无 oneOf/anyOf），该字段在后端不做入参校验——前端 zod 校验不受影响。`);
-			return {};
+	// 类型：数组形态 = union / nullable 展开
+	const rawType = s.type;
+	let type: string | undefined;
+	let nullable = false;
+	if (Array.isArray(rawType)) {
+		const nonNull = rawType.filter((t): t is string => t !== "null");
+		if (nonNull.length === 1) {
+			type = nonNull[0];
+			nullable = rawType.includes("null");
 		}
-		case "nullable": {
-			const inner = convert(def.innerType, where, diag);
-			return { ...inner, nullable: true };
+		else {
+			diag.warnings.push(`${where}：联合类型 ${JSON.stringify(rawType)} 无法进 oj .schema（白名单无 oneOf/anyOf），该字段在后端不做入参校验；前端 zod 校验不受影响。`);
+			return undefined;
 		}
-		case "optional":
-		case "default":
-			return convert(def.innerType, where, diag);
-		case "date":
-			// JSON 无日期类型：线上是 ISO 串，后端按 string 校验
-			return { type: "string" };
-		case "string":
-		case "number":
-		case "boolean": {
-			const out: Record<string, unknown> = { type: def.type };
-			return { ...out, ...constraintsOf(def, where, diag) };
-		}
-		default:
-			diag.warnings.push(`${where}：zod 类型 "${def.type}" 无法转 oj .schema，该字段在后端不做入参校验。`);
-			return {};
 	}
-}
+	else if (typeof rawType === "string") {
+		type = rawType;
+	}
 
-/** params/query 通道：只允许扁平标量，array/object 是永远无法满足的死契约 */
-function assertFlatScalars(schema: Record<string, unknown>, where: string): void {
-	if (schema.type === "object" && typeof schema.properties === "object") {
-		for (const [key, child] of Object.entries(schema.properties as Record<string, unknown>)) {
-			const type = (child as { type?: string }).type;
-			if (type && !FLAT_SCALARS.has(type)) {
-				throw new Error(
-					`[ojm-api] 契约 ${where}.${key}：params/query 通道只允许扁平标量（string/number/integer/boolean/null），收到 "${type}"——`
-					+ "params/query 在 HTTP 里只有字符串形态，声明 array/object 是永远无法满足的死契约（oj 装配期即拒）。",
-				);
+	if (type)
+		out.type = type;
+	if (nullable)
+		out.nullable = true;
+
+	// format 是 JSON Schema 专有键，oj 白名单无——静默跳过会削弱校验，故告警
+	if (typeof s.format === "string") {
+		diag.warnings.push(`${where}：format "${s.format}" 不在 oj .schema 白名单，已跳过（后端不校验该格式约束；需要后端强校验请改用 .regex()，Rust regex 写法）。`);
+	}
+
+	// 对象：递归裁剪每个属性；required 仅保留「确有可表达约束」的键（避免空 required）
+	if (type === "object" || (type === undefined && s.properties)) {
+		const props = s.properties as Record<string, unknown> | undefined;
+		if (props) {
+			const properties: Record<string, unknown> = {};
+			for (const [k, v] of Object.entries(props)) {
+				const child = convert(v, `${where}.${k}`, diag);
+				if (child !== undefined)
+					properties[k] = child;
+			}
+			if (Object.keys(properties).length) {
+				out.properties = properties;
+				const required = ((s.required as string[]) ?? []).filter(k => k in properties);
+				if (required.length)
+					out.required = required;
 			}
 		}
 	}
+
+	// 数组：递归裁剪 items
+	if (type === "array" && s.items) {
+		const items = convert(s.items, `${where}[]`, diag);
+		if (items !== undefined)
+			out.items = items;
+	}
+
+	// 字面量联合已转 enum（oj 支持）
+	if (Array.isArray(s.enum))
+		out.enum = s.enum;
+
+	// 数值 / 字符串 / 数组 边界约束（白名单内）
+	for (const key of ["minimum", "maximum", "minLength", "maxLength", "minItems", "maxItems"] as const) {
+		const v = numOf(s[key]);
+		if (v !== undefined)
+			out[key] = v;
+	}
+
+	if (typeof s.pattern === "string") {
+		assertRustCompatiblePattern(s.pattern, where, diag);
+		out.pattern = s.pattern;
+	}
+	if (typeof s.additionalProperties === "boolean")
+		out.additionalProperties = s.additionalProperties;
+	// default 纯注解：oj 不补值，但保留做文档/后端语义提示无害
+	if (s.default !== undefined)
+		out.default = s.default;
+
+	return Object.keys(out).length > 0 ? out : undefined;
 }
 
 /** 端点 → oj `.schema` 三通道（无声明的通道不出现）；附带降级诊断 */
@@ -221,7 +168,7 @@ export function ojSchemaOfEndpoint(ep: IrEndpoint, diag: OjSchemaDiag = { warnin
 		if (channel !== "body")
 			assertFlatScalars(converted, where);
 		// 空对象 = 该通道无可表达约束，不写（写了 oj 会当「任意对象」收下，反而弱于不声明）
-		if (Object.keys(converted).length > 0)
+		if (converted && Object.keys(converted).length > 0)
 			out[channel] = converted;
 	}
 	return Object.keys(out).length > 0 ? out : undefined;

package/src/contract/emit-stub.ts

@@ -4,8 +4,8 @@ import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { emitOjSchemaLine } from "./emit-oj-schema";
-import { keyOf } from "./emit-schema";
-import { splitRoute } from "./ir";
+import { splitRoute, wirePrefixOf } from "./ir";
+import { jsonSchemaToSample } from "./json-schema-sample";
 
 /**
  * AC-D10 §9.1：handler stub 发射器 + 指纹幂等。
@@ -40,6 +40,12 @@ export interface PlanStubOptions {
 	eslintFix?: (code: string, filePath: string) => Promise<string>
 	/** 收集 .schema 降级诊断（契约里 oj 表达不了的约束会记在这里，不静默丢） */
 	diag?: OjSchemaDiag
+	/**
+	 * 已实现路由键（`"METHOD /abs/path"`，handler-scan 的 implementedRouteKeys 产出）。
+	 * DDD reshape（oj v0.1.64 嵌套组）后 handler 可住在模块根单文件等非镜像位置——
+	 * 这些端点跳过 stub 生成，否则镜像 stub 与真实 handler 双写同路由。
+	 */
+	implemented?: Set<string>
 }
 
 /** oj 方法名映射（DELETE → del）。OPTIONS 不在契约表达范围（runtime 白名单拒绝） */
@@ -67,62 +73,9 @@ export function hashContent(body: string): string {
 	return createHash("sha256").update(norm).digest("hex");
 }
 
-/** 最小示例值源码生成（与 mock.ts 的值版有意不收敛——此处产代码模板文本） */
+/** 最小示例值源码生成：JSON Schema → 确定性示例值 → TS 字面量（JSON.stringify 即合法源码） */
 function exampleSourceFromSchema(schema: unknown): string {
-	const def = (schema as { _zod?: { def?: Record<string, unknown> } })?._zod?.def;
-	if (!def)
-		return "null";
-	switch (def.type) {
-		case "string": {
-			for (const check of (def.checks as { _zod?: { def?: Record<string, unknown> } }[]) ?? []) {
-				const format = check._zod?.def?.format as string | undefined;
-				if (format === "email")
-					return "\"user@example.com\"";
-				if (format === "uuid")
-					return "\"00000000-0000-0000-0000-000000000000\"";
-				if (format === "datetime")
-					return "\"2026-01-01T00:00:00.000Z\"";
-				if (format === "date")
-					return "\"2026-01-01\"";
-				if (format === "url")
-					return "\"https://example.com\"";
-			}
-			return "\"示例\"";
-		}
-		case "number": {
-			for (const check of (def.checks as { _zod?: { def?: Record<string, unknown> } }[]) ?? []) {
-				const cd = check._zod?.def;
-				if (cd?.check === "greater_than")
-					return String(cd.inclusive === false ? (cd.value as number) + 1 : cd.value);
-			}
-			return "1";
-		}
-		case "boolean":
-			return "true";
-		case "date":
-			return "\"2026-01-01T00:00:00.000Z\"";
-		case "literal":
-			return JSON.stringify((def.values as unknown[])[0]);
-		case "enum":
-			return JSON.stringify(Object.keys(def.entries as object)[0]);
-		case "union":
-			return exampleSourceFromSchema((def.options as unknown[])[0]);
-		case "array":
-			return `[${exampleSourceFromSchema(def.element)}]`;
-		case "object": {
-			const entries = Object.entries(def.shape as Record<string, unknown>)
-				.map(([k, v]) => `\t\t${keyOf(k)}: ${exampleSourceFromSchema(v).replaceAll("\n", "\n\t\t")},`);
-			return `{\n${entries.join("\n")}\n\t}`;
-		}
-		case "optional":
-			return exampleSourceFromSchema(def.innerType);
-		case "nullable":
-			return "null";
-		case "default":
-			return JSON.stringify(def.defaultValue);
-		default:
-			return "null";
-	}
+	return JSON.stringify(jsonSchemaToSample(schema));
 }
 
 function emitHandler(ep: IrEndpoint, diag?: OjSchemaDiag): string {
@@ -165,8 +118,15 @@ export async function planStubWrites(ir: IrEndpoint[], opts: PlanStubOptions): P
 	const fix = opts.eslintFix ?? ((code: string) => Promise.resolve(code));
 
 	// 按（模块段 + 目录镜像）分组 → 一个 api.ts
+	// 已在别处（模块根嵌套组 / 其他文件）实现的端点不进 stub 计划。
 	const groups = new Map<string, IrEndpoint[]>();
 	for (const ep of ir) {
+		if (opts.implemented) {
+			const ojFullAbs = (ep.apiPrefix + ep.route).replace(/\/{2,}/g, "/");
+			const contractAbs = `${wirePrefixOf(ep)}${ep.route}`;
+			if ([ojFullAbs, contractAbs].some(a => opts.implemented!.has(`${ep.method} ${a}`)))
+				continue;
+		}
 		const { dir } = splitRoute(ep.route);
 		const rel = [ep.apiPrefix.replace(/^\//, ""), dir, "api.ts"].filter(Boolean).join("/");
 		const list = groups.get(rel) ?? [];