@commercetools/nimbus-docs-build 0.0.0-canary-20251107124701

package/README.md

@@ -0,0 +1,129 @@
+# @commercetools/nimbus-docs-build
+
+Documentation build system for the Nimbus design system. This package handles:
+
+- **MDX Parsing**: Extracts frontmatter, generates table of contents, supports multi-view documentation
+- **TypeScript Type Extraction**: Parses component props using react-docgen-typescript
+- **Route Generation**: Creates route manifests for documentation navigation
+- **Search Index**: Generates searchable documentation index
+- **Build Caching**: Incremental builds with file hashing
+- **Content Validation**: Validates documentation structure and content
+- **Asset Optimization**: Optimizes images and static assets
+- **SEO Generation**: Creates robots.txt and sitemap.xml
+
+## Installation
+
+```bash
+pnpm add -D @commercetools/nimbus-docs-build
+```
+
+## Usage
+
+### Configuration
+
+Create a `docs-build.config.ts` file:
+
+```typescript
+import { defineConfig } from '@commercetools/nimbus-docs-build';
+
+export default defineConfig({
+  sources: {
+    packagesDir: './packages',
+    componentIndexPath: './packages/nimbus/src/index.ts',
+  },
+  output: {
+    routesDir: './src/data/routes',
+    manifestPath: './src/data/route-manifest.json',
+    searchIndexPath: './src/data/search-index.json',
+    typesDir: './public/generated/types',
+  },
+  cache: {
+    enabled: true,
+  },
+  seo: {
+    baseUrl: 'https://nimbus.commercetools.com',
+    generateRobots: true,
+    generateSitemap: true,
+  },
+});
+```
+
+### Programmatic API
+
+```typescript
+import { build } from '@commercetools/nimbus-docs-build';
+
+const result = await build({
+  sources: {
+    packagesDir: './packages',
+  },
+  output: {
+    routesDir: './dist/routes',
+    manifestPath: './dist/manifest.json',
+    searchIndexPath: './dist/search.json',
+    typesDir: './dist/types',
+  },
+});
+
+console.log(`Built ${result.routeCount} routes`);
+```
+
+### Individual Builders
+
+```typescript
+import {
+  parseMdx,
+  parseTypes,
+  generateRouteManifest,
+} from '@commercetools/nimbus-docs-build';
+
+// Parse a single MDX file
+const doc = await parseMdx('./path/to/file.mdx');
+
+// Extract TypeScript types
+await parseTypes({
+  componentIndexPath: './src/index.ts',
+  outputPath: './dist/types.json',
+});
+
+// Generate route manifest
+await generateRouteManifest(docs, './dist/manifest.json');
+```
+
+## Features
+
+### Multi-View Documentation
+
+Supports multiple views for a single documentation page:
+
+- `button.mdx` - Main documentation (overview)
+- `button.dev.mdx` - Developer-specific view
+- `button.api.mdx` - API reference view
+
+### Incremental Builds
+
+Uses file hashing to skip unchanged files, dramatically improving build times.
+
+### Content Validation
+
+Validates:
+- Required frontmatter fields
+- Menu structure
+- Content presence
+- Internal links
+
+### TypeScript Type Extraction
+
+Automatically extracts and filters component props:
+- Filters out HTML attributes
+- Filters out Chakra system props
+- Filters out React internals
+- Enriches with JSDoc metadata
+
+## Configuration Options
+
+See TypeScript definitions for complete configuration options.
+
+## License
+
+MIT

package/dist/assets/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Asset optimization exports
+ */
+export * from "./optimize-assets.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/assets/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/assets/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,sBAAsB,CAAC"}

package/dist/assets/index.js

@@ -0,0 +1,5 @@
+/**
+ * Asset optimization exports
+ */
+export * from "./optimize-assets.js";
+//# sourceMappingURL=index.js.map

package/dist/assets/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/assets/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,sBAAsB,CAAC"}

package/dist/assets/optimize-assets.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Copy and optimize images from packages to docs
+ */
+export declare function optimizeAssets(sourceDir: string, outputDir: string, imageExtensions?: string[]): Promise<void>;
+//# sourceMappingURL=optimize-assets.d.ts.map

package/dist/assets/optimize-assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimize-assets.d.ts","sourceRoot":"","sources":["../../src/assets/optimize-assets.ts"],"names":[],"mappings":"AAUA;;GAEG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,eAAe,GAAE,MAAM,EAAuD,GAC7E,OAAO,CAAC,IAAI,CAAC,CA2Bf"}

package/dist/assets/optimize-assets.js

@@ -0,0 +1,36 @@
+/**
+ * Asset Optimization
+ *
+ * Optimizes images and other static assets for documentation
+ */
+import fs from "fs/promises";
+import path from "path";
+import { findFilesByExtensions } from "../utils/file-utils.js";
+import { flog } from "../utils/logger.js";
+/**
+ * Copy and optimize images from packages to docs
+ */
+export async function optimizeAssets(sourceDir, outputDir, imageExtensions = [".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"]) {
+    try {
+        // Ensure output directory exists
+        await fs.mkdir(outputDir, { recursive: true });
+        // Find all image files
+        const images = await findFilesByExtensions(sourceDir, imageExtensions);
+        flog(`[Assets] Found ${images.length} images to process`);
+        // Copy images to output directory
+        for (const imagePath of images) {
+            const relativePath = path.relative(sourceDir, imagePath);
+            const outputPath = path.join(outputDir, relativePath);
+            // Ensure output directory exists
+            await fs.mkdir(path.dirname(outputPath), { recursive: true });
+            // Copy file
+            await fs.copyFile(imagePath, outputPath);
+        }
+        flog(`[Assets] Optimized ${images.length} assets`);
+    }
+    catch (error) {
+        console.error("Error optimizing assets:", error);
+        throw error;
+    }
+}
+//# sourceMappingURL=optimize-assets.js.map

package/dist/assets/optimize-assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimize-assets.js","sourceRoot":"","sources":["../../src/assets/optimize-assets.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,MAAM,aAAa,CAAC;AAC7B,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE1C;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,SAAiB,EACjB,SAAiB,EACjB,kBAA4B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC;IAE9E,IAAI,CAAC;QACH,iCAAiC;QACjC,MAAM,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAE/C,uBAAuB;QACvB,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;QAEvE,IAAI,CAAC,kBAAkB,MAAM,CAAC,MAAM,oBAAoB,CAAC,CAAC;QAE1D,kCAAkC;QAClC,KAAK,MAAM,SAAS,IAAI,MAAM,EAAE,CAAC;YAC/B,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;YACzD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;YAEtD,iCAAiC;YACjC,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAE9D,YAAY;YACZ,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;QAC3C,CAAC;QAED,IAAI,CAAC,sBAAsB,MAAM,CAAC,MAAM,SAAS,CAAC,CAAC;IACrD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,KAAK,CAAC,CAAC;QACjD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/builders/build.d.ts

@@ -0,0 +1,6 @@
+import type { DocsBuilderConfig, BuildResult } from "../types/config.js";
+/**
+ * Main build function
+ */
+export declare function build(config: DocsBuilderConfig): Promise<BuildResult>;
+//# sourceMappingURL=build.d.ts.map

package/dist/builders/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/builders/build.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGzE;;GAEG;AACH,wBAAsB,KAAK,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CA+E3E"}

package/dist/builders/build.js

@@ -0,0 +1,65 @@
+/**
+ * Main Documentation Build Orchestrator
+ *
+ * Coordinates the entire documentation build process with optional caching
+ */
+import { performance } from "perf_hooks";
+import { validateContent } from "../validation/validate-content.js";
+import { optimizeAssets } from "../assets/optimize-assets.js";
+import { buildMdx } from "./mdx-builder.js";
+import { buildTypes } from "./types-builder.js";
+import { buildManifest } from "./manifest-builder.js";
+import { buildSeo } from "./seo-builder.js";
+import { flog, successLog } from "../utils/logger.js";
+/**
+ * Main build function
+ */
+export async function build(config) {
+    const startTime = performance.now();
+    console.log("\n🚀 Starting documentation build...\n");
+    try {
+        // Step 1-2: Parse MDX files and write per-route JSON
+        const docs = await buildMdx(config.sources.packagesDir, config.output.routesDir);
+        // Step 3: Validate content
+        if (config.validation?.enabled !== false) {
+            flog("[3/6] Validating content...");
+            const errors = validateContent(docs);
+            const errorCount = errors.filter((e) => e.severity === "error").length;
+            if (errorCount > 0 && config.validation?.strict) {
+                throw new Error("Content validation failed");
+            }
+        }
+        // Step 4: Generate route manifest and search index
+        const manifest = await buildManifest(docs, config.output.manifestPath, config.output.searchIndexPath);
+        // Step 5: Parse TypeScript types
+        let componentCount = 0;
+        if (config.sources.componentIndexPath) {
+            componentCount = await buildTypes(config.sources.componentIndexPath, config.output.typesDir, config.propFilter);
+        }
+        // Step 6: Optimize assets
+        if (config.output.assetsDir && config.assets?.enabled !== false) {
+            flog("[6/6] Optimizing assets...");
+            await optimizeAssets(config.sources.packagesDir, config.output.assetsDir, config.assets?.imageExtensions);
+        }
+        // Optional: Generate SEO files
+        if (config.seo?.baseUrl) {
+            await buildSeo(manifest, config.seo.baseUrl, config.seo.generateRobots ? config.output.robotsPath : undefined, config.seo.generateSitemap ? config.output.sitemapPath : undefined);
+        }
+        const endTime = performance.now();
+        const duration = endTime - startTime;
+        successLog(`Documentation build completed in ${(duration / 1000).toFixed(2)}s ✨`);
+        return {
+            routeCount: docs.size,
+            componentCount,
+            duration,
+            cacheUsed: false,
+            filesRebuilt: docs.size,
+            filesCached: 0,
+        };
+    }
+    catch (error) {
+        console.error("\n❌ Build failed:", error);
+        throw error;
+    }
+}
+//# sourceMappingURL=build.js.map

package/dist/builders/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../src/builders/build.ts"],"names":[],"mappings":"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"}

package/dist/builders/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Builder exports
+ */
+export * from "./mdx-builder.js";
+export * from "./types-builder.js";
+export * from "./manifest-builder.js";
+export * from "./seo-builder.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/builders/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/builders/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC"}

package/dist/builders/index.js

@@ -0,0 +1,8 @@
+/**
+ * Builder exports
+ */
+export * from "./mdx-builder.js";
+export * from "./types-builder.js";
+export * from "./manifest-builder.js";
+export * from "./seo-builder.js";
+//# sourceMappingURL=index.js.map

package/dist/builders/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/builders/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC"}

package/dist/builders/manifest-builder.d.ts

@@ -0,0 +1,6 @@
+import type { MdxDocument, RouteManifest } from "../types/mdx.js";
+/**
+ * Build route manifest and search index
+ */
+export declare function buildManifest(docs: Map<string, MdxDocument>, manifestPath: string, searchIndexPath: string): Promise<RouteManifest>;
+//# sourceMappingURL=manifest-builder.d.ts.map

package/dist/builders/manifest-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-builder.d.ts","sourceRoot":"","sources":["../../src/builders/manifest-builder.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGlE;;GAEG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,EAC9B,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,aAAa,CAAC,CAQxB"}

package/dist/builders/manifest-builder.js

@@ -0,0 +1,19 @@
+/**
+ * Manifest Builder
+ *
+ * Generates route manifest and search index
+ */
+import { generateRouteManifest } from "../generators/routes.js";
+import { generateSearchIndex } from "../generators/search.js";
+import { flog } from "../utils/logger.js";
+/**
+ * Build route manifest and search index
+ */
+export async function buildManifest(docs, manifestPath, searchIndexPath) {
+    flog("[4/6] Generating route manifest...");
+    const manifest = await generateRouteManifest(docs, manifestPath);
+    flog("[4/6] Generating search index...");
+    await generateSearchIndex(docs, searchIndexPath);
+    return manifest;
+}
+//# sourceMappingURL=manifest-builder.js.map

package/dist/builders/manifest-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-builder.js","sourceRoot":"","sources":["../../src/builders/manifest-builder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE1C;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAA8B,EAC9B,YAAoB,EACpB,eAAuB;IAEvB,IAAI,CAAC,oCAAoC,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,MAAM,qBAAqB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAEjE,IAAI,CAAC,kCAAkC,CAAC,CAAC;IACzC,MAAM,mBAAmB,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IAEjD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/builders/mdx-builder.d.ts

@@ -0,0 +1,6 @@
+import type { MdxDocument } from "../types/mdx.js";
+/**
+ * Build MDX documentation
+ */
+export declare function buildMdx(packagesDir: string, routesOutputDir: string): Promise<Map<string, MdxDocument>>;
+//# sourceMappingURL=mdx-builder.d.ts.map

package/dist/builders/mdx-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mdx-builder.d.ts","sourceRoot":"","sources":["../../src/builders/mdx-builder.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA0BnD;;GAEG;AACH,wBAAsB,QAAQ,CAC5B,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAanC"}

package/dist/builders/mdx-builder.js

@@ -0,0 +1,40 @@
+/**
+ * MDX Builder
+ *
+ * Handles MDX file discovery, parsing, and per-route JSON generation
+ */
+import fs from "fs/promises";
+import { parseAllMdx } from "../parsers/parse-mdx.js";
+import { flog } from "../utils/logger.js";
+import { findFiles } from "../utils/file-utils.js";
+import { validateFilePath } from "../utils/validate-file-path.js";
+/**
+ * Write per-route JSON files for all documents
+ */
+async function writeRouteFiles(docs, outputDir) {
+    // Ensure output directory exists
+    await fs.mkdir(outputDir, { recursive: true });
+    // Write per-route JSON files
+    for (const [, doc] of docs) {
+        // Use route field (derived from menu path) for consistent filenames across the system
+        const routeId = doc.meta.route.replace(/\//g, "-");
+        const outputPath = validateFilePath(outputDir, `${routeId}.json`);
+        // Write per-route JSON
+        await fs.writeFile(outputPath, JSON.stringify(doc, null, 2));
+    }
+}
+/**
+ * Build MDX documentation
+ */
+export async function buildMdx(packagesDir, routesOutputDir) {
+    flog("[1/6] Finding MDX files...");
+    const mdxFiles = await findFiles(packagesDir, ".mdx");
+    flog(`Found ${mdxFiles.length} MDX files`);
+    flog("[2/6] Parsing MDX files...");
+    const docs = await parseAllMdx(mdxFiles);
+    flog(`[MDX] Parsed ${docs.size} documentation files`);
+    // Write per-route JSON files
+    await writeRouteFiles(docs, routesOutputDir);
+    return docs;
+}
+//# sourceMappingURL=mdx-builder.js.map

package/dist/builders/mdx-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mdx-builder.js","sourceRoot":"","sources":["../../src/builders/mdx-builder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,MAAM,aAAa,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAElE;;GAEG;AACH,KAAK,UAAU,eAAe,CAC5B,IAA8B,EAC9B,SAAiB;IAEjB,iCAAiC;IACjC,MAAM,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE/C,6BAA6B;IAC7B,KAAK,MAAM,CAAC,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;QAC3B,sFAAsF;QACtF,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACnD,MAAM,UAAU,GAAG,gBAAgB,CAAC,SAAS,EAAE,GAAG,OAAO,OAAO,CAAC,CAAC;QAElE,uBAAuB;QACvB,MAAM,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,WAAmB,EACnB,eAAuB;IAEvB,IAAI,CAAC,4BAA4B,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACtD,IAAI,CAAC,SAAS,QAAQ,CAAC,MAAM,YAAY,CAAC,CAAC;IAE3C,IAAI,CAAC,4BAA4B,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,CAAC,gBAAgB,IAAI,CAAC,IAAI,sBAAsB,CAAC,CAAC;IAEtD,6BAA6B;IAC7B,MAAM,eAAe,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IAE7C,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/builders/seo-builder.d.ts

@@ -0,0 +1,6 @@
+import type { RouteManifest } from "../types/mdx.js";
+/**
+ * Build SEO files
+ */
+export declare function buildSeo(manifest: RouteManifest, baseUrl: string, robotsPath?: string, sitemapPath?: string): Promise<void>;
+//# sourceMappingURL=seo-builder.d.ts.map

package/dist/builders/seo-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo-builder.d.ts","sourceRoot":"","sources":["../../src/builders/seo-builder.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;GAEG;AACH,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/builders/seo-builder.js

@@ -0,0 +1,19 @@
+/**
+ * SEO Builder
+ *
+ * Generates SEO files (robots.txt, sitemap.xml)
+ */
+import { generateRobots } from "../generators/robots.js";
+import { generateSitemap } from "../generators/sitemap.js";
+/**
+ * Build SEO files
+ */
+export async function buildSeo(manifest, baseUrl, robotsPath, sitemapPath) {
+    if (robotsPath) {
+        await generateRobots(baseUrl, robotsPath);
+    }
+    if (sitemapPath) {
+        await generateSitemap(manifest, baseUrl, sitemapPath);
+    }
+}
+//# sourceMappingURL=seo-builder.js.map

package/dist/builders/seo-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo-builder.js","sourceRoot":"","sources":["../../src/builders/seo-builder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAG3D;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,QAAuB,EACvB,OAAe,EACf,UAAmB,EACnB,WAAoB;IAEpB,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAC5C,CAAC;IAED,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,eAAe,CAAC,QAAQ,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;IACxD,CAAC;AACH,CAAC"}

package/dist/builders/types-builder.d.ts

@@ -0,0 +1,6 @@
+import type { DocsBuilderConfig } from "../types/config.js";
+/**
+ * Build TypeScript component types
+ */
+export declare function buildTypes(componentIndexPath: string, typesOutputDir: string, propFilter?: DocsBuilderConfig["propFilter"]): Promise<number>;
+//# sourceMappingURL=types-builder.d.ts.map

package/dist/builders/types-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-builder.d.ts","sourceRoot":"","sources":["../../src/builders/types-builder.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;GAEG;AACH,wBAAsB,UAAU,CAC9B,kBAAkB,EAAE,MAAM,EAC1B,cAAc,EAAE,MAAM,EACtB,UAAU,CAAC,EAAE,iBAAiB,CAAC,YAAY,CAAC,GAC3C,OAAO,CAAC,MAAM,CAAC,CAajB"}

package/dist/builders/types-builder.js

@@ -0,0 +1,18 @@
+/**
+ * Types Builder
+ *
+ * Handles TypeScript type extraction and generation
+ */
+import { parseTypesToFiles } from "../parsers/parse-types.js";
+import { flog } from "../utils/logger.js";
+/**
+ * Build TypeScript component types
+ */
+export async function buildTypes(componentIndexPath, typesOutputDir, propFilter) {
+    flog("[5/6] Parsing TypeScript types...");
+    const manifest = await parseTypesToFiles(componentIndexPath, typesOutputDir, propFilter);
+    const componentCount = Object.keys(manifest).length;
+    flog(`[TSX] Parsed ${componentCount} component types`);
+    return componentCount;
+}
+//# sourceMappingURL=types-builder.js.map

package/dist/builders/types-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-builder.js","sourceRoot":"","sources":["../../src/builders/types-builder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAG1C;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,kBAA0B,EAC1B,cAAsB,EACtB,UAA4C;IAE5C,IAAI,CAAC,mCAAmC,CAAC,CAAC;IAE1C,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CACtC,kBAAkB,EAClB,cAAc,EACd,UAAU,CACX,CAAC;IAEF,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC;IACpD,IAAI,CAAC,gBAAgB,cAAc,kBAAkB,CAAC,CAAC;IAEvD,OAAO,cAAc,CAAC;AACxB,CAAC"}

package/dist/cache/build-cache.d.ts

@@ -0,0 +1,41 @@
+import type { BuildCache } from "../types/config.js";
+/**
+ * Calculate file hash for cache validation
+ *
+ * @param filePath - Absolute path to file (should be pre-validated by caller)
+ * @note Callers must ensure filePath is validated to prevent path traversal
+ */
+export declare function calculateFileHash(filePath: string): Promise<string>;
+/**
+ * Load build cache from disk
+ */
+export declare function loadCache(cacheDir?: string): Promise<BuildCache>;
+/**
+ * Save build cache to disk
+ */
+export declare function saveCache(cache: BuildCache, cacheDir?: string): Promise<void>;
+/**
+ * Check if a file needs rebuilding
+ */
+export declare function needsRebuild(filePath: string, cache: BuildCache): Promise<boolean>;
+/**
+ * Update cache entry for a file
+ */
+export declare function updateCacheEntry(cache: BuildCache, filePath: string, hash: string, outputPath: string): void;
+/**
+ * Clear stale cache entries (files that no longer exist)
+ */
+export declare function cleanCache(cache: BuildCache, validFiles: string[]): Promise<void>;
+/**
+ * Get cache statistics
+ */
+export declare function getCacheStats(cache: BuildCache): {
+    totalFiles: number;
+    oldestEntry: number;
+    newestEntry: number;
+};
+/**
+ * Clear entire cache
+ */
+export declare function clearCache(cacheDir?: string): Promise<void>;
+//# sourceMappingURL=build-cache.d.ts.map

package/dist/cache/build-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-cache.d.ts","sourceRoot":"","sources":["../../src/cache/build-cache.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAgBrD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGzE;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAoBtE;AAED;;GAEG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,UAAU,EACjB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,OAAO,CAAC,CAsBlB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB,IAAI,CAMN;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB,CAcA;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQjE"}