specleaf 0.0.0-stage → 1.1.0

package/lib/cli.js

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+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 } from "node:url";
+import $RefParser 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/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",
+	"$defs",
+	"definitions",
+	"schemas",
+	"examples",
+	"headers",
+	"links",
+	"paths",
+	"responses",
+	"callbacks",
+	"securitySchemes",
+	"requestBodies",
+	"parameters",
+	"dependentSchemas"
+]);
+function literalPayload(path, value) {
+	const tokens = path.split("/");
+	const key = tokens.at(-1);
+	const parent = tokens.at(-2);
+	if (maps.has(parent)) return false;
+	return key.startsWith("x-") || key === "example" || key === "default" || key === "const" || key === "enum" && Array.isArray(value) || key === "examples" && Array.isArray(value) || key === "value" && tokens.at(-3) === "examples";
+}
+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 文件或模块目录路径。");
+	return isAbsolute(entry) ? entry : resolve(root, entry);
+}
+function references(value, pointer = "#", result = []) {
+	if (!value || typeof value !== "object") return result;
+	if (typeof value.$ref === "string") result.push(`${pointer}/$ref → ${value.$ref}`);
+	for (const [key, child] of Object.entries(value)) references(child, `${pointer}/${pointerEscape(key)}`, result);
+	return result;
+}
+async function loadContract(entry) {
+	entry = contractEntry(process.cwd(), entry);
+	const parser = new $RefParser();
+	try {
+		const document = await parser.bundle(entry, {
+			resolve: { http: false },
+			parse: {
+				binary: false,
+				text: false
+			},
+			resolveExcludedPathMatcher: literalPayload,
+			bundle: { excludedPathMatcher: literalPayload }
+		});
+		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 对象。");
+		return {
+			document,
+			files: parser.$refs.paths(),
+			entry
+		};
+	} catch (cause) {
+		const error = cause;
+		const sources = parser.$refs.values();
+		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);
+		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"), [...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")}`);
+}
+// build/generate.ts
+var projectRoot = fileURLToPath(new URL("../", import.meta.url));
+function escapeHtml(value) {
+	return value.replace(/[&<>"']/g, (character) => ({
+		"&": "&amp;",
+		"<": "&lt;",
+		">": "&gt;",
+		"\"": "&quot;",
+		"'": "&#39;"
+	})[character]);
+}
+async function renderHtml(contract) {
+	const assets = new URL("../lib/assets/", import.meta.url);
+	const [javascript, stylesheet, favicon] = await Promise.all([
+		"ui.js",
+		"ui.css",
+		"favicon.svg"
+	].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(documentationTitle(contract.document));
+	return `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<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(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>
+</head>
+<body><div id="root"></div><script id="specleaf-contract" type="application/json">${serializeContract(contract.document)}<\/script><script>${script}<\/script></body>
+</html>\n`;
+}
+async function canonical(path) {
+	try {
+		return await realpath(path);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+		const parent = dirname(path);
+		if (parent === path) throw error;
+		return join(await canonical(parent), basename(path));
+	}
+}
+async function protectSources(output, sources) {
+	const target = await canonical(output);
+	const targetStat = await stat(output).catch((error) => {
+		if (error.code !== "ENOENT") throw error;
+	});
+	for (const source of sources) {
+		const sourceStat = await stat(source);
+		if (target === await canonical(source) || targetStat && targetStat.dev === sourceStat.dev && targetStat.ino === sourceStat.ino) throw new Error(`禁止输出覆盖入口或引用文件：${output}\n来源文件：${source}`);
+	}
+}
+async function generate(input, destination) {
+	const contract = await loadDocumentation(input);
+	const output = resolve(destination);
+	let temporary;
+	try {
+		await protectSources(output, contract.files);
+		const html = await renderHtml(contract);
+		await mkdir(dirname(output), { recursive: true });
+		temporary = join(dirname(output), `.${basename(output)}.${randomUUID()}.tmp`);
+		await writeFile(temporary, html, {
+			encoding: "utf8",
+			flag: "wx"
+		});
+		await protectSources(output, contract.files);
+		await rename(temporary, output);
+		return output;
+	} catch (cause) {
+		throw new Error(`HTML 生成或写入失败：${output}\n${cause.message}`, { cause });
+	} finally {
+		if (temporary) await rm(temporary, { force: true });
+	}
+}
+// build/cli.ts
+var help = `用法：specleaf <input> [-o <output.html>]
+
+把本地 OpenAPI 3.0 / 3.1 YAML / JSON 文件或模块目录转为单个离线 HTML。
+目录递归发现 openapi.yaml、openapi.yml、openapi.json，各模块独立浏览。
+输入、输出路径相对调用目录解析，默认输出 ./openapi.html。
+
+选项：
+  -o, --output <文件>  指定输出文件
+  -h, --help           显示帮助
+  -v, --version        显示版本
+`;
+function parseArguments(args) {
+	let input;
+	let output = "openapi.html";
+	let positional = false;
+	for (let index = 0; index < args.length; index++) {
+		const argument = args[index];
+		if (!positional && (argument === "--help" || argument === "-h")) return {
+			output,
+			help: true
+		};
+		if (!positional && (argument === "--version" || argument === "-v")) return {
+			output,
+			version: true
+		};
+		if (!positional && argument === "--") {
+			positional = true;
+			continue;
+		}
+		if (!positional && (argument === "-o" || argument === "--output")) {
+			const value = args[++index];
+			if (!value || value.startsWith("-")) throw new Error(`${argument} 缺少输出文件路径。`);
+			output = value;
+		} else if (!positional && argument.startsWith("--output=")) {
+			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 input = argument;
+	}
+	if (!input) throw new Error("缺少 OpenAPI 输入文件或模块目录。");
+	return {
+		input,
+		output
+	};
+}
+try {
+	const args = parseArguments(process.argv.slice(2));
+	if (args.help) process.stdout.write(help);
+	else if (args.version) {
+		const { version } = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+		process.stdout.write(`${version}\n`);
+	} else {
+		const cwd = fileURLToPath(import.meta.url) === resolve(projectRoot, "build/cli.ts") && process.env.npm_lifecycle_event === "generate" ? process.env.INIT_CWD || process.cwd() : process.cwd();
+		const output = await generate(contractEntry(cwd, args.input), resolve(cwd, args.output));
+		process.stdout.write(`已生成离线 HTML：${output}\n`);
+	}
+} catch (error) {
+	process.stderr.write(`错误：${error.message}\n运行 specleaf --help 查看用法。\n`);
+	process.exitCode = 1;
+}
+export { parseArguments };

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "specleaf",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "将本地 OpenAPI 3.0 / 3.1 YAML / JSON 文件或模块目录转为按模块分组、离线阅读的单文件 HTML 文档。",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SuperPx-CN/specleaf.git"
+  },
+  "homepage": "https://github.com/SuperPx-CN/specleaf#readme",
+  "bugs": {
+    "url": "https://github.com/SuperPx-CN/specleaf/issues"
+  },
+  "type": "module",
+  "bin": {
+    "specleaf": "lib/cli.js"
+  },
+  "files": [
+    "lib/cli.js",
+    "lib/assets/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "npm run typecheck && npm run build:package && node build/build.ts",
+    "build:package": "node build/package.ts",
+    "prepack": "npm run typecheck && npm run build:package",
+    "pregenerate": "npm run build:package",
+    "generate": "node build/cli.ts",
+    "preview": "vite preview --host 127.0.0.1",
+    "typecheck": "tsc --noEmit",
+    "pretest": "npm run build:package",
+    "test": "vitest run",
+    "test:package": "node tests/package.mjs",
+    "pretest:e2e": "npm run build",
+    "test:e2e": "playwright test"
+  },
+  "dependencies": {
+    "@apidevtools/json-schema-ref-parser": "^16.0.5"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.64.1",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "lucide-react": "^0.468.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "typescript": "~5.9.3",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5"
+  }
+}