@wsxjs/wsx-press 0.0.18

package/src/node/plugin.ts

@@ -0,0 +1,223 @@
+/**
+ * @wsxjs/wsx-press/node/plugin
+ * Vite plugin for WSX-Press documentation system
+ */
+
+import type { Plugin } from "vite";
+import path from "path";
+import fs from "fs-extra";
+import { createLogger } from "@wsxjs/wsx-logger";
+import { scanDocsMetadata } from "./metadata";
+import { generateSearchIndex } from "./search";
+import { generateTOCCollection } from "./toc";
+import { generateApiDocs, type TypeDocConfig } from "./typedoc";
+
+const logger = createLogger("WSXPress");
+
+/**
+ * WSX-Press 插件配置
+ */
+export interface WSXPressOptions {
+    /** 文档根目录 */
+    docsRoot: string;
+    /** API 文档配置（可选） */
+    api?: TypeDocConfig;
+    /** 输出目录（默认：.wsx-press） */
+    outputDir?: string;
+}
+
+/**
+ * WSX-Press Vite 插件
+ *
+ * @param options - 插件配置选项
+ * @returns Vite 插件实例
+ */
+export function wsxPress(options: WSXPressOptions): Plugin {
+    const { docsRoot, api, outputDir = ".wsx-press" } = options;
+
+    let absoluteOutputDir: string;
+    let absoluteDocsRoot: string;
+
+    return {
+        name: "vite-plugin-wsx-press",
+        enforce: "pre",
+
+        /**
+         * Vite 配置解析后，解析绝对路径
+         */
+        configResolved(config) {
+            // 在配置解析后解析绝对路径
+            // 使用简单的字符串检查，避免构建时 path 模块的问题
+            const isAbsolutePath = (p: string) => {
+                // Unix/Linux/Mac 绝对路径以 / 开头
+                // Windows 绝对路径以盘符开头（如 C:）或 \\ 开头
+                return p.startsWith("/") || /^[A-Za-z]:/.test(p) || p.startsWith("\\\\");
+            };
+
+            absoluteOutputDir = isAbsolutePath(outputDir)
+                ? outputDir
+                : path.resolve(config.root, outputDir);
+
+            absoluteDocsRoot = isAbsolutePath(docsRoot)
+                ? docsRoot
+                : path.resolve(config.root, docsRoot);
+        },
+
+        /**
+         * 构建开始时生成元数据和搜索索引
+         */
+        async buildStart() {
+            try {
+                // 如果路径还未解析（configResolved 未调用），使用默认值
+                if (!absoluteOutputDir || !absoluteDocsRoot) {
+                    const isAbsolutePath = (p: string) => {
+                        return p.startsWith("/") || /^[A-Za-z]:/.test(p) || p.startsWith("\\\\");
+                    };
+
+                    absoluteOutputDir = isAbsolutePath(outputDir)
+                        ? outputDir
+                        : path.resolve(process.cwd(), outputDir);
+
+                    absoluteDocsRoot = isAbsolutePath(docsRoot)
+                        ? docsRoot
+                        : path.resolve(process.cwd(), docsRoot);
+                }
+
+                // 确保输出目录存在
+                await fs.ensureDir(absoluteOutputDir);
+
+                logger.info("Starting documentation generation...");
+                logger.info(`Docs root: ${absoluteDocsRoot}`);
+                logger.info(`Output dir: ${absoluteOutputDir}`);
+
+                // 扫描文档元数据
+                const metadata = await scanDocsMetadata(absoluteDocsRoot);
+                const metadataPath = path.join(absoluteOutputDir, "docs-meta.json");
+                await fs.writeJSON(metadataPath, metadata, { spaces: 2 });
+                logger.info(
+                    `✅ Generated docs-meta.json with ${Object.keys(metadata).length} documents`
+                );
+
+                // 生成搜索索引
+                const searchIndex = await generateSearchIndex(metadata, absoluteDocsRoot);
+                const searchIndexPath = path.join(absoluteOutputDir, "search-index.json");
+                await fs.writeJSON(searchIndexPath, searchIndex, { spaces: 2 });
+                logger.info("✅ Generated search-index.json");
+
+                // 生成 TOC 数据
+                logger.info("Generating TOC collection...");
+                try {
+                    const tocCollection = await generateTOCCollection(metadata, absoluteDocsRoot);
+                    const tocPath = path.join(absoluteOutputDir, "docs-toc.json");
+                    await fs.writeJSON(tocPath, tocCollection, { spaces: 2 });
+                    logger.info(
+                        `✅ Generated docs-toc.json with ${Object.keys(tocCollection).length} documents`
+                    );
+                } catch (tocError) {
+                    logger.error("❌ Failed to generate TOC collection:", tocError);
+                    // 不抛出错误，继续构建流程
+                }
+
+                // 如果配置了 API 文档，生成 API 文档
+                if (api) {
+                    const apiOutputDir = api.outputDir || path.join(absoluteDocsRoot, "api");
+                    await generateApiDocs({
+                        ...api,
+                        outputDir: path.isAbsolute(apiOutputDir)
+                            ? apiOutputDir
+                            : path.resolve(process.cwd(), apiOutputDir),
+                    });
+                }
+            } catch (error) {
+                logger.error("Failed to generate documentation:", error);
+                throw error;
+            }
+        },
+
+        /**
+         * 配置开发服务器
+         * 在开发模式下通过 /.wsx-press 路径提供元数据和搜索索引
+         */
+        configureServer(server) {
+            // 添加中间件，在开发模式下提供元数据和搜索索引
+            server.middlewares.use("/.wsx-press", async (req, res, next) => {
+                try {
+                    const url = new URL(req.url || "/", `http://${req.headers.host}`);
+                    // 当中间件挂载在 /.wsx-press 下时，url.pathname 会是 /.wsx-press/docs-meta.json
+                    // 需要提取文件名部分（移除 /.wsx-press 前缀）
+                    const fullPath = url.pathname;
+                    // 移除 /.wsx-press 前缀，处理有/无尾部斜杠的情况
+                    const fileName = fullPath.replace(/^\/\.wsx-press\/?/, "").replace(/^\//, "");
+
+                    // 检查是否是支持的文件
+                    if (
+                        fileName === "docs-meta.json" ||
+                        fileName === "search-index.json" ||
+                        fileName === "docs-toc.json"
+                    ) {
+                        const file = path.join(absoluteOutputDir, fileName);
+                        if (await fs.pathExists(file)) {
+                            const content = await fs.readFile(file, "utf-8");
+                            res.setHeader("Content-Type", "application/json");
+                            res.end(content);
+                            return;
+                        }
+                    }
+
+                    // 如果文件不存在，尝试重新生成
+                    if (fileName === "docs-meta.json") {
+                        const metadata = await scanDocsMetadata(absoluteDocsRoot);
+                        await fs.ensureDir(absoluteOutputDir);
+                        await fs.writeJSON(
+                            path.join(absoluteOutputDir, "docs-meta.json"),
+                            metadata,
+                            {
+                                spaces: 2,
+                            }
+                        );
+                        res.setHeader("Content-Type", "application/json");
+                        res.end(JSON.stringify(metadata, null, 2));
+                        return;
+                    }
+
+                    if (fileName === "search-index.json") {
+                        const metadata = await scanDocsMetadata(absoluteDocsRoot);
+                        const searchIndex = await generateSearchIndex(metadata, absoluteDocsRoot);
+                        await fs.ensureDir(absoluteOutputDir);
+                        await fs.writeJSON(
+                            path.join(absoluteOutputDir, "search-index.json"),
+                            searchIndex,
+                            { spaces: 2 }
+                        );
+                        res.setHeader("Content-Type", "application/json");
+                        res.end(JSON.stringify(searchIndex, null, 2));
+                        return;
+                    }
+
+                    if (fileName === "docs-toc.json") {
+                        const metadata = await scanDocsMetadata(absoluteDocsRoot);
+                        const tocCollection = await generateTOCCollection(
+                            metadata,
+                            absoluteDocsRoot
+                        );
+                        await fs.ensureDir(absoluteOutputDir);
+                        await fs.writeJSON(
+                            path.join(absoluteOutputDir, "docs-toc.json"),
+                            tocCollection,
+                            { spaces: 2 }
+                        );
+                        res.setHeader("Content-Type", "application/json");
+                        res.end(JSON.stringify(tocCollection, null, 2));
+                        return;
+                    }
+
+                    next();
+                } catch (error) {
+                    logger.error("Middleware error:", error);
+                    res.statusCode = 500;
+                    res.end(JSON.stringify({ error: String(error) }));
+                }
+            });
+        },
+    };
+}

package/src/node/search.ts

@@ -0,0 +1,53 @@
+/**
+ * @wsxjs/wsx-press/node/search
+ * Search index generation
+ */
+
+import path from "path";
+import fs from "fs-extra";
+import type { DocsMetaCollection, SearchIndex, SearchDocument } from "../types";
+
+/**
+ * 生成搜索索引
+ *
+ * @param metadata - 文档元数据集合
+ * @param docsRoot - 文档根目录路径
+ * @returns 搜索索引
+ */
+export async function generateSearchIndex(
+    metadata: DocsMetaCollection,
+    docsRoot: string
+): Promise<SearchIndex> {
+    const documents: SearchDocument[] = [];
+
+    for (const [key, meta] of Object.entries(metadata)) {
+        const filePath = path.join(docsRoot, `${key}.md`);
+        const content = await fs.readFile(filePath, "utf-8");
+        const textContent = content
+            .replace(/^---[\s\S]*?---/, "") // 移除 frontmatter
+            .replace(/```[\s\S]*?```/g, "") // 移除代码块
+            .replace(/[#*`_[\]()]/g, "") // 移除 Markdown 标记
+            .trim();
+
+        documents.push({
+            id: key,
+            title: meta.title,
+            category: meta.category,
+            route: meta.route,
+            content: textContent.substring(0, 500),
+        });
+    }
+
+    return {
+        documents,
+        options: {
+            keys: [
+                { name: "title", weight: 0.7 },
+                { name: "content", weight: 0.3 },
+            ],
+            threshold: 0.3,
+            includeScore: true,
+            includeMatches: true,
+        },
+    };
+}

package/src/node/toc.ts

@@ -0,0 +1,148 @@
+/**
+ * @wsxjs/wsx-press/node/toc
+ * Table of Contents generation from markdown files
+ */
+
+import path from "path";
+import fs from "fs-extra";
+import { marked, type Tokens } from "marked";
+import type { Token } from "marked";
+import type { DocsMetaCollection } from "../types";
+
+/**
+ * TOC 项接口
+ */
+export interface TOCItem {
+    /** 标题级别 (1-6) */
+    level: number;
+    /** 标题文本 */
+    text: string;
+    /** 锚点 ID */
+    id: string;
+    /** 子项 */
+    children: TOCItem[];
+}
+
+/**
+ * 文档 TOC 数据
+ */
+export interface DocTOC {
+    /** 文档路径（相对于 docsRoot） */
+    docPath: string;
+    /** TOC 项列表 */
+    items: TOCItem[];
+}
+
+/**
+ * TOC 数据集合（按文档路径索引）
+ */
+export type TOCCollection = Record<string, TOCItem[]>;
+
+/**
+ * 从 Markdown 内容中提取标题并生成 TOC
+ *
+ * @param markdown - Markdown 内容
+ * @returns TOC 项列表
+ */
+export function extractTOCFromMarkdown(markdown: string): TOCItem[] {
+    // 移除 frontmatter
+    const contentWithoutFrontmatter = markdown.replace(/^---[\s\S]*?---\n/, "");
+
+    try {
+        // 使用 marked 解析 markdown
+        const tokens = marked.lexer(contentWithoutFrontmatter);
+        const tocItems: TOCItem[] = [];
+        const stack: TOCItem[] = [];
+
+        // 遍历 tokens，提取标题
+        for (const token of tokens) {
+            if (token.type === "heading") {
+                const headingToken = token as Tokens.Heading;
+                const level = headingToken.depth;
+                const text = extractTextFromTokens(headingToken.tokens);
+                const id = generateId(text);
+
+                const item: TOCItem = {
+                    level,
+                    text,
+                    id,
+                    children: [],
+                };
+
+                // 构建层级结构
+                while (stack.length > 0 && stack[stack.length - 1].level >= level) {
+                    stack.pop();
+                }
+
+                if (stack.length === 0) {
+                    tocItems.push(item);
+                } else {
+                    stack[stack.length - 1].children.push(item);
+                }
+
+                stack.push(item);
+            }
+        }
+
+        return tocItems;
+    } catch (error) {
+        console.warn("Failed to extract TOC from markdown:", error);
+        return [];
+    }
+}
+
+/**
+ * 从 tokens 中提取纯文本
+ */
+function extractTextFromTokens(tokens: Token[]): string {
+    return tokens
+        .map((token) => {
+            if (token.type === "text") {
+                return (token as Tokens.Text).text;
+            } else if (token.type === "strong" || token.type === "em") {
+                const inlineToken = token as Tokens.Generic;
+                if ("tokens" in inlineToken && Array.isArray(inlineToken.tokens)) {
+                    return extractTextFromTokens(inlineToken.tokens);
+                }
+            }
+            return "";
+        })
+        .join("");
+}
+
+/**
+ * 生成锚点 ID
+ */
+function generateId(text: string): string {
+    return text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, "")
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .trim();
+}
+
+/**
+ * 为所有文档生成 TOC 数据
+ *
+ * @param metadata - 文档元数据集合
+ * @param docsRoot - 文档根目录路径
+ * @returns TOC 数据集合
+ */
+export async function generateTOCCollection(
+    metadata: DocsMetaCollection,
+    docsRoot: string
+): Promise<TOCCollection> {
+    const tocCollection: TOCCollection = {};
+
+    for (const [key, _meta] of Object.entries(metadata)) {
+        const filePath = path.join(docsRoot, `${key}.md`);
+        if (await fs.pathExists(filePath)) {
+            const content = await fs.readFile(filePath, "utf-8");
+            const tocItems = extractTOCFromMarkdown(content);
+            tocCollection[key] = tocItems;
+        }
+    }
+
+    return tocCollection;
+}

package/src/node/typedoc.ts

@@ -0,0 +1,96 @@
+/**
+ * @wsxjs/wsx-press/node/typedoc
+ * TypeDoc API documentation generation
+ */
+
+import { Application, TSConfigReader, TypeDocReader } from "typedoc";
+import fs from "fs-extra";
+
+/**
+ * TypeDoc 配置选项
+ */
+export interface TypeDocConfig {
+    /** 入口点文件路径数组 */
+    entryPoints: string[];
+    /** TypeScript 配置文件路径 */
+    tsconfig: string;
+    /** 输出目录 */
+    outputDir: string;
+    /** 是否排除私有成员 */
+    excludePrivate?: boolean;
+    /** 是否排除受保护成员 */
+    excludeProtected?: boolean;
+    /** 是否排除内部成员 */
+    excludeInternal?: boolean;
+    /** 公共路径前缀 */
+    publicPath?: string;
+}
+
+/**
+ * 生成 API 文档
+ *
+ * @param config - TypeDoc 配置
+ * @throws {Error} 如果生成失败
+ */
+export async function generateApiDocs(config: TypeDocConfig): Promise<void> {
+    const {
+        entryPoints,
+        tsconfig,
+        outputDir,
+        excludePrivate = true,
+        excludeProtected = false,
+        excludeInternal = true,
+        publicPath = "/api/",
+    } = config;
+
+    // 验证入口点存在
+    for (const entryPoint of entryPoints) {
+        if (!(await fs.pathExists(entryPoint))) {
+            throw new Error(`Entry point not found: ${entryPoint}`);
+        }
+    }
+
+    // 验证 tsconfig 存在
+    if (!(await fs.pathExists(tsconfig))) {
+        throw new Error(`TypeScript config not found: ${tsconfig}`);
+    }
+
+    // 确保输出目录存在
+    await fs.ensureDir(outputDir);
+
+    try {
+        // 创建 TypeDoc 应用实例
+        // 注意：publicPath 是 typedoc-plugin-markdown 的选项，不是 TypeDoc 核心选项
+        const app = await Application.bootstrapWithPlugins({
+            entryPoints,
+            tsconfig,
+            plugin: ["typedoc-plugin-markdown"],
+            theme: "markdown",
+            // 输出配置
+            readme: "none",
+            excludePrivate,
+            excludeProtected,
+            excludeInternal,
+            // Markdown 插件配置（使用类型断言，因为这些是插件选项）
+            ...({ publicPath } as Record<string, unknown>),
+        });
+
+        // 添加配置读取器
+        app.options.addReader(new TSConfigReader());
+        app.options.addReader(new TypeDocReader());
+
+        // 转换项目
+        const project = await app.convert();
+
+        if (!project) {
+            throw new Error("Failed to convert TypeScript project");
+        }
+
+        // 生成文档
+        await app.generateDocs(project, outputDir);
+    } catch (error) {
+        throw new Error(
+            `Failed to generate API documentation: ${error instanceof Error ? error.message : String(error)}`
+        );
+    }
+}

package/src/types/wsx.d.ts

@@ -0,0 +1,11 @@
+/**
+ * WSX TypeScript 声明文件
+ * 支持 .wsx 文件导入
+ */
+
+declare module "*.wsx" {
+    import type { LightComponent, WebComponent } from "@wsxjs/wsx-core";
+    // Allow any class that extends WebComponent or LightComponent
+    const Component: new (...args: unknown[]) => WebComponent | LightComponent;
+    export default Component;
+}

package/src/types.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect } from "vitest";
+import { DocumentLoadError } from "./types";
+import type { DocMetadata, SearchDocument, DocsMetaCollection } from "./types";
+
+describe("类型定义", () => {
+    describe("DocumentLoadError", () => {
+        it("应该正确创建 NOT_FOUND 错误", () => {
+            const error = new DocumentLoadError("文档未找到", "NOT_FOUND");
+            expect(error.message).toBe("文档未找到");
+            expect(error.code).toBe("NOT_FOUND");
+            expect(error.name).toBe("DocumentLoadError");
+            expect(error.details).toBeUndefined();
+        });
+
+        it("应该正确创建 NETWORK_ERROR 错误", () => {
+            const error = new DocumentLoadError("网络错误", "NETWORK_ERROR", { status: 500 });
+            expect(error.code).toBe("NETWORK_ERROR");
+            expect(error.details).toEqual({ status: 500 });
+        });
+
+        it("应该正确创建 PARSE_ERROR 错误", () => {
+            const error = new DocumentLoadError("解析错误", "PARSE_ERROR");
+            expect(error.code).toBe("PARSE_ERROR");
+        });
+
+        it("应该正确继承 Error", () => {
+            const error = new DocumentLoadError("测试错误", "NOT_FOUND");
+            expect(error).toBeInstanceOf(Error);
+            expect(error.stack).toBeDefined();
+        });
+    });
+
+    describe("类型兼容性", () => {
+        it("DocMetadata 应该符合接口定义", () => {
+            const metadata: DocMetadata = {
+                title: "测试文档",
+                category: "guide",
+                route: "/docs/guide/test",
+            };
+            expect(metadata.title).toBe("测试文档");
+            expect(metadata.category).toBe("guide");
+            expect(metadata.route).toBe("/docs/guide/test");
+        });
+
+        it("DocMetadata 应该支持可选字段", () => {
+            const metadata: DocMetadata = {
+                title: "测试",
+                category: "guide",
+                route: "/docs/guide/test",
+                prev: "/docs/guide/prev",
+                next: "/docs/guide/next",
+                description: "描述",
+                tags: ["tag1", "tag2"],
+            };
+            expect(metadata.prev).toBe("/docs/guide/prev");
+            expect(metadata.next).toBe("/docs/guide/next");
+            expect(metadata.description).toBe("描述");
+            expect(metadata.tags).toEqual(["tag1", "tag2"]);
+        });
+
+        it("DocMetadata 应该支持 null 值", () => {
+            const metadata: DocMetadata = {
+                title: "测试",
+                category: "guide",
+                route: "/docs/guide/test",
+                prev: null,
+                next: null,
+            };
+            expect(metadata.prev).toBeNull();
+            expect(metadata.next).toBeNull();
+        });
+
+        it("SearchDocument 应该符合接口定义", () => {
+            const doc: SearchDocument = {
+                id: "test",
+                title: "测试",
+                category: "guide",
+                route: "/docs/guide/test",
+                content: "内容",
+            };
+            expect(doc.id).toBe("test");
+            expect(doc.title).toBe("测试");
+            expect(doc.category).toBe("guide");
+            expect(doc.route).toBe("/docs/guide/test");
+            expect(doc.content).toBe("内容");
+        });
+
+        it("DocsMetaCollection 应该符合类型定义", () => {
+            const collection: DocsMetaCollection = {
+                "guide/intro": {
+                    title: "介绍",
+                    category: "guide",
+                    route: "/docs/guide/intro",
+                },
+                "guide/advanced": {
+                    title: "高级",
+                    category: "guide",
+                    route: "/docs/guide/advanced",
+                },
+            };
+            expect(Object.keys(collection)).toHaveLength(2);
+            expect(collection["guide/intro"].title).toBe("介绍");
+            expect(collection["guide/advanced"].title).toBe("高级");
+        });
+
+        it("DocMetadata 应该支持扩展字段", () => {
+            const metadata: DocMetadata = {
+                title: "测试",
+                category: "guide",
+                route: "/docs/guide/test",
+                customField: "custom value",
+                anotherField: 123,
+            };
+            expect((metadata as Record<string, unknown>).customField).toBe("custom value");
+            expect((metadata as Record<string, unknown>).anotherField).toBe(123);
+        });
+    });
+});