rspress-plugin-api-extractor 0.1.1 → 0.1.2

package/index.js

@@ -5,9 +5,10 @@ import { fileURLToPath } from "node:url";
 import { NodeContext, NodeFileSystem } from "@effect/platform-node";
 import { Context, Data, Effect, Layer, LogLevel, Logger, ManagedRuntime, Metric, MetricBoundaries, Option, Schema, Stream } from "effect";
 import { FileSystem } from "@effect/platform";
-import { ApiDocumentedItem, ApiItemKind, ApiModel, ApiReleaseTagMixin, ReleaseTag } from "@microsoft/api-extractor-model";
+import { ApiDocumentedItem, ApiItemKind, ApiModel } from "@microsoft/api-extractor-model";
 import gray_matter from "gray-matter";
 import { createHash } from "node:crypto";
+import { CrossLinker, TypeSignatureFormatter, extractPlainText, getDeprecation, getExamples, getParams, getReleaseTag, getReturns, getSummary, hasModifierTag, loadApiModel } from "api-extractor-llms";
 import { format } from "prettier";
 import { imageSizeFromFile } from "image-size/fromFile";
 import { rendererRich, transformerTwoslash } from "@shikijs/twoslash";
@@ -145,14 +146,7 @@ const logBuildSummary = Effect.gen(function*() {
 });
 class ApiParser {
     static hasModifierTag(item, tagName) {
-        if (item instanceof ApiDocumentedItem) {
-            const tsdoc = item.tsdocComment;
-            if (tsdoc?.modifierTagSet) {
-                const modifierTags = tsdoc.modifierTagSet.nodes || [];
-                for (const tag of modifierTags)if (tag.tagName === `@${tagName}`) return true;
-            }
-        }
-        return false;
+        return hasModifierTag(item, tagName);
     }
     static categorizeApiItems(source, categories) {
         const items = {};
@@ -209,143 +203,25 @@ class ApiParser {
         return members;
     }
     static extractPlainText(node) {
-        const parts = [];
-        const nodeAny = node;
-        if ("PlainText" === node.kind) return nodeAny.text || "";
-        if ("SoftBreak" === node.kind) return " ";
-        if ("CodeSpan" === node.kind) return `\`${nodeAny.code || ""}\``;
-        if ("LinkTag" === node.kind) {
-            if (nodeAny.linkText) return ApiParser.extractPlainText(nodeAny.linkText);
-            if (nodeAny.codeDestination?.memberReferences?.[0]?.memberIdentifier) return nodeAny.codeDestination.memberReferences[0].memberIdentifier.identifier || "";
-            return "";
-        }
-        if (node.getChildNodes && "function" == typeof node.getChildNodes) {
-            const children = node.getChildNodes();
-            for (const child of children){
-                const childText = ApiParser.extractPlainText(child);
-                if (childText) parts.push(childText);
-            }
-        }
-        return parts.join("");
+        return extractPlainText(node);
     }
     static getSummary(item) {
-        if (item instanceof ApiDocumentedItem) {
-            const tsdoc = item.tsdocComment;
-            if (tsdoc?.summarySection) {
-                const summary = ApiParser.extractPlainText(tsdoc.summarySection);
-                return summary.replace(/\s+/g, " ").trim();
-            }
-        }
-        return "";
+        return getSummary(item);
     }
     static getReleaseTag(item) {
-        if (ApiReleaseTagMixin.isBaseClassOf(item)) {
-            const releaseTag = item.releaseTag;
-            switch(releaseTag){
-                case ReleaseTag.Public:
-                    break;
-                case ReleaseTag.Beta:
-                    return "Beta";
-                case ReleaseTag.Alpha:
-                    return "Alpha";
-                case ReleaseTag.Internal:
-                    return "Internal";
-                default:
-                    break;
-            }
-        }
-        return "Public";
+        return getReleaseTag(item);
     }
     static getParams(item) {
-        const paramList = [];
-        const paramTypes = new Map();
-        const parameters = item.parameters;
-        if (parameters && Array.isArray(parameters)) for (const param of parameters){
-            const paramExcerpt = param.parameterTypeExcerpt;
-            if (paramExcerpt?.text) {
-                const paramName = param.name || "";
-                paramTypes.set(paramName, paramExcerpt.text.trim());
-            }
-        }
-        if (item instanceof ApiDocumentedItem) {
-            const tsdoc = item.tsdocComment;
-            if (tsdoc?.params) {
-                for (const paramBlock of tsdoc.params.blocks){
-                    const paramAny = paramBlock;
-                    const paramName = paramAny.parameterName || "";
-                    const description = ApiParser.extractPlainText(paramAny.content);
-                    const paramType = paramTypes.get(paramName);
-                    paramList.push({
-                        name: paramName,
-                        ...null != paramType ? {
-                            type: paramType
-                        } : {},
-                        description: description.replace(/\s+/g, " ").trim()
-                    });
-                }
-                return paramList;
-            }
-        }
-        if (paramTypes.size > 0) for (const [name, type] of paramTypes.entries())paramList.push({
-            name,
-            type,
-            description: ""
-        });
-        return paramList;
+        return getParams(item);
     }
     static getReturns(item) {
-        if (item instanceof ApiDocumentedItem) {
-            const tsdoc = item.tsdocComment;
-            if (tsdoc?.returnsBlock) {
-                const returnsAny = tsdoc.returnsBlock;
-                const description = ApiParser.extractPlainText(returnsAny.content);
-                return {
-                    description: description.replace(/\s+/g, " ").trim()
-                };
-            }
-        }
-        return null;
+        return getReturns(item);
     }
     static getExamples(item) {
-        if (item instanceof ApiDocumentedItem) {
-            const tsdoc = item.tsdocComment;
-            const examples = [];
-            for (const customBlock of tsdoc?.customBlocks || []){
-                const blockTag = customBlock.blockTag;
-                if (blockTag?.tagNameWithUpperCase === "@EXAMPLE") {
-                    const content = customBlock.content;
-                    for (const node of content.nodes || [])if ("FencedCode" === node.kind) {
-                        const fencedCode = node;
-                        examples.push({
-                            language: fencedCode.language || "typescript",
-                            code: fencedCode.code || ""
-                        });
-                    }
-                    if (0 === examples.length) {
-                        const text = ApiParser.extractPlainText(content);
-                        if (text.trim()) examples.push({
-                            language: "typescript",
-                            code: text.trim()
-                        });
-                    }
-                }
-            }
-            return examples;
-        }
-        return [];
+        return getExamples(item);
     }
     static getDeprecation(item) {
-        if (item instanceof ApiDocumentedItem) {
-            const tsdoc = item.tsdocComment;
-            if (tsdoc?.deprecatedBlock) {
-                const deprecatedAny = tsdoc.deprecatedBlock;
-                const message = ApiParser.extractPlainText(deprecatedAny.content);
-                return {
-                    message: message.replace(/\s+/g, " ").trim()
-                };
-            }
-        }
-        return null;
+        return getDeprecation(item);
     }
     static getInheritance(item) {
         const result = {};
@@ -841,21 +717,14 @@ class MarkdownCrossLinker {
         for (const [name, route] of routes)this.apiItemRoutes.set(name, route);
     }
     addCrossLinks(text) {
-        let result = text;
-        const sortedNames = Array.from(this.apiItemRoutes.keys()).sort((a, b)=>b.length - a.length);
-        for (const name of sortedNames){
-            const route = this.apiItemRoutes.get(name);
-            if (!route) continue;
-            const regex = new RegExp(`\\b${name}\\b(?![a-zA-Z])`, "g");
-            result = result.replace(regex, (match, offset)=>{
-                const beforeMatch = result.substring(0, offset);
-                if (beforeMatch.endsWith("](") || beforeMatch.endsWith("[")) return match;
-                const backtickCount = (beforeMatch.match(/`/g) || []).length;
-                if (backtickCount % 2 === 1) return match;
-                return `[${match}](${route})`;
-            });
-        }
-        return result;
+        if (0 === this.apiItemRoutes.size) return text;
+        const refs = Array.from(this.apiItemRoutes.keys()).map((name)=>({
+                name,
+                kind: "type",
+                slug: name.toLowerCase()
+            }));
+        const linker = new CrossLinker(refs, (ref)=>this.apiItemRoutes.get(ref.name) ?? "");
+        return linker.addLinks(text);
     }
     addCrossLinksHtml(text) {
         let result = text;
@@ -878,57 +747,13 @@ class MarkdownCrossLinker {
     }
 }
 const markdownCrossLinker = new MarkdownCrossLinker();
-class TypeSignatureFormatter {
-    maxLineLength;
-    indent;
+class formatter_TypeSignatureFormatter extends TypeSignatureFormatter {
     apiItemRoutes;
     constructor(maxLineLength = 80, indent = "  ", apiItemRoutes){
-        this.maxLineLength = maxLineLength;
-        this.indent = indent;
-        this.apiItemRoutes = apiItemRoutes;
-    }
-    format(excerpt) {
-        if (!excerpt.spannedTokens || 0 === excerpt.spannedTokens.length) return this.stripExportDeclare(excerpt.text);
-        const tokens = excerpt.spannedTokens;
-        let currentLine = "";
-        const lines = [];
-        let bracketDepth = 0;
-        let lastTokenText = "";
-        for(let i = 0; i < tokens.length; i++){
-            const token = tokens[i];
-            let tokenText = token.text;
-            if (0 === i) tokenText = this.stripExportDeclare(tokenText);
-            if ("" === tokenText.trim()) continue;
-            if ("{" === tokenText || "[" === tokenText || "(" === tokenText) bracketDepth++;
-            else if ("}" === tokenText || "]" === tokenText || ")" === tokenText) bracketDepth--;
-            const isUnion = "|" === tokenText.trim();
-            const isIntersection = "&" === tokenText.trim();
-            const isOperator = isUnion || isIntersection;
-            if (lastTokenText && this.needsSpaceBefore(lastTokenText, tokenText)) currentLine += " ";
-            currentLine += tokenText;
-            lastTokenText = tokenText;
-            if (isOperator && 0 === bracketDepth && currentLine.length > this.maxLineLength && i < tokens.length - 1) {
-                lines.push(currentLine.trimEnd());
-                currentLine = this.indent;
-            }
-        }
-        if (currentLine.trim()) lines.push(currentLine.trimEnd());
-        if (lines.length <= 1) {
-            let result = "";
-            let lastNonEmptyTokenText = "";
-            for(let i = 0; i < tokens.length; i++){
-                const token = tokens[i];
-                let tokenText = token.text;
-                if (0 === i) tokenText = this.stripExportDeclare(tokenText);
-                if ("" !== tokenText.trim()) {
-                    if (lastNonEmptyTokenText && this.needsSpaceBefore(lastNonEmptyTokenText, tokenText)) result += " ";
-                    result += tokenText;
-                    lastNonEmptyTokenText = tokenText;
-                }
-            }
-            return result.trimStart();
-        }
-        return this.stripExportDeclare(lines.join("\n"));
+        super({
+            maxLineLength,
+            indent
+        }), this.apiItemRoutes = apiItemRoutes;
     }
     addLinks(text, excerpt) {
         if (!excerpt.spannedTokens || !this.apiItemRoutes) return text;
@@ -945,40 +770,12 @@ class TypeSignatureFormatter {
         }
         return result;
     }
-    stripExportDeclare(text) {
-        const trimmed = text.trim();
-        let result = trimmed.replace(/^export\s+declare\s+/i, "").replace(/^export\s+/i, "").replace(/^declare\s+/i, "");
-        result = result.replace(/\bexport\s+declare\s+/gi, "").replace(/\bexport\s+/gi, "").replace(/\bdeclare\s+/gi, "");
-        return result;
-    }
-    needsSpaceBefore(prevText, currentText) {
-        if (/\s$/.test(prevText)) return false;
-        if (/^\s/.test(currentText)) return false;
-        if (currentText.trim().startsWith("<")) return false;
-        if (currentText.trim().match(/^[,;]/)) return false;
-        if (prevText.trim().endsWith(",")) return true;
-        if ("=" === currentText.trim() || currentText.trim().startsWith("=")) return true;
-        if (prevText.trim().endsWith("=")) return true;
-        if ("|" === currentText.trim() || "&" === currentText.trim()) return true;
-        if ("|" === prevText.trim() || "&" === prevText.trim()) return true;
-        if ("{" === prevText.trim() && "}" !== currentText.trim()) return true;
-        if ("}" === currentText.trim() && "{" !== prevText.trim()) return true;
-        if (prevText.trim().match(/^[[(]$/)) return false;
-        if (currentText.trim().match(/^[\])]$/)) return false;
-        if (prevText.trim().endsWith(":")) return true;
-        if (prevText.trim().endsWith("?:")) return true;
-        if (currentText.trim().startsWith(":") && !prevText.trim().match(/[,;:?]$/)) return false;
-        if (currentText.trim().startsWith("{") && /[a-zA-Z0-9_>]$/.test(prevText.trim())) return true;
-        const prevEndsAlphanumeric = /[a-zA-Z0-9_>]$/.test(prevText.trim());
-        const currentStartsAlphanumeric = /^[a-zA-Z0-9_<]/.test(currentText.trim());
-        return prevEndsAlphanumeric && currentStartsAlphanumeric;
-    }
     escapeRegExp(string) {
         return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     }
 }
 class ClassPageGenerator {
-    typeFormatter = new TypeSignatureFormatter();
+    typeFormatter = new formatter_TypeSignatureFormatter();
     async generate(apiClass, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom) {
         const shouldSuppressErrors = suppressExampleErrors ?? true;
         const name = apiClass.displayName;
@@ -1364,7 +1161,7 @@ class EnumPageGenerator {
     }
 }
 class FunctionPageGenerator {
-    typeFormatter = new TypeSignatureFormatter();
+    typeFormatter = new formatter_TypeSignatureFormatter();
     async generate(apiFunction, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom) {
         const shouldSuppressErrors = suppressExampleErrors ?? true;
         const name = apiFunction.displayName;
@@ -1468,7 +1265,7 @@ overview: true
     }
 }
 class InterfacePageGenerator {
-    typeFormatter = new TypeSignatureFormatter();
+    typeFormatter = new formatter_TypeSignatureFormatter();
     async generate(apiInterface, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom) {
         const shouldSuppressErrors = suppressExampleErrors ?? true;
         const name = apiInterface.displayName;
@@ -1707,7 +1504,7 @@ class InterfacePageGenerator {
     }
 }
 class NamespacePageGenerator {
-    typeFormatter = new TypeSignatureFormatter();
+    typeFormatter = new formatter_TypeSignatureFormatter();
     async generate(apiNamespace, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom) {
         const shouldSuppressErrors = suppressExampleErrors ?? true;
         const name = apiNamespace.displayName;
@@ -1910,7 +1707,7 @@ class NamespacePageGenerator {
     }
 }
 class TypeAliasPageGenerator {
-    typeFormatter = new TypeSignatureFormatter();
+    typeFormatter = new formatter_TypeSignatureFormatter();
     async generate(apiTypeAlias, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom) {
         const shouldSuppressErrors = suppressExampleErrors ?? true;
         const name = apiTypeAlias.displayName;
@@ -1984,7 +1781,7 @@ class TypeAliasPageGenerator {
     }
 }
 class VariablePageGenerator {
-    typeFormatter = new TypeSignatureFormatter();
+    typeFormatter = new formatter_TypeSignatureFormatter();
     async generate(apiVariable, baseRoute, packageName, singularName, apiScope, apiName, sourceConfig, suppressExampleErrors, llmsPlugin, availableFrom) {
         const shouldSuppressErrors = suppressExampleErrors ?? true;
         const name = apiVariable.displayName;
@@ -4172,10 +3969,9 @@ async function generateShikiHast(code, highlighter, transformers, enableTwoslash
 }
 class ApiModelLoader {
     static async loadFromPath(modelPath) {
-        const apiModel = new ApiModel();
         const resolvedPath = node_path.resolve(modelPath.toString());
         if (!node_fs.existsSync(resolvedPath)) throw new Error(`API model file not found: ${resolvedPath}`);
-        return apiModel.loadPackage(resolvedPath);
+        return loadApiModel(resolvedPath);
     }
     static async loadPackageJsonFromPath(pkgPath) {
         const resolvedPath = node_path.resolve(pkgPath.toString());
@@ -6267,7 +6063,7 @@ function ApiExtractorPluginImpl(rawOptions) {
             if (rspressLlmsEnabled && resolvedLlmsPlugin.enabled && resolvedLlmsPlugin.scopes) {
                 if (!updatedConfig.builderConfig.resolve) updatedConfig.builderConfig.resolve = {};
                 const pluginDir = node_path.dirname(fileURLToPath(import.meta.url));
-                const customLlmsViewOptions = node_path.resolve(pluginDir, "../../src/runtime/components/ApiLlmsViewOptions/index.tsx");
+                const customLlmsViewOptions = node_path.resolve(pluginDir, "runtime/components/ApiLlmsViewOptions/index.js");
                 const pluginRequire = createRequire(import.meta.url);
                 const rspressCoreDir = node_path.dirname(pluginRequire.resolve("@rspress/core/package.json"));
                 const originalLlmsViewOptions = node_path.join(rspressCoreDir, "dist/theme/components/Llms/LlmsViewOptions.js");
@@ -6317,7 +6113,7 @@ function ApiExtractorPluginImpl(rawOptions) {
                 updatedConfig.themeConfig.apiExtractorScopes = scopes;
                 if (!updatedConfig.globalUIComponents) updatedConfig.globalUIComponents = [];
                 const llmsComponentPluginDir = node_path.dirname(fileURLToPath(import.meta.url));
-                const llmsComponentPath = node_path.resolve(llmsComponentPluginDir, "../../src/runtime/components/ApiLlmsPackageActions/index.tsx");
+                const llmsComponentPath = node_path.resolve(llmsComponentPluginDir, "runtime/components/ApiLlmsPackageActions/index.js");
                 updatedConfig.globalUIComponents.push(llmsComponentPath);
             }
             return updatedConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rspress-plugin-api-extractor",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": false,
   "description": "RSPress plugin for generating API documentation from TypeScript API Extractor models",
   "keywords": [
@@ -49,6 +49,7 @@
     "@effect/sql-sqlite-node": "^0.52.0",
     "@microsoft/api-extractor-model": "^7.33.8",
     "@shikijs/twoslash": "^4.1.0",
+    "api-extractor-llms": "0.1.0",
     "clsx": "^2.1.1",
     "effect": "^3.21.2",
     "gray-matter": "^4.0.3",

package/runtime/components/ApiExample/index.js

@@ -0,0 +1,29 @@
+import { Fragment, jsx } from "react/jsx-runtime";
+import { createElement, useMemo } from "react";
+import { decodeHast } from "../../utils/decode-hast.js";
+import { ExampleBlock } from "../ExampleBlock/index.js";
+function ApiExample({ code, hast }) {
+    const parsedHast = useMemo(()=>decodeHast(hast, "ApiExample"), [
+        hast
+    ]);
+    if (import.meta.env.SSG_MD) {
+        const header = "```typescript\n";
+        const footer = "\n```\n";
+        return /*#__PURE__*/ jsx(Fragment, {
+            children: `${header}${code.trim()}${footer}`
+        });
+    }
+    if (parsedHast) return /*#__PURE__*/ createElement(ExampleBlock, {
+        hast: parsedHast,
+        code: code.trim()
+    });
+    return /*#__PURE__*/ jsx("pre", {
+        children: /*#__PURE__*/ jsx("code", {
+            className: "language-typescript",
+            children: code.trim()
+        })
+    });
+}
+const components_ApiExample = ApiExample;
+export default components_ApiExample;
+export { ApiExample };