@libar-dev/architect 1.0.0-pre.3 → 1.0.0-pre.5

package/dist/generators/index.d.ts

@@ -1,50 +0,0 @@
-/**
- * Generators Module
- *
- * @architect
- * @architect-core @architect-infra
- * @architect-pattern Generators Module
- *
- * RDM (RenderableDocument Model) based document generation system.
- * Uses Zod 4 codecs to transform MasterDataset into RenderableDocuments.
- *
- * ### When to Use
- *
- * - When importing generator types, registry, or orchestrator functions
- * - When building custom generators or extending the generation pipeline
- * - When programmatically generating documentation from code
- *
- * ## Usage
- *
- * ```typescript
- * import { generatorRegistry } from '@libar-dev/architect/generators';
- * import '@libar-dev/architect/generators/built-in'; // Register built-in generators
- *
- * const generator = generatorRegistry.get('patterns');
- * const output = await generator.generate(patterns, context);
- * ```
- *
- * ### Key Concepts
- *
- * - **DocumentGenerator Protocol:** Minimal interface for pluggable generators
- * - **Codec-Based Generators:** Use Zod 4 codecs for type-safe transformations
- * - **Registry Pattern:** Explicit registration for transparency
- */
-export type { DocumentGenerator, GeneratorContext, GeneratorOutput, OutputFile } from './types.js';
-export { GeneratorRegistry, generatorRegistry } from './registry.js';
-export { CodecBasedGenerator, createCodecGenerator, DOCUMENT_TYPES, type DocumentType, } from './codec-based.js';
-export { generateDocumentation, type GenerateOptions, type GenerateResult, type GeneratedFile, type GenerationError, type GenerationWarning, } from './orchestrator.js';
-export { buildMasterDataset, type PipelineOptions, mergePatterns, transformToMasterDataset, type RawDataset, type RuntimeMasterDataset, } from './pipeline/index.js';
-export { createProductAreaConfigs, PRODUCT_AREA_VALUES, type ProductAreaConfigOptions, } from './built-in/reference-generators.js';
-/**
- * NOTE: Built-in generators are NOT auto-registered.
- * Import './built-in/index.js' explicitly to register them:
- *
- * ```typescript
- * import '@libar-dev/architect/generators/built-in';
- * ```
- *
- * This explicit registration makes side effects visible and prevents
- * accidental registration in contexts where it's not needed.
- */
-//# sourceMappingURL=index.d.ts.map

package/dist/generators/index.js

@@ -1,54 +0,0 @@
-/**
- * Generators Module
- *
- * @architect
- * @architect-core @architect-infra
- * @architect-pattern Generators Module
- *
- * RDM (RenderableDocument Model) based document generation system.
- * Uses Zod 4 codecs to transform MasterDataset into RenderableDocuments.
- *
- * ### When to Use
- *
- * - When importing generator types, registry, or orchestrator functions
- * - When building custom generators or extending the generation pipeline
- * - When programmatically generating documentation from code
- *
- * ## Usage
- *
- * ```typescript
- * import { generatorRegistry } from '@libar-dev/architect/generators';
- * import '@libar-dev/architect/generators/built-in'; // Register built-in generators
- *
- * const generator = generatorRegistry.get('patterns');
- * const output = await generator.generate(patterns, context);
- * ```
- *
- * ### Key Concepts
- *
- * - **DocumentGenerator Protocol:** Minimal interface for pluggable generators
- * - **Codec-Based Generators:** Use Zod 4 codecs for type-safe transformations
- * - **Registry Pattern:** Explicit registration for transparency
- */
-// Generator registry (singleton + class for custom instances)
-export { GeneratorRegistry, generatorRegistry } from './registry.js';
-// Codec-based generators (RDM architecture)
-export { CodecBasedGenerator, createCodecGenerator, DOCUMENT_TYPES, } from './codec-based.js';
-// Orchestrator - programmatic API for documentation generation
-export { generateDocumentation, } from './orchestrator.js';
-// Pipeline - MasterDataset transformation for ProcessStateAPI usage
-export { buildMasterDataset, mergePatterns, transformToMasterDataset, } from './pipeline/index.js';
-// Product area and reference document config helpers (for downstream repo configs)
-export { createProductAreaConfigs, PRODUCT_AREA_VALUES, } from './built-in/reference-generators.js';
-/**
- * NOTE: Built-in generators are NOT auto-registered.
- * Import './built-in/index.js' explicitly to register them:
- *
- * ```typescript
- * import '@libar-dev/architect/generators/built-in';
- * ```
- *
- * This explicit registration makes side effects visible and prevents
- * accidental registration in contexts where it's not needed.
- */
-//# sourceMappingURL=index.js.map

package/dist/generators/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/generators/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH,8DAA8D;AAC9D,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAErE,4CAA4C;AAC5C,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,GAEf,MAAM,kBAAkB,CAAC;AAE1B,+DAA+D;AAC/D,OAAO,EACL,qBAAqB,GAMtB,MAAM,mBAAmB,CAAC;AAE3B,oEAAoE;AACpE,OAAO,EACL,kBAAkB,EAElB,aAAa,EACb,wBAAwB,GAGzB,MAAM,qBAAqB,CAAC;AAE7B,mFAAmF;AACnF,OAAO,EACL,wBAAwB,EACxB,mBAAmB,GAEpB,MAAM,oCAAoC,CAAC;AAE5C;;;;;;;;;;GAUG"}

package/dist/generators/orchestrator.d.ts

@@ -1,265 +0,0 @@
-/**
- * @architect
- * @architect-core @architect-infra
- * @architect-pattern Documentation Generation Orchestrator
- * @architect-status completed
- * @architect-arch-role service
- * @architect-arch-context generator
- * @architect-arch-layer application
- * @architect-uses Pattern Scanner, Doc Extractor, Gherkin Scanner, Gherkin Extractor, Generator Registry, JSON Output Codec
- * @architect-used-by CLI, Programmatic API
- * @architect-usecase "When running full documentation generation pipeline"
- * @architect-usecase "When merging TypeScript and Gherkin patterns"
- * @architect-convention pipeline-architecture
- *
- * ## Orchestrator Pipeline Responsibilities
- *
- * **Invariant:** The orchestrator is the integration boundary for full docs generation:
- * it delegates dataset construction to the shared pipeline, then executes codecs and
- * writes files.
- *
- * **Rationale:** Splitting orchestration into dataset construction (shared) and output
- * execution (orchestrator-owned) keeps Data API and validation consumers aligned on one
- * read-model path while preserving generator-specific output handling.
- *
- * ## Steps 1-8 via buildMasterDataset()
- *
- * Steps 1-8 (config load, TypeScript/Gherkin scan + extraction, merge, hierarchy
- * derivation, workflow load, and `transformToMasterDataset`) are delegated to
- * `buildMasterDataset()`.
- *
- * ## Steps 9-10: Codec Execution and File Writing
- *
- * After dataset creation, the orchestrator owns Step 9 (codec execution per generator,
- * output rendering, additional file fan-out) and Step 10 (path validation, overwrite
- * policy, and persisted file writes).
- *
- * ### When to Use
- *
- * - Running complete documentation generation programmatically
- * - Integrating doc generation into build scripts
- * - Testing the full pipeline without CLI overhead
- */
-import type { TagRegistry, ExtractedPattern } from '../validation-schemas/index.js';
-import type { ResolvedConfig } from '../config/project-config.js';
-import type { Result } from '../types/index.js';
-import type { CodecOptions } from '../renderable/generate.js';
-/**
- * Options for documentation generation
- */
-export interface GenerateOptions {
-    /** Glob patterns for TypeScript source files */
-    input: string[];
-    /** Glob patterns to exclude */
-    exclude?: string[];
-    /** Base directory for resolving relative paths */
-    baseDir: string;
-    /** Output directory for generated files */
-    outputDir: string;
-    /** Generator names to run (e.g., ['patterns', 'adrs']) */
-    generators: string[];
-    /** Overwrite existing files (default: false) */
-    overwrite?: boolean;
-    /** Glob patterns for .feature files (supports multiple patterns) */
-    features?: string | string[] | null;
-    /** Path to custom workflow config (loads default if not specified) */
-    workflowPath?: string | null;
-    /**
-     * Git diff base branch for PR-scoped generators.
-     * When provided, auto-detects changed files by comparing HEAD to this branch.
-     * @example "main", "develop"
-     */
-    gitDiffBase?: string;
-    /**
-     * Explicit list of changed files. Overrides git detection when provided.
-     * Useful for programmatic use or when git detection is not desired.
-     */
-    changedFiles?: string[];
-    /**
-     * Release version filter for PR Changes generator.
-     * @example "v0.2.0"
-     */
-    releaseFilter?: string;
-    /**
-     * Custom context inference rules for auto-inferring bounded context from file paths.
-     *
-     * When provided, these rules are prepended to the default rules (user rules take precedence).
-     * Use this to map your project's directory structure to bounded contexts for architecture diagrams.
-     *
-     * @example
-     * contextInferenceRules: [
-     *   { pattern: 'packages/orders/**', context: 'orders' },
-     *   { pattern: 'packages/inventory/**', context: 'inventory' },
-     * ]
-     */
-    contextInferenceRules?: ReadonlyArray<{
-        pattern: string;
-        context: string;
-    }>;
-    /**
-     * Per-codec options passed through to codec factories.
-     * Merged with any options the orchestrator computes (e.g., PR changes).
-     * Computed options take precedence over user-provided options.
-     */
-    codecOptions?: CodecOptions;
-}
-/**
- * Result of documentation generation
- */
-export interface GenerateResult {
-    /** Extracted patterns from source code */
-    readonly patterns: readonly ExtractedPattern[];
-    /** Generated files (path + content) */
-    readonly files: readonly GeneratedFile[];
-    /** Tag registry used for generation */
-    readonly registry: TagRegistry;
-    /** Errors encountered during generation */
-    readonly errors: readonly GenerationError[];
-    /** Warnings (non-fatal issues) */
-    readonly warnings: readonly GenerationWarning[];
-}
-/**
- * Generated file with metadata
- */
-export interface GeneratedFile {
-    /** Relative path from outputDir */
-    path: string;
-    /** Full absolute path */
-    fullPath: string;
-    /** File content */
-    content: string;
-    /** Generator that created this file */
-    generator: string;
-    /** Whether file was written (false if skipped due to overwrite=false) */
-    written: boolean;
-}
-/**
- * Generation error
- */
-export interface GenerationError {
-    type: 'scan' | 'extraction' | 'generator' | 'file-write';
-    message: string;
-    generator?: string;
-    filePath?: string;
-}
-/**
- * Detail for a single error within a warning
- */
-export interface WarningDetail {
-    file: string;
-    line?: number;
-    column?: number;
-    message: string;
-}
-/**
- * Generation warning
- */
-export interface GenerationWarning {
-    type: 'scan' | 'extraction' | 'overwrite-skipped' | 'config' | 'cleanup';
-    message: string;
-    count?: number;
-    filePath?: string;
-    /** Detailed error information for each affected file */
-    details?: WarningDetail[];
-}
-/**
- * Generate documentation from TypeScript source code
- *
- * Orchestrates the complete pipeline:
- * 1. Load tag registry
- * 2. Scan source files for @architect directives
- * 3. Extract patterns from directives
- * 4. Run specified generators
- * 5. Write output files
- *
- * @param options - Generation options
- * @returns Result with patterns, files, and any errors/warnings
- *
- * @example
- * ```typescript
- * import { generateDocumentation } from '@libar-dev/architect/generators';
- * import '@libar-dev/architect/generators/built-in';
- *
- * const result = await generateDocumentation({
- *   input: ['src/**\/*.ts'],
- *   baseDir: process.cwd(),
- *   outputDir: 'docs',
- *   generators: ['patterns'],
- *   overwrite: true
- * });
- *
- * console.log(`Generated ${result.files.length} files`);
- * console.log(`Extracted ${result.patterns.length} patterns`);
- * ```
- */
-export declare function generateDocumentation(options: GenerateOptions): Promise<Result<GenerateResult, string>>;
-/**
- * Result from cleaning up orphaned session files.
- */
-export interface CleanupResult {
-    /** Files that were successfully deleted */
-    readonly deleted: readonly string[];
-    /** Errors encountered during cleanup (non-fatal) */
-    readonly errors: readonly string[];
-}
-/**
- * Clean up orphaned session files in a directory.
- *
- * Deletes session files (phase-*.md) that are not in the preserve list.
- * This is used to clean up stale session files when phases complete.
- *
- * @param outputDir - Base output directory
- * @param sessionsDir - Subdirectory containing session files (e.g., "sessions/")
- * @param preserveFiles - Set of file basenames to preserve (e.g., "phase-39.md")
- * @returns Result with deleted files and any errors
- *
- * @example
- * ```typescript
- * const result = await cleanupOrphanedSessionFiles(
- *   "/output",
- *   "sessions/",
- *   new Set(["phase-39.md"])  // Keep active phase
- * );
- * console.log(`Deleted ${result.deleted.length} orphaned files`);
- * ```
- */
-export declare function cleanupOrphanedSessionFiles(outputDir: string, sessionsDir: string, preserveFiles: Set<string>): Promise<CleanupResult>;
-/**
- * Options for config-based generation
- */
-export interface GenerateFromConfigOptions {
-    /** Override generator names (ignores config defaults) */
-    readonly generators?: readonly string[];
-    /** Git diff base branch for PR-scoped generators */
-    readonly gitDiffBase?: string;
-    /** Explicit changed file list for PR-scoped generators */
-    readonly changedFiles?: string[];
-    /** Release version filter for PR Changes generator */
-    readonly releaseFilter?: string;
-    /** Per-codec options (merged with config-level codecOptions, CLI takes precedence) */
-    readonly codecOptions?: CodecOptions;
-}
-/**
- * Generate documentation from a fully resolved config.
- *
- * Groups generators by their effective source config, then calls
- * `generateDocumentation()` once per group. This reuses all existing
- * pipeline logic while minimizing redundant file scans.
- *
- * @param config - Fully resolved configuration (from `loadProjectConfig()`)
- * @param options - Optional overrides for generators, git diff, and release filter
- * @returns Result with merged patterns, files, errors, and warnings from all groups
- *
- * @example
- * ```typescript
- * import { generateFromConfig } from '@libar-dev/architect/generators';
- * import { loadProjectConfig } from '@libar-dev/architect/config';
- *
- * const config = await loadProjectConfig(process.cwd());
- * const result = await generateFromConfig(config, {
- *   generators: ['patterns', 'roadmap'],
- * });
- * ```
- */
-export declare function generateFromConfig(config: ResolvedConfig, options?: GenerateFromConfigOptions): Promise<Result<GenerateResult, string>>;
-//# sourceMappingURL=orchestrator.d.ts.map