@openpkg-ts/doc-generator 0.1.0

package/dist/shared/chunk-taeg9090.js

@@ -0,0 +1,171 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/core/query.ts
+function formatSchema(schema) {
+  if (!schema)
+    return "unknown";
+  if (typeof schema === "string")
+    return schema;
+  if (typeof schema === "object" && schema !== null) {
+    if ("$ref" in schema && typeof schema.$ref === "string") {
+      return schema.$ref.replace("#/types/", "");
+    }
+    if ("anyOf" in schema && Array.isArray(schema.anyOf)) {
+      return schema.anyOf.map((s) => formatSchema(s)).join(" | ");
+    }
+    if ("allOf" in schema && Array.isArray(schema.allOf)) {
+      return schema.allOf.map((s) => formatSchema(s)).join(" & ");
+    }
+    if ("type" in schema && schema.type === "array") {
+      const items = "items" in schema ? formatSchema(schema.items) : "unknown";
+      return `${items}[]`;
+    }
+    if ("type" in schema && schema.type === "tuple" && "items" in schema) {
+      const items = schema.items.map(formatSchema).join(", ");
+      return `[${items}]`;
+    }
+    if ("type" in schema && schema.type === "object") {
+      if ("properties" in schema && schema.properties) {
+        const props = Object.entries(schema.properties).map(([k, v]) => `${k}: ${formatSchema(v)}`).join("; ");
+        return `{ ${props} }`;
+      }
+      return "object";
+    }
+    if ("type" in schema && typeof schema.type === "string") {
+      return schema.type;
+    }
+  }
+  return "unknown";
+}
+function formatTypeParameters(typeParams) {
+  if (!typeParams?.length)
+    return "";
+  const params = typeParams.map((tp) => {
+    let str = tp.name;
+    if (tp.constraint)
+      str += ` extends ${tp.constraint}`;
+    if (tp.default)
+      str += ` = ${tp.default}`;
+    return str;
+  });
+  return `<${params.join(", ")}>`;
+}
+function formatParameters(sig) {
+  if (!sig?.parameters?.length)
+    return "()";
+  const params = sig.parameters.map((p) => {
+    const optional = p.required === false ? "?" : "";
+    const rest = p.rest ? "..." : "";
+    const type = formatSchema(p.schema);
+    return `${rest}${p.name}${optional}: ${type}`;
+  });
+  return `(${params.join(", ")})`;
+}
+function formatReturnType(sig) {
+  if (!sig?.returns)
+    return "void";
+  return formatSchema(sig.returns.schema);
+}
+function buildSignatureString(exp, sigIndex = 0) {
+  const sig = exp.signatures?.[sigIndex];
+  const typeParams = formatTypeParameters(exp.typeParameters || sig?.typeParameters);
+  switch (exp.kind) {
+    case "function": {
+      const params = formatParameters(sig);
+      const returnType = formatReturnType(sig);
+      return `function ${exp.name}${typeParams}${params}: ${returnType}`;
+    }
+    case "class": {
+      const ext = exp.extends ? ` extends ${exp.extends}` : "";
+      const impl = exp.implements?.length ? ` implements ${exp.implements.join(", ")}` : "";
+      return `class ${exp.name}${typeParams}${ext}${impl}`;
+    }
+    case "interface": {
+      const ext = exp.extends ? ` extends ${exp.extends}` : "";
+      return `interface ${exp.name}${typeParams}${ext}`;
+    }
+    case "type": {
+      const typeValue = typeof exp.type === "string" ? exp.type : formatSchema(exp.schema);
+      return `type ${exp.name}${typeParams} = ${typeValue}`;
+    }
+    case "enum": {
+      return `enum ${exp.name}`;
+    }
+    case "variable": {
+      const typeValue = typeof exp.type === "string" ? exp.type : formatSchema(exp.schema);
+      return `const ${exp.name}: ${typeValue}`;
+    }
+    default:
+      return exp.name;
+  }
+}
+function resolveTypeRef(ref, spec) {
+  const id = ref.replace("#/types/", "");
+  return spec.types?.find((t) => t.id === id);
+}
+function isMethod(member) {
+  return !!member.signatures?.length;
+}
+function isProperty(member) {
+  return !member.signatures?.length;
+}
+function getMethods(members) {
+  return members?.filter(isMethod) ?? [];
+}
+function getProperties(members) {
+  return members?.filter(isProperty) ?? [];
+}
+function groupByVisibility(members) {
+  const groups = {
+    public: [],
+    protected: [],
+    private: []
+  };
+  for (const member of members ?? []) {
+    const visibility = member.visibility ?? "public";
+    groups[visibility].push(member);
+  }
+  return groups;
+}
+function sortByName(items) {
+  return [...items].sort((a, b) => a.name.localeCompare(b.name));
+}
+function sortByKindThenName(exports) {
+  const kindOrder = {
+    function: 0,
+    class: 1,
+    interface: 2,
+    type: 3,
+    enum: 4,
+    variable: 5,
+    namespace: 6,
+    module: 7,
+    reference: 8,
+    external: 9
+  };
+  return [...exports].sort((a, b) => {
+    const kindDiff = kindOrder[a.kind] - kindOrder[b.kind];
+    if (kindDiff !== 0)
+      return kindDiff;
+    return a.name.localeCompare(b.name);
+  });
+}
+
+export { __toESM, __require, formatSchema, formatTypeParameters, formatParameters, formatReturnType, buildSignatureString, resolveTypeRef, isMethod, isProperty, getMethods, getProperties, groupByVisibility, sortByName, sortByKindThenName };

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@openpkg-ts/doc-generator",
+  "version": "0.1.0",
+  "description": "API doc generator consuming OpenPkg specs. TypeDoc alternative for modern doc frameworks.",
+  "keywords": [
+    "openpkg",
+    "documentation",
+    "api-docs",
+    "typescript",
+    "react"
+  ],
+  "homepage": "https://github.com/doccov/doccov#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doccov/doccov.git",
+    "directory": "packages/doc-generator"
+  },
+  "license": "MIT",
+  "author": "Ryan Waits",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./react": {
+      "import": "./dist/react.js",
+      "types": "./dist/react.d.ts"
+    },
+    "./react/styled": {
+      "import": "./dist/react-styled.js",
+      "types": "./dist/react-styled.d.ts"
+    },
+    "./cli": {
+      "import": "./dist/cli.js",
+      "types": "./dist/cli.d.ts"
+    }
+  },
+  "bin": {
+    "openpkg-docs": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "bunup",
+    "dev": "bunup --watch",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:watch": "bun test --watch"
+  },
+  "dependencies": {
+    "@openpkg-ts/spec": "workspace:*",
+    "commander": "^14.0.0"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19",
+    "tailwindcss": "^4"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "tailwindcss": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.0.0",
+    "bunup": "latest",
+    "react": "^19.0.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/embedded/README.md

@@ -0,0 +1,81 @@
+# Embedded API Docs Template
+
+This template shows how to integrate generated MDX files into existing documentation sites.
+
+## Usage
+
+Generate MDX files for your API:
+
+```bash
+npx openpkg-docs generate ./openpkg.json --format mdx --out ./docs/api --nav fumadocs
+```
+
+## Fumadocs Integration
+
+1. Copy generated files to `content/docs/api/`
+2. Use the generated `meta.json` for navigation
+3. Import and use components in your MDX
+
+```tsx
+// Example: content/docs/api/functions/use-state.mdx
+---
+title: useState
+description: React state hook
+---
+
+# useState
+
+\`function useState<T>(initial: T): [T, (value: T) => void]\`
+
+...
+```
+
+## Docusaurus Integration
+
+1. Copy generated files to `docs/api/`
+2. Use generated `sidebars.js` for navigation
+
+```js
+// sidebars.js
+const apiSidebar = require('./docs/api/sidebars.js');
+
+module.exports = {
+  docs: [
+    // ... your existing sidebar
+    {
+      type: 'category',
+      label: 'API Reference',
+      items: apiSidebar,
+    },
+  ],
+};
+```
+
+## File Structure
+
+After generation:
+
+```
+docs/api/
+├── meta.json          # Fumadocs navigation
+├── sidebars.js        # Docusaurus navigation
+├── functions/
+│   ├── use-state.mdx
+│   └── use-effect.mdx
+├── classes/
+│   └── store.mdx
+├── interfaces/
+│   └── options.mdx
+└── types/
+    └── config.mdx
+```
+
+## Customization
+
+Override frontmatter in generated files or use the JSON output for custom rendering:
+
+```bash
+npx openpkg-docs generate ./openpkg.json --format json --out ./api.json
+```
+
+Then build your own components using the JSON data.

package/templates/embedded/docusaurus/sidebars.js

@@ -0,0 +1,38 @@
+// Auto-generated sidebar configuration for Docusaurus
+// Usage: Import in your main sidebars.js and add to your sidebar config
+
+module.exports = [
+  {
+    type: 'category',
+    label: 'Functions',
+    items: [
+      { type: 'doc', id: 'api/use-state', label: 'useState' },
+      { type: 'doc', id: 'api/use-effect', label: 'useEffect' },
+      { type: 'doc', id: 'api/use-callback', label: 'useCallback' },
+    ],
+  },
+  {
+    type: 'category',
+    label: 'Classes',
+    items: [
+      { type: 'doc', id: 'api/store', label: 'Store' },
+      { type: 'doc', id: 'api/client', label: 'Client' },
+    ],
+  },
+  {
+    type: 'category',
+    label: 'Interfaces',
+    items: [
+      { type: 'doc', id: 'api/options', label: 'Options' },
+      { type: 'doc', id: 'api/config', label: 'Config' },
+    ],
+  },
+  {
+    type: 'category',
+    label: 'Types',
+    items: [
+      { type: 'doc', id: 'api/callback', label: 'Callback' },
+      { type: 'doc', id: 'api/handler', label: 'Handler' },
+    ],
+  },
+];

package/templates/embedded/fumadocs/meta.json

@@ -0,0 +1,26 @@
+{
+  "root": true,
+  "title": "API Reference",
+  "pages": [
+    {
+      "title": "Functions",
+      "pages": ["use-state", "use-effect", "use-callback"],
+      "defaultOpen": true
+    },
+    {
+      "title": "Classes",
+      "pages": ["store", "client"],
+      "defaultOpen": true
+    },
+    {
+      "title": "Interfaces",
+      "pages": ["options", "config"],
+      "defaultOpen": true
+    },
+    {
+      "title": "Types",
+      "pages": ["callback", "handler"],
+      "defaultOpen": true
+    }
+  ]
+}

package/templates/standalone/index.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>API Documentation</title>
+  <link rel="stylesheet" href="/src/styles.css">
+</head>
+<body class="bg-white dark:bg-zinc-900 text-zinc-900 dark:text-zinc-100">
+  <div id="app" class="max-w-4xl mx-auto px-6 py-12">
+    <header class="mb-12">
+      <h1 class="text-4xl font-bold mb-4">API Reference</h1>
+      <p class="text-zinc-600 dark:text-zinc-400">Documentation generated from OpenPkg spec</p>
+    </header>
+
+    <div id="search" class="mb-8">
+      <input
+        type="search"
+        id="search-input"
+        placeholder="Search documentation..."
+        class="w-full px-4 py-2 rounded-lg border border-zinc-200 dark:border-zinc-700 bg-white dark:bg-zinc-800 focus:outline-none focus:ring-2 focus:ring-blue-500"
+      >
+      <div id="search-results" class="mt-4"></div>
+    </div>
+
+    <main id="content">
+      <!-- API docs content will be injected here -->
+      <p class="text-zinc-500">Loading documentation...</p>
+    </main>
+  </div>
+
+  <script type="module" src="/src/main.ts"></script>
+</body>
+</html>

package/templates/standalone/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "api-docs",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "search": "pagefind --site dist"
+  },
+  "devDependencies": {
+    "vite": "^6.0.0",
+    "pagefind": "^1.3.0",
+    "@tailwindcss/vite": "^4.0.0",
+    "tailwindcss": "^4.0.0"
+  }
+}

package/templates/standalone/src/main.ts

@@ -0,0 +1,223 @@
+// Main entry for standalone API docs site
+// This is a template that gets customized during build
+
+async function init() {
+  const content = document.getElementById('content');
+
+  // Load API data
+  try {
+    const response = await fetch('/api.json');
+    if (!response.ok) throw new Error('Failed to load API data');
+
+    const spec = await response.json();
+    renderDocs(spec);
+  } catch (err) {
+    if (content) {
+      content.innerHTML = `<p class="text-red-500">Failed to load documentation: ${err}</p>`;
+    }
+  }
+
+  // Initialize Pagefind search if available
+  initSearch();
+}
+
+function renderDocs(spec: {
+  name: string;
+  description?: string;
+  exports: Array<{
+    id: string;
+    name: string;
+    kind: string;
+    signature: string;
+    description?: string;
+    deprecated?: boolean;
+    parameters?: Array<{
+      name: string;
+      type: string;
+      required: boolean;
+      description?: string;
+    }>;
+    returns?: {
+      type: string;
+      description?: string;
+    };
+    members?: Array<{
+      name: string;
+      kind: string;
+      type?: string;
+      description?: string;
+    }>;
+  }>;
+}) {
+  const content = document.getElementById('content');
+  if (!content) return;
+
+  // Group by kind
+  const byKind: Record<string, typeof spec.exports> = {};
+  for (const exp of spec.exports) {
+    if (!byKind[exp.kind]) byKind[exp.kind] = [];
+    byKind[exp.kind].push(exp);
+  }
+
+  const kindOrder = ['function', 'class', 'interface', 'type', 'enum', 'variable'];
+  const sections = kindOrder
+    .filter((kind) => byKind[kind]?.length)
+    .map((kind) => {
+      const exports = byKind[kind];
+      const cards = exports.map(renderExportCard).join('');
+      return `
+        <section class="kind-section">
+          <h2 class="text-2xl font-semibold mb-6 capitalize">${kind}s</h2>
+          ${cards}
+        </section>
+      `;
+    })
+    .join('');
+
+  content.innerHTML = sections;
+}
+
+function renderExportCard(exp: {
+  id: string;
+  name: string;
+  signature: string;
+  description?: string;
+  deprecated?: boolean;
+  parameters?: Array<{
+    name: string;
+    type: string;
+    required: boolean;
+    description?: string;
+  }>;
+  returns?: {
+    type: string;
+    description?: string;
+  };
+  members?: Array<{
+    name: string;
+    kind: string;
+    type?: string;
+    description?: string;
+  }>;
+}): string {
+  const deprecated = exp.deprecated
+    ? '<span class="text-orange-500 text-sm ml-2">[Deprecated]</span>'
+    : '';
+  const desc = exp.description
+    ? `<p class="mt-3 text-zinc-600 dark:text-zinc-400">${escapeHtml(exp.description)}</p>`
+    : '';
+
+  let details = '';
+
+  // Parameters
+  if (exp.parameters?.length) {
+    const rows = exp.parameters
+      .map(
+        (p) => `
+      <tr>
+        <td><code>${escapeHtml(p.name)}</code></td>
+        <td><code>${escapeHtml(p.type)}</code></td>
+        <td>${p.required ? 'Yes' : 'No'}</td>
+        <td>${p.description ? escapeHtml(p.description) : '-'}</td>
+      </tr>
+    `,
+      )
+      .join('');
+
+    details += `
+      <h4 class="font-medium mt-4 mb-2">Parameters</h4>
+      <table class="param-table">
+        <thead><tr><th>Name</th><th>Type</th><th>Required</th><th>Description</th></tr></thead>
+        <tbody>${rows}</tbody>
+      </table>
+    `;
+  }
+
+  // Returns
+  if (exp.returns) {
+    details += `
+      <h4 class="font-medium mt-4 mb-2">Returns</h4>
+      <p><code>${escapeHtml(exp.returns.type)}</code>${exp.returns.description ? ` - ${escapeHtml(exp.returns.description)}` : ''}</p>
+    `;
+  }
+
+  // Members
+  if (exp.members?.length) {
+    const items = exp.members
+      .map(
+        (m) => `
+      <li><code>${escapeHtml(m.name)}</code>${m.type ? `: <code>${escapeHtml(m.type)}</code>` : ''}${m.description ? ` - ${escapeHtml(m.description)}` : ''}</li>
+    `,
+      )
+      .join('');
+
+    details += `
+      <h4 class="font-medium mt-4 mb-2">Members</h4>
+      <ul class="list-disc list-inside space-y-1">${items}</ul>
+    `;
+  }
+
+  return `
+    <article class="export-card" id="${exp.id}">
+      <h3 class="text-lg font-semibold">${escapeHtml(exp.name)}${deprecated}</h3>
+      <pre class="signature"><code>${escapeHtml(exp.signature)}</code></pre>
+      ${desc}
+      ${details}
+    </article>
+  `;
+}
+
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+async function initSearch() {
+  const searchInput = document.getElementById('search-input') as HTMLInputElement | null;
+  const searchResults = document.getElementById('search-results');
+
+  if (!searchInput || !searchResults) return;
+
+  // Try to load Pagefind
+  try {
+    // @ts-ignore - Pagefind is loaded at runtime
+    const pagefind = await import('/_pagefind/pagefind.js');
+    await pagefind.init();
+
+    searchInput.addEventListener('input', async (e) => {
+      const query = (e.target as HTMLInputElement).value;
+      if (!query) {
+        searchResults.innerHTML = '';
+        return;
+      }
+
+      const search = await pagefind.search(query);
+      const results = await Promise.all(
+        search.results
+          .slice(0, 5)
+          .map((r: { data: () => Promise<{ url: string; title: string; excerpt: string }> }) =>
+            r.data(),
+          ),
+      );
+
+      searchResults.innerHTML = results
+        .map(
+          (r: { url: string; title: string; excerpt: string }) => `
+        <a href="${r.url}" class="block p-3 rounded hover:bg-zinc-100 dark:hover:bg-zinc-800">
+          <div class="font-medium">${r.title}</div>
+          <div class="text-sm text-zinc-500">${r.excerpt}</div>
+        </a>
+      `,
+        )
+        .join('');
+    });
+  } catch {
+    // Pagefind not available, fallback to JSON search
+    searchInput.placeholder = 'Search (JSON fallback)...';
+  }
+}
+
+init();