specleaf 0.0.0-stage → 1.0.0

package/lib/cli.js

@@ -0,0 +1,223 @@
+#!/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 { randomUUID } from "node:crypto";
+// src/lib/openapi.ts
+var pointerEscape = (value) => value.replace(/~/g, "~0").replace(/\//g, "~1");
+// build/contract.ts
+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);
+		throw new Error([
+			`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 });
+	}
+}
+// 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(contract.document.info.title);
+	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(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 loadContract(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.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.0.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"
+  }
+}