@oj-module/cli 0.1.17 → 0.1.21

package/src/contract/handler-scan.ts

@@ -0,0 +1,263 @@
+import type { IrEndpoint } from "./ir";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import ts from "typescript";
+
+/**
+ * oj handler 文件的 AST 扫描（scan 职责独立成模块，供 check 对账与 emit-stub
+ * 已实现判定共用——check → run/emit-stub 存在反向依赖，扫描器放哪边都会循环）。
+ *
+ * 扫描口径与 oj v0.1.64 内省同规则：default 导出对象的动词键 = 端点；非动词键 +
+ * 对象值 = 嵌套组（组名 = 路径段，字符串字面量键与标识符键同等）；语句起始的
+ * `.route = "..."` 为路由覆写（绝对 / 开头挂 base 根下，否则相对本层前缀）。
+ */
+
+/**
+ * oj 方法名 → HTTP 动词（emit-stub 的反向映射）。
+ * 注意**不含 options**：契约运行时故意不表达 OPTIONS（预检请求由 fetch/CORS 层处理，
+ * 见 runtime/contract 的方法白名单）——oj 树里的 options handler 因此永不进对账表
+ * （不会被误报「未登记」）；routes.js 的 options 行经 parseRoutesJs 的
+ * 大写回落归一，同样不误报 drift。
+ */
+export 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;
+
+export 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("/");
+}
+
+/** 对账键（方法 + 全路径） */
+export function pathKey(method: string, path: string): string {
+	return `${method} ${path}`;
+}
+
+/**
+ * handler 的有效 wire 全路径（带前导 /）：绝对 `.route` 即其自身；相对尾巴 = `/` + full。
+ * 用于与契约 contractAbs（wirePrefix + route）对齐比对。
+ */
+export function handlerAbs(h: HandlerRow): string {
+	return h.tail?.startsWith("/") ? h.tail : `/${h.full}`;
+}
+
+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) {
+			// oj v0.1.64：组名可以是连字符等非标识符（"audit-log"），字符串字面量键与
+			// 标识符键同等解析。保留限制：元素访问式元数据（api["x-y"].route = ...）
+			// 仍不支持——reshape 授权形态为字符串字面量键 + 组内函数挂 .route。
+			const name = (prop.name && (ts.isIdentifier(prop.name) || ts.isStringLiteral(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;
+}
+
+/** 递归收全部 api.ts / api.js（目录形态与模块根单文件同扫） */
+export 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;
+}
+
+/**
+ * 已实现路由键集合（`"METHOD /abs/path"`，含绝对 .route 形态）。
+ * emit-stub 据此跳过「已在别处（模块根嵌套组 / 其他文件）实现」的端点——否则 DDD
+ * reshape 后镜像 stub 与真实 handler 双写同路由，oj 路由表出现重复注册。
+ */
+export function implementedRouteKeys(apiSrcDir: string): Set<string> {
+	const keys = new Set<string>();
+	for (const f of walkApiFiles(apiSrcDir)) {
+		const text = readFileSync(f, "utf8");
+		// stub 镜像文件不算实现——它们覆盖的路由需照常报「stub 缺失/待更新」
+		if (/^\/\/ (?:ojm|ram)-api:stub /.test(text))
+			continue;
+		for (const row of scanHandlerFile(f, apiSrcDir))
+			keys.add(pathKey(row.method, handlerAbs(row)));
+	}
+	return keys;
+}

package/src/contract/ir.ts

@@ -1,48 +1,12 @@
-import type { ApiDefinitionInput } from "@oj-module/runtime/contract";
-import { API_DEF } from "@oj-module/runtime/contract";
-
-/**
- * 旧端点品牌标记（`ram.api.def`）：存量工程若仍装着旧 runtime 产物，其端点打旧符号。
- * 只读兼容识别，故意不进 runtime 公共出口（兼容专用、且下个 major 会随之移除）。
- */
-const API_DEF_LEGACY = Symbol.for("ram.api.def");
-
 /**
- * AC-D12：契约 IR 构建 + schema 白名单。
+ * 统一中间表示（IR）。
  *
- * IR 是 codegen 的统一中间表示：evaluate 出的运行时对象在这里归一
- * （method 缺省、fullPath 拼接、参数段提取、目录切分），各发射器只消费 IR，
- * 不再触碰 zod 内部结构（除 emit-schema 的白名单内递归发射）。
+ * 翻译层退役后，IR 由 `openapi.json`（oj v0.1.73 `oj openapi` 产物）经
+ * `openapi-ir.ts` 构造——本模块只承载 IR 的**类型定义**与少量与路由拼接/切分
+ * 相关的纯函数（`wirePrefixOf` / `splitRoute`），供 emit-client、emit-stub、check
+ * 复用，不再包含任何 zod 求值/白名单逻辑。
  */
 
-/** schema 白名单 def.type（zod v4 `_zod.def.type`） */
-const ALLOWED_TYPES = new Set([
-	"string",
-	"number",
-	"boolean",
-	"date",
-	"object",
-	"array",
-	"enum",
-	"literal",
-	"union",
-	"optional",
-	"nullable",
-	"default",
-]);
-
-/** 白名单内 string/number 约束 check 名（zod v4 check 实例 `_zod.def.check`） */
-const ALLOWED_CHECKS = new Set([
-	"min_length",
-	"max_length",
-	"length_equals",
-	"greater_than",
-	"less_than",
-	"multiple_of",
-	"number_format",
-	"string_format",
-]);
-
 /** multipart 文件部件（DSL 声明归一：required/multiple 显式化，发射器不再看 undefined） */
 export interface IrFormFile {
 	name: string
@@ -51,7 +15,7 @@ export interface IrFormFile {
 }
 
 /**
- * multipart 请求体：文本部件保留 schema（转 JSON Schema / 发射 api.schemas 用），
+ * multipart 请求体：文本部件保留 schema（JSON Schema，转 api.schemas 用），
  * 文件部件只有名字与形态——binary 刻意不进 schema（FormData 由生成 client 组装）。
  */
 export interface IrForm {
@@ -62,7 +26,7 @@ export interface IrForm {
 }
 
 export interface IrEndpoint {
-	/** 契约文件里的导出名，如 "getOrderDetail" */
+	/** 端点方法名（来自 operationId 的 camelCase 推导） */
 	name: string
 	apiPrefix: string
 	/** 线上前缀（D-M8）：缺省 = apiPrefix */
@@ -77,7 +41,7 @@ export interface IrEndpoint {
 	querySchema?: unknown
 	paramsSchema?: unknown
 	bodySchema?: unknown
-	/** multipart/form-data 请求体（与 bodySchema 互斥，定义期已拦截） */
+	/** multipart/form-data 请求体（与 bodySchema 互斥） */
 	form?: IrForm
 	dataSchema?: unknown
 	raw: boolean
@@ -85,60 +49,15 @@ export interface IrEndpoint {
 	description?: string
 }
 
-interface ZodLike { _zod?: { def?: Record<string, unknown> } }
-
-function defOf(schema: unknown, where: string): Record<string, unknown> {
-	const def = (schema as ZodLike)?._zod?.def;
-	if (!def || typeof def.type !== "string") {
-		throw new Error(`[ojm-api] 契约 schema 白名单校验失败（${where}）：不是 zod schema——契约只接受 @oj-module/runtime/contract 导出的 z 构建的 schema。`);
-	}
-	return def;
-}
-
-/**
- * 递归白名单校验：拒绝 pipe/transform（def.type "pipe"）、refine（custom check）、
- * coerce（def.coerce）、lazy 等——它们无法保真反向发射为源码 / 无法转 OpenAPI。
- */
-export function assertWhitelisted(schema: unknown, where: string): void {
-	const def = defOf(schema, where);
-	const type = def.type as string;
-	if (!ALLOWED_TYPES.has(type)) {
-		throw new Error(`[ojm-api] 契约 schema 超出白名单（${where}）：类型 "${type}" 不支持。白名单：${[...ALLOWED_TYPES].join("/")}；transform/refine/coerce/pipe/lazy 无法进入契约（无法转 OpenAPI 与保真发射），请改用纯数据结构约束。`);
-	}
-	if (def.coerce === true) {
-		throw new Error(`[ojm-api] 契约 schema 超出白名单（${where}）：z.coerce.* 不支持——params/query 请直接声明语义类型（如 z.number()），URL 序列化由生成物负责。`);
-	}
-	for (const check of (def.checks as unknown[]) ?? []) {
-		const checkName = (check as ZodLike)?._zod?.def?.check as string | undefined;
-		if (checkName && !ALLOWED_CHECKS.has(checkName)) {
-			throw new Error(`[ojm-api] 契约 schema 超出白名单（${where}）：约束 "${checkName}" 不支持（refine/superRefine 属 custom 校验，无法转 OpenAPI）。`);
-		}
-	}
-	if (type === "object") {
-		for (const [key, child] of Object.entries(def.shape as Record<string, unknown>)) {
-			assertWhitelisted(child, `${where}.${key}`);
-		}
-	}
-	else if (type === "array") {
-		assertWhitelisted(def.element, `${where}[]`);
-	}
-	else if (type === "union") {
-		(def.options as unknown[]).forEach((opt, i) => assertWhitelisted(opt, `${where}<${i}>`));
-	}
-	else if (type === "optional" || type === "nullable" || type === "default") {
-		assertWhitelisted(def.innerType, where);
-	}
+/** 线上前缀（D-M8）：urlPrefix 声明时取之（URL 命名空间 ≠ 目录名），否则回落 apiPrefix */
+export function wirePrefixOf(api: { apiPrefix: string, urlPrefix?: string }): string {
+	return api.urlPrefix ?? api.apiPrefix;
 }
 
 /**
  * route →（目录镜像 + `.route` 尾巴）切分（AC-D10 §4 算法，stub 生成与
  * --check 对账共用同一实现）：静态前缀段 → 目录；自首个参数段起的尾巴 → `.route`。
  */
-/** 线上前缀（D-M8）：urlPrefix 声明时取之（URL 命名空间 ≠ 目录名），否则回落 apiPrefix */
-export function wirePrefixOf(api: { apiPrefix: string, urlPrefix?: string }): string {
-	return api.urlPrefix ?? api.apiPrefix;
-}
-
 export function splitRoute(route: string): { dir: string, tail?: string } {
 	const segs = route.split("/").filter(Boolean);
 	const firstParam = segs.findIndex(seg => seg.startsWith("{"));
@@ -149,90 +68,3 @@ export function splitRoute(route: string): { dir: string, tail?: string } {
 		tail: segs.slice(firstParam).join("/"),
 	};
 }
-
-/** 提取 route 参数段名（catch-all 去 * 前缀） */
-function paramNamesOf(route: string): string[] {
-	return route.split("/")
-		.filter(seg => seg.startsWith("{"))
-		.map(seg => seg.replace(/^\{\*?/, "").replace(/\}$/, ""));
-}
-
-/** evaluate 出的模块导出 → IR 端点数组 */
-export function buildIr(exports: Record<string, unknown>): IrEndpoint[] {
-	const endpoints: IrEndpoint[] = [];
-	for (const [name, value] of Object.entries(exports)) {
-		// 双符号识别（R3）：新契约打 ojm.api.def，存量（旧 runtime 产物）打 ram.api.def
-		const brand = value as Record<PropertyKey, unknown> | undefined;
-		if (brand?.[API_DEF] !== true && brand?.[API_DEF_LEGACY] !== true)
-			continue;
-		const def = value as ApiDefinitionInput;
-		// schema 白名单（报错文案含端点名 + 字段路径）
-		for (const slot of ["query", "params", "body", "data"] as const) {
-			const schema = def[slot];
-			if (schema)
-				assertWhitelisted(schema, `${name}.${slot}`);
-		}
-		// multipart/form-data（与 body 互斥，定义期已拦截）：文本部件走同一套 schema 白名单；
-		// 文件部件只有名字/形态，二进制刻意不进 schema（JSON Schema 无 binary、FormData 由 client 组装）
-		let form: IrForm | undefined;
-		if (def.form) {
-			let fieldNames: string[] = [];
-			if (def.form.fields) {
-				assertWhitelisted(def.form.fields, `${name}.form.fields`);
-				const fieldsDef = defOf(def.form.fields, `${name}.form.fields`);
-				if (fieldsDef.type !== "object") {
-					throw new Error(`[ojm-api] 契约端点 "${name}"：form.fields 必须是 z.object（收到类型 "${String(fieldsDef.type)}"）——文本部件按字段名进 multipart 表单（OpenAPI 同形）；单个非对象值请改用 body（JSON）。`);
-				}
-				fieldNames = Object.keys(fieldsDef.shape as Record<string, unknown>);
-			}
-			form = {
-				fieldsSchema: def.form.fields,
-				fieldNames,
-				files: (def.form.files ?? []).map(f => ({ name: f.name, required: f.required === true, multiple: f.multiple === true })),
-			};
-		}
-		const paramNames = paramNamesOf(def.route);
-		// 评审 F8：params schema 键必须覆盖 route 参数段——否则生成物 URL 插值出 undefined
-		if (def.params) {
-			const shape = (def.params as unknown as ZodLike)?._zod?.def?.shape as Record<string, unknown> | undefined;
-			if (!shape) {
-				throw new Error(`[ojm-api] 契约端点 "${name}"：params 必须是 z.object（收到非 object schema）——params 与 route 参数段一一对应。`);
-			}
-			const missing = paramNames.filter(p => !(p in shape));
-			if (missing.length) {
-				throw new Error(`[ojm-api] 契约端点 "${name}"：params schema 缺 route 参数段 ${missing.map(p => `{${p}}`).join("、")} 的键——两者须一一对应（缺省 params 则参数段全按 string 声明，二选一）。`);
-			}
-		}
-		endpoints.push({
-			name,
-			apiPrefix: def.apiPrefix,
-			urlPrefix: def.urlPrefix,
-			route: def.route,
-			method: def.method ?? "GET",
-			// apiPrefix "/" 为框架内部根级端点（如 runtime 自带 role-list）——拼出 "//" 即错
-			fullPath: wirePrefixOf(def) === "/" ? def.route : `${wirePrefixOf(def)}${def.route}`,
-			paramNames,
-			querySchema: def.query,
-			paramsSchema: def.params,
-			bodySchema: def.body,
-			form,
-			dataSchema: def.data,
-			raw: def.response === "raw",
-			ignoreLoading: def.ignoreLoading,
-			description: def.description,
-		});
-	}
-
-	// 同（目录, method）冲突：oj 中同一 api.ts 文件同一方法名只能有一个 handler
-	const seen = new Map<string, string>();
-	for (const ep of endpoints) {
-		const { dir } = splitRoute(ep.route);
-		const key = `${ep.apiPrefix}|${dir}|${ep.method}`;
-		const existing = seen.get(key);
-		if (existing) {
-			throw new Error(`[ojm-api] 契约路由冲突："${existing}" 与 "${ep.name}" 都映射到 ${ep.apiPrefix}/${dir}/api.ts 的 ${ep.method}——同一目录同一方法只能有一个端点（oj 一文件一方法一 handler），请调整 route 拆目录。`);
-		}
-		seen.set(key, ep.name);
-	}
-	return endpoints;
-}

package/src/contract/json-schema-sample.ts

@@ -0,0 +1,72 @@
+/**
+ * JSON Schema（oj `openapi.json` 白名单子集）→ 示例值。
+ *
+ * 零依赖（不引入 faker，保证 emit-stub 复用时不与 mock 形成循环依赖）：
+ * 示例值**确定性**生成，便于 stub / mock 字节稳定。仅覆盖 oj `.schema` 表达力
+ * （type / properties / items / enum / min / max / minLength / maxLength）；
+ * `pattern` 是 Rust regex，无法表达，忽略（示例值不强制满足 pattern）。
+ *
+ * 语义与 emit-stub 的示例源码生成共用同一套（emit-stub 用 JSON.stringify 把返回值
+ * 包成 TS 字面量）。
+ */
+
+function numOf(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+/** 类型数组 ["string","null"] → 取非 null 实类型；其余返回 undefined（无法取样本） */
+function singleTypeOf(type: unknown): string | undefined {
+	if (typeof type === "string")
+		return type;
+	if (Array.isArray(type)) {
+		const nonNull = (type as unknown[]).filter(t => t !== "null");
+		return nonNull.length === 1 ? (nonNull[0] as string) : undefined;
+	}
+	return undefined;
+}
+
+export function jsonSchemaToSample(schema: unknown): unknown {
+	if (!schema || typeof schema !== "object")
+		return null;
+	const s = schema as Record<string, unknown>;
+	// enum 优先：oj 把 zod enum 翻成 {type, enum}，示例值应取枚举首值（而非「示例」占位），
+	// 否则 mock/client 示例值永远偏离真实取值。
+	if (Array.isArray(s.enum) && s.enum.length > 0)
+		return s.enum[0];
+	const type = singleTypeOf(s.type);
+
+	switch (type) {
+		case "string": {
+			const min = numOf(s.minLength) ?? 0;
+			const max = numOf(s.maxLength) ?? Number.POSITIVE_INFINITY;
+			// 默认「示例」恰好 2 字：低于 min 则补足，高于 max 则截断（保约束成立）
+			let word = "示例";
+			if (word.length < min)
+				word = "示".repeat(Math.max(min, 1));
+			if (Number.isFinite(max) && word.length > max)
+				word = word.slice(0, max);
+			return word;
+		}
+		case "integer":
+		case "number": {
+			const min = numOf(s.minimum) ?? 1;
+			const lo = Number.isFinite(min) ? Math.ceil(min) : 1;
+			return lo;
+		}
+		case "boolean":
+			return true;
+		case "array":
+			return [jsonSchemaToSample(s.items)];
+		case "object": {
+			const out: Record<string, unknown> = {};
+			const props = (s.properties as Record<string, unknown>) ?? {};
+			for (const [k, v] of Object.entries(props))
+				out[k] = jsonSchemaToSample(v);
+			return out;
+		}
+		default:
+			if (Array.isArray(s.enum) && s.enum.length > 0)
+				return s.enum[0];
+			return null;
+	}
+}