@godcreator/word-report 0.4.0 → 0.5.0

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-D25NLmLx.mjs → assemble-BEt9_xsB.mjs}

@@ -182,6 +182,29 @@ const schema = {
 				"latex": {
 					"type": "string",
 					"minLength": 1
+				},
+				"plainText": {
+					"type": "array",
+					"minItems": 1,
+					"description": "Word writes these runs as text instead of a MathType object; the web view still renders latex.",
+					"items": {
+						"type": "object",
+						"properties": {
+							"text": { "$ref": "#/$defs/line" },
+							"marks": {
+								"type": "array",
+								"items": { "enum": [
+									"em",
+									"sub",
+									"sup"
+								] },
+								"uniqueItems": true,
+								"not": { "allOf": [{ "contains": { "const": "sub" } }, { "contains": { "const": "sup" } }] }
+							}
+						},
+						"required": ["text"],
+						"additionalProperties": false
+					}
 				}
 			},
 			"required": [
@@ -1192,4 +1215,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,8 +1,10 @@
-import { n as ReportExportResult, o as ReportCheckResult, t as ReportExportOptions } from "./export-DC764Umz.mjs";
+import { n as ReportExportResult, o as ReportCheckResult, t as ReportExportOptions } from "./export-DMKj4gl2.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;
@@ -13,6 +15,7 @@ declare function parseCliArgs(args: string[], cwd?: string): CliCommand | undefi
 interface CliDependencies {
   reportExport?: (options: ReportExportOptions) => Promise<ReportExportResult>;
   checkReports?: (siteDir: string) => Promise<ReportCheckResult>;
+  reportEntryIn?: (siteDir: string, reportId: string) => Promise<string>;
   sleep?: (milliseconds: number) => Promise<void>;
   stdout?: (text: string) => void;
   stderr?: (text: string) => void;

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { n as reportExport, r as checkReports } from "./export-DJQiBPPU.mjs";
-import { r as reportEntryOf } from "./report-files-CgWzLxH-.mjs";
+import { n as reportExport, r as checkReports } from "./export-B01-yaAq.mjs";
+import { o as reportEntryIn, s as reportEntryOf } from "./report-files-Dfr71bRv.mjs";
 import path from "node:path";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -8,10 +8,10 @@ import { fileURLToPath } from "node:url";
 const help = `用法：report-docx <export|status> <报告 id> [选项]
       report-docx check [选项]
 
-报告在站点目录的 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 报告整份）的格式、引用与图片，有问题时退出码非零
 
 选项：
   --site <目录>     站点目录（默认当前目录）
@@ -57,14 +57,14 @@ function parseCliArgs(args, cwd = process.cwd()) {
 	if (command !== "export" && command !== "status") throw new Error(`认不出的命令 ${JSON.stringify(command)}：只有 export、status、check；用 --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) } : {}
@@ -113,7 +113,11 @@ 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, {
+		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/core.d.mts

@@ -1,4 +1,4 @@
-import { C as SingleImageFigure, E as TableCell, S as Section, T as Table, _ as ReportContentError, a as CellBlock, b as ReportInline, c as ContentWarning, d as FigurePanel, f as Include, g as ReportBlock, h as Paragraph, i as Bibliography, l as Equation, m as MultiImageFigure, n as AssemblyOptions, o as Code, p as IndexEntry, r as AssemblyResult, s as CompiledReport, t as Abstract, u as Figure, v as ReportDocument, w as SourceLocation, x as ReportList, y as ReportIndex } from "./types-Bcl48xQN.mjs";
+import { C as Section, D as TableCell, E as Table, S as ReportList, T as SourceLocation, _ as ReportBlock, a as CellBlock, b as ReportIndex, c as ContentWarning, d as FigurePanel, f as Include, g as PlainMathRun, h as Paragraph, i as Bibliography, l as Equation, m as MultiImageFigure, n as AssemblyOptions, o as Code, p as IndexEntry, r as AssemblyResult, s as CompiledReport, t as Abstract, u as Figure, v as ReportContentError, w as SingleImageFigure, x as ReportInline, y as ReportDocument } from "./types-Ea2OT6Ac.mjs";
 //#region src/core/assemble.d.ts
 declare function assembleDocument(entry: string, files: Record<string, string | ReportDocument>, options?: AssemblyOptions): AssemblyResult;
 //#endregion
@@ -10,4 +10,39 @@ 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
+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, MultiImageFigure, Paragraph, PlainMathRun, ReportBlock, ReportContentError, ReportDocument, ReportIndex, ReportInline, ReportList, Section, SingleImageFigure, SourceLocation, Table, TableCell, assembleDocument, assembleMdxReport, compileMdxReport, mdxReportInputsOf, 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-D25NLmLx.mjs";
+import { i as validateDocument, n as safeRelativePath, o as parseReportJson, s as ReportContentError, t as assembleDocument } from "./assemble-BEt9_xsB.mjs";
+import { a as mdxReportInputsOf, i as compileMdxReport, n as MDX_REFERENCES_NAME, o as GENERATED_ID_PREFIX, r as assembleMdxReport, t as MDX_ENTRY_NAME } from "./mdx-C1RVv6E-.mjs";
+export { GENERATED_ID_PREFIX, MDX_ENTRY_NAME, MDX_REFERENCES_NAME, ReportContentError, assembleDocument, assembleMdxReport, compileMdxReport, mdxReportInputsOf, parseReportJson, safeRelativePath, validateDocument };

package/dist/{export-DJQiBPPU.mjs → export-B01-yaAq.mjs}

@@ -1,5 +1,6 @@
-import { a as parseReportJson, i as walk, n as safeRelativePath, o as ReportContentError, r as validateDocument, t as assembleDocument } from "./assemble-D25NLmLx.mjs";
-import { a as reportsDirName } from "./report-files-CgWzLxH-.mjs";
+import { a as walk, i as validateDocument, n as safeRelativePath, o as parseReportJson, s as ReportContentError, t as assembleDocument } from "./assemble-BEt9_xsB.mjs";
+import { a as mdxReportInputsOf, r as assembleMdxReport, t as MDX_ENTRY_NAME } from "./mdx-C1RVv6E-.mjs";
+import { l as reportsDirName, t as JSON_ENTRY_NAME } from "./report-files-Dfr71bRv.mjs";
 import { access, mkdir, open, readFile, readdir, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
@@ -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++;
@@ -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) {
@@ -502,7 +558,7 @@ async function reportExport(options) {
 	const outputs = await outputPaths(engine, previous);
 	if (!await exists(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 指过去`,
+		message: `Word 引擎 ${engine} 里还没有 Python 环境：在那里运行 python -m venv .venv、.venv\\Scripts\\pip install -r requirements.txt 与 .venv\\Scripts\\pip install --no-build-isolation --no-deps -e .（要本机装着 Word 与 MathType）；node_modules 里的路径太长时 Word 打不开图片，把 engine/ 复制到路径短的目录、用 --engine 或环境变量 DOCREPORT_ENGINE_ROOT 指过去`,
 		...outputs
 	};
 	let current;

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

@@ -1,4 +1,4 @@
-import { c as ContentWarning } from "./types-Bcl48xQN.mjs";
+import { c as ContentWarning } from "./types-Ea2OT6Ac.mjs";
 //#region src/node/check.d.ts
 interface ReportCheckDiagnostic {
   file: string;
@@ -20,7 +20,10 @@ 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/export.d.ts
@@ -38,7 +41,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';