@godcreator/word-report 0.3.1 → 0.4.1

package/README.md

@@ -13,7 +13,7 @@
 | `@godcreator/code-pin`、`@godcreator/doc-export`、`@godcreator/trajectory` | 钉码、生成物、轨迹卡与星轨盘 |
 | `@godcreator/docfirst` | 命令行 `docfirst`：核对、确认、生成 |
 | `@godcreator/collab` | 项目协作：任务与模块、日志与日历、通知、合并检查 |
-| `@godcreator/word-report` | 报告：JSON 报告文档、报告列表与报告页、命令行 `report-docx`（检查、导出 Word） |
+| `@godcreator/word-report` | 报告：正文写成 MDX 或 JSON 的报告文档、报告列表与报告页、命令行 `report-docx`（检查、导出 Word、JSON 转 MDX） |
 
 | 插件（`plugins/`） | 做什么 |
 | --- | --- |

package/dist/{assemble-3cx8L2vo.mjs → assemble-BpllQNVY.mjs}

@@ -994,12 +994,21 @@ function assembleDocument(entry, files, options = {}) {
 	}
 	const counts = {
 		decimal: 0,
-		appendix: 0,
-		figure: 0,
-		table: 0
+		appendix: 0
 	};
 	let appendixSeen = false;
-	const eqCounts = /* @__PURE__ */ new Map();
+	const chapterCounts = {
+		figure: /* @__PURE__ */ new Map(),
+		table: /* @__PURE__ */ new Map(),
+		equation: /* @__PURE__ */ new Map()
+	};
+	/** 图、编号表格、编号公式各自按所在的顶层章从 1 编，写成「章号-n」；导出 Word 的题注同样取章号，不在编号章里就没有章号可取 */
+	function chapterNumber(node, kind, chapter) {
+		if (!chapter) fail(node, `Numbered ${kind} outside a numbered chapter`);
+		const n = (chapterCounts[kind].get(chapter) ?? 0) + 1;
+		chapterCounts[kind].set(chapter, n);
+		return `${chapter}-${n}`;
+	}
 	function blockNumbers(blocks, depth = 0, chapter, parentNumber, parentMode, tables = 0) {
 		let decimal = 0;
 		for (const node of blocks) {
@@ -1029,18 +1038,15 @@ function assembleDocument(entry, files, options = {}) {
 				continue;
 			}
 			if (node.type === "figure") {
-				number = String(++counts.figure);
+				number = chapterNumber(node, "figure", chapter);
 				label = `图 ${number}`;
 			}
 			if (node.type === "table" && node.numbered) {
-				number = String(++counts.table);
+				number = chapterNumber(node, "table", chapter);
 				label = `表 ${number}`;
 			}
 			if (node.type === "equation" && node.numbered) {
-				if (!chapter) fail(node, "Numbered equation outside a numbered chapter");
-				const n = (eqCounts.get(chapter) ?? 0) + 1;
-				eqCounts.set(chapter, n);
-				number = `${chapter}-${n}`;
+				number = chapterNumber(node, "equation", chapter);
 				label = `式（${number}）`;
 			}
 			if (node.id) index[node.id] = {
@@ -1186,4 +1192,4 @@ function alphabet(n) {
 	return s;
 }
 //#endregion
-export { parseReportJson as a, walk as i, safeRelativePath as n, ReportContentError as o, validateDocument as r, assembleDocument as t };
+export { walk as a, validateDocument as i, safeRelativePath as n, parseReportJson as o, stableValue as r, ReportContentError as s, assembleDocument as t };

package/dist/cli.d.mts

@@ -1,18 +1,27 @@
-import { n as ReportExportResult, o as ReportCheckResult, t as ReportExportOptions } from "./export-DC764Umz.mjs";
+import { a as ConvertReportResult, c as ReportCheckResult, n as ReportExportResult, t as ReportExportOptions } from "./export-Da4yhrZa.mjs";
 //#region src/node/cli.d.ts
+/** export、status 的入口要看磁盘上是哪种报告，由 main 补上 */
 type CliCommand = {
   command: 'export' | 'status';
-  options: ReportExportOptions;
+  reportId: string;
+  options: Omit<ReportExportOptions, 'entry'>;
 } | {
   command: 'check';
   siteDir: string;
   json: boolean;
+} | {
+  command: 'convert';
+  siteDir: string;
+  sourceId: string;
+  targetId: string;
 };
 /** 解析命令行；要显示说明时回 undefined。参数不对直接报错 */
 declare function parseCliArgs(args: string[], cwd?: string): CliCommand | undefined;
 interface CliDependencies {
   reportExport?: (options: ReportExportOptions) => Promise<ReportExportResult>;
   checkReports?: (siteDir: string) => Promise<ReportCheckResult>;
+  reportEntryIn?: (siteDir: string, reportId: string) => Promise<string>;
+  convertReportToMdx?: (siteDir: string, sourceId: string, targetId: string) => Promise<ConvertReportResult>;
   sleep?: (milliseconds: number) => Promise<void>;
   stdout?: (text: string) => void;
   stderr?: (text: string) => void;

package/dist/cli.mjs

@@ -1,17 +1,19 @@
 #!/usr/bin/env node
-import { n as reportExport, r as checkReports } from "./export-TbclsIsE.mjs";
-import { r as reportEntryOf } from "./report-files-DM9Ea6yK.mjs";
+import { i as checkReports, r as reportExport, t as convertReportToMdx } from "./convert-o7bPWP9A.mjs";
+import { o as reportEntryIn, s as reportEntryOf } from "./report-files-BsIvifZe.mjs";
 import path from "node:path";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region src/node/cli.ts
 const help = `用法：report-docx <export|status> <报告 id> [选项]
       report-docx check [选项]
+      report-docx convert <JSON 报告 id> <新报告 id> [--site <目录>]
 
-报告在站点目录的 reports/<报告 id>/content.json。
-export  导出这份报告的 Word 与 PDF，等这次导出做完，把结果按 JSON 打出来
-status  只看这份报告的导出状态，不启动 Word
-check   检查站点里全部报告（每份报告、每一章）的格式、引用与图片，有问题时退出码非零
+报告在站点目录的 reports/<报告 id>/：入口是 content.json（JSON 报告）或 index.mdx（MDX 报告）。
+export   导出这份报告的 Word 与 PDF，等这次导出做完，把结果按 JSON 打出来
+status   只看这份报告的导出状态，不启动 Word
+check    检查站点里全部报告（JSON 报告的每份与每一章、MDX 报告整份）的格式、引用与图片，有问题时退出码非零
+convert  把一份 JSON 报告转成一份新的 MDX 报告，转完编译回来和原报告逐项比对，对不上就删掉新目录、退出码非零；不动原报告
 
 选项：
   --site <目录>     站点目录（默认当前目录）
@@ -43,7 +45,7 @@ function flagValuesOf(flags, allowed) {
 }
 /** 解析命令行；要显示说明时回 undefined。参数不对直接报错 */
 function parseCliArgs(args, cwd = process.cwd()) {
-	if (args.length === 0) throw new Error("缺少命令：export、status 或 check；用 --help 查看用法");
+	if (args.length === 0) throw new Error("缺少命令：export、status、check 或 convert；用 --help 查看用法");
 	if (args.includes("--help") || args.includes("-h")) return void 0;
 	const [command, ...rest] = args;
 	if (command === "check") {
@@ -54,17 +56,30 @@ function parseCliArgs(args, cwd = process.cwd()) {
 			json: switches.has("--json")
 		};
 	}
-	if (command !== "export" && command !== "status") throw new Error(`认不出的命令 ${JSON.stringify(command)}：只有 export、status、check；用 --help 查看用法`);
+	if (command === "convert") {
+		const [sourceId, targetId, ...flags] = rest;
+		if (sourceId === void 0 || targetId === void 0 || sourceId.startsWith("-") || targetId.startsWith("-")) throw new Error("convert 要给两个报告 id：要转的 JSON 报告、新的 MDX 报告");
+		reportEntryOf(sourceId);
+		reportEntryOf(targetId);
+		const { values } = flagValuesOf(flags, ["--site"]);
+		return {
+			command,
+			siteDir: path.resolve(cwd, values.get("--site") ?? "."),
+			sourceId,
+			targetId
+		};
+	}
+	if (command !== "export" && command !== "status") throw new Error(`认不出的命令 ${JSON.stringify(command)}：只有 export、status、check、convert；用 --help 查看用法`);
 	const [reportId, ...flags] = rest;
 	if (reportId === void 0 || reportId.startsWith("-")) throw new Error(`${command} 要给报告 id（站点 reports/ 下的目录名）`);
-	const entry = reportEntryOf(reportId);
+	reportEntryOf(reportId);
 	const { values } = flagValuesOf(flags, ["--site", "--engine"]);
 	const engine = values.get("--engine");
 	return {
 		command,
+		reportId,
 		options: {
 			siteDir: path.resolve(cwd, values.get("--site") ?? "."),
-			entry,
 			mode: "complete",
 			action: command === "export" ? "start" : "status",
 			...engine !== void 0 ? { engineDir: path.resolve(cwd, engine) } : {}
@@ -78,6 +93,12 @@ function checkReportText(result) {
 	if (result.problems.length === 0) lines.push("没有问题。");
 	return `${lines.join("\n")}\n`;
 }
+function convertReportText(result) {
+	if (result.converted) return `转好了：${result.targetDir}\n${result.files.map((file) => `  ${file}`).join("\n")}\n`;
+	const lines = [`没有转换：${result.reason}`];
+	for (const problem of result.problems) lines.push(`  ${problem}`);
+	return `${lines.join("\n")}\n`;
+}
 /** export 要等引擎做完同一个任务才退出：引擎在固定下来的快照上工作，进程退了就没人等它的结果 */
 async function runExport(options, dependencies) {
 	let result = await dependencies.reportExport(options);
@@ -113,7 +134,16 @@ async function main(args, dependencies = {}) {
 			write(parsed.json ? `${JSON.stringify(result)}\n` : checkReportText(result));
 			return result.problems.length > 0 ? 1 : 0;
 		}
-		const result = await runExport(parsed.options, {
+		if (parsed.command === "convert") {
+			const result = await (dependencies.convertReportToMdx ?? convertReportToMdx)(parsed.siteDir, parsed.sourceId, parsed.targetId);
+			write(convertReportText(result));
+			return result.converted ? 0 : 1;
+		}
+		const entry = await (dependencies.reportEntryIn ?? reportEntryIn)(parsed.options.siteDir, parsed.reportId);
+		const result = await runExport({
+			...parsed.options,
+			entry
+		}, {
 			reportExport: dependencies.reportExport ?? reportExport,
 			sleep
 		});

package/dist/{export-TbclsIsE.mjs → convert-o7bPWP9A.mjs}

@@ -1,6 +1,7 @@
-import { a as parseReportJson, i as walk, n as safeRelativePath, o as ReportContentError, r as validateDocument, t as assembleDocument } from "./assemble-3cx8L2vo.mjs";
-import { a as reportsDirName } from "./report-files-DM9Ea6yK.mjs";
-import { access, mkdir, open, readFile, readdir, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { a as walk, i as validateDocument, n as safeRelativePath, o as parseReportJson, r as stableValue, s as ReportContentError, t as assembleDocument } from "./assemble-BpllQNVY.mjs";
+import { a as assembleMdxReport, n as mdxReportPlanOf, r as MDX_ENTRY_NAME, s as mdxReportInputsOf } from "./mdx-4Rs1N1nv.mjs";
+import { l as reportsDirName, o as reportEntryIn, r as isMdxEntry, s as reportEntryOf, t as JSON_ENTRY_NAME } from "./report-files-BsIvifZe.mjs";
+import { access, copyFile, mkdir, open, readFile, readdir, realpath, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import sharp from "sharp";
@@ -51,18 +52,20 @@ async function readReport(entryAbsolute, options = {}) {
 			throw new ReportContentError("Unreadable report file", key);
 		}
 	}
+	async function readText(absolute, format) {
+		const { bytes, key } = await readWithin(absolute);
+		try {
+			return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+		} catch {
+			throw new ReportContentError(`Document must be UTF-8 ${format}`, key);
+		}
+	}
 	async function load(absolute) {
 		const key = relative(absolute);
 		if (visiting.has(key)) throw new ReportContentError("Circular document include", key);
 		if (Object.hasOwn(files, key)) return;
 		visiting.add(key);
-		const { bytes } = await readWithin(absolute);
-		let text;
-		try {
-			text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-		} catch {
-			throw new ReportContentError("Document must be UTF-8 JSON", key);
-		}
+		const text = await readText(absolute, "JSON");
 		files[key] = text;
 		const document = parseReportJson(text, key);
 		validateDocument(document, key);
@@ -76,8 +79,28 @@ async function readReport(entryAbsolute, options = {}) {
 		}
 		visiting.delete(key);
 	}
-	await load(entry);
-	const result = assembleDocument(relative(entry), files, options);
+	/** MDX 报告：入口、各章与文献列表都进快照，编译成一份文档再组装 */
+	async function loadMdx() {
+		const entryKey = relative(entry);
+		files[entryKey] = await readText(entry, "MDX");
+		const { chapters, references } = mdxReportInputsOf(files[entryKey], entryKey);
+		for (const chapter of chapters) files[chapter] = await readText(path.resolve(root, chapter), "MDX");
+		if (await stat(path.resolve(root, references)).then((info) => info.isFile(), (error) => {
+			if (error.code === "ENOENT") return false;
+			throw error;
+		})) files[references] = await readText(path.resolve(root, references), "MDX");
+		return assembleMdxReport({
+			reportId: path.basename(path.dirname(entry)),
+			entry: entryKey,
+			files
+		}, options);
+	}
+	let result;
+	if (path.basename(entry) === "index.mdx") result = await loadMdx();
+	else {
+		await load(entry);
+		result = assembleDocument(relative(entry), files, options);
+	}
 	const assetBytes = Object.create(null), normalized = /* @__PURE__ */ new Map();
 	for (const [src, source] of Object.entries(result.assets)) {
 		const folded = source.normalize("NFC").toLowerCase(), previous = normalized.get(folded);
@@ -121,7 +144,10 @@ async function readReport(entryAbsolute, options = {}) {
 }
 //#endregion
 //#region src/node/check.ts
-/** 检查站点 reports/ 下的每个 content.json（每份报告与每一章）：只用本包的代码，不执行站点里的脚本 */
+/**
+* 检查站点 reports/ 下的每个 content.json（每份报告与每一章）与每份 MDX 报告（报告目录根上的 index.mdx，只整份检查：MDX 的章不是独立文档）。
+* 只用本包的代码，不执行站点里的脚本
+*/
 async function checkReports(siteDir) {
 	const result = {
 		checked: 0,
@@ -136,7 +162,8 @@ async function checkReports(siteDir) {
 		throw new ReportContentError("没有这个站点目录", siteDir);
 	}
 	const relative = (file) => path.relative(root, file).split(path.sep).join("/");
-	const entries = [], directories = /* @__PURE__ */ new Set();
+	const entries = [], mdxEntries = [], directories = /* @__PURE__ */ new Set();
+	const reports = path.join(root, reportsDirName);
 	function diagnostic(error, file, mode) {
 		const known = error instanceof ReportContentError;
 		result.problems.push({
@@ -158,9 +185,9 @@ async function checkReports(siteDir) {
 			if (item.isSymbolicLink()) isDirectory = (await stat(file)).isDirectory();
 			if (isDirectory) await scan(file);
 			else if (item.name === "content.json") entries.push(file);
+			else if (item.name === "index.mdx" && path.dirname(directory) === reports) mdxEntries.push(file);
 		}
 	}
-	const reports = path.join(root, reportsDirName);
 	try {
 		await stat(reports);
 	} catch (error) {
@@ -169,6 +196,35 @@ async function checkReports(siteDir) {
 	}
 	await scan(reports);
 	entries.sort();
+	mdxEntries.sort();
+	for (const entry of mdxEntries) {
+		const file = relative(entry);
+		result.checked++;
+		try {
+			if (entries.includes(path.join(path.dirname(entry), "content.json"))) throw new ReportContentError(`报告目录里 ${JSON_ENTRY_NAME} 和 ${MDX_ENTRY_NAME} 只能留一个`, relative(path.dirname(entry)));
+			const report = await readReport(entry, {
+				root,
+				mode: "complete"
+			});
+			result.warnings.push(...report.warnings.map((warning) => ({
+				...warning,
+				entry: file,
+				mode: "complete"
+			})));
+			result.runs.push({
+				file,
+				mode: "complete",
+				passed: true
+			});
+		} catch (error) {
+			diagnostic(error, file, "complete");
+			result.runs.push({
+				file,
+				mode: "complete",
+				passed: false
+			});
+		}
+	}
 	for (const entry of entries) {
 		const file = relative(entry);
 		result.checked++;
@@ -216,7 +272,7 @@ async function checkReports(siteDir) {
 //#endregion
 //#region src/node/export.ts
 const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
-const exists = async (file) => access(file).then(() => true, () => false);
+const exists$1 = async (file) => access(file).then(() => true, () => false);
 async function saved(file) {
 	try {
 		return JSON.parse(await readFile(file, "utf8"));
@@ -242,7 +298,7 @@ function installedPackageDir() {
 const packagedEngineDir = (packageDir) => path.join(packageDir, "engine");
 /** 入口相对站点目录，不收本机的任意路径 */
 function reportEntry(entry) {
-	if (typeof entry !== "string" || !entry.endsWith("/content.json") || /[\\:\x00-\x1f]/.test(entry) || entry.startsWith("/") || entry.split("/").some((part) => !part || part === "." || part === "..")) throw new Error("报告入口要是站点目录里的相对 content.json 路径，如 reports/<报告 id>/content.json");
+	if (typeof entry !== "string" || !(entry.endsWith("/content.json") || entry.endsWith("/index.mdx")) || /[\\:\x00-\x1f]/.test(entry) || entry.startsWith("/") || entry.split("/").some((part) => !part || part === "." || part === "..")) throw new Error("报告入口要是站点目录里的相对路径，如 reports/<报告 id>/content.json 或 reports/<报告 id>/index.mdx");
 	return entry;
 }
 function reportMode(value) {
@@ -268,12 +324,12 @@ async function engineFingerprint(engine, compiler) {
 	}
 	inputs.push(["compiler/package.json", hash(await readFile(path.join(compiler, "package.json")))]);
 	await compilerFiles("dist");
-	if (await exists(path.join(compiler, "src"))) await compilerFiles("src");
+	if (await exists$1(path.join(compiler, "src"))) await compilerFiles("src");
 	return hash(JSON.stringify(inputs.sort(([a], [b]) => a.localeCompare(b))));
 }
-async function layoutOf(root, entry) {
+async function layoutOf$1(root, entry) {
 	const file = path.join(root, path.dirname(entry), "layout.json");
-	if (!await exists(file)) return { file };
+	if (!await exists$1(file)) return { file };
 	const resolved = await realpath(file), relative = path.relative(await realpath(root), resolved);
 	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error("布局文件不在站点目录里");
 	const bytes = await readFile(resolved);
@@ -294,7 +350,7 @@ async function capture(site, engine, compiler, entry, mode) {
 		mode
 	});
 	rejectMultiImageFigures(report.document);
-	const layout = await layoutOf(root, entry);
+	const layout = await layoutOf$1(root, entry);
 	const engineHash = await engineFingerprint(engine, compiler);
 	return {
 		report,
@@ -500,7 +556,7 @@ async function reportExport(options) {
 	const engine = path.resolve(options.engineDir ?? process.env.DOCREPORT_ENGINE_ROOT ?? packagedEngineDir(compiler));
 	const key = keyFor(site, entry, mode), active = await latestAttempt(engine, compiler, key, site), previous = await previousJob(engine, key, site, entry, mode);
 	const outputs = await outputPaths(engine, previous);
-	if (!await exists(path.join(engine, ".venv/Scripts/python.exe"))) return {
+	if (!await exists$1(path.join(engine, ".venv/Scripts/python.exe"))) return {
 		state: "unavailable",
 		message: `Word 引擎 ${engine} 里还没有 Python 环境：在那里运行 python -m venv .venv 与 .venv\\Scripts\\pip install -r requirements.txt（要本机装着 Word 与 MathType）；引擎放在别处时用 --engine 或环境变量 DOCREPORT_ENGINE_ROOT 指过去`,
 		...outputs
@@ -559,4 +615,152 @@ async function reportExport(options) {
 	};
 }
 //#endregion
-export { readReport as i, reportExport as n, checkReports as r, reportEntry as t };
+//#region src/node/convert.ts
+const MAX_LISTED_DIFFERENCES = 20;
+async function exists(file) {
+	return stat(file).then(() => true, (error) => {
+		if (error.code === "ENOENT") return false;
+		throw error;
+	});
+}
+async function layoutOf(reportDir) {
+	const file = path.join(reportDir, "layout.json");
+	if (!await exists(file)) return void 0;
+	const bytes = await readFile(file);
+	return {
+		bytes,
+		keys: Object.keys(JSON.parse(bytes.toString("utf8")))
+	};
+}
+const MARK_ORDER = [
+	"strong",
+	"em",
+	"sub",
+	"sup",
+	"code"
+];
+/**
+* 比对用的样子：只留写出来的 id（其余由编译器重新生成）、图片路径只看文件名、文档 id 不比、
+* 相邻且标记相同的文字合并、标记按固定顺序、有序列表的起始数 1 不写、没有块的单元格当成一个空段（MDX 的空格子编译成空段，Word 里两者一样）
+*/
+function comparable(document, keptIds) {
+	const normalize = (value) => {
+		if (Array.isArray(value)) {
+			const items = value.map(normalize);
+			const merged = [];
+			for (const item of items) {
+				const previous = merged.at(-1);
+				if (item?.["type"] === "text" && previous?.["type"] === "text" && stableValue(previous["marks"] ?? []) === stableValue(item["marks"] ?? [])) previous["text"] = `${previous["text"]}${item["text"]}`;
+				else merged.push(item);
+			}
+			return merged;
+		}
+		if (!value || typeof value !== "object") return value;
+		const copy = {};
+		for (const [key, child] of Object.entries(value)) {
+			if (key === "id" && !keptIds.has(child)) continue;
+			if (key === "src" && typeof child === "string") copy[key] = child.slice(child.lastIndexOf("/") + 1);
+			else if (key === "marks" && Array.isArray(child)) copy[key] = MARK_ORDER.filter((mark) => child.includes(mark));
+			else copy[key] = normalize(child);
+		}
+		if (copy["type"] === "list" && copy["start"] === 1) delete copy["start"];
+		if (Array.isArray(copy["cells"])) {
+			for (const cell of copy["cells"]) if (cell["blocks"].length === 0) cell["blocks"] = [{
+				type: "paragraph",
+				content: []
+			}];
+		}
+		return copy;
+	};
+	const { id: _documentId, ...rest } = document;
+	return normalize(rest);
+}
+function differencesOf(before, after, pointer = "") {
+	if (stableValue(before) === stableValue(after)) return [];
+	const bothArrays = Array.isArray(before) && Array.isArray(after);
+	const bothObjects = !bothArrays && before && after && typeof before === "object" && typeof after === "object" && !Array.isArray(before) && !Array.isArray(after);
+	if (bothArrays && before.length === after.length) return before.flatMap((item, index) => differencesOf(item, after[index], `${pointer}/${index}`));
+	if (bothObjects) return [.../* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)])].sort().flatMap((key) => differencesOf(before[key], after[key], `${pointer}/${key}`));
+	return [`${pointer || "/"}：原报告 ${JSON.stringify(before)}，转回来 ${JSON.stringify(after)}`];
+}
+/**
+* 把一份 JSON 报告转成一份新的 MDX 报告（reports/<新 id>/），不动原报告。
+* 原报告里有 MDX 写不出的内容就一个文件都不写；写完编译回来和原报告逐项比对，对不上就删掉新目录
+*/
+async function convertReportToMdx(siteDir, sourceId, targetId) {
+	const site = await realpath(siteDir);
+	const sourceEntry = await reportEntryIn(site, sourceId);
+	if (isMdxEntry(sourceEntry)) throw new Error(`报告 ${sourceId} 已经是 MDX 报告`);
+	if (!/^[a-z]/.test(targetId)) throw new Error(`新报告 id「${targetId}」要以字母开头：MDX 报告的目录名就是文档 id`);
+	const targetDir = path.join(site, path.dirname(reportEntryOf(targetId)));
+	if (await exists(targetDir)) throw new Error(`reports/${targetId} 已经存在：convert 只写新目录`);
+	const source = await readReport(path.join(site, sourceEntry), {
+		root: site,
+		mode: "complete"
+	});
+	const layout = await layoutOf(path.join(site, reportsDirName, sourceId));
+	const plan = mdxReportPlanOf(source.document, source.assets, layout?.keys ?? []);
+	if (plan.problems.length) return {
+		converted: false,
+		reason: `原报告里有 ${plan.problems.length} 处 MDX 写不出来，没有写任何文件`,
+		problems: plan.problems
+	};
+	await mkdir(path.join(targetDir, "assets"), { recursive: true });
+	const written = [];
+	try {
+		for (const [name, text] of Object.entries(plan.files)) {
+			await writeFile(path.join(targetDir, name), text);
+			written.push(name);
+		}
+		for (const [name, compiledPath] of Object.entries(plan.images)) {
+			await copyFile(path.join(site, source.assets[compiledPath]), path.join(targetDir, "assets", name));
+			written.push(`assets/${name}`);
+		}
+		if (layout) {
+			await writeFile(path.join(targetDir, "layout.json"), layout.bytes);
+			written.push("layout.json");
+		}
+		let converted;
+		try {
+			converted = await readReport(path.join(targetDir, "index.mdx"), {
+				root: site,
+				mode: "complete"
+			});
+		} catch (error) {
+			await rm(targetDir, {
+				recursive: true,
+				force: true
+			});
+			return {
+				converted: false,
+				reason: "转出来的 MDX 编译不过，已删掉新目录",
+				problems: [error instanceof Error ? error.message : String(error)]
+			};
+		}
+		const differences = differencesOf(comparable(source.document, plan.keptIds), comparable(converted.document, plan.keptIds));
+		if (differences.length) {
+			await rm(targetDir, {
+				recursive: true,
+				force: true
+			});
+			return {
+				converted: false,
+				reason: `转回来和原报告有 ${differences.length} 处对不上，已删掉新目录`,
+				problems: differences.slice(0, MAX_LISTED_DIFFERENCES)
+			};
+		}
+	} catch (error) {
+		await rm(targetDir, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	return {
+		converted: true,
+		targetDir,
+		files: written.sort()
+	};
+}
+//#endregion
+export { readReport as a, checkReports as i, reportEntry as n, reportExport as r, convertReportToMdx as t };

package/dist/core.d.mts

@@ -10,4 +10,59 @@ declare function parseReportJson(text: string, file?: string): unknown;
 declare function validateDocument(value: unknown, file?: string): asserts value is ReportDocument;
 declare function safeRelativePath(raw: string, asset?: boolean): string;
 //#endregion
-export { Abstract, AssemblyOptions, AssemblyResult, Bibliography, CellBlock, Code, CompiledReport, ContentWarning, Equation, Figure, FigurePanel, Include, IndexEntry, MultiImageFigure, Paragraph, ReportBlock, ReportContentError, ReportDocument, ReportIndex, ReportInline, ReportList, Section, SingleImageFigure, SourceLocation, Table, TableCell, assembleDocument, parseReportJson, safeRelativePath, validateDocument };
+//#region src/core/mdx/compile.d.ts
+/** 报告目录里固定名字的两个文件 */
+declare const MDX_ENTRY_NAME = "index.mdx";
+declare const MDX_REFERENCES_NAME = "references.mdx";
+interface MdxReportInput {
+  /** 报告目录名，用作文档 id */
+  reportId: string;
+  /** 入口 index.mdx 在 files 里的键；章与文献列表的路径相对它所在的目录 */
+  entry: string;
+  /** 路径 → MDX 原文：入口、chapters 列的各章，以及存在时的 references.mdx */
+  files: Record<string, string>;
+}
+interface CompiledMdxReport {
+  document: ReportDocument;
+  /** 节点 id → MDX 文件与「行:列」 */
+  sources: Record<string, SourceLocation>;
+  /** 编译结果里的 JSON 指针 → 最近的有记录的上级节点的 MDX 位置 */
+  locate(pointer: string): SourceLocation | undefined;
+  /** 编进来的 MDX 文件，按入口、各章、文献列表的顺序 */
+  files: string[];
+}
+/** 读入口原文就知道还要读哪些文件：章按 chapters 的顺序，文献列表 references.mdx 有没有由调用方看磁盘 */
+declare function mdxReportInputsOf(indexText: string, entry: string): {
+  chapters: string[];
+  references: string;
+};
+/** 整份 MDX 报告 → 一份 docreport 文档（入口正文在前，各章按 chapters 的顺序接在后面）；只解析、不执行 MDX */
+declare function compileMdxReport({ reportId, entry, files }: MdxReportInput): CompiledMdxReport;
+/** 编译并组装一份 MDX 报告：结果和 JSON 报告的组装结果同形，sources 指向 MDX 的行列，dependencies 是编进来的 MDX 文件 */
+declare function assembleMdxReport(input: MdxReportInput, options?: AssemblyOptions): AssemblyResult;
+//#endregion
+//#region src/core/mdx/ids.d.ts
+/** 编译器生成的 id 都以它开头；手写的 id 不许用，两边就不会撞 */
+declare const GENERATED_ID_PREFIX = "auto-";
+//#endregion
+//#region src/core/mdx/emit.d.ts
+/**
+ * 组装好的 docreport 文档 → 一份 MDX 报告的各个文件：convert 命令用它迁移 JSON 报告。
+ * 只有被引用的、layout.json 里出现的、文献与脚注的 id 写出来，其余交给编译器重新生成；
+ * MDX 写不出的内容记进 problems（带 JSON 指针），有一条就不该写文件
+ */
+interface MdxReportPlan {
+  /** 文件名（相对新报告目录）→ MDX 原文 */
+  files: Record<string, string>;
+  /** 新报告里的图片文件名（assets/ 下）→ 原图在组装结果里的路径（AssemblyResult.assets 的键） */
+  images: Record<string, string>;
+  /** 写出来的手写 id：比对时只有它们要求两边一样 */
+  keptIds: Set<string>;
+  problems: string[];
+}
+/** 哪些 id 要写出来：被 ref 指到的、layout.json 的键、文献与脚注（它们本来就靠 id 对应） */
+declare function keptIdsOf(document: ReportDocument, layoutKeys: string[]): Set<string>;
+/** 组装好的文档 → MDX 报告。assets 是组装结果的 assets（图在组装结果里的路径 → 原图路径） */
+declare function mdxReportPlanOf(document: ReportDocument, assets: Record<string, string>, layoutKeys: string[]): MdxReportPlan;
+//#endregion
+export { Abstract, AssemblyOptions, AssemblyResult, Bibliography, CellBlock, Code, type CompiledMdxReport, CompiledReport, ContentWarning, Equation, Figure, FigurePanel, GENERATED_ID_PREFIX, Include, IndexEntry, MDX_ENTRY_NAME, MDX_REFERENCES_NAME, type MdxReportInput, type MdxReportPlan, MultiImageFigure, Paragraph, ReportBlock, ReportContentError, ReportDocument, ReportIndex, ReportInline, ReportList, Section, SingleImageFigure, SourceLocation, Table, TableCell, assembleDocument, assembleMdxReport, compileMdxReport, keptIdsOf, mdxReportInputsOf, mdxReportPlanOf, parseReportJson, safeRelativePath, validateDocument };

package/dist/core.mjs

@@ -1 +1,3 @@
-export { o as ReportContentError, t as assembleDocument, a as parseReportJson, n as safeRelativePath, r as validateDocument } from "./assemble-3cx8L2vo.mjs";
+import { i as validateDocument, n as safeRelativePath, o as parseReportJson, s as ReportContentError, t as assembleDocument } from "./assemble-BpllQNVY.mjs";
+import { a as assembleMdxReport, c as GENERATED_ID_PREFIX, i as MDX_REFERENCES_NAME, n as mdxReportPlanOf, o as compileMdxReport, r as MDX_ENTRY_NAME, s as mdxReportInputsOf, t as keptIdsOf } from "./mdx-4Rs1N1nv.mjs";
+export { GENERATED_ID_PREFIX, MDX_ENTRY_NAME, MDX_REFERENCES_NAME, ReportContentError, assembleDocument, assembleMdxReport, compileMdxReport, keptIdsOf, mdxReportInputsOf, mdxReportPlanOf, parseReportJson, safeRelativePath, validateDocument };

package/dist/{export-DC764Umz.d.mts → export-Da4yhrZa.d.mts}

@@ -20,9 +20,28 @@ interface ReportCheckResult {
     mode: 'standalone' | 'complete';
   })[];
 }
-/** 检查站点 reports/ 下的每个 content.json（每份报告与每一章）：只用本包的代码，不执行站点里的脚本 */
+/**
+ * 检查站点 reports/ 下的每个 content.json（每份报告与每一章）与每份 MDX 报告（报告目录根上的 index.mdx，只整份检查：MDX 的章不是独立文档）。
+ * 只用本包的代码，不执行站点里的脚本
+ */
 declare function checkReports(siteDir: string): Promise<ReportCheckResult>;
 //#endregion
+//#region src/node/convert.d.ts
+type ConvertReportResult = {
+  converted: true;
+  targetDir: string;
+  files: string[];
+} | {
+  converted: false;
+  reason: string;
+  problems: string[];
+};
+/**
+ * 把一份 JSON 报告转成一份新的 MDX 报告（reports/<新 id>/），不动原报告。
+ * 原报告里有 MDX 写不出的内容就一个文件都不写；写完编译回来和原报告逐项比对，对不上就删掉新目录
+ */
+declare function convertReportToMdx(siteDir: string, sourceId: string, targetId: string): Promise<ConvertReportResult>;
+//#endregion
 //#region src/node/export.d.ts
 type Mode = 'complete' | 'standalone';
 type Job = {
@@ -38,7 +57,7 @@ type Job = {
 };
 interface ReportExportOptions {
   siteDir: string;
-  /** 相对站点目录的 content.json 路径，如 reports/<报告 id>/content.json（reportEntryOf） */
+  /** 相对站点目录的入口路径：reports/<报告 id>/content.json 或 reports/<报告 id>/index.mdx（reportEntryIn） */
   entry: string;
   mode?: Mode;
   action?: 'start' | 'status';
@@ -64,4 +83,4 @@ declare function reportEntry(entry: unknown): string;
 /** Package API: callers can start or inspect a render without a website or workbench process. */
 declare function reportExport(options: ReportExportOptions): Promise<ReportExportResult>;
 //#endregion
-export { ReportCheckDiagnostic as a, reportExport as i, ReportExportResult as n, ReportCheckResult as o, reportEntry as r, checkReports as s, ReportExportOptions as t };
+export { ConvertReportResult as a, ReportCheckResult as c, reportExport as i, checkReports as l, ReportExportResult as n, convertReportToMdx as o, reportEntry as r, ReportCheckDiagnostic as s, ReportExportOptions as t };