specleaf 1.0.0 → 1.1.1

package/lib/cli.js

@@ -1,12 +1,76 @@
 #!/usr/bin/env node
-import { mkdir, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import $RefParser from "@apidevtools/json-schema-ref-parser";
+import { mkdir, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import $RefParser, { getJsonSchemaRefParserDefaultOptions } from "@apidevtools/json-schema-ref-parser";
 import { randomUUID } from "node:crypto";
 // src/lib/openapi.ts
 var pointerEscape = (value) => value.replace(/~/g, "~0").replace(/\//g, "~1");
+// build/references.ts
+function rootReferenceTracker(entry, excluded) {
+	const root = pathToFileURL(entry);
+	const origins = /* @__PURE__ */ new WeakMap();
+	function remember(value, source, seen = /* @__PURE__ */ new WeakSet(), namedResource = false) {
+		if (!value || typeof value !== "object" || seen.has(value)) return;
+		seen.add(value);
+		namedResource ||= typeof value.$id === "string";
+		if (!namedResource) origins.set(value, source);
+		for (const child of Object.values(value)) remember(child, source, seen, namedResource);
+	}
+	const defaults = getJsonSchemaRefParserDefaultOptions().parse;
+	const parsers = Object.fromEntries(["json", "yaml"].map((name) => {
+		const plugin = defaults[name];
+		const parse = plugin.parse;
+		return [name, {
+			...plugin,
+			async parse(file) {
+				const value = typeof parse === "function" ? await parse.call(this, file) : parse;
+				remember(value, new URL(file.url.replace(/^([a-z]):\//i, "file:///$1:/"), root));
+				return value;
+			}
+		}];
+	}));
+	function internalize(document) {
+		const seen = /* @__PURE__ */ new WeakSet();
+		function visit(value, path = "#") {
+			if (!value || typeof value !== "object" || excluded(path, value) || seen.has(value)) return;
+			seen.add(value);
+			if (typeof value.$ref === "string" && !value.$ref.startsWith("#")) {
+				const source = origins.get(value);
+				const target = source ? new URL(value.$ref, source) : void 0;
+				if (target && target.href.split("#")[0] === root.href) value.$ref = target.hash || "#";
+				if (!value.$ref.startsWith("#")) throw new Error(`契约合并后仍有外部引用：${path}/$ref → ${value.$ref}`);
+			}
+			for (const [key, child] of Object.entries(value)) visit(child, `${path}/${pointerEscape(key)}`);
+		}
+		visit(document);
+	}
+	return {
+		parsers,
+		internalize
+	};
+}
 // build/contract.ts
+var DocumentationLoadError = class extends Error {
+	files;
+	directories;
+	constructor(message, files, directories, options) {
+		super(message, options);
+		this.files = files;
+		this.directories = directories;
+	}
+};
+var moduleEntryNames = /* @__PURE__ */ new Set([
+	"openapi.yaml",
+	"openapi.yml",
+	"openapi.json"
+]);
+var ignoredDirectories = /* @__PURE__ */ new Set([
+	"node_modules",
+	"dist",
+	"build",
+	"coverage"
+]);
 var maps = /* @__PURE__ */ new Set([
 	"properties",
 	"patternProperties",
@@ -33,7 +97,7 @@ function literalPayload(path, value) {
 }
 function contractEntry(root, configured = process.env.OPENAPI_ENTRY) {
 	const entry = configured || "examples/openapi.yaml";
-	if (/^[a-z][a-z\d+.-]*:/i.test(entry) && !/^[a-z]:[\\/]/i.test(entry)) throw new Error("OpenAPI 入口必须是本地 YAML / JSON 文件路径。");
+	if (/^[a-z][a-z\d+.-]*:/i.test(entry) && !/^[a-z]:[\\/]/i.test(entry)) throw new Error("OpenAPI 入口必须是本地 YAML / JSON 文件或模块目录路径。");
 	return isAbsolute(entry) ? entry : resolve(root, entry);
 }
 function references(value, pointer = "#", result = []) {
@@ -46,9 +110,11 @@ async function loadContract(entry) {
 	entry = contractEntry(process.cwd(), entry);
 	const parser = new $RefParser();
 	try {
+		const references = rootReferenceTracker(entry, literalPayload);
 		const document = await parser.bundle(entry, {
 			resolve: { http: false },
 			parse: {
+				...references.parsers,
 				binary: false,
 				text: false
 			},
@@ -57,6 +123,7 @@ async function loadContract(entry) {
 		});
 		if (!/^3\.(0|1)\.\d+$/.test(document.openapi || "")) throw new Error(`仅支持 OpenAPI 3.0 / 3.1，当前版本：${document.openapi ?? "缺失"}`);
 		if (!document.info?.title || !document.paths || typeof document.paths !== "object" || Array.isArray(document.paths)) throw new Error("契约必须包含 info.title 和 paths 对象。");
+		references.internalize(document);
 		return {
 			document,
 			files: parser.$refs.paths(),
@@ -68,15 +135,98 @@ async function loadContract(entry) {
 		const locations = Object.entries(sources).flatMap(([file, value]) => references(value).map((ref) => `${file} ${ref}`));
 		const relevant = locations.filter((location) => error.targetToken && location.includes(error.targetToken) || error.source && location.includes(error.source.split("/").at(-1)));
 		const context = (relevant.length ? relevant : locations).slice(0, 8);
-		throw new Error([
+		const files = /* @__PURE__ */ new Set([entry, ...parser.$refs.paths()]);
+		for (const [file, value] of Object.entries(sources)) {
+			const visit = (node, pointer = "#") => {
+				if (!node || typeof node !== "object" || literalPayload(pointer, node)) return;
+				if (typeof node.$ref === "string") {
+					const target = node.$ref.split("#")[0];
+					if (target && !/^[a-z][a-z\d+.-]*:/i.test(target)) try {
+						files.add(resolve(dirname(file), decodeURIComponent(target)));
+					} catch {}
+				}
+				for (const [key, child] of Object.entries(node)) visit(child, `${pointer}/${pointerEscape(key)}`);
+			};
+			visit(value);
+		}
+		throw new DocumentationLoadError([
 			`OpenAPI 契约解析失败：${entry}`,
 			error.message,
 			error.source ? `来源文件：${error.source}` : "",
 			error.path?.length ? `引用位置：#/${error.path.map(pointerEscape).join("/")}` : "",
 			context.length ? `引用上下文：\n${context.join("\n")}` : ""
-		].filter(Boolean).join("\n"), { cause });
+		].filter(Boolean).join("\n"), [...files], [...new Set([...files].map(dirname))], { cause });
+	}
+}
+async function loadDocumentation(input) {
+	const entry = contractEntry(process.cwd(), input);
+	const files = /* @__PURE__ */ new Set();
+	const directories = /* @__PURE__ */ new Set([dirname(entry)]);
+	try {
+		if (!(await stat(entry)).isDirectory()) {
+			const contract = await loadContract(entry);
+			return {
+				...contract,
+				directories: [...new Set(contract.files.map(dirname))]
+			};
+		}
+		const entries = [];
+		const discover = async (directory) => {
+			directories.add(directory);
+			const children = await readdir(directory, { withFileTypes: true });
+			const candidates = [];
+			for (const child of children) if (moduleEntryNames.has(child.name) && (child.isFile() || child.isSymbolicLink() && (await stat(join(directory, child.name))).isFile())) candidates.push(child);
+			candidates.forEach((child) => files.add(join(directory, child.name)));
+			if (candidates.length > 1) throw new Error(`模块目录存在多个 OpenAPI 入口：${directory}\n${candidates.map((child) => child.name).sort().join("、")}`);
+			if (candidates.length) entries.push({
+				id: relative(entry, directory).split(sep).join("/") || ".",
+				entry: join(directory, candidates[0].name)
+			});
+			for (const child of children) if (child.isDirectory() && !child.name.startsWith(".") && !ignoredDirectories.has(child.name)) await discover(join(directory, child.name));
+		};
+		await discover(entry);
+		if (!entries.length) throw new Error(`模块目录中未找到 openapi.yaml、openapi.yml 或 openapi.json：${entry}`);
+		entries.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+		const modules = [];
+		for (const module of entries) try {
+			const contract = await loadContract(module.entry);
+			contract.files.forEach((file) => {
+				files.add(file);
+				directories.add(dirname(file));
+			});
+			modules.push({
+				id: module.id,
+				document: contract.document
+			});
+		} catch (cause) {
+			if (cause instanceof DocumentationLoadError) {
+				cause.files.forEach((file) => files.add(file));
+				cause.directories.forEach((directory) => directories.add(directory));
+			}
+			throw new Error(`模块「${module.id}」解析失败\n${cause.message}`, { cause });
+		}
+		return {
+			document: {
+				kind: "specleaf/modules",
+				title: basename(entry),
+				modules
+			},
+			files: [...files],
+			entry,
+			directories: [...directories]
+		};
+	} catch (cause) {
+		if (cause instanceof DocumentationLoadError) throw cause;
+		throw new DocumentationLoadError(`OpenAPI 文档加载失败：${entry}\n${cause.message}`, [...files, entry], [...directories], { cause });
 	}
 }
+// src/lib/documentation.ts
+function isModuleCollection(document) {
+	return document.kind === "specleaf/modules" && Array.isArray(document.modules) && !("openapi" in document);
+}
+function documentationTitle(document) {
+	return isModuleCollection(document) ? document.title : document.info.title;
+}
 // build/serialize.ts
 function serializeContract(document) {
 	return JSON.stringify(document).replace(/[<>&\u2028\u2029]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
@@ -101,7 +251,7 @@ async function renderHtml(contract) {
 	].map((file) => readFile(new URL(file, assets), "utf8")));
 	const script = javascript.replace(/<\/script/gi, "<\\/script");
 	const css = stylesheet.replace(/<\/style/gi, "\\3c /style");
-	const title = escapeHtml(contract.document.info.title);
+	const title = escapeHtml(documentationTitle(contract.document));
 	return `<!doctype html>
 <html lang="zh-CN">
 <head>
@@ -109,7 +259,7 @@ async function renderHtml(contract) {
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <meta name="theme-color" content="#7357e8">
 <meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:; font-src data:; connect-src 'none'; base-uri 'none'; form-action 'none'">
-<meta name="description" content="${escapeHtml(contract.document.info.description || contract.document.info.title)}">
+<meta name="description" content="${escapeHtml(isModuleCollection(contract.document) ? contract.document.title : contract.document.info.description || contract.document.info.title)}">
 <title>${title} · API 文档</title>
 <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,${encodeURIComponent(favicon)}">
 <style>${css}</style>
@@ -138,7 +288,7 @@ async function protectSources(output, sources) {
 	}
 }
 async function generate(input, destination) {
-	const contract = await loadContract(input);
+	const contract = await loadDocumentation(input);
 	const output = resolve(destination);
 	let temporary;
 	try {
@@ -162,7 +312,8 @@ async function generate(input, destination) {
 // build/cli.ts
 var help = `用法：specleaf <input> [-o <output.html>]
 
-把本地 OpenAPI 3.0 / 3.1 YAML 或 JSON 转为单个离线 HTML。
+把本地 OpenAPI 3.0 / 3.1 YAML / JSON 文件或模块目录转为单个离线 HTML。
+目录递归发现 openapi.yaml、openapi.yml、openapi.json，各模块独立浏览。
 输入、输出路径相对调用目录解析，默认输出 ./openapi.html。
 
 选项：
@@ -196,10 +347,10 @@ function parseArguments(args) {
 			output = argument.slice(9);
 			if (!output) throw new Error("--output 缺少输出文件路径。");
 		} else if (!positional && argument.startsWith("-")) throw new Error(`未知参数：${argument}`);
-		else if (input) throw new Error(`只能指定一个输入文件，多余输入：${argument}`);
+		else if (input) throw new Error(`只能指定一个输入文件或目录，多余输入：${argument}`);
 		else input = argument;
 	}
-	if (!input) throw new Error("缺少 OpenAPI 输入文件。");
+	if (!input) throw new Error("缺少 OpenAPI 输入文件或模块目录。");
 	return {
 		input,
 		output

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "specleaf",
-  "version": "1.0.0",
-  "description": "将本地 OpenAPI 3.0 / 3.1 YAML 或 JSON 转为可离线阅读的单文件 HTML 文档。",
+  "version": "1.1.1",
+  "description": "将本地 OpenAPI 3.0 / 3.1 YAML / JSON 文件或模块目录转为按模块分组、离线阅读的单文件 HTML 文档。",
   "license": "MIT",
   "repository": {
     "type": "git",