@libar-dev/architect 1.0.0-pre.3

package/dist/extractor/dual-source-extractor.js

@@ -0,0 +1,407 @@
+/**
+ * @architect
+ * @architect-extractor
+ * @architect-pattern DualSourceExtractor
+ * @architect-status completed
+ * @architect-uses DocExtractor, GherkinExtractor, GherkinScanner
+ * @architect-used-by Orchestrator
+ * @architect-arch-role service
+ * @architect-arch-context extractor
+ * @architect-arch-layer application
+ *
+ * ## DualSourceExtractor - Compose Pattern Data from Code + Features
+ *
+ * Extracts pattern metadata from both TypeScript code stubs (@architect-*)
+ * and Gherkin feature files (@architect-*), validates consistency,
+ * and composes unified pattern data for documentation generation.
+ *
+ * ### When to Use
+ *
+ * - When implementing USDP Pattern 2 (Standard) or higher
+ * - When you have both code stubs AND timeline features
+ * - When generating artifacts that need both timeless and temporal data
+ * - When validating cross-source consistency (pattern name, phase alignment)
+ *
+ * ### Key Concepts
+ *
+ * - **Code Source**: @architect-* tags define timeless pattern graph
+ * - **Feature Source**: @architect-* tags add temporal process metadata
+ * - **Cross-Validation**: Pattern name + phase must match across sources
+ * - **Deliverables**: Parsed from Gherkin Background tables in features
+ */
+import { getPatternName } from '../api/pattern-helpers.js';
+// Import Zod schemas and inferred types (schema-first pattern)
+import { ProcessMetadataSchema, DeliverableSchema, } from '../validation-schemas/index.js';
+import { DEFAULT_STATUS } from '../taxonomy/status-values.js';
+/**
+ * Extract process metadata from Gherkin feature tags
+ *
+ * Uses schema validation instead of type assertions to ensure data integrity.
+ * Returns null if required tags are missing OR if validation fails.
+ *
+ * @param feature - Scanned Gherkin feature
+ * @returns Process metadata or null if missing required tags or validation fails
+ */
+export function extractProcessMetadata(feature) {
+    const tags = feature.feature.tags;
+    // Extract normalized tags (scanner strips @ and configured prefix like @architect-)
+    const patternTag = tags.find((t) => t.startsWith('pattern:'));
+    const phaseTag = tags.find((t) => t.startsWith('phase:'));
+    const statusTag = tags.find((t) => t.startsWith('status:'));
+    if (!patternTag || !phaseTag) {
+        // Missing required tags
+        return null;
+    }
+    const pattern = patternTag.replace('pattern:', '');
+    const phaseStr = phaseTag.replace('phase:', '');
+    const phase = parseInt(phaseStr, 10);
+    const status = statusTag?.replace('status:', '') ?? DEFAULT_STATUS;
+    // Extract optional tags
+    const quarterTag = tags.find((t) => t.startsWith('quarter:'));
+    const effortTag = tags.find((t) => t.startsWith('effort:'));
+    const teamTag = tags.find((t) => t.startsWith('team:'));
+    const workflowTag = tags.find((t) => t.startsWith('workflow:'));
+    const completedTag = tags.find((t) => t.startsWith('completed:'));
+    const effortActualTag = tags.find((t) => t.startsWith('effort-actual:'));
+    const riskTag = tags.find((t) => t.startsWith('risk:'));
+    const briefTag = tags.find((t) => t.startsWith('brief:'));
+    const productAreaTag = tags.find((t) => t.startsWith('product-area:'));
+    const userRoleTag = tags.find((t) => t.startsWith('user-role:'));
+    const businessValueTag = tags.find((t) => t.startsWith('business-value:'));
+    const quarter = quarterTag?.replace('quarter:', '');
+    const effort = effortTag?.replace('effort:', '');
+    const team = teamTag?.replace('team:', '');
+    const workflow = workflowTag?.replace('workflow:', '');
+    const completed = completedTag?.replace('completed:', '');
+    const effortActual = effortActualTag?.replace('effort-actual:', '');
+    const risk = riskTag?.replace('risk:', '');
+    const brief = briefTag?.replace('brief:', '');
+    const productArea = productAreaTag?.replace('product-area:', '');
+    const userRole = userRoleTag?.replace('user-role:', '');
+    // Business value may have surrounding quotes - strip them
+    const businessValueRaw = businessValueTag?.replace('business-value:', '');
+    const businessValue = businessValueRaw?.replace(/^["']|["']$/g, '');
+    // Build raw metadata object (no type assertions)
+    const rawMetadata = {
+        pattern,
+        phase,
+        status,
+        ...(quarter && { quarter }),
+        ...(effort && { effort }),
+        ...(team && { team }),
+        ...(workflow && { workflow }),
+        ...(completed && { completed }),
+        ...(effortActual && { effortActual }),
+        ...(risk && { risk }),
+        ...(brief && { brief }),
+        ...(productArea && { productArea }),
+        ...(userRole && { userRole }),
+        ...(businessValue && { businessValue }),
+    };
+    // Validate against schema (schema-first enforcement)
+    const validation = ProcessMetadataSchema.safeParse(rawMetadata);
+    if (!validation.success) {
+        // Log validation failure for debugging (but don't fail silently)
+        console.warn(`Process metadata validation failed in ${feature.filePath}: ` +
+            validation.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join(', '));
+        return null;
+    }
+    return validation.data;
+}
+/**
+ * Parse a Tests cell value to a number
+ *
+ * Handles various formats:
+ * - "Yes" / "No" → 1 / 0
+ * - Numbers as strings → parsed int
+ * - Empty → 0
+ *
+ * @param value - Tests cell value
+ * @returns Number of tests
+ */
+function parseTestsValue(value) {
+    const trimmed = value.trim().toLowerCase();
+    // Handle Yes/No/True/False
+    if (trimmed === 'yes' || trimmed === 'true' || trimmed === '✓' || trimmed === '✅') {
+        return 1;
+    }
+    if (trimmed === 'no' ||
+        trimmed === 'false' ||
+        trimmed === '✗' ||
+        trimmed === '' ||
+        trimmed === '-') {
+        return 0;
+    }
+    // Try to parse as number
+    const parsed = parseInt(trimmed, 10);
+    return isNaN(parsed) ? 0 : parsed;
+}
+/**
+ * Extract deliverables from Gherkin Background table
+ *
+ * Parses Background section looking for DataTables with a "Deliverable" column.
+ * Expected table format:
+ * | Deliverable | Status | Tests | Location |
+ *
+ * Optional columns for extended tracking:
+ * | Deliverable | Status | Tests | Location | Finding | Release |
+ *
+ * - **Finding**: Review traceability ID (e.g., "CODE-001")
+ * - **Release**: Semver version for changelog grouping (e.g., "v0.2.0")
+ *
+ * @param feature - Scanned Gherkin feature with optional background
+ * @returns Array of deliverables or empty array if no table found
+ *
+ * @example
+ * ```gherkin
+ * Background: Deliverables
+ *   Given the following deliverables:
+ *     | Deliverable | Status | Tests | Location | Finding | Release |
+ *     | Fix parseArgs() call | Done | Yes | src/cli/generate-docs.ts | CODE-001 | v0.2.0 |
+ *     | Update README.md | Done | No | README.md | DOC-001 | v0.2.0 |
+ * ```
+ */
+export function extractDeliverables(feature) {
+    // Check if feature has a background section
+    if (!feature.background) {
+        return [];
+    }
+    const deliverables = [];
+    // Search for DataTables in background steps
+    for (const step of feature.background.steps) {
+        if (!step.dataTable) {
+            continue;
+        }
+        const { headers, rows } = step.dataTable;
+        // Check if this table has a "Deliverable" column (case-insensitive)
+        const deliverableIdx = headers.findIndex((h) => h.toLowerCase() === 'deliverable');
+        if (deliverableIdx === -1) {
+            continue;
+        }
+        // Find other columns (case-insensitive)
+        const statusIdx = headers.findIndex((h) => h.toLowerCase() === 'status');
+        const testsIdx = headers.findIndex((h) => h.toLowerCase() === 'tests');
+        const locationIdx = headers.findIndex((h) => h.toLowerCase() === 'location');
+        const findingIdx = headers.findIndex((h) => h.toLowerCase() === 'finding');
+        const releaseIdx = headers.findIndex((h) => h.toLowerCase() === 'release');
+        // Store header names for reliable lookup (avoid empty-string key match)
+        const deliverableHeader = headers[deliverableIdx];
+        const statusHeader = statusIdx >= 0 ? headers[statusIdx] : undefined;
+        const testsHeader = testsIdx >= 0 ? headers[testsIdx] : undefined;
+        const locationHeader = locationIdx >= 0 ? headers[locationIdx] : undefined;
+        const findingHeader = findingIdx >= 0 ? headers[findingIdx] : undefined;
+        const releaseHeader = releaseIdx >= 0 ? headers[releaseIdx] : undefined;
+        if (!deliverableHeader)
+            continue;
+        // Parse each row with schema validation
+        for (const row of rows) {
+            const name = row[deliverableHeader]?.trim() ?? '';
+            const rawStatus = statusHeader ? (row[statusHeader]?.trim() ?? '') : '';
+            const status = rawStatus.toLowerCase();
+            const testsValue = testsHeader ? (row[testsHeader]?.trim() ?? '0') : '0';
+            const location = locationHeader ? (row[locationHeader]?.trim() ?? '') : '';
+            const findingRaw = findingHeader ? row[findingHeader]?.trim() : undefined;
+            const finding = findingRaw !== '' ? findingRaw : undefined;
+            const releaseRaw = releaseHeader ? row[releaseHeader]?.trim() : undefined;
+            const release = releaseRaw !== '' ? releaseRaw : undefined;
+            // Build raw deliverable object (no type assertions)
+            const rawDeliverable = {
+                name,
+                status,
+                tests: parseTestsValue(testsValue),
+                location,
+                ...(finding && { finding }),
+                ...(release && { release }),
+            };
+            // Validate against schema (schema-first enforcement)
+            const validation = DeliverableSchema.safeParse(rawDeliverable);
+            if (!validation.success) {
+                // Skip invalid deliverables with warning (name might be empty or tests negative)
+                console.warn(`Deliverable validation failed in ${feature.filePath}: ` +
+                    validation.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join(', '));
+                continue;
+            }
+            deliverables.push(validation.data);
+        }
+    }
+    return deliverables;
+}
+/**
+ * Combine patterns from code and features into dual-source patterns
+ *
+ * Validates that pattern names and phases match across sources.
+ * Creates unified pattern objects with both code and process metadata.
+ *
+ * **Pattern Name Collisions:**
+ * When multiple code files use the same `@architect-pattern` name (e.g.,
+ * ServiceIndependence with ECST and Reservation sub-patterns), they are
+ * automatically merged:
+ * - Categories, dependencies, and enables are unioned across all sources
+ * - Primary pattern (first in array) provides base metadata
+ * - All source patterns are preserved in the `sources` array
+ * - Console warning is emitted for visibility
+ *
+ * @param codePatterns - Patterns extracted from TypeScript code
+ * @param featureFiles - Scanned Gherkin feature files
+ * @returns Dual-source extraction results
+ *
+ * @example
+ * ```typescript
+ * // Extract from both sources
+ * const codeScan = await scanPatterns({ patterns: 'packages/**\/*.ts' });
+ * const featureScan = await scanGherkinFiles({ patterns: 'tests/features/**\/*.feature' });
+ *
+ * if (codeScan.ok && featureScan.ok) {
+ *   const codeExtraction = extractPatterns(codeScan.value.files, '/project');
+ *   const dualSource = combineSources(codeExtraction.patterns, featureScan.value.files);
+ *
+ *   console.log(`Combined: ${dualSource.patterns.length}`);
+ *   console.log(`Code-only: ${dualSource.codeOnly.length}`);
+ *   console.log(`Feature-only: ${dualSource.featureOnly.length}`);
+ *   console.log(`Validation errors: ${dualSource.validationErrors.length}`);
+ *
+ *   // Check for collisions
+ *   for (const pattern of dualSource.patterns) {
+ *     if (pattern.sources) {
+ *       console.log(`${pattern.patternName} has ${pattern.sources.length} implementations`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export function combineSources(codePatterns, featureFiles) {
+    const combined = [];
+    const codeOnly = [];
+    const featureOnly = [];
+    const validationErrors = [];
+    const warnings = [];
+    // Build index of code patterns by patternName (supports collisions)
+    // When multiple code files use same pattern name, they're stored as an array
+    const codeIndex = new Map();
+    for (const pattern of codePatterns) {
+        if (pattern.patternName) {
+            const existing = codeIndex.get(pattern.patternName) ?? [];
+            codeIndex.set(pattern.patternName, [...existing, pattern]);
+        }
+    }
+    // Build index of features by pattern name
+    const featureIndex = new Map();
+    for (const feature of featureFiles) {
+        const metadata = extractProcessMetadata(feature);
+        if (metadata) {
+            featureIndex.set(metadata.pattern, { metadata, file: feature });
+        }
+    }
+    // Combine matching patterns
+    for (const [patternName, codePatternArray] of codeIndex.entries()) {
+        const featureData = featureIndex.get(patternName);
+        if (!featureData) {
+            // Code-only patterns (no matching feature)
+            codeOnly.push(...codePatternArray);
+            continue;
+        }
+        const { metadata: processMetadata, file: featureFile } = featureData;
+        // Handle pattern collision (multiple code sources for same pattern name)
+        const hasCollision = codePatternArray.length > 1;
+        const primaryPattern = codePatternArray[0];
+        if (!primaryPattern) {
+            // Should never happen but TypeScript needs the check
+            console.warn(`Pattern "${patternName}" has no code patterns in array`);
+            continue;
+        }
+        // Cross-validate: Phase must match (if both present)
+        if (primaryPattern.phase !== undefined && processMetadata.phase !== primaryPattern.phase) {
+            validationErrors.push({
+                codeName: patternName,
+                featureName: processMetadata.pattern,
+                codePhase: primaryPattern.phase,
+                featurePhase: processMetadata.phase,
+                sources: {
+                    code: primaryPattern.source.file,
+                    feature: featureFile.filePath,
+                },
+                message: `Phase mismatch: code has ${primaryPattern.phase}, feature has ${processMetadata.phase}`,
+            });
+            // Still combine but note the error
+        }
+        // Extract deliverables from feature
+        const deliverables = extractDeliverables(featureFile);
+        // Note: ExtractedPattern has 'category' (singular), not 'categories' (plural)
+        // For collision handling, we use the primary pattern's category
+        // Future enhancement: could merge categories if schema changes
+        // Merge dependencies (union)
+        const mergedDependsOn = hasCollision
+            ? Array.from(new Set(codePatternArray.flatMap((p) => p.dependsOn ?? [])))
+            : primaryPattern.dependsOn;
+        // Merge enables (union)
+        const mergedEnables = hasCollision
+            ? Array.from(new Set(codePatternArray.flatMap((p) => p.enables ?? [])))
+            : primaryPattern.enables;
+        // Combine into dual-source pattern
+        // Destructure to exclude existing deliverables (exactOptionalPropertyTypes requires this)
+        const { deliverables: _existingDeliverables, ...patternWithoutDeliverables } = primaryPattern;
+        const dualSourcePattern = {
+            ...patternWithoutDeliverables,
+            ...(mergedDependsOn && mergedDependsOn.length > 0 && { dependsOn: mergedDependsOn }),
+            ...(mergedEnables && mergedEnables.length > 0 && { enables: mergedEnables }),
+            process: processMetadata,
+            ...(deliverables.length > 0 && { deliverables }),
+            ...(hasCollision && { sources: codePatternArray }),
+        };
+        combined.push(dualSourcePattern);
+        // Collect warning about collision (structured, not console.warn)
+        if (hasCollision) {
+            warnings.push(`Pattern name collision: "${patternName}" defined in ${codePatternArray.length} files: ` +
+                codePatternArray.map((p) => p.source.file).join(', '));
+        }
+        // Remove from feature index (mark as matched)
+        featureIndex.delete(patternName);
+    }
+    // Remaining features are feature-only (no matching code)
+    for (const [_, { metadata }] of featureIndex.entries()) {
+        featureOnly.push(metadata);
+    }
+    return {
+        patterns: combined,
+        codeOnly,
+        featureOnly,
+        validationErrors,
+        warnings,
+    };
+}
+/**
+ * Validate dual-source consistency
+ *
+ * Checks that patterns are properly aligned across sources.
+ * Reports code stubs without features and features without code.
+ *
+ * @param results - Dual-source extraction results
+ * @returns Validation summary
+ */
+export function validateDualSource(results) {
+    const errors = [];
+    const warnings = [];
+    // Errors: Cross-validation failures
+    for (const error of results.validationErrors) {
+        errors.push(`${error.codeName}: ${error.message}`);
+    }
+    // Warnings: Orphaned stubs (code without feature)
+    for (const pattern of results.codeOnly) {
+        if (pattern.status === DEFAULT_STATUS) {
+            const name = getPatternName(pattern);
+            warnings.push(`Roadmap pattern "${name}" has code stub but no feature file`);
+        }
+    }
+    // Warnings: Features without code stubs
+    for (const metadata of results.featureOnly) {
+        if (metadata.status === DEFAULT_STATUS) {
+            warnings.push(`Feature "${metadata.pattern}" (phase ${metadata.phase}) has no code stub`);
+        }
+    }
+    return {
+        isValid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+//# sourceMappingURL=dual-source-extractor.js.map

package/dist/extractor/dual-source-extractor.js.map

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

package/dist/extractor/gherkin-extractor.d.ts

@@ -0,0 +1,170 @@
+/**
+ * @architect
+ * @architect-extractor
+ * @architect-pattern GherkinExtractor
+ * @architect-status completed
+ * @architect-implements GherkinRulesSupport
+ * @architect-uses GherkinTypes, GherkinASTParser
+ * @architect-used-by DualSourceExtractor, Orchestrator
+ * @architect-arch-role service
+ * @architect-arch-context extractor
+ * @architect-arch-layer application
+ *
+ * ## GherkinExtractor - Convert Feature Files to Pattern Documentation
+ *
+ * Transforms scanned Gherkin feature files into ExtractedPattern objects
+ * for inclusion in generated documentation. Maps feature tags, descriptions,
+ * and scenarios to pattern metadata.
+ *
+ * ### When to Use
+ *
+ * - When building multi-source documentation (TypeScript + Gherkin)
+ * - When converting acceptance criteria to pattern documentation
+ * - When defining roadmap patterns in .feature files before implementation
+ *
+ * ### Key Concepts
+ *
+ * - **Feature → Pattern**: Feature name becomes pattern name
+ * - **Tags → Metadata**: @pattern:Name, @phase:N map to pattern fields
+ * - **Scenarios → Use Cases**: Acceptance criteria become "When to Use" examples
+ */
+import type { ScannedGherkinFile } from '../validation-schemas/feature.js';
+import { type ExtractedPattern } from '../validation-schemas/extracted-pattern.js';
+import type { TagRegistry } from '../validation-schemas/tag-registry.js';
+import { type GherkinPatternValidationError } from '../types/errors.js';
+/**
+ * Semantic tags for scenario categorization.
+ *
+ * These tags identify the nature of a scenario (e.g., happy-path, validation)
+ * and are extracted from scenario tags during pattern extraction.
+ */
+export declare const SEMANTIC_SCENARIO_TAGS: readonly ["happy-path", "validation", "business-failure", "business-rule", "compensation", "idempotency", "expiration", "workflow-state"];
+/**
+ * Configuration for Gherkin extractor
+ */
+export interface GherkinExtractorConfig {
+    /** Base directory for computing relative paths */
+    readonly baseDir: string;
+    /** Tag registry for category inference */
+    readonly tagRegistry?: TagRegistry;
+    /** Convert scenarios to "When to Use" examples (default: true) */
+    readonly scenariosAsUseCases?: boolean;
+}
+/**
+ * Result of Gherkin pattern extraction
+ *
+ * Contains both successfully extracted patterns and any validation errors
+ * encountered during extraction. This enables partial success scenarios
+ * where some patterns extract successfully while others fail validation.
+ */
+export interface GherkinExtractionResult {
+    /** Successfully extracted patterns */
+    readonly patterns: readonly ExtractedPattern[];
+    /** Validation errors for patterns that failed extraction */
+    readonly errors: readonly GherkinPatternValidationError[];
+}
+/**
+ * Extract patterns from scanned Gherkin feature files
+ *
+ * Converts feature file metadata into ExtractedPattern objects that can be
+ * merged with TypeScript-sourced patterns for unified documentation generation.
+ *
+ * Returns both successfully extracted patterns and validation errors for
+ * patterns that failed extraction. This enables partial success scenarios.
+ *
+ * @param scannedFiles - Array of scanned Gherkin files
+ * @param config - Extractor configuration (requires baseDir for relative paths)
+ * @returns Object containing extracted patterns and any validation errors
+ *
+ * @example
+ * ```typescript
+ * const scanResult = await scanGherkinFiles({
+ *   patterns: 'tests/features/roadmap/**\/*.feature'
+ * });
+ *
+ * if (scanResult.ok) {
+ *   const { patterns, errors } = extractPatternsFromGherkin(scanResult.value.files, {
+ *     baseDir: process.cwd()
+ *   });
+ *   console.log(`${patterns.length} patterns extracted, ${errors.length} errors`);
+ * }
+ * ```
+ */
+export declare function extractPatternsFromGherkin(scannedFiles: readonly ScannedGherkinFile[], config: GherkinExtractorConfig): GherkinExtractionResult;
+/**
+ * Infer behavior file path from timeline feature file path using convention
+ *
+ * Convention: `timeline/phase-N[suffix]-name.feature` → `behavior/name.feature`
+ *
+ * Handles edge cases:
+ * - `phase-37-remaining-work-enhancement.feature` → `remaining-work-enhancement.feature`
+ * - `phase-02b-enhanced-dogfooding.feature` → `enhanced-dogfooding.feature`
+ * - `phase-03-watch-mode.feature` → `watch-mode.feature`
+ *
+ * @param timelineFilePath - Relative path to timeline feature file
+ * @returns Inferred behavior file path, or undefined if not a timeline file
+ */
+export declare function inferBehaviorFilePath(timelineFilePath: string): string | undefined;
+/**
+ * Extract patterns from scanned Gherkin feature files (async variant)
+ *
+ * This is the async version of `extractPatternsFromGherkin` that performs
+ * file existence checks asynchronously in parallel, avoiding event loop blocking.
+ *
+ * Use this variant when processing many feature files or when running on
+ * systems with slow disk I/O.
+ *
+ * @param scannedFiles - Array of scanned Gherkin files
+ * @param config - Extractor configuration (requires baseDir for relative paths)
+ * @returns Promise resolving to extracted patterns and validation errors
+ *
+ * @example
+ * ```typescript
+ * const scanResult = await scanGherkinFiles({
+ *   patterns: 'tests/features/roadmap/**\/*.feature'
+ * });
+ *
+ * if (scanResult.ok) {
+ *   const { patterns, errors } = await extractPatternsFromGherkinAsync(
+ *     scanResult.value.files,
+ *     { baseDir: process.cwd() }
+ *   );
+ * }
+ * ```
+ */
+export declare function extractPatternsFromGherkinAsync(scannedFiles: readonly ScannedGherkinFile[], config: GherkinExtractorConfig): Promise<GherkinExtractionResult>;
+/**
+ * Compute children arrays from parent references
+ *
+ * Post-processing step that populates the `children` field on each pattern
+ * by finding all patterns that reference it via their `parent` field.
+ *
+ * This enables bidirectional hierarchy navigation:
+ * - Child → Parent: via `parent` field (explicit in feature file)
+ * - Parent → Children: via `children` field (computed here)
+ *
+ * **Performance Note:** This function does NOT re-validate patterns through
+ * the schema because:
+ * 1. Input patterns have already been validated by extractPatternsFromGherkin()
+ * 2. We're only adding a `children: string[]` field which matches the schema
+ * 3. Re-validation of the complex ExtractedPatternSchema is expensive (~320 lines)
+ *
+ * This invariant is safe because:
+ * - The children array is derived from validated pattern names
+ * - ExtractedPatternSchema.children is defined as `z.array(z.string()).readonly().optional()`
+ *
+ * @param patterns - Array of validated ExtractedPattern objects
+ * @returns New array with `children` populated (does not mutate input)
+ *
+ * @example
+ * ```typescript
+ * const rawPatterns = extractPatternsFromGherkin(files, config);
+ * const patternsWithHierarchy = computeHierarchyChildren(rawPatterns);
+ *
+ * // Now epic patterns have children arrays
+ * const epic = patternsWithHierarchy.find(p => p.level === 'epic');
+ * console.log(epic.children); // ["PhaseA", "PhaseB"]
+ * ```
+ */
+export declare function computeHierarchyChildren(patterns: readonly ExtractedPattern[]): ExtractedPattern[];
+//# sourceMappingURL=gherkin-extractor.d.ts.map

package/dist/extractor/gherkin-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gherkin-extractor.d.ts","sourceRoot":"","sources":["../../src/extractor/gherkin-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAOH,OAAO,KAAK,EACV,kBAAkB,EAGnB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,4CAA4C,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AAMzE,OAAO,EAEL,KAAK,6BAA6B,EACnC,MAAM,oBAAoB,CAAC;AAQ5B;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,2IASzB,CAAC;AA2LX;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,kEAAkE;IAClE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC/C,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,SAAS,6BAA6B,EAAE,CAAC;CAC3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,SAAS,kBAAkB,EAAE,EAC3C,MAAM,EAAE,sBAAsB,GAC7B,uBAAuB,CAgHzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOlF;AA+BD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,+BAA+B,CACnD,YAAY,EAAE,SAAS,kBAAkB,EAAE,EAC3C,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAAC,uBAAuB,CAAC,CA4GlC;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GACpC,gBAAgB,EAAE,CA4BpB"}