@openpkg-ts/doc-generator 0.1.0

package/README.md

@@ -0,0 +1,324 @@
+# @openpkg-ts/doc-generator
+
+API documentation generator consuming OpenPkg specs. A modern alternative to TypeDoc for doc frameworks like Fumadocs, Mintlify, and Docusaurus.
+
+## Features
+
+- **Multiple output formats**: Markdown/MDX, HTML, JSON
+- **React components**: Headless and pre-styled (Tailwind v4)
+- **Search indexes**: Pagefind and Algolia compatible
+- **Framework adapters**: Fumadocs, Docusaurus, and generic navigation
+- **CLI tooling**: Generate static docs or dev server
+
+## Installation
+
+```bash
+npm install @openpkg-ts/doc-generator
+# or
+bun add @openpkg-ts/doc-generator
+```
+
+## Quick Start
+
+### Programmatic API
+
+```ts
+import { createDocs } from '@openpkg-ts/doc-generator'
+
+// Load from file or object
+const docs = createDocs('./openpkg.json')
+
+// Query exports
+docs.getExport('useState')
+docs.getExportsByKind('function')
+docs.getExportsByTag('@beta')
+docs.search('hook')
+
+// Render
+docs.toMarkdown()                      // Full MDX
+docs.toMarkdown({ export: 'useState' }) // Single export
+docs.toHTML()                          // Standalone HTML
+docs.toJSON()                          // Structured JSON
+docs.toNavigation()                    // Sidebar structure
+docs.toSearchIndex()                   // Search records
+```
+
+### CLI
+
+```bash
+# Generate MDX files for existing site
+npx openpkg-docs generate ./openpkg.json --out ./docs/api
+
+# Generate JSON for custom rendering
+npx openpkg-docs generate ./openpkg.json --format json --out ./api.json
+
+# Generate with navigation
+npx openpkg-docs generate ./openpkg.json --out ./docs/api --nav fumadocs
+
+# Build standalone site
+npx openpkg-docs build ./openpkg.json --out ./api-docs
+
+# Dev server with hot reload
+npx openpkg-docs dev ./openpkg.json --port 3001
+```
+
+### React Components
+
+```tsx
+// Headless (unstyled, composable)
+import { Signature, ParamTable, ExampleBlock } from '@openpkg-ts/doc-generator/react'
+
+<Signature signature={fn.signatures[0]} />
+<ParamTable params={fn.signatures[0].parameters} />
+<ExampleBlock examples={fn.examples} />
+```
+
+```tsx
+// Pre-styled (Tailwind v4)
+import { FunctionPage, ClassPage } from '@openpkg-ts/doc-generator/react/styled'
+
+<FunctionPage export={fn} />
+<ClassPage export={cls} />
+```
+
+## API Reference
+
+### Core Functions
+
+#### `createDocs(input: string | OpenPkg): DocsInstance`
+
+Create a docs instance from file path or spec object.
+
+```ts
+const docs = createDocs('./openpkg.json')
+// or
+const docs = createDocs(specObject)
+```
+
+#### `loadSpec(spec: OpenPkg): DocsInstance`
+
+Create a docs instance from spec object directly.
+
+### DocsInstance Methods
+
+| Method | Description |
+|--------|-------------|
+| `getExport(id)` | Get export by ID |
+| `getExportsByKind(kind)` | Get exports of specific kind |
+| `getExportsByTag(tag)` | Get exports with JSDoc tag |
+| `search(query)` | Search by name/description |
+| `getDeprecated()` | Get deprecated exports |
+| `groupByKind()` | Group exports by kind |
+| `toMarkdown(options?)` | Render to MDX |
+| `toHTML(options?)` | Render to HTML |
+| `toJSON(options?)` | Render to JSON |
+| `toNavigation(options?)` | Generate navigation |
+| `toSearchIndex(options?)` | Generate search index |
+
+### Query Utilities
+
+```ts
+import {
+  formatSchema,
+  buildSignatureString,
+  getMethods,
+  getProperties,
+  groupByVisibility,
+  sortByKindThenName,
+} from '@openpkg-ts/doc-generator'
+
+formatSchema({ type: 'string' }) // 'string'
+buildSignatureString(fn) // 'function greet(name: string): string'
+getMethods(classExport.members) // [{ name: 'foo', signatures: [...] }]
+```
+
+### Render Options
+
+#### Markdown Options
+
+```ts
+docs.toMarkdown({
+  export: 'greet',           // Single export mode
+  frontmatter: true,         // Include YAML frontmatter
+  codeSignatures: true,      // Use code blocks for signatures
+  headingOffset: 1,          // Start at h2 instead of h1
+  sections: {
+    signature: true,
+    description: true,
+    parameters: true,
+    returns: true,
+    examples: true,
+  },
+})
+```
+
+#### HTML Options
+
+```ts
+docs.toHTML({
+  export: 'greet',           // Single export mode
+  fullDocument: true,        // Wrap in HTML document
+  includeStyles: true,       // Include default CSS
+  customCSS: '.custom {}',   // Custom CSS to inject
+  title: 'API Reference',    // Page title
+})
+```
+
+#### Navigation Options
+
+```ts
+docs.toNavigation({
+  format: 'fumadocs',        // 'fumadocs' | 'docusaurus' | 'generic'
+  groupBy: 'kind',           // 'kind' | 'module' | 'tag' | 'none'
+  basePath: '/api',          // Base URL for links
+  sortAlphabetically: true,  // Sort exports by name
+})
+```
+
+#### Search Options
+
+```ts
+docs.toSearchIndex({
+  baseUrl: '/docs/api',
+  includeMembers: true,
+  includeParameters: true,
+  weights: {
+    name: 10,
+    description: 5,
+    signature: 3,
+  },
+})
+```
+
+## React Components
+
+### Headless Components
+
+Unstyled, composable primitives for building custom UIs:
+
+| Component | Props | Description |
+|-----------|-------|-------------|
+| `Signature` | `SignatureProps` | Render type signature |
+| `ParamTable` | `ParamTableProps` | Parameter table |
+| `TypeTable` | `TypeTableProps` | Type properties table |
+| `MembersTable` | `MembersTableProps` | Class/interface members |
+| `ExampleBlock` | `ExampleBlockProps` | Code examples |
+| `CollapsibleMethod` | `CollapsibleMethodProps` | Expandable method |
+| `ExpandableProperty` | `ExpandablePropertyProps` | Nested properties |
+
+### Styled Components
+
+Pre-styled with Tailwind v4:
+
+| Component | Props | Description |
+|-----------|-------|-------------|
+| `FunctionPage` | `FunctionPageProps` | Function documentation |
+| `ClassPage` | `ClassPageProps` | Class documentation |
+| `InterfacePage` | `InterfacePageProps` | Interface documentation |
+| `EnumPage` | `EnumPageProps` | Enum documentation |
+| `VariablePage` | `VariablePageProps` | Variable documentation |
+| `APIPage` | `APIPageProps` | Full API page wrapper |
+
+## CLI Commands
+
+### `generate`
+
+Generate MDX or JSON files from OpenPkg spec.
+
+```bash
+openpkg-docs generate <spec> [options]
+
+Options:
+  -o, --out <dir>       Output directory (default: ./api-docs)
+  -f, --format <type>   Output format: mdx or json (default: mdx)
+  --nav <format>        Navigation: fumadocs, docusaurus, generic
+  --flat                Flat file structure
+  --group-by <type>     Group by: kind, module, tag, none (default: kind)
+  --base-path <path>    Base path for links (default: /api)
+  --verbose             Verbose output
+```
+
+### `build`
+
+Build standalone HTML documentation site.
+
+```bash
+openpkg-docs build <spec> [options]
+
+Options:
+  -o, --out <dir>       Output directory (default: ./docs)
+  --title <title>       Site title
+  --search              Enable search index generation
+  --verbose             Verbose output
+```
+
+### `dev`
+
+Start development server with hot reload.
+
+```bash
+openpkg-docs dev <spec> [options]
+
+Options:
+  -p, --port <port>     Port number (default: 3000)
+  --open                Open browser automatically
+```
+
+## Framework Integration
+
+### Fumadocs
+
+```ts
+import { toFumadocsMetaJSON } from '@openpkg-ts/doc-generator'
+
+const meta = toFumadocsMetaJSON(spec, { groupBy: 'kind' })
+fs.writeFileSync('docs/api/meta.json', meta)
+```
+
+### Docusaurus
+
+```ts
+import { toDocusaurusSidebarJS } from '@openpkg-ts/doc-generator'
+
+const sidebar = toDocusaurusSidebarJS(spec, { basePath: 'api' })
+fs.writeFileSync('sidebars.js', sidebar)
+```
+
+## Search Integration
+
+### Pagefind
+
+```ts
+import { toPagefindRecords } from '@openpkg-ts/doc-generator'
+
+const records = toPagefindRecords(spec, {
+  baseUrl: '/docs/api',
+  weights: { name: 10, description: 5 },
+})
+```
+
+### Algolia
+
+```ts
+import { toAlgoliaRecords } from '@openpkg-ts/doc-generator'
+
+const records = toAlgoliaRecords(spec, { baseUrl: '/api' })
+// Upload to Algolia index
+```
+
+## Migrating from TypeDoc
+
+1. Generate OpenPkg spec using `@openpkg-ts/extract` or `@doccov/sdk`
+2. Replace TypeDoc config with doc-generator CLI or API
+3. Use React components for custom rendering
+
+| TypeDoc | doc-generator |
+|---------|---------------|
+| `typedoc.json` | `openpkg.json` (spec) |
+| `--out ./docs` | `--out ./docs` |
+| `--theme minimal` | `toHTML()` or React components |
+| Plugin system | Framework adapters |
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,389 @@
+#!/usr/bin/env node
+import {
+  createDocs,
+  exportToMarkdown,
+  toDocusaurusSidebarJS,
+  toFumadocsMetaJSON,
+  toHTML,
+  toJSONString,
+  toNavigation,
+  toPagefindRecords
+} from "./shared/chunk-7hg53zpt.js";
+import {
+  __require,
+  __toESM
+} from "./shared/chunk-taeg9090.js";
+
+// src/cli.ts
+import { readFileSync } from "node:fs";
+import * as path4 from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+
+// src/cli/build.ts
+import { exec } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { promisify } from "node:util";
+var execAsync = promisify(exec);
+function registerBuildCommand(program) {
+  program.command("build <spec>").description("Build static HTML documentation site").option("-o, --out <dir>", "Output directory", "./api-docs").option("-t, --title <title>", "Site title override").option("--no-search", "Disable Pagefind search indexing").option("--verbose", "Verbose output").action(async (specPath, options) => {
+    try {
+      const resolvedSpec = path.resolve(specPath);
+      if (!fs.existsSync(resolvedSpec)) {
+        console.error(`Error: Spec file not found: ${resolvedSpec}`);
+        process.exit(1);
+      }
+      const docs = createDocs(resolvedSpec);
+      const outDir = path.resolve(options.out);
+      const exports = docs.getAllExports();
+      if (options.verbose) {
+        console.log(`Spec: ${resolvedSpec}`);
+        console.log(`Output: ${outDir}`);
+        console.log(`Exports: ${exports.length}`);
+      }
+      fs.mkdirSync(outDir, { recursive: true });
+      console.log("Generating HTML...");
+      const indexHtml = toHTML(docs.spec, {
+        title: options.title,
+        includeStyles: true,
+        fullDocument: true
+      });
+      fs.writeFileSync(path.join(outDir, "index.html"), indexHtml);
+      const pagesDir = path.join(outDir, "api");
+      fs.mkdirSync(pagesDir, { recursive: true });
+      for (const exp of exports) {
+        const exportHtml = toHTML(docs.spec, {
+          export: exp.name,
+          title: options.title ? `${exp.name} | ${options.title}` : undefined,
+          includeStyles: true,
+          fullDocument: true,
+          headContent: `<link rel="canonical" href="./api/${slugify(exp.name)}.html">`
+        });
+        const filename = `${slugify(exp.name)}.html`;
+        fs.writeFileSync(path.join(pagesDir, filename), exportHtml);
+        if (options.verbose) {
+          console.log(`  api/${filename}`);
+        }
+      }
+      console.log(`Generated ${exports.length + 1} HTML files`);
+      if (options.search !== false) {
+        console.log("Building search index...");
+        try {
+          await execAsync(`npx pagefind --site ${outDir} --output-subdir _pagefind`, {
+            cwd: process.cwd()
+          });
+          console.log("Search index created");
+        } catch (err) {
+          if (options.verbose) {
+            console.log("Pagefind not available, generating search.json fallback");
+          }
+          const records = toPagefindRecords(docs.spec, {
+            baseUrl: "/api"
+          });
+          fs.writeFileSync(path.join(outDir, "search.json"), JSON.stringify(records, null, 2));
+          console.log("Generated search.json fallback");
+        }
+      }
+      console.log(`
+Build complete: ${outDir}`);
+      console.log(`
+To serve locally:`);
+      console.log(`  npx serve ${outDir}`);
+    } catch (err) {
+      console.error("Error:", err instanceof Error ? err.message : err);
+      process.exit(1);
+    }
+  });
+}
+function slugify(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+}
+
+// src/cli/dev.ts
+import * as fs2 from "node:fs";
+import * as http from "node:http";
+import * as path2 from "node:path";
+function registerDevCommand(program) {
+  program.command("dev <spec>").description("Start dev server with hot reload").option("-p, --port <port>", "Port to serve on", "3001").option("-h, --host <host>", "Host to bind to", "localhost").option("--open", "Open browser on start").option("--verbose", "Verbose output").action(async (specPath, options) => {
+    try {
+      const resolvedSpec = path2.resolve(specPath);
+      if (!fs2.existsSync(resolvedSpec)) {
+        console.error(`Error: Spec file not found: ${resolvedSpec}`);
+        process.exit(1);
+      }
+      const port = Number.parseInt(options.port, 10);
+      const host = options.host ?? "localhost";
+      let docs = createDocs(resolvedSpec);
+      let lastMtime = fs2.statSync(resolvedSpec).mtimeMs;
+      console.log(`
+Starting dev server...`);
+      console.log(`  Spec: ${resolvedSpec}`);
+      console.log(`  Exports: ${docs.getAllExports().length}`);
+      const watcher = fs2.watch(resolvedSpec, (eventType) => {
+        if (eventType === "change") {
+          const currentMtime = fs2.statSync(resolvedSpec).mtimeMs;
+          if (currentMtime !== lastMtime) {
+            lastMtime = currentMtime;
+            try {
+              docs = createDocs(resolvedSpec);
+              console.log(`
+[${new Date().toLocaleTimeString()}] Spec reloaded (${docs.getAllExports().length} exports)`);
+            } catch (err) {
+              console.error(`
+[${new Date().toLocaleTimeString()}] Error reloading spec:`, err instanceof Error ? err.message : err);
+            }
+          }
+        }
+      });
+      const server = http.createServer((req, res) => {
+        const url = new URL(req.url || "/", `http://${host}:${port}`);
+        const pathname = url.pathname;
+        if (options.verbose) {
+          console.log(`${req.method} ${pathname}`);
+        }
+        try {
+          if (pathname.startsWith("/api/")) {
+            const exportName = pathname.replace("/api/", "").replace(".html", "").replace(/-/g, "");
+            const exp = findExport(docs, exportName);
+            if (exp) {
+              const html = toHTML(docs.spec, {
+                export: exp.name,
+                includeStyles: true,
+                fullDocument: true,
+                headContent: hotReloadScript(port)
+              });
+              res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+              res.end(html);
+              return;
+            }
+          }
+          if (pathname === "/" || pathname === "/index.html") {
+            const html = toHTML(docs.spec, {
+              includeStyles: true,
+              fullDocument: true,
+              headContent: hotReloadScript(port)
+            });
+            res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            res.end(html);
+            return;
+          }
+          if (pathname === "/__reload") {
+            res.writeHead(200, {
+              "Content-Type": "text/event-stream",
+              "Cache-Control": "no-cache",
+              Connection: "keep-alive"
+            });
+            const interval = setInterval(() => {
+              res.write(`data: ping
+
+`);
+            }, 2000);
+            const reloadWatcher = fs2.watch(resolvedSpec, () => {
+              res.write(`data: reload
+
+`);
+            });
+            req.on("close", () => {
+              clearInterval(interval);
+              reloadWatcher.close();
+            });
+            return;
+          }
+          res.writeHead(404, { "Content-Type": "text/html" });
+          res.end("<h1>404 Not Found</h1>");
+        } catch (err) {
+          console.error("Server error:", err);
+          res.writeHead(500, { "Content-Type": "text/html" });
+          res.end(`<h1>500 Server Error</h1><pre>${err instanceof Error ? err.message : err}</pre>`);
+        }
+      });
+      server.listen(port, host, () => {
+        console.log(`
+  Local:   http://${host}:${port}/`);
+        console.log(`
+  Watching for spec changes...`);
+        console.log(`  Press Ctrl+C to stop
+`);
+        if (options.open) {
+          const openCmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+          import("node:child_process").then(({ exec: exec2 }) => {
+            exec2(`${openCmd} http://${host}:${port}/`);
+          });
+        }
+      });
+      process.on("SIGINT", () => {
+        console.log(`
+
+Shutting down...`);
+        watcher.close();
+        server.close();
+        process.exit(0);
+      });
+    } catch (err) {
+      console.error("Error:", err instanceof Error ? err.message : err);
+      process.exit(1);
+    }
+  });
+}
+function findExport(docs, searchName) {
+  const lowerSearch = searchName.toLowerCase();
+  return docs.getAllExports().find((exp) => {
+    const lowerName = exp.name.toLowerCase().replace(/[^a-z0-9]/g, "");
+    return lowerName === lowerSearch || exp.id === searchName;
+  });
+}
+function hotReloadScript(port) {
+  return `
+<script>
+(function() {
+  const source = new EventSource('http://localhost:${port}/__reload');
+  source.onmessage = function(e) {
+    if (e.data === 'reload') {
+      window.location.reload();
+    }
+  };
+  source.onerror = function() {
+    source.close();
+    setTimeout(() => window.location.reload(), 1000);
+  };
+})();
+</script>`;
+}
+
+// src/cli/generate.ts
+import * as fs3 from "node:fs";
+import * as path3 from "node:path";
+function slugify2(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+}
+function registerGenerateCommand(program) {
+  program.command("generate <spec>").description("Generate MDX or JSON files from OpenPkg spec").option("-o, --out <dir>", "Output directory", "./api-docs").option("-f, --format <format>", "Output format: mdx or json", "mdx").option("--nav <format>", "Navigation format: fumadocs, docusaurus, generic").option("--flat", "Flat file structure (no grouping folders)").option("--group-by <groupBy>", "Group by: kind, module, tag, none", "kind").option("--base-path <path>", "Base path for navigation links", "/api").option("--verbose", "Verbose output").action(async (specPath, options) => {
+    try {
+      const resolvedSpec = path3.resolve(specPath);
+      if (!fs3.existsSync(resolvedSpec)) {
+        console.error(`Error: Spec file not found: ${resolvedSpec}`);
+        process.exit(1);
+      }
+      const docs = createDocs(resolvedSpec);
+      const exports = docs.getAllExports();
+      const outDir = path3.resolve(options.out);
+      if (options.verbose) {
+        console.log(`Spec: ${resolvedSpec}`);
+        console.log(`Output: ${outDir}`);
+        console.log(`Format: ${options.format}`);
+        console.log(`Exports: ${exports.length}`);
+      }
+      fs3.mkdirSync(outDir, { recursive: true });
+      if (options.format === "json") {
+        const jsonContent = toJSONString(docs.spec, { pretty: true });
+        const jsonPath = path3.join(outDir, "api.json");
+        fs3.writeFileSync(jsonPath, jsonContent);
+        console.log(`Generated ${jsonPath}`);
+      } else {
+        const groupBy = options.groupBy ?? "kind";
+        const isFlat = options.flat ?? false;
+        const groups = new Map;
+        for (const exp of exports) {
+          let groupKey;
+          if (isFlat || groupBy === "none") {
+            groupKey = "";
+          } else if (groupBy === "kind") {
+            groupKey = `${exp.kind}s`;
+          } else if (groupBy === "module") {
+            groupKey = extractModule(exp.source?.file) || "core";
+          } else if (groupBy === "tag") {
+            const categoryTag = exp.tags?.find((t) => t.name === "category" || t.name === "@category");
+            groupKey = categoryTag?.text || "other";
+          } else {
+            groupKey = "";
+          }
+          const existing = groups.get(groupKey) ?? [];
+          existing.push(exp);
+          groups.set(groupKey, existing);
+        }
+        let fileCount = 0;
+        for (const [group, groupExports] of groups) {
+          const groupDir = group ? path3.join(outDir, slugify2(group)) : outDir;
+          if (group) {
+            fs3.mkdirSync(groupDir, { recursive: true });
+          }
+          for (const exp of groupExports) {
+            const mdx = exportToMarkdown(exp, {
+              frontmatter: true,
+              codeSignatures: true
+            });
+            const filename = `${slugify2(exp.name)}.mdx`;
+            const filePath = path3.join(groupDir, filename);
+            fs3.writeFileSync(filePath, mdx);
+            fileCount++;
+            if (options.verbose) {
+              console.log(`  ${group ? `${group}/` : ""}${filename}`);
+            }
+          }
+        }
+        console.log(`Generated ${fileCount} MDX files in ${outDir}`);
+      }
+      if (options.nav) {
+        const basePath = options.basePath ?? "/api";
+        const navOptions = {
+          format: options.nav,
+          groupBy: options.groupBy ?? "kind",
+          basePath
+        };
+        let navContent;
+        let navFilename;
+        switch (options.nav) {
+          case "fumadocs":
+            navContent = toFumadocsMetaJSON(docs.spec, navOptions);
+            navFilename = "meta.json";
+            break;
+          case "docusaurus":
+            navContent = toDocusaurusSidebarJS(docs.spec, navOptions);
+            navFilename = "sidebars.js";
+            break;
+          default:
+            navContent = JSON.stringify(toNavigation(docs.spec, navOptions), null, 2);
+            navFilename = "nav.json";
+            break;
+        }
+        const navPath = path3.join(outDir, navFilename);
+        fs3.writeFileSync(navPath, navContent);
+        console.log(`Generated ${navPath}`);
+      }
+    } catch (err) {
+      console.error("Error:", err instanceof Error ? err.message : err);
+      process.exit(1);
+    }
+  });
+}
+function extractModule(filePath) {
+  if (!filePath)
+    return;
+  const parts = filePath.split("/");
+  const lastPart = parts[parts.length - 1];
+  if (lastPart === "index.ts" || lastPart === "index.tsx") {
+    return parts[parts.length - 2];
+  }
+  return lastPart.replace(/\.[jt]sx?$/, "");
+}
+
+// src/cli.ts
+var __filename2 = fileURLToPath(import.meta.url);
+var __dirname2 = path4.dirname(__filename2);
+var version = "0.0.1";
+try {
+  const packageJson = JSON.parse(readFileSync(path4.join(__dirname2, "../package.json"), "utf-8"));
+  version = packageJson.version;
+} catch {}
+var program = new Command;
+program.name("openpkg-docs").description("Generate API documentation from OpenPkg specs").version(version).option("-c, --config <path>", "Config file path").option("-v, --verbose", "Verbose output");
+registerBuildCommand(program);
+registerGenerateCommand(program);
+registerDevCommand(program);
+program.command("*", { hidden: true }).action(() => {
+  program.outputHelp();
+});
+program.parseAsync().catch(() => {
+  process.exit(1);
+});