rspress-plugin-api-extractor 0.1.0

package/0~llms-program.js

@@ -0,0 +1,344 @@
+import node_path from "node:path";
+import { FileSystem } from "@effect/platform";
+import { Effect } from "effect";
+const LLMS_TXT_LINE_RE = /^-\s+\[([^\]]+)\]\(([^)]+)\)(?::\s*(.+))?$/;
+function parseLlmsTxtLine(line) {
+    const trimmed = line.trim();
+    if ("" === trimmed) return null;
+    const match = LLMS_TXT_LINE_RE.exec(trimmed);
+    if (!match) return null;
+    const title = match[1];
+    const url = match[2];
+    const rawDescription = match[3];
+    return {
+        title,
+        url,
+        description: rawDescription ? rawDescription.trim() : void 0
+    };
+}
+function filterLlmsTxt(content, apiRoutes, pointers) {
+    const lines = content.split("\n");
+    const filtered = [];
+    for (const line of lines){
+        const entry = parseLlmsTxtLine(line);
+        if (!(entry && apiRoutes.has(entry.url))) filtered.push(line);
+    }
+    let result = filtered.join("\n");
+    if (pointers.length > 0) {
+        result += "\n\n";
+        for (const pointer of pointers)result += `- For ${pointer.name} API docs, see [${pointer.name} llms.txt](${pointer.llmsTxtUrl})\n`;
+    }
+    return result;
+}
+function generateStructuredLlmsTxt(content, apiRoutes, packages) {
+    const lines = content.split("\n");
+    let title = "";
+    for (const line of lines)if (line.startsWith("# ")) {
+        title = line;
+        break;
+    }
+    const allEntries = [];
+    for (const line of lines){
+        const entry = parseLlmsTxtLine(line);
+        if (entry && !apiRoutes.has(entry.url)) allEntries.push(entry);
+    }
+    const packageEntries = new Map();
+    const others = [];
+    for (const entry of allEntries){
+        let matched = false;
+        for (const pkg of packages){
+            const base = pkg.packageRoute.endsWith("/") ? pkg.packageRoute : `${pkg.packageRoute}/`;
+            if (entry.url.startsWith(base) || entry.url === pkg.packageRoute) {
+                const existing = packageEntries.get(pkg.packageName) ?? [];
+                existing.push(entry);
+                packageEntries.set(pkg.packageName, existing);
+                matched = true;
+                break;
+            }
+        }
+        if (!matched) others.push(entry);
+    }
+    const output = [];
+    if (title) {
+        output.push(title);
+        output.push("");
+    }
+    if (others.length > 0) {
+        output.push("## Others");
+        output.push("");
+        for (const entry of others)output.push(formatEntry(entry));
+        output.push("");
+    }
+    const packagesWithEntries = packages;
+    if (packagesWithEntries.length > 0) {
+        output.push("## Packages");
+        output.push("");
+        for (const pkg of packagesWithEntries){
+            const versionSuffix = pkg.version ? ` ${pkg.version}` : "";
+            output.push(`### ${pkg.name}${versionSuffix}`);
+            output.push("");
+            if (pkg.description) {
+                output.push(pkg.description);
+                output.push("");
+            }
+            const entries = packageEntries.get(pkg.packageName) ?? [];
+            for (const entry of entries)output.push(formatEntry(entry));
+            output.push(`- [API Reference](${pkg.llmsApiTxtUrl})`);
+            output.push("");
+        }
+    }
+    return output.join("\n");
+}
+function parseSections(content) {
+    if ("" === content.trim()) return [];
+    const sections = [];
+    const frontmatterPattern = /^---\nurl:\s*(.+)\n---$/gm;
+    let match = frontmatterPattern.exec(content);
+    const boundaries = [];
+    while(null !== match){
+        boundaries.push({
+            url: match[1].trim(),
+            start: match.index,
+            fmEnd: match.index + match[0].length
+        });
+        match = frontmatterPattern.exec(content);
+    }
+    for(let i = 0; i < boundaries.length; i++){
+        const boundary = boundaries[i];
+        const nextStart = i + 1 < boundaries.length ? boundaries[i + 1].start : content.length;
+        const sectionContent = content.slice(boundary.start, nextStart);
+        sections.push({
+            url: boundary.url,
+            raw: sectionContent.trimEnd()
+        });
+    }
+    return sections;
+}
+function filterLlmsFullTxt(content, apiRoutes) {
+    if ("" === content.trim()) return "";
+    const sections = parseSections(content);
+    const kept = sections.filter((section)=>!apiRoutes.has(section.url));
+    if (0 === kept.length) return "";
+    return kept.map((section)=>section.raw).join("\n\n\n");
+}
+function formatEntry(entry) {
+    if (entry.description) return `- [${entry.title}](${entry.url}): ${entry.description}`;
+    return `- [${entry.title}](${entry.url})`;
+}
+function generatePackageLlmsTxt(input) {
+    const parts = [
+        `# ${input.name}`,
+        "",
+        `> API documentation for the ${input.packageName} package`
+    ];
+    if (input.guidePages.length > 0) {
+        parts.push("");
+        parts.push("## Guides");
+        parts.push("");
+        for (const page of input.guidePages)parts.push(formatEntry(page));
+    }
+    if (input.apiPages.length > 0) {
+        parts.push("");
+        parts.push("## API Reference");
+        parts.push("");
+        for (const page of input.apiPages)parts.push(formatEntry(page));
+    }
+    parts.push("");
+    return parts.join("\n");
+}
+function generatePackageLlmsFullTxt(pages) {
+    if (0 === pages.length) return "";
+    const sections = [];
+    for (const page of pages)sections.push(`---\nurl: ${page.url}\n---\n\n${page.content}`);
+    return sections.join("\n\n\n");
+}
+function buildApiRoutes(buildResults) {
+    const apiRoutes = new Set();
+    for (const result of buildResults){
+        const base = result.baseRoute.endsWith("/") ? result.baseRoute : `${result.baseRoute}/`;
+        for (const relPath of result.generatedFiles){
+            if (!relPath.endsWith(".mdx")) continue;
+            const mdPath = relPath.replace(/\.mdx$/, ".md");
+            const routeUrl = `${base}${mdPath}`;
+            apiRoutes.add(routeUrl);
+        }
+    }
+    return apiRoutes;
+}
+function discoverPrefixes(buildResults) {
+    const prefixes = new Set();
+    prefixes.add("");
+    for (const result of buildResults){
+        const segments = result.baseRoute.split("/").filter(Boolean);
+        if (segments.length > 1) {
+            const prefixSegments = segments.slice(0, -1);
+            prefixes.add(prefixSegments.join("/"));
+        }
+    }
+    return prefixes;
+}
+function buildPackagePointers(buildResults, prefix, packageRoutes) {
+    const pointers = [];
+    for (const result of buildResults){
+        if ("" !== prefix && !result.baseRoute.startsWith(`/${prefix}/`)) continue;
+        const displayName = result.apiName ?? result.packageName;
+        const pkgRoute = packageRoutes.get(result.packageName) ?? result.baseRoute;
+        const base = pkgRoute.endsWith("/") ? pkgRoute : `${pkgRoute}/`;
+        pointers.push({
+            name: displayName,
+            llmsTxtUrl: `${base}llms.txt`
+        });
+    }
+    return pointers;
+}
+function collectApiEntries(globalLlmsTxtContent, result) {
+    const base = result.baseRoute.endsWith("/") ? result.baseRoute : `${result.baseRoute}/`;
+    const entries = [];
+    for (const line of globalLlmsTxtContent.split("\n")){
+        const entry = parseLlmsTxtLine(line);
+        if (entry) {
+            if (entry.url.startsWith(base)) entries.push(entry);
+        }
+    }
+    return entries;
+}
+function collectGuideEntries(globalLlmsTxtContent, apiRoutes, packageRoute) {
+    const base = packageRoute.endsWith("/") ? packageRoute : `${packageRoute}/`;
+    const entries = [];
+    for (const line of globalLlmsTxtContent.split("\n")){
+        const entry = parseLlmsTxtLine(line);
+        if (entry) {
+            if ((entry.url === packageRoute || entry.url.startsWith(base)) && !apiRoutes.has(entry.url)) entries.push(entry);
+        }
+    }
+    return entries;
+}
+function extractSections(globalLlmsFullContent, urlPredicate) {
+    const pages = [];
+    if (!globalLlmsFullContent) return pages;
+    const frontmatterPattern = /^---\nurl:\s*(.+)\n---$/gm;
+    let match = frontmatterPattern.exec(globalLlmsFullContent);
+    const boundaries = [];
+    while(null !== match){
+        boundaries.push({
+            url: match[1].trim(),
+            start: match.index,
+            fmEnd: match.index + match[0].length
+        });
+        match = frontmatterPattern.exec(globalLlmsFullContent);
+    }
+    for(let i = 0; i < boundaries.length; i++){
+        const boundary = boundaries[i];
+        if (!urlPredicate(boundary.url)) continue;
+        const nextStart = i + 1 < boundaries.length ? boundaries[i + 1].start : globalLlmsFullContent.length;
+        const content = globalLlmsFullContent.slice(boundary.fmEnd, nextStart).trim();
+        pages.push({
+            url: boundary.url,
+            content
+        });
+    }
+    return pages;
+}
+function collectApiPageContent(globalLlmsFullContent, result) {
+    const base = result.baseRoute.endsWith("/") ? result.baseRoute : `${result.baseRoute}/`;
+    return extractSections(globalLlmsFullContent, (url)=>url.startsWith(base));
+}
+function processLlmsFiles(input) {
+    return Effect.gen(function*() {
+        const fs = yield* FileSystem.FileSystem;
+        const { outDir, buildResults, llmsPlugin, packageRoutes } = input;
+        if (0 === buildResults.length) return;
+        const apiRoutes = buildApiRoutes(buildResults);
+        yield* Effect.logDebug(`Built ${apiRoutes.size} API routes for LLMs filtering`);
+        if (0 === apiRoutes.size) return;
+        const prefixes = discoverPrefixes(buildResults);
+        yield* Effect.forEach([
+            ...prefixes
+        ], (prefix)=>processPrefix(fs, outDir, prefix, buildResults, apiRoutes, llmsPlugin, packageRoutes), {
+            concurrency: "unbounded"
+        });
+    });
+}
+function processPrefix(fs, outDir, prefix, buildResults, apiRoutes, llmsPlugin, packageRoutes) {
+    return Effect.gen(function*() {
+        const prefixDir = prefix ? node_path.join(outDir, prefix) : outDir;
+        const llmsTxtPath = node_path.join(prefixDir, "llms.txt");
+        const llmsTxtExists = yield* fs.exists(llmsTxtPath).pipe(Effect.orElseSucceed(()=>false));
+        if (!llmsTxtExists) return;
+        const llmsTxtContent = yield* fs.readFileString(llmsTxtPath).pipe(Effect.orDie);
+        const llmsFullTxtPath = node_path.join(prefixDir, "llms-full.txt");
+        const llmsFullTxtExists = yield* fs.exists(llmsFullTxtPath).pipe(Effect.orElseSucceed(()=>false));
+        const llmsFullTxtContent = llmsFullTxtExists ? yield* fs.readFileString(llmsFullTxtPath).pipe(Effect.orDie) : "";
+        if (llmsPlugin.scopes) {
+            const packageScopes = buildResults.map((r)=>{
+                const pkgRoute = packageRoutes.get(r.packageName) ?? r.baseRoute;
+                return {
+                    name: r.apiName ?? r.packageName,
+                    packageName: r.packageName,
+                    version: r.packageVersion,
+                    description: r.packageDescription,
+                    packageRoute: pkgRoute,
+                    llmsApiTxtUrl: `${pkgRoute.endsWith("/") ? pkgRoute : `${pkgRoute}/`}llms-api.txt`
+                };
+            });
+            const structuredLlmsTxt = generateStructuredLlmsTxt(llmsTxtContent, apiRoutes, packageScopes);
+            yield* fs.writeFileString(llmsTxtPath, structuredLlmsTxt).pipe(Effect.orDie);
+        } else {
+            const pointers = buildPackagePointers(buildResults, prefix, packageRoutes);
+            const filteredLlmsTxt = filterLlmsTxt(llmsTxtContent, apiRoutes, pointers);
+            yield* fs.writeFileString(llmsTxtPath, filteredLlmsTxt).pipe(Effect.orDie);
+        }
+        if (llmsFullTxtContent) {
+            const filteredLlmsFullTxt = filterLlmsFullTxt(llmsFullTxtContent, apiRoutes);
+            yield* fs.writeFileString(llmsFullTxtPath, filteredLlmsFullTxt).pipe(Effect.orDie);
+        }
+        if (llmsPlugin.scopes) {
+            const prefixResults = "" === prefix ? [
+                ...buildResults
+            ] : buildResults.filter((r)=>r.baseRoute.startsWith(`/${prefix}/`));
+            yield* Effect.forEach(prefixResults, (result)=>generatePerPackageFiles(fs, outDir, result, llmsTxtContent, llmsFullTxtContent, apiRoutes, llmsPlugin, packageRoutes.get(result.packageName) ?? result.baseRoute), {
+                concurrency: "unbounded"
+            });
+        }
+    });
+}
+function generatePerPackageFiles(fs, outDir, result, globalLlmsTxtContent, globalLlmsFullContent, apiRoutes, llmsPlugin, packageRoute) {
+    return Effect.gen(function*() {
+        const pkgRouteSegment = packageRoute.replace(/^\//, "");
+        const packageLlmsDir = pkgRouteSegment ? node_path.join(outDir, pkgRouteSegment) : outDir;
+        yield* fs.makeDirectory(packageLlmsDir, {
+            recursive: true
+        }).pipe(Effect.orDie);
+        const displayName = result.apiName ?? result.packageName;
+        const apiEntries = collectApiEntries(globalLlmsTxtContent, result);
+        const guideEntries = collectGuideEntries(globalLlmsTxtContent, apiRoutes, packageRoute);
+        const packageLlmsTxt = generatePackageLlmsTxt({
+            name: displayName,
+            packageName: result.packageName,
+            guidePages: guideEntries,
+            apiPages: apiEntries
+        });
+        yield* fs.writeFileString(node_path.join(packageLlmsDir, "llms.txt"), packageLlmsTxt).pipe(Effect.orDie);
+        const apiPageContent = collectApiPageContent(globalLlmsFullContent, result);
+        const guideRouteUrls = new Set(guideEntries.map((e)=>e.url));
+        const guidePageContent = globalLlmsFullContent ? extractSections(globalLlmsFullContent, (url)=>guideRouteUrls.has(url)) : [];
+        const fullPageContent = [
+            ...guidePageContent,
+            ...apiPageContent
+        ];
+        if (fullPageContent.length > 0) {
+            const packageLlmsFullTxt = generatePackageLlmsFullTxt(fullPageContent);
+            yield* fs.writeFileString(node_path.join(packageLlmsDir, "llms-full.txt"), packageLlmsFullTxt).pipe(Effect.orDie);
+        }
+        if (llmsPlugin.apiTxt && apiPageContent.length > 0) {
+            const apiTxtContent = generatePackageLlmsFullTxt(apiPageContent);
+            yield* fs.writeFileString(node_path.join(packageLlmsDir, "llms-api.txt"), apiTxtContent).pipe(Effect.orDie);
+        }
+        if (guidePageContent.length > 0) {
+            const docsTxtContent = generatePackageLlmsFullTxt(guidePageContent);
+            yield* fs.writeFileString(node_path.join(packageLlmsDir, "llms-docs.txt"), docsTxtContent).pipe(Effect.orDie);
+        }
+        yield* Effect.logDebug(`Generated LLMs files for ${displayName} in ${packageLlmsDir}`);
+    });
+}
+export { processLlmsFiles };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# rspress-plugin-api-extractor
+
+[![npm](https://img.shields.io/npm/v/rspress-plugin-api-extractor?label=npm&color=cb3837)](https://www.npmjs.com/package/rspress-plugin-api-extractor)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.1.0](https://img.shields.io/badge/Node.js-%3E%3D24.1.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+An [RSPress](https://rspress.dev/) 2.0 plugin that generates interactive API documentation from [Microsoft API Extractor](https://api-extractor.com/) models. Point it at your `.api.json` files and you get a documentation site: syntax-highlighted signatures, Twoslash hover tooltips, type references that cross-link between pages and copy-paste code examples.
+
+## Install
+
+```bash
+npm install rspress-plugin-api-extractor
+# or
+pnpm add rspress-plugin-api-extractor
+```
+
+The plugin is a peer of `@rspress/core`, `react` and `react-dom`; install those too if your site does not already have them.
+
+## Quick start
+
+```ts
+// rspress.config.ts
+import { defineConfig } from "@rspress/core";
+import { ApiExtractorPlugin } from "rspress-plugin-api-extractor";
+
+export default defineConfig({
+  root: "docs",
+  plugins: [
+    ApiExtractorPlugin({
+      api: {
+        packageName: "my-library",
+        model: "./api/my-library.api.json",
+      },
+    }),
+  ],
+});
+```
+
+```bash
+npx rspress dev
+# Generates one MDX page per public API item and serves them at http://localhost:3000
+```
+
+The plugin reads your `.api.json` model and writes one MDX page per public API item under your docs root, grouped into category folders (classes, interfaces, functions, type aliases, enums, variables and namespaces) with navigation metadata. To produce the model, pair it with [@savvy-web/rslib-builder](https://github.com/savvy-web/rslib-builder), which emits the `.api.json` as part of your TypeScript build.
+
+## Features
+
+- Generates API docs from `.api.json` models for classes, interfaces, functions, type aliases, enums, variables and namespaces.
+- Type-checks code examples and adds Twoslash hover tooltips that show inferred types.
+- Cross-links type references between pages, so a type named in a signature links to its own page.
+- Drives single-package sites, multi-package portals, RSPress multiVersion and i18n from one plugin.
+- Handles multi-entry-point packages: it deduplicates re-exports and notes which entry points each item is available from.
+- Writes per-package `llms*.txt` files and in-page actions for pointing an assistant at one package's docs.
+
+## Documentation
+
+- [Getting started](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/01-getting-started.md) — Install, minimal config, first build.
+- [Configuration](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/02-configuration.md) — Full plugin-options reference.
+- [Config helpers](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/03-config-helpers.md) — `fromFolder` and `fromModelsDir` for discovering config from package folders.
+- [Single package](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/04-single-package.md) — The single-API recipe.
+- [Multi-package](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/05-multi-package.md) — The multi-API portal recipe.
+- [Versioned](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/06-versioned.md) — Documenting major versions side by side.
+- [i18n](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/07-i18n.md) — Internationalized documentation.
+- [Multi-entry points](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/08-multi-entry-points.md) — Deduplication, "Available from" and route collisions.
+- [LLMs](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/09-llms.md) — Per-package `llms*.txt` files and assistant actions.
+- [Runtime components](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/10-runtime-components.md) — The runtime components and live `with-api` code blocks.
+- [Troubleshooting](https://github.com/spencerbeggs/rspress-plugin-api-extractor/blob/main/docs/11-troubleshooting.md) — Route collisions, forgotten exports, Twoslash errors and stale caches.
+
+## License
+
+[MIT](LICENSE)