@libar-dev/architect 1.0.0-pre.3

package/dist/generators/source-mapping-validator.d.ts

@@ -0,0 +1,118 @@
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern SourceMappingValidator
+ * @architect-status completed
+ *
+ * ## Source Mapping Validator - Pre-flight Validation
+ *
+ * Performs pre-flight checks on source mapping tables before extraction begins.
+ * Validates file existence, extraction method validity, and format correctness
+ * to fail fast with clear errors rather than producing incomplete output.
+ *
+ * ### When to Use
+ *
+ * - Before document generation from source mappings
+ * - When validating decision document source tables
+ * - When checking extraction method compatibility
+ *
+ * ### Validation Checks
+ *
+ * 1. **File existence**: Source files must exist and be files (not directories)
+ * 2. **Method validity**: Extraction methods must be recognized
+ * 3. **Compatibility**: Extraction methods must match file types
+ * 4. **Table format**: Required columns must be present
+ */
+import { Result } from '../types/result.js';
+import { type SourceMappingEntry } from '../renderable/codecs/decision-doc.js';
+import type { Warning, WarningCollector } from './warning-collector.js';
+/**
+ * Validation error with context
+ */
+export interface ValidationError {
+    /** Error message describing the issue */
+    message: string;
+    /** The source mapping row that caused the error (if applicable) */
+    row?: SourceMappingEntry;
+    /** Suggested alternatives or fixes */
+    suggestions?: string[];
+}
+/**
+ * Complete validation result
+ */
+export interface ValidationResult {
+    /** Whether validation passed (no errors) */
+    isValid: boolean;
+    /** Validation errors (validation fails if any exist) */
+    errors: ValidationError[];
+    /** Non-fatal warnings */
+    warnings: Warning[];
+}
+/**
+ * Options for the validator
+ */
+export interface ValidatorOptions {
+    /** Base directory for resolving relative paths */
+    baseDir: string;
+    /** Optional warning collector for non-fatal issues (reserved for future use) */
+    warningCollector?: WarningCollector;
+}
+/**
+ * Valid extraction methods for reference
+ */
+export declare const VALID_EXTRACTION_METHODS: readonly string[];
+/**
+ * Validate that a source file exists
+ *
+ * @param mapping - The source mapping entry to validate
+ * @param baseDir - Base directory for resolving relative paths
+ * @returns Result with void on success, ValidationError on failure
+ */
+export declare function validateFileExists(mapping: SourceMappingEntry, baseDir: string): Result<void, ValidationError>;
+/**
+ * Validate that an extraction method is valid
+ *
+ * @param method - The extraction method string
+ * @returns Result with normalized method on success, ValidationError on failure
+ */
+export declare function validateExtractionMethod(method: string): Result<string, ValidationError>;
+/**
+ * Validate that an extraction method is compatible with the file type
+ *
+ * @param mapping - The source mapping entry to validate
+ * @returns Result with void on success, ValidationError on failure
+ */
+export declare function validateMethodFileCompatibility(mapping: SourceMappingEntry): Result<void, ValidationError>;
+/**
+ * Validate table format has required columns
+ *
+ * @param columns - Array of column names from the table header
+ * @returns Result with column mapping on success, ValidationError on failure
+ */
+export declare function validateTableFormat(columns: string[]): Result<Record<string, string>, ValidationError>;
+/**
+ * Validate a complete source mapping table
+ *
+ * Performs all validation checks and collects all errors rather than
+ * stopping at the first one.
+ *
+ * @param mappings - Array of source mapping entries to validate
+ * @param options - Validation options including base directory
+ * @returns ValidationResult with all errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = validateSourceMappingTable(mappings, {
+ *   baseDir: process.cwd(),
+ *   warningCollector: createWarningCollector()
+ * });
+ *
+ * if (!result.isValid) {
+ *   for (const error of result.errors) {
+ *     console.error(error.message);
+ *   }
+ * }
+ * ```
+ */
+export declare function validateSourceMappingTable(mappings: readonly SourceMappingEntry[], options: ValidatorOptions): ValidationResult;
+//# sourceMappingURL=source-mapping-validator.d.ts.map

package/dist/generators/source-mapping-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-mapping-validator.d.ts","sourceRoot":"","sources":["../../src/generators/source-mapping-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAMxE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAEhB,mEAAmE;IACnE,GAAG,CAAC,EAAE,kBAAkB,CAAC;IAEzB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IAEjB,wDAAwD;IACxD,MAAM,EAAE,eAAe,EAAE,CAAC;IAE1B,yBAAyB;IACzB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAEhB,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAMD;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAAsC,CAAC;AAuC7F;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,MAAM,GACd,MAAM,CAAC,IAAI,EAAE,eAAe,CAAC,CAmC/B;AAiCD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAkCxF;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,kBAAkB,GAC1B,MAAM,CAAC,IAAI,EAAE,eAAe,CAAC,CAoD/B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EAAE,GAChB,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe,CAAC,CAsBjD;AA0CD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,EACvC,OAAO,EAAE,gBAAgB,GACxB,gBAAgB,CAmClB"}

package/dist/generators/source-mapping-validator.js

@@ -0,0 +1,334 @@
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern SourceMappingValidator
+ * @architect-status completed
+ *
+ * ## Source Mapping Validator - Pre-flight Validation
+ *
+ * Performs pre-flight checks on source mapping tables before extraction begins.
+ * Validates file existence, extraction method validity, and format correctness
+ * to fail fast with clear errors rather than producing incomplete output.
+ *
+ * ### When to Use
+ *
+ * - Before document generation from source mappings
+ * - When validating decision document source tables
+ * - When checking extraction method compatibility
+ *
+ * ### Validation Checks
+ *
+ * 1. **File existence**: Source files must exist and be files (not directories)
+ * 2. **Method validity**: Extraction methods must be recognized
+ * 3. **Compatibility**: Extraction methods must match file types
+ * 4. **Table format**: Required columns must be present
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { Result } from '../types/result.js';
+import { isSelfReference, normalizeExtractionMethod, EXTRACTION_METHODS, } from '../renderable/codecs/decision-doc.js';
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Valid extraction methods for reference
+ */
+export const VALID_EXTRACTION_METHODS = Object.values(EXTRACTION_METHODS);
+/**
+ * Methods that only work with TypeScript files
+ */
+const TYPESCRIPT_ONLY_METHODS = new Set([
+    '@extract-shapes tag',
+    'JSDoc section',
+    'createViolation() patterns',
+]);
+/**
+ * Methods that only work with Gherkin feature files
+ */
+const GHERKIN_ONLY_METHODS = new Set(['Rule blocks', 'Scenario Outline Examples']);
+/**
+ * Methods that only work with self-reference (THIS DECISION)
+ */
+const SELF_REFERENCE_ONLY_METHODS = new Set(['Decision rule description', 'Fenced code block']);
+/**
+ * Required columns for source mapping tables
+ */
+const REQUIRED_COLUMNS = ['Section', 'Source File', 'Extraction Method'];
+/**
+ * Column name aliases
+ */
+const COLUMN_ALIASES = {
+    Source: 'Source File',
+    How: 'Extraction Method',
+    Extraction: 'Extraction Method',
+};
+// =============================================================================
+// Individual Validators
+// =============================================================================
+/**
+ * Validate that a source file exists
+ *
+ * @param mapping - The source mapping entry to validate
+ * @param baseDir - Base directory for resolving relative paths
+ * @returns Result with void on success, ValidationError on failure
+ */
+export function validateFileExists(mapping, baseDir) {
+    // Skip validation for self-references (THIS DECISION markers)
+    if (isSelfReference(mapping.sourceFile)) {
+        return Result.ok(undefined);
+    }
+    const fullPath = path.resolve(baseDir, mapping.sourceFile);
+    // Check if path exists
+    if (!fs.existsSync(fullPath)) {
+        return Result.err({
+            message: `File not found: ${mapping.sourceFile}`,
+            row: mapping,
+        });
+    }
+    // Check if it's a file (not a directory)
+    try {
+        const stats = fs.statSync(fullPath);
+        if (stats.isDirectory()) {
+            return Result.err({
+                message: `Expected file, got directory: ${mapping.sourceFile}`,
+                row: mapping,
+            });
+        }
+    }
+    catch (error) {
+        // Capture the actual error for better debugging (permission denied, etc.)
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        return Result.err({
+            message: `Unable to read file: ${mapping.sourceFile} (${errorMessage})`,
+            row: mapping,
+        });
+    }
+    return Result.ok(undefined);
+}
+/**
+ * Additional aliases for extraction methods
+ * Maps normalized (lowercase, underscore-to-space) forms to canonical method keys
+ */
+const METHOD_ALIASES = {
+    'rule blocks': 'RULE_BLOCKS',
+    rule_blocks: 'RULE_BLOCKS',
+    ruleblocks: 'RULE_BLOCKS',
+    '@extract-shapes tag': 'EXTRACT_SHAPES',
+    'extract-shapes': 'EXTRACT_SHAPES',
+    'extract shapes': 'EXTRACT_SHAPES',
+    'decision rule description': 'DECISION_RULE_DESCRIPTION',
+    decision_rule_description: 'DECISION_RULE_DESCRIPTION',
+    'jsdoc section': 'JSDOC_SECTION',
+    jsdoc_section: 'JSDOC_SECTION',
+    'createviolation() patterns': 'CREATE_VIOLATION_PATTERNS',
+    'createviolation patterns': 'CREATE_VIOLATION_PATTERNS',
+    create_violation_patterns: 'CREATE_VIOLATION_PATTERNS',
+    'fenced code block': 'FENCED_CODE_BLOCK',
+    fenced_code_block: 'FENCED_CODE_BLOCK',
+    'scenario outline examples': 'SCENARIO_OUTLINE_EXAMPLES',
+    scenario_outline_examples: 'SCENARIO_OUTLINE_EXAMPLES',
+};
+/**
+ * Normalize a method string by lowercasing and replacing underscores with spaces
+ */
+function normalizeMethodString(method) {
+    return method.toLowerCase().trim().replace(/_/g, ' ');
+}
+/**
+ * Validate that an extraction method is valid
+ *
+ * @param method - The extraction method string
+ * @returns Result with normalized method on success, ValidationError on failure
+ */
+export function validateExtractionMethod(method) {
+    // Trim whitespace before validation to handle leading/trailing spaces
+    const trimmedMethod = method.trim();
+    // Check for empty method
+    if (trimmedMethod.length === 0) {
+        return Result.err({
+            message: 'Extraction method is required',
+        });
+    }
+    // First, try using the built-in normalization
+    const normalizedKey = normalizeExtractionMethod(trimmedMethod);
+    if (normalizedKey !== 'unknown') {
+        // Return the canonical form of the method
+        return Result.ok(EXTRACTION_METHODS[normalizedKey]);
+    }
+    // Try our extended aliases
+    const normalizedString = normalizeMethodString(trimmedMethod);
+    const aliasKey = METHOD_ALIASES[normalizedString];
+    if (aliasKey) {
+        return Result.ok(EXTRACTION_METHODS[aliasKey]);
+    }
+    // Check if it's close to a known method for suggestions
+    const suggestions = findSimilarMethods(trimmedMethod);
+    return Result.err({
+        message: `Unknown extraction method: ${trimmedMethod}`,
+        suggestions,
+    });
+}
+/**
+ * Validate that an extraction method is compatible with the file type
+ *
+ * @param mapping - The source mapping entry to validate
+ * @returns Result with void on success, ValidationError on failure
+ */
+export function validateMethodFileCompatibility(mapping) {
+    const { sourceFile, extractionMethod } = mapping;
+    // Skip compatibility check for self-references with self-reference-only methods
+    if (isSelfReference(sourceFile)) {
+        // Self-references can use any method, but primarily use self-reference methods
+        return Result.ok(undefined);
+    }
+    // Normalize the method for comparison
+    const normalizedKey = normalizeExtractionMethod(extractionMethod);
+    if (normalizedKey === 'unknown') {
+        // Method validation will catch this
+        return Result.ok(undefined);
+    }
+    const normalizedMethod = EXTRACTION_METHODS[normalizedKey];
+    const ext = path.extname(sourceFile).toLowerCase();
+    // Check TypeScript-only methods against feature files
+    if (TYPESCRIPT_ONLY_METHODS.has(normalizedMethod)) {
+        if (ext === '.feature') {
+            const alternatives = Array.from(GHERKIN_ONLY_METHODS);
+            return Result.err({
+                message: `Method "${normalizedMethod}" cannot be used with .feature files`,
+                row: mapping,
+                suggestions: alternatives,
+            });
+        }
+    }
+    // Check Gherkin-only methods against TypeScript files
+    if (GHERKIN_ONLY_METHODS.has(normalizedMethod)) {
+        if (ext === '.ts' || ext === '.tsx' || ext === '.js' || ext === '.jsx') {
+            return Result.err({
+                message: `Method "${normalizedMethod}" requires .feature file`,
+                row: mapping,
+            });
+        }
+    }
+    // Check self-reference-only methods against actual files
+    if (SELF_REFERENCE_ONLY_METHODS.has(normalizedMethod)) {
+        if (!isSelfReference(sourceFile)) {
+            return Result.err({
+                message: `Method "${normalizedMethod}" can only be used with THIS DECISION`,
+                row: mapping,
+            });
+        }
+    }
+    return Result.ok(undefined);
+}
+/**
+ * Validate table format has required columns
+ *
+ * @param columns - Array of column names from the table header
+ * @returns Result with column mapping on success, ValidationError on failure
+ */
+export function validateTableFormat(columns) {
+    const columnMapping = {};
+    const normalizedColumns = new Set();
+    // Process each column, applying aliases
+    for (const col of columns) {
+        const trimmed = col.trim();
+        const mapped = COLUMN_ALIASES[trimmed] ?? trimmed;
+        columnMapping[trimmed] = mapped;
+        normalizedColumns.add(mapped);
+    }
+    // Check for required columns
+    for (const required of REQUIRED_COLUMNS) {
+        if (!normalizedColumns.has(required)) {
+            return Result.err({
+                message: `Missing required column: ${required}`,
+            });
+        }
+    }
+    return Result.ok(columnMapping);
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Find extraction methods similar to the given string
+ */
+function findSimilarMethods(method) {
+    const methodLower = method.toLowerCase();
+    const suggestions = [];
+    // Check for partial matches
+    for (const validMethod of VALID_EXTRACTION_METHODS) {
+        const validLower = validMethod.toLowerCase();
+        // Check if any word in the valid method appears in the input
+        const validWords = validLower.split(/[\s-]+/);
+        const inputWords = methodLower.split(/[\s-]+/);
+        const hasCommonWord = validWords.some((vw) => inputWords.some((iw) => vw.includes(iw) || iw.includes(vw)) && vw.length > 2);
+        if (hasCommonWord) {
+            suggestions.push(validMethod);
+        }
+    }
+    // If no suggestions found, provide the most common ones
+    if (suggestions.length === 0) {
+        suggestions.push('@extract-shapes tag', 'Rule blocks');
+    }
+    return suggestions;
+}
+// =============================================================================
+// Main Validation Function
+// =============================================================================
+/**
+ * Validate a complete source mapping table
+ *
+ * Performs all validation checks and collects all errors rather than
+ * stopping at the first one.
+ *
+ * @param mappings - Array of source mapping entries to validate
+ * @param options - Validation options including base directory
+ * @returns ValidationResult with all errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = validateSourceMappingTable(mappings, {
+ *   baseDir: process.cwd(),
+ *   warningCollector: createWarningCollector()
+ * });
+ *
+ * if (!result.isValid) {
+ *   for (const error of result.errors) {
+ *     console.error(error.message);
+ *   }
+ * }
+ * ```
+ */
+export function validateSourceMappingTable(mappings, options) {
+    const errors = [];
+    for (const mapping of mappings) {
+        // 1. Validate file existence
+        const fileResult = validateFileExists(mapping, options.baseDir);
+        if (!fileResult.ok) {
+            errors.push(fileResult.error);
+        }
+        // 2. Validate extraction method
+        const methodResult = validateExtractionMethod(mapping.extractionMethod);
+        if (!methodResult.ok) {
+            errors.push({
+                ...methodResult.error,
+                row: mapping,
+            });
+        }
+        // 3. Validate method-file compatibility (only if method is valid)
+        if (methodResult.ok) {
+            const compatResult = validateMethodFileCompatibility(mapping);
+            if (!compatResult.ok) {
+                errors.push(compatResult.error);
+            }
+        }
+    }
+    // Note: Validation is pass/fail per row, no warnings are generated.
+    // The warnings array is kept in the interface for future extensibility.
+    return {
+        isValid: errors.length === 0,
+        errors,
+        warnings: [],
+    };
+}
+//# sourceMappingURL=source-mapping-validator.js.map

package/dist/generators/source-mapping-validator.js.map

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

package/dist/generators/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @architect
+ */
+import type { ExtractedPattern, TagRegistry } from '../validation-schemas';
+import type { LoadedWorkflow } from '../validation-schemas/workflow-config.js';
+import type { RuntimeMasterDataset } from './pipeline/index.js';
+import type { CodecOptions } from '../renderable/generate.js';
+/**
+ * @architect-generator
+ * @architect-pattern GeneratorTypes
+ * @architect-status completed
+ * @architect-used-by GeneratorRegistry, GeneratorFactory, Orchestrator, SectionRegistry
+ * @architect-extract-shapes DocumentGenerator, GeneratorContext, GeneratorOutput
+ *
+ * ## GeneratorTypes - Pluggable Document Generation Interface
+ *
+ * Minimal interface for pluggable generators that produce documentation from patterns.
+ * Both JSON-configured built-in generators and TypeScript custom generators implement this.
+ *
+ * ### When to Use
+ *
+ * - Creating a new document format (ADRs, planning docs, API specs)
+ * - Building custom generators in TypeScript
+ * - Integrating with the unified CLI
+ *
+ * ### Key Concepts
+ *
+ * - **Generator:** Transforms patterns → document files
+ * - **Context:** Runtime environment (base paths, registries, scenarios)
+ * - **Output:** Map of file paths → content
+ */
+export interface DocumentGenerator {
+    /** Unique generator name (e.g., "patterns", "adrs", "planning") */
+    readonly name: string;
+    /** Optional description shown in --list-generators */
+    readonly description?: string;
+    /**
+     * Generate documentation from extracted patterns.
+     *
+     * @param patterns - Extracted patterns from source code
+     * @param context - Runtime context (paths, registry, scenario map)
+     * @returns Generated files with paths relative to outputDir
+     */
+    generate(patterns: readonly ExtractedPattern[], context: GeneratorContext): Promise<GeneratorOutput>;
+}
+/**
+ * Runtime context provided to generators.
+ */
+export interface GeneratorContext {
+    /** Base directory for resolving relative paths */
+    readonly baseDir: string;
+    /** Output directory for generated files */
+    readonly outputDir: string;
+    /** Tag registry with category/aggregation definitions */
+    readonly registry: TagRegistry;
+    /** Optional workflow configuration for status handling */
+    readonly workflow?: LoadedWorkflow;
+    /**
+     * Pre-computed pattern views for efficient access.
+     *
+     * Contains patterns grouped by status, phase, quarter, category, and source,
+     * computed in a single pass. Sections should use these pre-computed views
+     * instead of filtering the raw patterns array.
+     */
+    readonly masterDataset?: RuntimeMasterDataset;
+    /**
+     * Optional codec-specific options for document generation.
+     *
+     * Used to pass runtime configuration (e.g., changedFiles for PR changes)
+     * through the CLI → Orchestrator → Generator → Codec pipeline.
+     *
+     * @example
+     * ```typescript
+     * const context: GeneratorContext = {
+     *   // ... other fields
+     *   codecOptions: {
+     *     "pr-changes": { changedFiles: ["src/foo.ts"], releaseFilter: "v0.2.0" }
+     *   }
+     * };
+     * ```
+     */
+    readonly codecOptions?: CodecOptions;
+}
+/**
+ * Output from generator execution.
+ */
+export interface GeneratorOutput {
+    /** Files to write (path relative to outputDir) */
+    readonly files: readonly OutputFile[];
+    /** Files to delete for cleanup (path relative to outputDir) */
+    readonly filesToDelete?: readonly string[];
+    /** Optional metadata for registry.json or other purposes */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Single output file.
+ */
+export interface OutputFile {
+    /** Path relative to outputDir (e.g., "PATTERNS.md", "patterns/core.md") */
+    readonly path: string;
+    /** File content as string */
+    readonly content: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/generators/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/generators/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0CAA0C,CAAC;AAC/E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,sDAAsD;IACtD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;;OAMG;IACH,QAAQ,CACN,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAE/B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAEnC;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,oBAAoB,CAAC;IAE9C;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IAEtC,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE3C,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B"}

package/dist/generators/types.js

@@ -0,0 +1,5 @@
+/**
+ * @architect
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/generators/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/generators/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}