@hyperdrive.bot/bmad-workflow 1.0.2

package/dist/services/parsers/prd-parser.d.ts

@@ -0,0 +1,123 @@
+/**
+ * PRD Parser Service
+ *
+ * Extracts epic information from Product Requirements Document (PRD) markdown files.
+ * Supports multiple epic header formats for resilient parsing.
+ *
+ * Supported Formats (in order of precedence):
+ * - ## Epic 1 Title (space-separated, PRIMARY format from prd-tmpl.yaml)
+ * - ## Epic 1: Title (colon-separated)
+ * - ## Epic 1 - Title (dash-separated)
+ * - ## 1: Title (number only with colon)
+ * - ## 1. Title (number with period)
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ namespace: 'parser' })
+ * const parser = new PrdParser(logger)
+ * const epics = parser.parseEpics(prdContent, 'prd.md')
+ * ```
+ */
+import type pino from 'pino';
+/**
+ * Represents an epic extracted from a PRD document
+ */
+export interface Epic {
+    /**
+     * Full number as it appears in source (e.g., "Epic 1", "1")
+     */
+    fullNumber: string;
+    /**
+     * Epic number (1, 2, 3, etc.)
+     */
+    number: number;
+    /**
+     * Position in source document (line number, 0-indexed)
+     */
+    position: number;
+    /**
+     * Epic title extracted from header
+     */
+    title: string;
+}
+/**
+ * PRD Parser Service
+ *
+ * Parses Product Requirements Documents to extract epic information
+ * using multiple resilient patterns for different markdown formats.
+ */
+export declare class PrdParser {
+    private readonly logger;
+    /**
+     * Epic header patterns in order of specificity (most specific first)
+     *
+     * CRITICAL: Pattern order matches prd-tmpl.yaml output format
+     * Template generates: ## Epic 1 Title (space-separated)
+     */
+    private readonly patterns;
+    /**
+     * Create a new PrdParser instance
+     *
+     * @param logger - Logger instance for structured logging
+     */
+    constructor(logger: pino.Logger);
+    /**
+     * Parse epics from PRD content
+     *
+     * Extracts epic information using multiple pattern matching strategies.
+     * Returns epics sorted by their position in the document (natural order).
+     *
+     * Patterns are tried in order of specificity. If a more specific pattern
+     * (containing "Epic" keyword) finds matches, generic number-only patterns
+     * are skipped to avoid false positives from section headers.
+     *
+     * @param prdContent - Full PRD markdown content
+     * @param prdPath - Path to PRD file (for error messages)
+     * @returns Array of Epic objects sorted by document position
+     * @throws {ParserError} When no epics are found in the PRD
+     * @example
+     * ```typescript
+     * const epics = parser.parseEpics(prdContent, 'docs/prd.md')
+     * console.log(`Found ${epics.length} epics`)
+     * ```
+     */
+    parseEpics(prdContent: string, prdPath: string): Epic[];
+    /**
+     * Deduplicate matches that appear at the same position
+     *
+     * When multiple patterns match the same line, keep only the first match.
+     *
+     * @param matches - Array of pattern matches
+     * @returns Deduplicated array of Epic objects
+     */
+    private deduplicateMatches;
+    /**
+     * Find the line number where a match appears
+     *
+     * @param lines - Array of lines from the document
+     * @param matchText - Text to find
+     * @returns Line number (0-indexed)
+     */
+    private findLineNumber;
+    /**
+     * Match a single pattern against PRD content
+     *
+     * @param pattern - Pattern configuration with name and regex
+     * @param pattern.name - Pattern name
+     * @param pattern.regex - Pattern regular expression
+     * @param lines - PRD content split into lines
+     * @param content - Full PRD content
+     * @returns Array of matches for this pattern
+     */
+    private matchPattern;
+    /**
+     * Validate epic numbers for duplicates and sequential order
+     *
+     * Logs warnings for issues but does not throw errors to allow
+     * parsing of imperfect PRDs.
+     *
+     * @param matches - Array of pattern matches
+     * @param prdPath - Path to PRD file (for logging)
+     */
+    private validateEpicNumbers;
+}

package/dist/services/parsers/prd-parser.js

@@ -0,0 +1,286 @@
+/**
+ * PRD Parser Service
+ *
+ * Extracts epic information from Product Requirements Document (PRD) markdown files.
+ * Supports multiple epic header formats for resilient parsing.
+ *
+ * Supported Formats (in order of precedence):
+ * - ## Epic 1 Title (space-separated, PRIMARY format from prd-tmpl.yaml)
+ * - ## Epic 1: Title (colon-separated)
+ * - ## Epic 1 - Title (dash-separated)
+ * - ## 1: Title (number only with colon)
+ * - ## 1. Title (number with period)
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ namespace: 'parser' })
+ * const parser = new PrdParser(logger)
+ * const epics = parser.parseEpics(prdContent, 'prd.md')
+ * ```
+ */
+import { ParserError } from '../../utils/errors.js';
+/**
+ * PRD Parser Service
+ *
+ * Parses Product Requirements Documents to extract epic information
+ * using multiple resilient patterns for different markdown formats.
+ */
+export class PrdParser {
+    logger;
+    /**
+     * Epic header patterns in order of specificity (most specific first)
+     *
+     * CRITICAL: Pattern order matches prd-tmpl.yaml output format
+     * Template generates: ## Epic 1 Title (space-separated)
+     */
+    patterns = [
+        {
+            name: 'Epic N Nested (N. Epic M:)',
+            regex: /^##\s+\d+\.\s+Epic\s+(\d+)\s*:\s*(.+?)$/gim,
+        },
+        {
+            name: 'Epic N: Title',
+            regex: /^##\s+Epic\s+(\d+)\s*:\s*(.+?)$/gim,
+        },
+        {
+            name: 'Epic N - Title',
+            regex: /^##\s+Epic\s+(\d+)\s+-\s+(.+?)$/gim,
+        },
+        {
+            name: 'Epic N Title (space)',
+            regex: /^##\s+Epic\s+(\d+)\s+(?![:-])(.+?)$/gim,
+        },
+        {
+            name: 'N: Title',
+            regex: /^##\s+(\d+)\s*:\s*(.+?)$/gim,
+        },
+        {
+            name: 'N. Title',
+            regex: /^##\s+(\d+)\s*\.\s+(.+?)$/gim,
+        },
+    ];
+    /**
+     * Create a new PrdParser instance
+     *
+     * @param logger - Logger instance for structured logging
+     */
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Parse epics from PRD content
+     *
+     * Extracts epic information using multiple pattern matching strategies.
+     * Returns epics sorted by their position in the document (natural order).
+     *
+     * Patterns are tried in order of specificity. If a more specific pattern
+     * (containing "Epic" keyword) finds matches, generic number-only patterns
+     * are skipped to avoid false positives from section headers.
+     *
+     * @param prdContent - Full PRD markdown content
+     * @param prdPath - Path to PRD file (for error messages)
+     * @returns Array of Epic objects sorted by document position
+     * @throws {ParserError} When no epics are found in the PRD
+     * @example
+     * ```typescript
+     * const epics = parser.parseEpics(prdContent, 'docs/prd.md')
+     * console.log(`Found ${epics.length} epics`)
+     * ```
+     */
+    parseEpics(prdContent, prdPath) {
+        this.logger.info({ prdPath }, 'Parsing epics from PRD');
+        // Split content into lines for position tracking
+        const lines = prdContent.split('\n');
+        // First pass: check if nested format exists (e.g., "## 7. Epic 1:")
+        // If found, "N." format is being used for sections, not epics
+        let hasNestedEpicFormat = false;
+        for (const pattern of this.patterns) {
+            if (pattern.name.includes('Nested')) {
+                const matches = this.matchPattern(pattern, lines, prdContent);
+                if (matches.length > 0) {
+                    hasNestedEpicFormat = true;
+                    break;
+                }
+            }
+        }
+        // Collect matches from all patterns - patterns are ordered by specificity
+        // More specific "Epic N" patterns come first in the array
+        const allMatches = [];
+        for (const pattern of this.patterns) {
+            // Skip "N. Title" pattern if nested format found (N. is used for sections)
+            if (hasNestedEpicFormat && pattern.name === 'N. Title') {
+                this.logger.debug({ patternName: pattern.name }, 'Skipping N. pattern - nested Epic format found in PRD');
+                continue;
+            }
+            const matches = this.matchPattern(pattern, lines, prdContent);
+            if (matches.length > 0) {
+                allMatches.push(...matches);
+                this.logger.debug({ matches: matches.length, patternName: pattern.name }, 'Pattern matched epics');
+            }
+        }
+        // Check if any epics were found
+        if (allMatches.length === 0) {
+            this.logger.error({ prdPath }, 'No epics found in PRD');
+            throw new ParserError('No epics found in PRD. Expected format: `## Epic N: Title` or similar', {
+                filePath: prdPath,
+                suggestion: 'Ensure PRD has epic headers like: ## Epic 1: Foundation',
+            });
+        }
+        // Sort by position (natural document order)
+        allMatches.sort((a, b) => a.position - b.position);
+        // Check for duplicates and non-sequential numbers
+        this.validateEpicNumbers(allMatches, prdPath);
+        // Convert to Epic interface and deduplicate by position
+        const epics = this.deduplicateMatches(allMatches);
+        this.logger.info({ epicCount: epics.length, prdPath }, 'Successfully parsed epics from PRD');
+        return epics;
+    }
+    /**
+     * Deduplicate matches that appear at the same position
+     *
+     * When multiple patterns match the same line, keep only the first match.
+     *
+     * @param matches - Array of pattern matches
+     * @returns Deduplicated array of Epic objects
+     */
+    deduplicateMatches(matches) {
+        const seenPositions = new Set();
+        const epics = [];
+        for (const match of matches) {
+            // Skip if we've already seen this position
+            if (seenPositions.has(match.position)) {
+                this.logger.debug({
+                    epicNumber: match.number,
+                    line: match.position + 1,
+                    patternName: match.patternName,
+                }, 'Skipping duplicate match at same position');
+                continue;
+            }
+            seenPositions.add(match.position);
+            epics.push({
+                fullNumber: match.fullNumber,
+                number: match.number,
+                position: match.position,
+                title: match.title,
+            });
+            this.logger.debug({
+                epicNumber: match.number,
+                line: match.position + 1,
+                patternName: match.patternName,
+                title: match.title,
+            }, 'Epic matched successfully');
+        }
+        return epics;
+    }
+    /**
+     * Find the line number where a match appears
+     *
+     * @param lines - Array of lines from the document
+     * @param matchText - Text to find
+     * @returns Line number (0-indexed)
+     */
+    findLineNumber(lines, matchText) {
+        for (const [i, line] of lines.entries()) {
+            if (line.includes(matchText.trim())) {
+                return i;
+            }
+        }
+        return 0; // Fallback to start of document
+    }
+    /**
+     * Match a single pattern against PRD content
+     *
+     * @param pattern - Pattern configuration with name and regex
+     * @param pattern.name - Pattern name
+     * @param pattern.regex - Pattern regular expression
+     * @param lines - PRD content split into lines
+     * @param content - Full PRD content
+     * @returns Array of matches for this pattern
+     */
+    matchPattern(pattern, lines, content) {
+        const matches = [];
+        const regex = new RegExp(pattern.regex.source, pattern.regex.flags);
+        let match;
+        // Reset regex state
+        regex.lastIndex = 0;
+        // Execute regex and collect all matches
+        while ((match = regex.exec(content)) !== null) {
+            const epicNumber = Number.parseInt(match[1], 10);
+            const epicTitle = match[2].trim();
+            const fullMatch = match[0];
+            // Find line number of this match
+            const position = this.findLineNumber(lines, fullMatch);
+            // Extract fullNumber based on pattern type
+            let fullNumber;
+            if (pattern.name.includes('Nested')) {
+                // For nested format "## N. Epic M:", use "Epic M"
+                fullNumber = `Epic ${epicNumber}`;
+            }
+            else if (pattern.name.startsWith('Epic N')) {
+                // For Epic patterns, use "Epic N"
+                fullNumber = `Epic ${epicNumber}`;
+            }
+            else {
+                // For generic patterns, extract from match
+                fullNumber = fullMatch
+                    .replace(/^##\s*/, '')
+                    .split(/[:-]/)[0]
+                    .trim();
+            }
+            matches.push({
+                fullNumber,
+                number: epicNumber,
+                patternName: pattern.name,
+                position,
+                title: epicTitle,
+            });
+        }
+        return matches;
+    }
+    /**
+     * Validate epic numbers for duplicates and sequential order
+     *
+     * Logs warnings for issues but does not throw errors to allow
+     * parsing of imperfect PRDs.
+     *
+     * @param matches - Array of pattern matches
+     * @param prdPath - Path to PRD file (for logging)
+     */
+    validateEpicNumbers(matches, prdPath) {
+        // Check for duplicate numbers
+        const numberCounts = new Map();
+        const numberPositions = new Map();
+        for (const match of matches) {
+            const count = numberCounts.get(match.number) || 0;
+            numberCounts.set(match.number, count + 1);
+            const positions = numberPositions.get(match.number) || [];
+            positions.push(match.position);
+            numberPositions.set(match.number, positions);
+        }
+        // Log warnings for duplicates
+        for (const [number, count] of numberCounts.entries()) {
+            if (count > 1) {
+                const positions = numberPositions.get(number) || [];
+                this.logger.warn({
+                    epicNumber: number,
+                    lines: positions.map((p) => p + 1), // Convert to 1-indexed for user display
+                    occurrences: count,
+                    prdPath,
+                }, 'Duplicate epic number found');
+            }
+        }
+        // Check for non-sequential numbers
+        const uniqueNumbers = [...new Set(matches.map((m) => m.number))].sort((a, b) => a - b);
+        for (let i = 1; i < uniqueNumbers.length; i++) {
+            const current = uniqueNumbers[i];
+            const previous = uniqueNumbers[i - 1];
+            if (current !== previous + 1) {
+                this.logger.warn({
+                    expected: previous + 1,
+                    found: current,
+                    prdPath,
+                }, 'Epic numbers are not sequential');
+            }
+        }
+    }
+}

package/dist/services/parsers/standalone-story-parser.d.ts

@@ -0,0 +1,114 @@
+/**
+ * StandaloneStoryParser Service
+ *
+ * Parses standalone story files that don't follow the epic.story numbering pattern.
+ * Supports stories like JIRA tickets, bug fixes, and ad-hoc tasks.
+ *
+ * Examples:
+ * - JIRA-SIGN-10.md
+ * - bugfix-auth-timeout.md
+ * - feature-dark-mode.md
+ */
+import type pino from 'pino';
+import type { StandaloneStoryMetadata, StoryStatus } from '../../models/story.js';
+import type { FileManager } from '../file-system/file-manager.js';
+/**
+ * StandaloneStoryParser service for parsing non-epic stories
+ *
+ * Provides methods to parse standalone story files that don't follow
+ * the epic.story numbering convention. Uses filename as unique ID and
+ * optionally extracts category/prefix.
+ */
+export declare class StandaloneStoryParser {
+    /**
+     * FileManager instance for file operations
+     */
+    private readonly fileManager;
+    /**
+     * Logger instance for parsing operations
+     */
+    private readonly logger;
+    /**
+     * Create a new StandaloneStoryParser instance
+     *
+     * @param fileManager - FileManager service for file operations
+     * @param logger - Pino logger instance for logging parsing operations
+     * @example
+     * const logger = createLogger({ namespace: 'services:parsers:standalone-story' })
+     * const fileManager = new FileManager(logger)
+     * const parser = new StandaloneStoryParser(fileManager, logger)
+     */
+    constructor(fileManager: FileManager, logger: pino.Logger);
+    /**
+     * Parse standalone story metadata from a story file
+     *
+     * Extracts ID from filename, optional category/prefix, title from H1 header,
+     * and status from either inline or section-based format. Does not require
+     * epic.story numbering pattern.
+     *
+     * @param storyPath - Path to the story markdown file
+     * @returns Standalone story metadata with ID, title, status, and optional category
+     * @throws If file cannot be read
+     * @throws {ParserError} If story structure is invalid (missing title, missing status)
+     * @example
+     * const metadata = await parser.parseStoryMetadata('docs/stories/JIRA-SIGN-10.md')
+     * console.log(metadata.id) // "JIRA-SIGN-10"
+     * console.log(metadata.category) // "JIRA-SIGN"
+     * console.log(metadata.type) // "standalone"
+     */
+    parseStoryMetadata(storyPath: string): Promise<StandaloneStoryMetadata>;
+    /**
+     * Update story status in a standalone story file
+     *
+     * Reads the story file, detects the current status format (inline or section-based),
+     * and updates the status value while preserving the original format.
+     *
+     * @param storyPath - Path to the story markdown file
+     * @param newStatus - New status value to set
+     * @throws If file cannot be read or written
+     * @throws {ParserError} If status format cannot be detected
+     * @example
+     * await parser.updateStoryStatus('docs/stories/JIRA-SIGN-10.md', 'Done')
+     */
+    updateStoryStatus(storyPath: string, newStatus: StoryStatus): Promise<void>;
+    /**
+     * Detect status format (inline vs section-based) and extract current status
+     *
+     * @param content - Story file content
+     * @param storyPath - Path to story file (for error context)
+     * @returns Object with format type and old status value
+     * @throws {ParserError} If status format cannot be detected
+     */
+    private detectStatusFormat;
+    /**
+     * Extract unique ID and optional category from filename
+     *
+     * Parses filename to create a unique ID (filename without extension)
+     * and optionally extracts category prefix. Supports patterns like:
+     * - JIRA-SIGN-10.md → id: "JIRA-SIGN-10", category: "JIRA-SIGN"
+     * - bugfix-auth.md → id: "bugfix-auth", category: "bugfix"
+     * - simple-task.md → id: "simple-task", category: undefined
+     *
+     * @param storyPath - Path to the story file
+     * @returns Object with id and optional category
+     */
+    private extractIdAndCategory;
+    /**
+     * Extract story status using multiple pattern strategies
+     *
+     * @param content - Story file content
+     * @param storyPath - Path to story file (for error context)
+     * @returns Extracted status value
+     * @throws {ParserError} If status cannot be found
+     */
+    private extractStatus;
+    /**
+     * Extract story title from H1 header
+     *
+     * @param content - Story file content
+     * @param storyPath - Path to story file (for error context)
+     * @returns Extracted title
+     * @throws {ParserError} If H1 header is not found
+     */
+    private extractTitle;
+}