@libar-dev/architect 1.0.0-pre.3

package/dist/cli/dataset-cache.js

@@ -0,0 +1,179 @@
+/**
+ * @architect
+ * @architect-cli
+ * @architect-pattern DatasetCache
+ * @architect-status active
+ * @architect-implements DataAPICLIErgonomics
+ * @architect-arch-role infrastructure
+ * @architect-arch-context cli
+ * @architect-arch-layer infrastructure
+ * @architect-uses PipelineFactory, WorkflowConfigSchema
+ *
+ * ## Dataset Cache - MasterDataset Persistence with mtime Invalidation
+ *
+ * Caches the full PipelineResult (MasterDataset + ValidationSummary + warnings)
+ * to a JSON file. Subsequent CLI invocations skip the 2-5s pipeline rebuild
+ * when no source files have changed.
+ *
+ * ### Design Decisions
+ *
+ * - DD-1: Excludes LoadedWorkflow (contains Maps), reconstructs on load via createLoadedWorkflow()
+ * - DD-2: Cache at node_modules/.cache/architect/dataset.json
+ * - DD-3: Cache key = sha256(sorted file mtimes + pipeline options hash)
+ * - DD-4: All errors produce cache miss (never throw)
+ */
+import * as fs from 'fs';
+import * as fsp from 'fs/promises';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { glob } from 'glob';
+import { createLoadedWorkflow } from '../validation-schemas/workflow-config.js';
+/** Cache format version — bump when the serialization format changes. */
+const CACHE_VERSION = '1';
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Resolve the cache directory for a given base directory.
+ */
+export function getCacheDir(baseDir) {
+    return path.join(path.resolve(baseDir), 'node_modules', '.cache', 'architect');
+}
+/**
+ * Compute a cache key from pipeline options and source file mtimes.
+ *
+ * The key captures:
+ * - Sorted list of source files with their modification times
+ * - Pipeline options that affect output (input patterns, features, baseDir, workflowPath)
+ *
+ * Any change to source files or pipeline config produces a different key.
+ */
+export async function computeCacheKey(opts) {
+    const baseDir = path.resolve(opts.baseDir);
+    const hash = crypto.createHash('sha256');
+    // Hash pipeline options that affect dataset output
+    hash.update(JSON.stringify({
+        input: opts.input,
+        features: opts.features,
+        baseDir,
+        workflowPath: opts.workflowPath ?? null,
+        mergeConflictStrategy: opts.mergeConflictStrategy,
+        includeValidation: opts.includeValidation ?? true,
+    }));
+    // Resolve glob patterns to file lists and collect mtimes
+    const fileMtimes = [];
+    for (const pattern of [...opts.input, ...opts.features]) {
+        const files = await glob(pattern, { cwd: baseDir, absolute: true });
+        for (const file of files.sort()) {
+            try {
+                const stat = await fsp.stat(file);
+                fileMtimes.push(`${file}:${stat.mtimeMs}`);
+            }
+            catch {
+                // File disappeared between glob and stat — include as changed
+                fileMtimes.push(`${file}:missing`);
+            }
+        }
+    }
+    // Also include config file mtime if it exists (.ts or .js)
+    for (const configName of ['architect.config.ts', 'architect.config.js']) {
+        const configPath = path.join(baseDir, configName);
+        try {
+            const configStat = await fsp.stat(configPath);
+            fileMtimes.push(`${configPath}:${configStat.mtimeMs}`);
+        }
+        catch {
+            fileMtimes.push(`${configPath}:absent`);
+        }
+    }
+    hash.update(fileMtimes.join('\n'));
+    return hash.digest('hex');
+}
+/**
+ * Attempt to load a cached PipelineResult.
+ *
+ * Returns `undefined` on any error (corrupt cache, key mismatch, etc.).
+ * Never throws — the caller should fall back to running the full pipeline.
+ */
+export async function tryLoadCache(cacheKey, cacheDir) {
+    try {
+        const cachePath = path.join(cacheDir, 'dataset.json');
+        const raw = await fsp.readFile(cachePath, 'utf-8');
+        const cached = JSON.parse(raw);
+        // Validate cache version and key
+        if (cached.metadata.version !== CACHE_VERSION)
+            return undefined;
+        if (cached.metadata.key !== cacheKey)
+            return undefined;
+        // Reconstruct RuntimeMasterDataset from plain MasterDataset + WorkflowConfig
+        const dataset = cached.dataset;
+        if (cached.workflowConfig !== null) {
+            const workflow = createLoadedWorkflow(cached.workflowConfig);
+            // Assign workflow back onto the deserialized dataset (Maps are not JSON-serializable)
+            Object.assign(dataset, { workflow });
+        }
+        const ageMs = Date.now() - new Date(cached.metadata.timestamp).getTime();
+        return {
+            result: {
+                dataset,
+                validation: cached.validation,
+                warnings: cached.warnings,
+                scanMetadata: cached.scanMetadata,
+            },
+            ageMs,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Write a PipelineResult to the cache file.
+ *
+ * Strips the non-serializable `workflow` field and stores the `WorkflowConfig`
+ * separately for reconstruction on load. Uses atomic write (tmp + rename).
+ *
+ * Never throws — cache write failures are silently ignored.
+ */
+export async function writeCache(result, cacheKey, cacheDir) {
+    try {
+        await fsp.mkdir(cacheDir, { recursive: true });
+        // Extract WorkflowConfig (serializable) from LoadedWorkflow (has Maps)
+        const workflowConfig = result.dataset.workflow?.config ?? null;
+        // Strip the non-serializable workflow field from the dataset
+        const { workflow: _workflow, ...serializableDataset } = result.dataset;
+        const cacheData = {
+            metadata: {
+                key: cacheKey,
+                timestamp: new Date().toISOString(),
+                version: CACHE_VERSION,
+            },
+            dataset: serializableDataset,
+            workflowConfig,
+            validation: result.validation,
+            warnings: result.warnings,
+            scanMetadata: result.scanMetadata,
+        };
+        const cachePath = path.join(cacheDir, 'dataset.json');
+        const tmpPath = `${cachePath}.${process.pid}.${Date.now()}.tmp`;
+        await fsp.writeFile(tmpPath, JSON.stringify(cacheData), 'utf-8');
+        await fsp.rename(tmpPath, cachePath);
+    }
+    catch {
+        // Cache write failure is not fatal — next run will rebuild
+    }
+}
+/**
+ * Check whether a cache file exists (for dry-run reporting).
+ */
+export function cacheFileExists(cacheDir) {
+    try {
+        const cachePath = path.join(cacheDir, 'dataset.json');
+        const stat = fs.statSync(cachePath);
+        return { exists: true, sizeBytes: stat.size };
+    }
+    catch {
+        return { exists: false };
+    }
+}
+//# sourceMappingURL=dataset-cache.js.map

package/dist/cli/dataset-cache.js.map

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

package/dist/cli/error-handler.d.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * @architect
+ * @architect-cli
+ * @architect-pattern CLIErrorHandler
+ * @architect-status completed
+ * @architect-uses DocError
+ * @architect-used-by LintPatternsCLI, ValidatePatternsCLI, DocumentationGeneratorCLI
+ *
+ * ## CLIErrorHandler - Unified CLI Error Handling Utilities
+ *
+ * Provides type-safe error handling for all CLI commands using the
+ * DocError discriminated union pattern. Ensures structured error
+ * context is preserved and formatted consistently.
+ *
+ * ### When to Use
+ *
+ * - In catch blocks of CLI main functions
+ * - When formatting DocError for console output
+ * - When checking if an unknown error is a DocError
+ */
+import type { DocError } from '../types/errors.js';
+/**
+ * Type guard to check if an unknown value is a DocError
+ *
+ * Uses the discriminated union `type` property to identify DocError instances.
+ * All DocError variants have a `type` string property that uniquely identifies them.
+ *
+ * @param error - Unknown error value to check
+ * @returns True if the error is a DocError with recognized type
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await scanPatterns(config);
+ * } catch (error) {
+ *   if (isDocError(error)) {
+ *     // TypeScript knows error is DocError here
+ *     console.log(error.type, error.message);
+ *   }
+ * }
+ * ```
+ */
+export declare function isDocError(error: unknown): error is DocError;
+/**
+ * Format a DocError for console output with structured context
+ *
+ * Extracts file paths, line numbers, and validation errors from the
+ * DocError structure and formats them for human-readable output.
+ *
+ * @param error - DocError to format
+ * @returns Formatted error string with context
+ *
+ * @example
+ * ```typescript
+ * const error = createFileParseError('/path/to/file.ts', 'Syntax error', { line: 42 });
+ * console.error(formatDocError(error));
+ * // Output: "FILE_PARSE_ERROR: Failed to parse /path/to/file.ts at line 42: Syntax error"
+ * ```
+ */
+export declare function formatDocError(error: DocError): string;
+/**
+ * Unified CLI error handler that formats and exits
+ *
+ * Handles both DocError instances and generic Error/unknown values.
+ * Outputs structured error information and exits with specified code.
+ *
+ * @param error - Error to handle (DocError, Error, or unknown)
+ * @param exitCode - Process exit code (default: 1)
+ * @returns Never - always calls process.exit
+ *
+ * @example
+ * ```typescript
+ * async function main(): Promise<void> {
+ *   try {
+ *     await doWork();
+ *   } catch (error) {
+ *     handleCliError(error, 1);
+ *   }
+ * }
+ * ```
+ */
+export declare function handleCliError(error: unknown, exitCode?: number): never;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/cli/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../src/cli/error-handler.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CA6B5D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAqFtD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAI,GAAG,KAAK,CAgBlE"}

package/dist/cli/error-handler.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * @architect
+ * @architect-cli
+ * @architect-pattern CLIErrorHandler
+ * @architect-status completed
+ * @architect-uses DocError
+ * @architect-used-by LintPatternsCLI, ValidatePatternsCLI, DocumentationGeneratorCLI
+ *
+ * ## CLIErrorHandler - Unified CLI Error Handling Utilities
+ *
+ * Provides type-safe error handling for all CLI commands using the
+ * DocError discriminated union pattern. Ensures structured error
+ * context is preserved and formatted consistently.
+ *
+ * ### When to Use
+ *
+ * - In catch blocks of CLI main functions
+ * - When formatting DocError for console output
+ * - When checking if an unknown error is a DocError
+ */
+/**
+ * Type guard to check if an unknown value is a DocError
+ *
+ * Uses the discriminated union `type` property to identify DocError instances.
+ * All DocError variants have a `type` string property that uniquely identifies them.
+ *
+ * @param error - Unknown error value to check
+ * @returns True if the error is a DocError with recognized type
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await scanPatterns(config);
+ * } catch (error) {
+ *   if (isDocError(error)) {
+ *     // TypeScript knows error is DocError here
+ *     console.log(error.type, error.message);
+ *   }
+ * }
+ * ```
+ */
+export function isDocError(error) {
+    if (error === null || typeof error !== 'object') {
+        return false;
+    }
+    const maybeError = error;
+    // Check for required DocError properties
+    if (typeof maybeError.type !== 'string' || typeof maybeError.message !== 'string') {
+        return false;
+    }
+    // Verify type is one of the known DocError discriminators
+    const knownTypes = [
+        'FILE_SYSTEM_ERROR',
+        'FILE_PARSE_ERROR',
+        'DIRECTIVE_VALIDATION_ERROR',
+        'PATTERN_VALIDATION_ERROR',
+        'REGISTRY_VALIDATION_ERROR',
+        'MARKDOWN_GENERATION_ERROR',
+        'FILE_WRITE_ERROR',
+        'FEATURE_PARSE_ERROR',
+        'CONFIG_ERROR',
+        'PROCESS_METADATA_VALIDATION_ERROR',
+        'DELIVERABLE_VALIDATION_ERROR',
+        'GHERKIN_PATTERN_VALIDATION_ERROR',
+    ];
+    return knownTypes.includes(maybeError.type);
+}
+/**
+ * Format a DocError for console output with structured context
+ *
+ * Extracts file paths, line numbers, and validation errors from the
+ * DocError structure and formats them for human-readable output.
+ *
+ * @param error - DocError to format
+ * @returns Formatted error string with context
+ *
+ * @example
+ * ```typescript
+ * const error = createFileParseError('/path/to/file.ts', 'Syntax error', { line: 42 });
+ * console.error(formatDocError(error));
+ * // Output: "FILE_PARSE_ERROR: Failed to parse /path/to/file.ts at line 42: Syntax error"
+ * ```
+ */
+export function formatDocError(error) {
+    const lines = [];
+    // Main error message with type prefix
+    lines.push(`[${error.type}] ${error.message}`);
+    // Add structured context based on error type
+    switch (error.type) {
+        case 'FILE_SYSTEM_ERROR':
+        case 'FILE_PARSE_ERROR':
+        case 'FILE_WRITE_ERROR':
+        case 'FEATURE_PARSE_ERROR':
+            if ('file' in error) {
+                lines.push(`  File: ${error.file}`);
+            }
+            if ('line' in error && typeof error.line === 'number') {
+                lines.push(`  Line: ${error.line}`);
+            }
+            break;
+        case 'DIRECTIVE_VALIDATION_ERROR':
+            lines.push(`  File: ${error.file}`);
+            lines.push(`  Line: ${error.line}`);
+            if (error.directive) {
+                lines.push(`  Directive: ${error.directive}`);
+            }
+            break;
+        case 'PATTERN_VALIDATION_ERROR':
+        case 'GHERKIN_PATTERN_VALIDATION_ERROR':
+            lines.push(`  File: ${error.file}`);
+            lines.push(`  Pattern: ${error.patternName}`);
+            if ('validationErrors' in error &&
+                Array.isArray(error.validationErrors) &&
+                error.validationErrors.length > 0) {
+                lines.push('  Validation errors:');
+                for (const ve of error.validationErrors) {
+                    lines.push(`    - ${ve}`);
+                }
+            }
+            break;
+        case 'REGISTRY_VALIDATION_ERROR':
+            lines.push(`  Registry: ${error.registryPath}`);
+            if (error.validationErrors !== undefined && error.validationErrors.length > 0) {
+                lines.push('  Validation errors:');
+                for (const ve of error.validationErrors) {
+                    lines.push(`    - ${ve}`);
+                }
+            }
+            break;
+        case 'PROCESS_METADATA_VALIDATION_ERROR':
+        case 'DELIVERABLE_VALIDATION_ERROR':
+            lines.push(`  File: ${error.file}`);
+            if ('deliverableName' in error && error.deliverableName) {
+                lines.push(`  Deliverable: ${error.deliverableName}`);
+            }
+            if ('validationErrors' in error &&
+                Array.isArray(error.validationErrors) &&
+                error.validationErrors.length > 0) {
+                lines.push('  Validation errors:');
+                for (const ve of error.validationErrors) {
+                    lines.push(`    - ${ve}`);
+                }
+            }
+            break;
+        case 'CONFIG_ERROR':
+            lines.push(`  Field: ${error.field}`);
+            if (error.value !== undefined) {
+                lines.push(`  Value: ${JSON.stringify(error.value)}`);
+            }
+            break;
+        case 'MARKDOWN_GENERATION_ERROR':
+            lines.push(`  Pattern ID: ${error.patternId}`);
+            break;
+    }
+    return lines.join('\n');
+}
+/**
+ * Unified CLI error handler that formats and exits
+ *
+ * Handles both DocError instances and generic Error/unknown values.
+ * Outputs structured error information and exits with specified code.
+ *
+ * @param error - Error to handle (DocError, Error, or unknown)
+ * @param exitCode - Process exit code (default: 1)
+ * @returns Never - always calls process.exit
+ *
+ * @example
+ * ```typescript
+ * async function main(): Promise<void> {
+ *   try {
+ *     await doWork();
+ *   } catch (error) {
+ *     handleCliError(error, 1);
+ *   }
+ * }
+ * ```
+ */
+export function handleCliError(error, exitCode = 1) {
+    if (isDocError(error)) {
+        // Structured DocError - format with full context
+        console.error(formatDocError(error));
+    }
+    else if (error instanceof Error) {
+        // Standard Error - use message and optionally stack
+        console.error('Error:', error.message);
+        if (process.env['DEBUG']) {
+            console.error('Stack trace:', error.stack);
+        }
+    }
+    else {
+        // Unknown error type - stringify
+        console.error('Error:', String(error));
+    }
+    process.exit(exitCode);
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/cli/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../src/cli/error-handler.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,UAAU,GAAG,KAA8C,CAAC;IAElE,yCAAyC;IACzC,IAAI,OAAO,UAAU,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,UAAU,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QAClF,OAAO,KAAK,CAAC;IACf,CAAC;IAED,0DAA0D;IAC1D,MAAM,UAAU,GAAG;QACjB,mBAAmB;QACnB,kBAAkB;QAClB,4BAA4B;QAC5B,0BAA0B;QAC1B,2BAA2B;QAC3B,2BAA2B;QAC3B,kBAAkB;QAClB,qBAAqB;QACrB,cAAc;QACd,mCAAmC;QACnC,8BAA8B;QAC9B,kCAAkC;KACnC,CAAC;IAEF,OAAO,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,cAAc,CAAC,KAAe;IAC5C,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,sCAAsC;IACtC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAE/C,6CAA6C;IAC7C,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,mBAAmB,CAAC;QACzB,KAAK,kBAAkB,CAAC;QACxB,KAAK,kBAAkB,CAAC;QACxB,KAAK,qBAAqB;YACxB,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;gBACpB,KAAK,CAAC,IAAI,CAAC,WAAW,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;YACtC,CAAC;YACD,IAAI,MAAM,IAAI,KAAK,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACtD,KAAK,CAAC,IAAI,CAAC,WAAW,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;YACtC,CAAC;YACD,MAAM;QAER,KAAK,4BAA4B;YAC/B,KAAK,CAAC,IAAI,CAAC,WAAW,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;YACpC,KAAK,CAAC,IAAI,CAAC,WAAW,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;YACpC,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;gBACpB,KAAK,CAAC,IAAI,CAAC,gBAAgB,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;YAChD,CAAC;YACD,MAAM;QAER,KAAK,0BAA0B,CAAC;QAChC,KAAK,kCAAkC;YACrC,KAAK,CAAC,IAAI,CAAC,WAAW,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;YACpC,KAAK,CAAC,IAAI,CAAC,cAAc,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;YAC9C,IACE,kBAAkB,IAAI,KAAK;gBAC3B,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC;gBACrC,KAAK,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,EACjC,CAAC;gBACD,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;gBACnC,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;oBACxC,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;gBAC5B,CAAC;YACH,CAAC;YACD,MAAM;QAER,KAAK,2BAA2B;YAC9B,KAAK,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC;YAChD,IAAI,KAAK,CAAC,gBAAgB,KAAK,SAAS,IAAI,KAAK,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC9E,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;gBACnC,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;oBACxC,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;gBAC5B,CAAC;YACH,CAAC;YACD,MAAM;QAER,KAAK,mCAAmC,CAAC;QACzC,KAAK,8BAA8B;YACjC,KAAK,CAAC,IAAI,CAAC,WAAW,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;YACpC,IAAI,iBAAiB,IAAI,KAAK,IAAI,KAAK,CAAC,eAAe,EAAE,CAAC;gBACxD,KAAK,CAAC,IAAI,CAAC,kBAAkB,KAAK,CAAC,eAAe,EAAE,CAAC,CAAC;YACxD,CAAC;YACD,IACE,kBAAkB,IAAI,KAAK;gBAC3B,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC;gBACrC,KAAK,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,EACjC,CAAC;gBACD,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;gBACnC,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;oBACxC,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;gBAC5B,CAAC;YACH,CAAC;YACD,MAAM;QAER,KAAK,cAAc;YACjB,KAAK,CAAC,IAAI,CAAC,YAAY,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;YACtC,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC9B,KAAK,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACxD,CAAC;YACD,MAAM;QAER,KAAK,2BAA2B;YAC9B,KAAK,CAAC,IAAI,CAAC,iBAAiB,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;YAC/C,MAAM;IACV,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc,EAAE,QAAQ,GAAG,CAAC;IACzD,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACtB,iDAAiD;QACjD,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;IACvC,CAAC;SAAM,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAClC,oDAAoD;QACpD,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACzB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;SAAM,CAAC;QACN,iCAAiC;QACjC,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACzC,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACzB,CAAC"}

package/dist/cli/generate-docs.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * @architect
+ * @architect-core @architect-cli
+ * @architect-pattern Documentation Generator CLI
+ * @architect-status completed
+ * @architect-uses Orchestrator, Generator Registry
+ * @architect-used-by npm scripts, CI pipelines
+ * @architect-usecase "When generating documentation from command line"
+ * @architect-usecase "When integrating doc generation into npm scripts"
+ * @architect-extract-shapes CLIConfig
+ *
+ * ## architect-generate - Single Entry Point for All Documentation Generation
+ *
+ * Replaces multiple specialized CLIs with one unified interface that supports
+ * multiple generators in a single run.
+ *
+ * ### When to Use
+ *
+ * - Generating any documentation from annotated TypeScript source
+ * - Running multiple generators in one command
+ * - Using a project config file for reproducible builds
+ *
+ * ### Key Concepts
+ *
+ * - **Multi-Generator**: Run patterns, adrs, overview, custom generators together
+ * - **Explicit Registration**: Generators must be registered before use
+ */
+import '../generators/built-in/index.js';
+//# sourceMappingURL=generate-docs.d.ts.map

package/dist/cli/generate-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-docs.d.ts","sourceRoot":"","sources":["../../src/cli/generate-docs.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAeH,OAAO,iCAAiC,CAAC"}