@forge-ts/gen 0.3.1 → 0.5.0

package/dist/index.d.ts

@@ -1,5 +1,272 @@
 import { ForgeSymbol, ForgeConfig, ForgeResult } from '@forge-ts/core';
 
+/**
+ * A single generated documentation page.
+ * @public
+ */
+interface DocPage {
+    /** Relative path from outDir (e.g., "packages/core/index.md") */
+    path: string;
+    /** Page content (Markdown or MDX) */
+    content: string;
+    /** Frontmatter fields */
+    frontmatter: Record<string, string | number | boolean>;
+}
+/**
+ * Options controlling the doc site generator.
+ * @public
+ */
+interface SiteGeneratorOptions {
+    /** Output format */
+    format: "markdown" | "mdx";
+    /** SSG target for frontmatter */
+    ssgTarget?: "docusaurus" | "mintlify" | "nextra" | "vitepress";
+    /** Project name */
+    projectName: string;
+    /** Project description */
+    projectDescription?: string;
+}
+/**
+ * Groups symbols by their package based on file path.
+ *
+ * For monorepos (symbols under `packages/<name>/`) the package name is
+ * derived from the directory segment immediately after `packages/`.
+ * For non-monorepo projects all symbols fall under the project name.
+ *
+ * @param symbols - All extracted symbols.
+ * @param rootDir - Absolute path to the project root.
+ * @returns A map from package name to symbol list.
+ * @example
+ * ```typescript
+ * import { groupSymbolsByPackage } from "@forge-ts/gen";
+ * const grouped = groupSymbolsByPackage(symbols, "/path/to/project");
+ * console.log(grouped.has("core")); // true for monorepo
+ * ```
+ * @public
+ */
+declare function groupSymbolsByPackage(symbols: ForgeSymbol[], rootDir: string): Map<string, ForgeSymbol[]>;
+/**
+ * Generates a full multi-page documentation site from symbols grouped by package.
+ *
+ * Produces an index page, a getting-started page, and per-package pages for
+ * the API reference, types, functions, and examples.
+ *
+ * @param symbolsByPackage - Symbols grouped by package name.
+ * @param config - The resolved {@link ForgeConfig}.
+ * @param options - Site generation options.
+ * @returns An array of {@link DocPage} objects ready to be written to disk.
+ * @example
+ * ```typescript
+ * import { generateDocSite, groupSymbolsByPackage } from "@forge-ts/gen";
+ * const grouped = groupSymbolsByPackage(symbols, config.rootDir);
+ * const pages = generateDocSite(grouped, config, { format: "markdown", projectName: "my-project" });
+ * console.log(pages.length > 0); // true
+ * ```
+ * @public
+ */
+declare function generateDocSite(symbolsByPackage: Map<string, ForgeSymbol[]>, config: ForgeConfig, options: SiteGeneratorOptions): DocPage[];
+
+/**
+ * Supported SSG target identifiers.
+ * @public
+ */
+type SSGTarget = "mintlify" | "docusaurus" | "nextra" | "vitepress";
+/**
+ * A file to write to disk during scaffolding or generation.
+ * @public
+ */
+interface GeneratedFile {
+    /** Relative path from the docs output directory. */
+    path: string;
+    /** File content (string for text). */
+    content: string;
+}
+/**
+ * Style guide configuration for the SSG target.
+ * @public
+ */
+interface SSGStyleGuide {
+    /** File extension for doc pages. */
+    pageExtension: "md" | "mdx";
+    /** Whether the target supports MDX components. */
+    supportsMdx: boolean;
+    /** Whether frontmatter is required on every page. */
+    requiresFrontmatter: boolean;
+    /** Maximum recommended heading depth. */
+    maxHeadingDepth: number;
+    /** Component imports to add at top of MDX files (if supportsMdx). */
+    defaultImports: string[];
+    /** Code block language for TypeScript examples. */
+    codeBlockLanguage: "typescript" | "ts" | "tsx";
+}
+/**
+ * Scaffold manifest describing what `init docs` creates.
+ * @public
+ */
+interface ScaffoldManifest {
+    /** The SSG target this manifest is for. */
+    target: SSGTarget;
+    /** Files that will be created. */
+    files: GeneratedFile[];
+    /** npm dependencies to install. */
+    dependencies: Record<string, string>;
+    /** npm devDependencies to install. */
+    devDependencies: Record<string, string>;
+    /** Scripts to add to package.json. */
+    scripts: Record<string, string>;
+    /** Post-scaffold instructions for the user. */
+    instructions: string[];
+}
+/**
+ * Context passed to adapter methods.
+ * @public
+ */
+interface AdapterContext {
+    /** Resolved forge-ts configuration. */
+    config: ForgeConfig;
+    /** Project name (from package.json or directory). */
+    projectName: string;
+    /** Project description. */
+    projectDescription?: string;
+    /** The generated doc pages (from site-generator). */
+    pages: DocPage[];
+    /** All symbols extracted from the project. */
+    symbols: ForgeSymbol[];
+    /** Output directory for generated docs. */
+    outDir: string;
+}
+/**
+ * The central SSG adapter interface.
+ * Every doc platform provider implements this contract.
+ * One file per provider. No shared mutable state.
+ *
+ * @example
+ * ```typescript
+ * import { getAdapter } from "@forge-ts/gen";
+ * const adapter = getAdapter("mintlify");
+ * const files = adapter.transformPages(pages, context);
+ * ```
+ * @public
+ */
+interface SSGAdapter {
+    /** Unique target identifier. */
+    readonly target: SSGTarget;
+    /** Human-readable display name. */
+    readonly displayName: string;
+    /** Style guide for this platform. */
+    readonly styleGuide: SSGStyleGuide;
+    /**
+     * Generate the complete scaffold for a new doc site.
+     * Called by `forge-ts init docs --target <name>`.
+     * Returns all files, dependencies, and scripts needed.
+     *
+     * @param context - The adapter context for the current project.
+     * @returns A {@link ScaffoldManifest} with files, deps, and instructions.
+     * @example
+     * ```typescript
+     * import { getAdapter } from "@forge-ts/gen";
+     * const adapter = getAdapter("mintlify");
+     * const manifest = adapter.scaffold(context);
+     * console.log(manifest.files.length);
+     * ```
+     */
+    scaffold(context: AdapterContext): ScaffoldManifest;
+    /**
+     * Transform generic DocPages into platform-specific pages.
+     * Adds correct frontmatter, component imports, file extensions.
+     * Called during `forge-ts build`.
+     *
+     * @param pages - The generic doc pages to transform.
+     * @param context - The adapter context for the current project.
+     * @returns An array of {@link GeneratedFile} objects ready to write.
+     * @example
+     * ```typescript
+     * import { getAdapter } from "@forge-ts/gen";
+     * const adapter = getAdapter("docusaurus");
+     * const files = adapter.transformPages(pages, context);
+     * console.log(files[0].path.endsWith(".mdx")); // true
+     * ```
+     */
+    transformPages(pages: DocPage[], context: AdapterContext): GeneratedFile[];
+    /**
+     * Generate platform-specific configuration files.
+     * e.g., mint.json, sidebars.js, _meta.json, .vitepress/config.ts
+     * Called during `forge-ts build`.
+     *
+     * @param context - The adapter context for the current project.
+     * @returns An array of {@link GeneratedFile} objects ready to write.
+     * @example
+     * ```typescript
+     * import { getAdapter } from "@forge-ts/gen";
+     * const adapter = getAdapter("vitepress");
+     * const configs = adapter.generateConfig(context);
+     * console.log(configs[0].path); // ".vitepress/sidebar.json"
+     * ```
+     */
+    generateConfig(context: AdapterContext): GeneratedFile[];
+    /**
+     * Check if a scaffold already exists in the output directory.
+     * Used for safety checks before init or target change.
+     *
+     * @param outDir - The output directory to inspect.
+     * @returns `true` if a scaffold marker file already exists.
+     * @example
+     * ```typescript
+     * import { getAdapter } from "@forge-ts/gen";
+     * const adapter = getAdapter("mintlify");
+     * const exists = await adapter.detectExisting("./docs");
+     * if (exists) console.log("Scaffold already present");
+     * ```
+     */
+    detectExisting(outDir: string): Promise<boolean>;
+}
+
+/**
+ * Register an SSG adapter.
+ * Called once per provider at module load time.
+ *
+ * @param adapter - The adapter to register.
+ * @example
+ * ```typescript
+ * import { registerAdapter } from "@forge-ts/gen";
+ * registerAdapter(mintlifyAdapter);
+ * ```
+ * @public
+ */
+declare function registerAdapter(adapter: SSGAdapter): void;
+/**
+ * Get a registered adapter by target name.
+ * Throws if the target is not registered.
+ *
+ * @param target - The SSG target identifier.
+ * @returns The registered {@link SSGAdapter} for the given target.
+ * @throws `Error` if the target is not registered.
+ * @example
+ * ```typescript
+ * import { getAdapter } from "@forge-ts/gen";
+ * const adapter = getAdapter("mintlify");
+ * ```
+ * @public
+ */
+declare function getAdapter(target: SSGTarget): SSGAdapter;
+/**
+ * Get all registered adapter targets.
+ *
+ * @returns An array of all registered {@link SSGTarget} identifiers.
+ * @example
+ * ```typescript
+ * import { getAvailableTargets } from "@forge-ts/gen";
+ * const targets = getAvailableTargets(); // ["mintlify", "docusaurus", ...]
+ * ```
+ * @public
+ */
+declare function getAvailableTargets(): SSGTarget[];
+/**
+ * The default SSG target when none is specified.
+ * @public
+ */
+declare const DEFAULT_TARGET: SSGTarget;
+
 /**
  * Generates an `llms.txt` routing manifest from the extracted symbols.
  *
@@ -90,72 +357,6 @@ interface ReadmeSyncOptions {
  */
 declare function syncReadme(readmePath: string, symbols: ForgeSymbol[], options?: ReadmeSyncOptions): Promise<boolean>;
 
-/**
- * A single generated documentation page.
- * @public
- */
-interface DocPage {
-    /** Relative path from outDir (e.g., "packages/core/index.md") */
-    path: string;
-    /** Page content (Markdown or MDX) */
-    content: string;
-    /** Frontmatter fields */
-    frontmatter: Record<string, string | number | boolean>;
-}
-/**
- * Options controlling the doc site generator.
- * @public
- */
-interface SiteGeneratorOptions {
-    /** Output format */
-    format: "markdown" | "mdx";
-    /** SSG target for frontmatter */
-    ssgTarget?: "docusaurus" | "mintlify" | "nextra" | "vitepress";
-    /** Project name */
-    projectName: string;
-    /** Project description */
-    projectDescription?: string;
-}
-/**
- * Groups symbols by their package based on file path.
- *
- * For monorepos (symbols under `packages/<name>/`) the package name is
- * derived from the directory segment immediately after `packages/`.
- * For non-monorepo projects all symbols fall under the project name.
- *
- * @param symbols - All extracted symbols.
- * @param rootDir - Absolute path to the project root.
- * @returns A map from package name to symbol list.
- * @example
- * ```typescript
- * import { groupSymbolsByPackage } from "@forge-ts/gen";
- * const grouped = groupSymbolsByPackage(symbols, "/path/to/project");
- * console.log(grouped.has("core")); // true for monorepo
- * ```
- * @public
- */
-declare function groupSymbolsByPackage(symbols: ForgeSymbol[], rootDir: string): Map<string, ForgeSymbol[]>;
-/**
- * Generates a full multi-page documentation site from symbols grouped by package.
- *
- * Produces an index page, a getting-started page, and per-package pages for
- * the API reference, types, functions, and examples.
- *
- * @param symbolsByPackage - Symbols grouped by package name.
- * @param config - The resolved {@link ForgeConfig}.
- * @param options - Site generation options.
- * @returns An array of {@link DocPage} objects ready to be written to disk.
- * @example
- * ```typescript
- * import { generateDocSite, groupSymbolsByPackage } from "@forge-ts/gen";
- * const grouped = groupSymbolsByPackage(symbols, config.rootDir);
- * const pages = generateDocSite(grouped, config, { format: "markdown", projectName: "my-project" });
- * console.log(pages.length > 0); // true
- * ```
- * @public
- */
-declare function generateDocSite(symbolsByPackage: Map<string, ForgeSymbol[]>, config: ForgeConfig, options: SiteGeneratorOptions): DocPage[];
-
 /**
  * A single generated SSG configuration file.
  * @public
@@ -212,4 +413,4 @@ declare function generateSSGConfigs(pages: DocPage[], target: "docusaurus" | "mi
  */
 declare function generate(config: ForgeConfig): Promise<ForgeResult>;
 
-export { type DocPage, type MarkdownOptions, type ReadmeSyncOptions, type SSGConfigFile, type SiteGeneratorOptions, generate, generateDocSite, generateLlmsFullTxt, generateLlmsTxt, generateMarkdown, generateSSGConfigs, groupSymbolsByPackage, syncReadme };
+export { type AdapterContext, DEFAULT_TARGET, type DocPage, type GeneratedFile, type MarkdownOptions, type ReadmeSyncOptions, type SSGAdapter, type SSGConfigFile, type SSGStyleGuide, type SSGTarget, type ScaffoldManifest, type SiteGeneratorOptions, generate, generateDocSite, generateLlmsFullTxt, generateLlmsTxt, generateMarkdown, generateSSGConfigs, getAdapter, getAvailableTargets, groupSymbolsByPackage, registerAdapter, syncReadme };