@oj-module/cli 0.2.18 → 0.2.23

package/src/layout.ts

@@ -1,13 +1,24 @@
 /**
- * 模块工程布局探测（设计 D11，2026-09-11 硬切换）。
+ * 模块工程布局探测（设计 D11，2026-09-11 硬切换；2026-10 增补 module-root）。
  *
  * dev/build/preview 对「源码目录、产物目录、watch 目录」的全部路径取值
  * 一律经此模块，禁止各自手拼——布局分叉点收敛一处。
  *
- * 布局（uni-dev）：web/src/ + web/dist/（src/dist 同级配对）。
- * 框架根仓自身为平铺 web/<name>/（dogfooding，产物落 build/，不经 ojm）。
- * 硬切换只认 web/：存量 modules/ 工程不再探测，须迁移
- * （modules/ → web/，modules.config.ts → web.config.ts）。
+ * 三种布局（互斥）：
+ *   module-root  <project>/src/<name>/{api,web}   新布局：一目录一模块（设计 v2）
+ *   new           <project>/web/src/<name>        历史 uni-dev 布局
+ *   flat          <project>/web/<name>            框架根仓 dogfooding（产物落 build/）
+ *
+ * module-root 的判定只认「模块根标记文件」而不是单纯的 src/ 存在性：工程里
+ * 常有不属于模块的 src/（脚本、共享库），凭目录名猜会误判。
+ * `src/<x>/api/manifest.yaml` 与 `src/<x>/web/entry.ts` 是唯一真源（设计 C-6：
+ * 一侧可缺省，两侧皆无则不是模块）。
+ *
+ * 产物根在两套布局里语义相同、位置不变：
+ *   api/dist   oj 扁平 release 根（<name>-<version>/ 同层兄弟 + manifests.yaml）
+ *   web/dist   站点产物（shell + modules/ + modules.json）
+ * 产物按模块聚合已被设计 §2.2 否决（实证见该节），禁止在此引入第二套形状。
+ *
  * watch 目标绝不含产物目录：若 watch `web/`，重建产物（web/dist）
  * 会反过来触发重建，形成自触发循环（设计 §4）。
  */
@@ -15,40 +26,270 @@
 import fs from "node:fs";
 import path from "node:path";
 
+export type LayoutKind = "module-root" | "new" | "flat";
+
+/** 模块一侧的可缺省组合：两侧皆无不是模块（设计 C-6） */
+export interface ModuleSides {
+	name: string
+	/** 后端源码目录 `<project>/src/<name>/api`（无此侧为 undefined） */
+	apiSrc?: string
+	/** 前端源码目录 `<project>/src/<name>/web`（无此侧为 undefined） */
+	webSrc?: string
+}
+
 export interface ProjectLayout {
-	kind: "new" | "flat"
-	/** 模块源码目录（watch 与 build 的 entry 来源） */
+	kind: LayoutKind
+	projectRoot: string
+	/** 模块源码目录：module-root → `<project>/src`；new → `<project>/web/src`；flat → `<project>/web` */
 	modulesSrc: string
-	/** 产物目录：dev 写 modules.json + modules/；ojm build 合并全站于此 */
+	/** 站点产物根：module-root / new → `<project>/web/dist`；flat → `<project>/build` */
 	distDir: string
+	/** oj 扁平 release 根：恒为 `<project>/api/dist`（设计 C-3/C-7，不随布局变化） */
+	apiDist: string
 	/** fs.watch 目标（纯源码，永不落产物） */
 	watchTarget: string
+	/**
+	 * oj 的 `--module-root` 取值（源码树根目录），仅 module-root 有值。
+	 *
+	 * v0.1.85 语义：在**该目录的子树内递归**找 `manifest.yaml`，命中即停；模块身份取
+	 * manifest 的 `name`（目录名只作定位）。它与 `-d`/`--api-path` **互斥**——两者都是
+	 * 「源码树根」，同时给会被 clap 拒掉，所以调用方是二选一，不是「-d + 附加旗标」。
+	 */
+	moduleRoot?: string
 }
 
-export function resolveLayout(projectRoot: string): ProjectLayout {
-	if (fs.existsSync(path.join(projectRoot, "web/src"))) {
+function isDir(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	}
+	catch {
+		return false;
+	}
+}
+
+function isFile(p: string): boolean {
+	try {
+		return fs.statSync(p).isFile();
+	}
+	catch {
+		return false;
+	}
+}
+
+/**
+ * 扫描 module-root 布局的 `src/`：返回模块清单与「像模块但缺标记文件」的坏目录。
+ *
+ * 坏目录只在 module-root 被判定为当前布局后才报错（见 resolveLayout），
+ * 否则一个恰好带 `src/utils/api/` 的历史工程会被误伤。
+ */
+function scanModuleRoot(projectRoot: string): { modules: ModuleSides[], broken: string[] } | null {
+	const srcDir = path.join(projectRoot, "src");
+	if (!isDir(srcDir))
+		return null;
+
+	const modules: ModuleSides[] = [];
+	const broken: string[] = [];
+	// 按名字排序：readdir 的顺序取决于文件系统与创建历史（同一份源码在不同机器上可能不同），
+	// 而枚举顺序会进入构建顺序与产物内容——不排序则「同布局两次构建 sha256 相等」无法保证。
+	const entries = fs.readdirSync(srcDir, { withFileTypes: true })
+		.filter(ent => ent.isDirectory() && !ent.name.startsWith("."))
+		.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+	for (const ent of entries) {
+		const dir = path.join(srcDir, ent.name);
+		const apiDir = path.join(dir, "api");
+		const webDir = path.join(dir, "web");
+		const hasApi = isFile(path.join(apiDir, "manifest.yaml"));
+		const hasWeb = isFile(path.join(webDir, "entry.ts"));
+		if (!hasApi && !hasWeb) {
+			// 只把「有 api/ 或 web/ 子目录但缺标记」算坏目录；纯共享库目录（无两者）静默跳过
+			if (isDir(apiDir) || isDir(webDir))
+				broken.push(ent.name);
+			continue;
+		}
+		modules.push({
+			name: ent.name,
+			apiSrc: hasApi ? apiDir : undefined,
+			webSrc: hasWeb ? webDir : undefined,
+		});
+	}
+	return { modules, broken };
+}
+
+/** 历史布局：`web/src` 为 uni-dev 工程；`web/<name>/entry.ts` 为框架根仓 */
+function detectLegacyKind(projectRoot: string): LayoutKind | null {
+	if (isDir(path.join(projectRoot, "web", "src")))
+		return "new";
+	const webDir = path.join(projectRoot, "web");
+	if (isDir(webDir)) {
+		for (const ent of fs.readdirSync(webDir, { withFileTypes: true })) {
+			if (ent.isDirectory() && isFile(path.join(webDir, ent.name, "entry.ts")))
+				return "flat";
+		}
+	}
+	return null;
+}
+
+/**
+ * 探测布局；工程里没有任何模块源码时返回 null（供 `buildBackend` 这类「没有源码就
+ * 跳过」的调用方使用）。布局存在但**自相矛盾**（双树并存 / src 下有坏模块目录）仍抛错。
+ */
+export function tryResolveLayout(projectRoot: string): ProjectLayout | null {
+	const scanned = scanModuleRoot(projectRoot);
+	const isModuleRoot = !!scanned && scanned.modules.length > 0;
+	const legacyKind = detectLegacyKind(projectRoot);
+
+	// 互斥：两套源码树同时存在时静默选一个，会让 `ojm build` 构建 A 而 `ojm dev` 预览 B
+	if (isModuleRoot && legacyKind) {
+		throw new Error(
+			`[ojm] ${projectRoot} 同时存在两套模块源码树：src/<name>/{api,web} 与 `
+			+ `${legacyKind === "new" ? "web/src/<name>" : "web/<name>"}。\n`
+			+ "布局互斥，无法判断以哪套为准——请显式移除其中一套后重试。",
+		);
+	}
+
+	if (scanned && (isModuleRoot || legacyKind === null) && scanned.broken.length > 0) {
+		throw new Error(
+			`[ojm] ${projectRoot}/src 下这些目录既无 api/manifest.yaml 也无 web/entry.ts：\n${
+				scanned.broken.map(n => `  - src/${n}/`).join("\n")}\n`
+				+ "module-root 布局里一个目录 = 一个模块，至少需要其中一侧；"
+				+ "若这些目录不是模块（脚本、共享库），请移到 src/ 之外。",
+		);
+	}
+
+	if (isModuleRoot) {
+		return {
+			kind: "module-root",
+			projectRoot,
+			modulesSrc: path.join(projectRoot, "src"),
+			distDir: path.join(projectRoot, "web", "dist"),
+			apiDist: path.join(projectRoot, "api", "dist"),
+			watchTarget: path.join(projectRoot, "src"),
+			moduleRoot: path.join(projectRoot, "src"),
+		};
+	}
+
+	if (legacyKind === "new") {
 		return {
 			kind: "new",
-			modulesSrc: path.join(projectRoot, "web/src"),
-			distDir: path.join(projectRoot, "web/dist"),
-			watchTarget: path.join(projectRoot, "web/src"),
+			projectRoot,
+			modulesSrc: path.join(projectRoot, "web", "src"),
+			distDir: path.join(projectRoot, "web", "dist"),
+			apiDist: path.join(projectRoot, "api", "dist"),
+			watchTarget: path.join(projectRoot, "web", "src"),
 		};
 	}
+
 	// 框架根仓：平铺 web/<name>/（readModuleDefinition 的裸说明符扫描复用此探测，B10）
-	if (fs.existsSync(path.join(projectRoot, "web"))) {
+	if (legacyKind === "flat") {
 		return {
 			kind: "flat",
+			projectRoot,
 			modulesSrc: path.join(projectRoot, "web"),
 			distDir: path.join(projectRoot, "build"),
+			apiDist: path.join(projectRoot, "api", "dist"),
 			watchTarget: path.join(projectRoot, "web"),
 		};
 	}
+
+	return null;
+}
+
+export function resolveLayout(projectRoot: string): ProjectLayout {
+	const layout = tryResolveLayout(projectRoot);
+	if (layout)
+		return layout;
 	throw new Error(
-		`[ojm] ${projectRoot} 下未发现 web/——web 布局硬切换后只认 web/src + web/dist，`
+		`[ojm] ${projectRoot} 下未发现模块源码（硬切换后只认 web/src；2026-10 起也认 src/<name>/{api,web}）：\n`
+		+ "  - 新布局：src/<name>/{api/manifest.yaml 或 web/entry.ts}\n"
+		+ "  - 历史布局：web/src/<name>（uni-dev）或 web/<name>/entry.ts（框架根仓）\n"
 		+ "存量 modules/ 工程请迁移：modules/ → web/，modules.config.ts → web.config.ts。",
 	);
 }
 
+/**
+ * 枚举 module-root 布局的模块（设计 C-6：真源是标记文件，不是人工登记的 web.config.ts）。
+ * 历史布局的模块顺序由 `web.config.ts` 的 `modules` 决定，此处不适用。
+ */
+export function scanModules(layout: ProjectLayout): ModuleSides[] {
+	if (layout.kind !== "module-root")
+		throw new Error(`[ojm] scanModules 只适用于 module-root 布局，当前为 ${layout.kind}`);
+	return scanModuleRoot(layout.projectRoot)?.modules ?? [];
+}
+
+/** 契约工具的处理单元：模块名 + 该模块 api 侧目录（handler 目录镜像的根） */
+export interface ApiModuleRoot {
+	name: string
+	dir: string
+}
+
+/**
+ * 历史布局的模块 api 根：`<project>/api/src/<name>`。
+ *
+ * 单独导出是因为**纯后端工程**可能只有 `api/src` 而没有 `web/src`——`tryResolveLayout`
+ * 会返回 null，契约工具仍要能对账。
+ */
+export function legacyApiModuleRoots(projectRoot: string): ApiModuleRoot[] {
+	const root = path.join(projectRoot, "api", "src");
+	if (!isDir(root))
+		return [];
+	return fs.readdirSync(root, { withFileTypes: true })
+		.filter(entry => entry.isDirectory() && !entry.name.startsWith("."))
+		.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+		.map(entry => ({ name: entry.name, dir: path.join(root, entry.name) }));
+}
+
+/**
+ * 枚举后端模块的 api 根，供 `ojm api` 生成 / `--check` 对账**按模块**扫描。
+ *
+ * 为什么不直接 walk `apiModulesSrc(layout)`：module-root 布局的树根是 `src`，模块的
+ * api 侧在 `<src>/<name>/api`，中间那层 `api` 是**布局分隔符、不是路由段**。拿 `src`
+ * 当扫描根会双重出错——路由镜像多出 `api` 段（`system/api/users` ≠ 真实 `system/users`），
+ * 且 `src/<name>/web/__client/api.ts` 这种前端生成物也会被当 handler 扫进来。
+ *
+ * module-root → 按 `<name>/api/manifest.yaml` 判模块（与 build 同源，name 取 manifest）；
+ * 历史布局    → `<project>/api/src` 的一级目录即模块。
+ */
+export function apiModuleRoots(layout: ProjectLayout): ApiModuleRoot[] {
+	if (layout.kind !== "module-root")
+		return legacyApiModuleRoots(layout.projectRoot);
+	return scanModules(layout)
+		.filter((m): m is ModuleSides & { apiSrc: string } => !!m.apiSrc)
+		.map(m => ({ name: m.name, dir: m.apiSrc }));
+}
+
+/** `<project>/src/<name>` */
+export function moduleDir(layout: ProjectLayout, name: string): string {
+	return path.join(layout.modulesSrc, name);
+}
+
+/**
+ * 后端源码根。module-root 为 `<modulesSrc>/<name>/api`（模块的 api 侧目录）；
+ * 历史布局为 `<project>/api/src/<name>`——不在 modulesSrc 之下，必须走 projectRoot。
+ */
+export function apiSrcOf(layout: ProjectLayout, name: string): string {
+	return layout.kind === "module-root"
+		? path.join(layout.modulesSrc, name, "api")
+		: path.join(layout.projectRoot, "api", "src", name);
+}
+
+/**
+ * 后端源码的**根**目录：
+ *   module-root → `<project>/src`（oj 的 `--module-root` 取源码树根，模块在每层 api 子目录）
+ *   历史布局    → `<project>/api/src`（oj 的 `-d` / `--api-path` 取模块目录的父级）
+ */
+export function apiModulesSrc(layout: ProjectLayout): string {
+	return layout.kind === "module-root"
+		? layout.modulesSrc
+		: path.join(layout.projectRoot, "api", "src");
+}
+
+/** 前端源码目录（历史布局与模块目录同体） */
+export function webSrcOf(layout: ProjectLayout, name: string): string {
+	return layout.kind === "module-root"
+		? path.join(layout.modulesSrc, name, "web")
+		: path.join(layout.modulesSrc, name);
+}
+
 export function resolveWatchTarget(projectRoot: string): string {
 	return resolveLayout(projectRoot).watchTarget;
 }
@@ -56,21 +297,38 @@ export function resolveWatchTarget(projectRoot: string): string {
 /**
  * 定位工程 config.yaml。
  *
- * 唯一规范位置：`<project>/api/config.yaml`。
+ * 唯一规范位置由布局决定：
+ *   module-root → `<project>/config.yaml`
+ *   历史布局    → `<project>/api/config.yaml`
  *
- * 不能挪到与 api/ 同级的 config/ 目录：oj 的模块解析把「项目根」锚定在
- * **config 文件所在目录**，且相对 import 被钳制在该根内（devkit 手册第 5 章）。
- * config 一进 `config/` 子目录，`api/src` 就整体落到项目根之外，凡是带 `../`
- * 相对 import 的 handler（模板的 system/auth/_platform 依赖 `_shared/`）在
- * `ojm dev` 下会被判 `escapes project root` 而整条路由加载失败
- * （实测：26 个 api 文件 → 只剩 8 个，18 条路由被跳过）。
+ * module-root 下没有回退到 `api/config.yaml`：oj 把「项目根」锚定在 **config 文件所在目录**，
+ * 相对 import 被钳制在该根内（devkit 手册第 5 章）。源码搬到 `src/` 而 config 留在 `api/`
+ * 时，project root 收缩成 `<project>/api`，`src/` 整体落到根之外——凡是带 `../` 相对 import
+ * 的 handler 在 `ojm dev` 下会被判 `escapes project root` 而整条路由加载失败
+ * （实测：26 个 api 文件 → 只剩 8 个，18 条路由被跳过）。回退会把这个陷阱伪装成「能跑」。
  */
 export function resolveConfigPath(projectRoot: string): string {
-	return path.join(projectRoot, "api", "config.yaml");
+	const rootConfig = path.join(projectRoot, "config.yaml");
+	if (isFile(rootConfig))
+		return rootConfig;
+	const legacyConfig = path.join(projectRoot, "api", "config.yaml");
+	// 源码已是 module-root 但 config 还在 api/ ⇒ 迁移未完成。此时回退会踩上面那个陷阱，
+	// 且症状是「部分路由静默消失」，比直接失败更难排查。
+	if (isFile(legacyConfig) && (scanModuleRoot(projectRoot)?.modules.length ?? 0) > 0) {
+		throw new Error(
+			`[ojm] ${projectRoot} 已是 src/<name>/{api,web} 布局，但 config.yaml 仍在 api/ 下。\n`
+			+ `请移到 ${rootConfig}（证书目录随之变为 ${path.join(projectRoot, "config")}）。\n`
+			+ "oj 以 config 所在目录为 project root：config 留在 api/ 会把 src/ 甩到根外，"
+			+ "带 ../ 相对 import 的 handler 会被判 escapes project root 而整条路由不加载。",
+		);
+	}
+	return legacyConfig;
 }
 
 /**
- * 证书与密钥的唯一落点：`<project>/api/config/`（config.yaml 同级的 config/ 子目录）。
+ * 证书与密钥的唯一落点：config.yaml 同级的 `config/` 子目录。
+ *
+ * module-root → `<project>/config/`；历史布局 → `<project>/api/config/`。
  *
  * 三个入口都指向这里，别再各自手拼：
  *   ① `server.public_key_path`     → ./config/public.pem（oj 验签公钥）

package/src/lifecycle/__tests__/args.test.ts

@@ -0,0 +1,20 @@
+// BDD：ojm new 参数解析（统一审查 F8——多余位置参数须显式拒绝，不能静默丢弃）。
+// 静默丢弃的恶果：ojm new crm erp（手滑/粘贴）只建 crm，用户以为两份都建了。
+import { describe, expect, it } from "vitest";
+import { parseNewArgs } from "../../args";
+
+describe("parseNewArgs", () => {
+	it("name + 旗标组合", () => {
+		expect(parseNewArgs(["crm"])).toEqual({ name: "crm", layout: undefined, api: false });
+		expect(parseNewArgs(["crm", "--layout", "none", "--api"])).toEqual({ name: "crm", layout: "none", api: true });
+		expect(parseNewArgs([])).toEqual({ name: undefined, layout: undefined, api: false });
+	});
+
+	it("多余位置参数 → 报错而非静默丢弃", () => {
+		expect(() => parseNewArgs(["crm", "erp"])).toThrow(/只接受一个方案名/);
+	});
+
+	it("非法 --layout 值 → 报错", () => {
+		expect(() => parseNewArgs(["crm", "--layout", "sidebar"])).toThrow(/container \| none/);
+	});
+});

package/src/lifecycle/__tests__/builtin.test.ts

@@ -0,0 +1,97 @@
+// BDD：脚手架自带模块身份（`src/.ojm-builtin.json`）。
+// 消费契约：bundle 排除打包 / ojm info 折叠 / ojm new 拒名；文件缺失 → 空名单（旧工程兼容）。
+// 用例对应设计 docs/plans/2026-10-22-1640-multi-solution-bundle-design.md：
+//   B12（坏文件 fail-fast）/ T1（名单 == 白名单派生集）/ T2（copyIfAbsent，不覆盖用户手改）
+import { existsSync, mkdirSync, 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 { BUILTIN_LIST_FILE, deriveBuiltinModules, readBuiltinModules, writeBuiltinList } from "../../builtin";
+
+let project: string;
+
+beforeEach(() => {
+	project = mkdtempSync(join(tmpdir(), "ojm-builtin-"));
+});
+
+afterEach(() => {
+	rmSync(project, { recursive: true, force: true });
+});
+
+function writeList(content: string): void {
+	mkdirSync(join(project, "src"), { recursive: true });
+	writeFileSync(join(project, "src", BUILTIN_LIST_FILE), content);
+}
+
+describe("readBuiltinModules", () => {
+	it("文件缺失 → 空名单（旧工程/框架仓无内置概念，行为退化兼容）", () => {
+		expect(readBuiltinModules(project).size).toBe(0);
+	});
+
+	it("合法文件 → 返回 modules 集合", () => {
+		writeList(JSON.stringify({ modules: ["auth", "home"] }));
+		expect([...readBuiltinModules(project)].sort()).toEqual(["auth", "home"]);
+	});
+
+	it("b12 坏 JSON → fail-fast，报错含文件路径与错因（不静默降级）", () => {
+		writeList("{ not json");
+		expect(() => readBuiltinModules(project)).toThrow(new RegExp(`${BUILTIN_LIST_FILE.replace(".", "\\.")}`));
+	});
+
+	it("b12 modules 非数组 → fail-fast", () => {
+		writeList(JSON.stringify({ modules: "auth" }));
+		expect(() => readBuiltinModules(project)).toThrow(/modules/);
+	});
+
+	it("b12 modules 含非字符串项 → fail-fast", () => {
+		writeList(JSON.stringify({ modules: ["auth", 42] }));
+		expect(() => readBuiltinModules(project)).toThrow(/modules/);
+	});
+});
+
+describe("deriveBuiltinModules（名单派生自 init.include.yaml，单一真源）", () => {
+	it("t1 取 src/<name>/(api|web) 条目的模块名（含 web-only 模块），忽略无关路径", () => {
+		const include = new Set([
+			"src/auth/api",
+			"src/notification/api",
+			"src/login/web/entry.ts",
+			"src/oj-market/web/pages",
+			"src/styles.css",
+			"src/tsconfig.json",
+			"config.yaml",
+			"web.config.ts",
+		]);
+		expect([...deriveBuiltinModules(include)].sort())
+			.toEqual(["auth", "login", "notification", "oj-market"]);
+	});
+
+	it("白名单无模块条目 → 空集（不凭空造身份）", () => {
+		expect(deriveBuiltinModules(new Set(["config.yaml", "README.md"])).size).toBe(0);
+	});
+});
+
+describe("writeBuiltinList（init 接线：copyIfAbsent）", () => {
+	it("t1 写入派生名单（排序）+ 自注释头，返回 created", () => {
+		const include = new Set(["src/home/web/entry.ts", "src/auth/api", "src/login/web"]);
+		expect(writeBuiltinList(project, include)).toBe("created");
+		const p = join(project, "src", BUILTIN_LIST_FILE);
+		expect(existsSync(p)).toBe(true);
+		const doc = JSON.parse(readFileSync(p, "utf-8"));
+		expect(doc.modules).toEqual(["auth", "home", "login"]);
+		expect(typeof doc["//"]).toBe("string");
+	});
+
+	it("t2 已存在 → 返回 skipped 且内容原样不动（用户手改权）", () => {
+		const include = new Set(["src/auth/api"]);
+		expect(writeBuiltinList(project, include)).toBe("created");
+		const p = join(project, "src", BUILTIN_LIST_FILE);
+		writeFileSync(p, JSON.stringify({ modules: ["my-edit"] }));
+		expect(writeBuiltinList(project, include)).toBe("skipped");
+		expect(JSON.parse(readFileSync(p, "utf-8")).modules).toEqual(["my-edit"]);
+	});
+
+	it("派生集为空 → 不写文件，返回 none", () => {
+		expect(writeBuiltinList(project, new Set(["config.yaml"]))).toBe("none");
+		expect(existsSync(join(project, "src", BUILTIN_LIST_FILE))).toBe(false);
+	});
+});