@hyperdrive.bot/bmad-workflow 1.0.18 → 1.0.19

package/dist/services/review/review-phase-executor.js

@@ -0,0 +1,152 @@
+/**
+ * Review Phase Executor
+ *
+ * Orchestrates automated code review on completed stories. Runs scanners
+ * via SelfHealLoop, classifies issues, tracks tech debt, and produces
+ * PASS/FAIL verdicts per story.
+ *
+ * The interface is consumed by WorkflowOrchestrator for both sequential
+ * and pipelined review execution paths. The concrete implementation
+ * (DefaultReviewPhaseExecutor) composes SelfHealLoop and TechDebtTracker.
+ */
+import { Severity } from './types.js';
+/** Default severity threshold that blocks the pipeline */
+const DEFAULT_BLOCK_ON = Severity.HIGH;
+/** Severity rank for comparison (higher = more severe) */
+const SEVERITY_RANK = {
+    [Severity.CRITICAL]: 4,
+    [Severity.HIGH]: 3,
+    [Severity.MEDIUM]: 2,
+    [Severity.LOW]: 1,
+};
+/**
+ * Concrete implementation of ReviewPhaseExecutor.
+ *
+ * Composes SelfHealLoop (scan + classify + fix) and TechDebtTracker
+ * (MEDIUM issues → story file / session backlog). Accepts dependencies
+ * via constructor injection for testability.
+ */
+export class DefaultReviewPhaseExecutor {
+    logger;
+    reporter;
+    selfHealLoop;
+    techDebtTracker;
+    constructor(selfHealLoop, techDebtTracker, logger, reporter) {
+        this.selfHealLoop = selfHealLoop;
+        this.techDebtTracker = techDebtTracker;
+        this.logger = logger;
+        this.reporter = reporter;
+    }
+    /**
+     * Review a single story using the self-heal loop.
+     *
+     * @param story - Story to review
+     * @param config - Workflow configuration
+     * @returns ReviewResult with verdict and issues
+     */
+    async reviewStory(story, config) {
+        const storyId = story.fullNumber;
+        const storyFile = story.filePath ?? '';
+        const blockOn = config.reviewBlockOn ?? DEFAULT_BLOCK_ON;
+        this.logger.info({ storyId, blockOn }, 'Reviewing story');
+        const context = {
+            baseBranch: 'main',
+            changedFiles: [],
+            projectRoot: config.cwd ?? process.cwd(),
+            referenceFiles: config.references ?? [],
+            storyFile,
+            storyId,
+        };
+        // Run self-heal loop (scan → classify → fix → rescan)
+        const result = await this.selfHealLoop.execute(context);
+        // Override verdict based on config.reviewBlockOn threshold
+        const blockingIssues = result.issues.filter((issue) => SEVERITY_RANK[issue.severity] >= SEVERITY_RANK[blockOn]);
+        const verdict = blockingIssues.length > 0 ? 'FAIL' : 'PASS';
+        // Track MEDIUM issues as tech debt
+        if (storyFile) {
+            await this.techDebtTracker.appendToStory(result.issues, storyFile);
+        }
+        // Build final result early so reporter gets the enriched result
+        const finalResult = {
+            issues: result.issues,
+            iterations: result.iterations,
+            message: verdict === 'FAIL'
+                ? `${blockingIssues.length} blocking issue(s) (>= ${blockOn}) remain after ${result.iterations} iteration(s)`
+                : result.message,
+            verdict,
+        };
+        // Append review report to story file
+        if (this.reporter && storyFile) {
+            await this.reporter.appendStoryReport(storyFile, finalResult);
+        }
+        if (verdict === 'FAIL') {
+            this.logger.warn({
+                blockingCount: blockingIssues.length,
+                iterations: result.iterations,
+                storyId,
+                verdict,
+            }, `Story ${storyId} review FAILED — ${blockingIssues.length} blocking issue(s) remain`);
+        }
+        else {
+            this.logger.info({ iterations: result.iterations, storyId, verdict }, `Story ${storyId} review PASSED`);
+        }
+        return finalResult;
+    }
+    /**
+     * Review all stories and return a map of storyId → ReviewResult.
+     *
+     * Only stories with verdict PASS are considered passing. FAIL stories
+     * are logged with a warning including failure reasons.
+     *
+     * @param stories - Story file paths to review
+     * @param config - Workflow configuration
+     * @returns Map of story identifier to ReviewResult
+     */
+    async reviewAll(stories, config) {
+        const results = new Map();
+        if (stories.length === 0) {
+            this.logger.info('No stories to review');
+            return results;
+        }
+        this.logger.info({ storyCount: stories.length }, 'Starting review for all stories');
+        for (const storyFile of stories) {
+            const storyId = this.extractStoryId(storyFile);
+            const story = {
+                epicNumber: 0,
+                filePath: storyFile,
+                fullNumber: storyId,
+                number: 0,
+                title: storyId,
+            };
+            const result = await this.reviewStory(story, config);
+            results.set(storyId, result);
+        }
+        // Log summary
+        let passCount = 0;
+        let failCount = 0;
+        for (const [storyId, result] of results) {
+            if (result.verdict === 'PASS') {
+                passCount++;
+            }
+            else {
+                failCount++;
+                this.logger.warn({ reason: result.message, storyId }, 'Story excluded from QA — review FAILED');
+            }
+        }
+        this.logger.info({ failCount, passCount, totalStories: stories.length }, 'Review phase complete');
+        // Write session-level reports (reporter handles undefined sessionDir gracefully)
+        if (this.reporter) {
+            const sessionDir = config.sessionDir;
+            await this.reporter.writeSessionReports(sessionDir, results);
+        }
+        return results;
+    }
+    /**
+     * Extract a story identifier from a file path.
+     * e.g. "docs/stories/PROJ-story-1.001.md" → "PROJ-story-1.001"
+     */
+    extractStoryId(filePath) {
+        const filename = filePath.split('/').pop() ?? filePath;
+        return filename.replace(/\.md$/, '');
+    }
+}

package/dist/services/review/review-queue.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Review Queue
+ *
+ * FIFO queue for coordinating pipelined review execution. Dev workers enqueue
+ * completed stories; review workers dequeue and process them. Supports concurrent
+ * consumers with async waiting when queue is empty.
+ *
+ * Lifecycle:
+ *   Producer: dev workers → enqueue(story) on successful dev completion
+ *   Consumer: review workers → dequeue() to process stories for review
+ *   Close: when all dev workers finish → close() → consumers drain → terminate
+ *
+ * @example
+ * ```typescript
+ * import pino from 'pino'
+ * import { ReviewQueue } from './review-queue.js'
+ *
+ * const logger = pino()
+ * const queue = new ReviewQueue(logger)
+ *
+ * // Dev worker: enqueue completed story
+ * queue.enqueue(story)
+ *
+ * // Review worker: dequeue story for review
+ * const story = await queue.dequeue()
+ * if (story === null) {
+ *   // Queue is closed and empty
+ *   return
+ * }
+ *
+ * // When all dev workers finish, close the queue
+ * queue.close()
+ * ```
+ */
+import type pino from 'pino';
+import type { Story } from '../../models/story.js';
+/**
+ * FIFO queue for pipelined review coordination.
+ *
+ * Provides async waiting for consumers when queue is empty. Safe for concurrent
+ * access in Node.js event loop (no mutex needed due to single-threaded execution).
+ */
+export declare class ReviewQueue {
+    /**
+     * Flag indicating no more stories will be added
+     */
+    private closed;
+    /**
+     * Structured logger instance
+     */
+    private readonly logger;
+    /**
+     * Internal FIFO queue of stories
+     */
+    private queue;
+    /**
+     * Array of waiting dequeue promises
+     */
+    private waiters;
+    /**
+     * Creates a new ReviewQueue instance
+     *
+     * @param logger - Pino logger for structured logging
+     */
+    constructor(logger: pino.Logger);
+    /**
+     * Signals that no more stories will be added to the queue.
+     * All waiting dequeue calls will be resolved with null.
+     */
+    close(): void;
+    /**
+     * Removes and returns the next story from the queue.
+     * If queue is empty and not closed, waits asynchronously for a story to be enqueued.
+     * If queue is closed and empty, returns null.
+     *
+     * @returns Promise that resolves to the next story, or null if queue is closed and empty
+     */
+    dequeue(): Promise<null | Story>;
+    /**
+     * Adds a story to the queue
+     *
+     * @param story - The story to enqueue
+     * @throws Error if queue is already closed
+     */
+    enqueue(story: Story): void;
+    /**
+     * Gets the number of pending stories in the queue
+     *
+     * @returns Number of stories waiting to be dequeued
+     */
+    getPendingCount(): number;
+    /**
+     * Checks if the queue is empty
+     *
+     * @returns true if queue has no items, false otherwise
+     */
+    isEmpty(): boolean;
+}

package/dist/services/review/review-queue.js

@@ -0,0 +1,174 @@
+/**
+ * Review Queue
+ *
+ * FIFO queue for coordinating pipelined review execution. Dev workers enqueue
+ * completed stories; review workers dequeue and process them. Supports concurrent
+ * consumers with async waiting when queue is empty.
+ *
+ * Lifecycle:
+ *   Producer: dev workers → enqueue(story) on successful dev completion
+ *   Consumer: review workers → dequeue() to process stories for review
+ *   Close: when all dev workers finish → close() → consumers drain → terminate
+ *
+ * @example
+ * ```typescript
+ * import pino from 'pino'
+ * import { ReviewQueue } from './review-queue.js'
+ *
+ * const logger = pino()
+ * const queue = new ReviewQueue(logger)
+ *
+ * // Dev worker: enqueue completed story
+ * queue.enqueue(story)
+ *
+ * // Review worker: dequeue story for review
+ * const story = await queue.dequeue()
+ * if (story === null) {
+ *   // Queue is closed and empty
+ *   return
+ * }
+ *
+ * // When all dev workers finish, close the queue
+ * queue.close()
+ * ```
+ */
+/**
+ * FIFO queue for pipelined review coordination.
+ *
+ * Provides async waiting for consumers when queue is empty. Safe for concurrent
+ * access in Node.js event loop (no mutex needed due to single-threaded execution).
+ */
+export class ReviewQueue {
+    /**
+     * Flag indicating no more stories will be added
+     */
+    closed = false;
+    /**
+     * Structured logger instance
+     */
+    logger;
+    /**
+     * Internal FIFO queue of stories
+     */
+    queue = [];
+    /**
+     * Array of waiting dequeue promises
+     */
+    waiters = [];
+    /**
+     * Creates a new ReviewQueue instance
+     *
+     * @param logger - Pino logger for structured logging
+     */
+    constructor(logger) {
+        this.logger = logger;
+        this.logger.debug('ReviewQueue initialized');
+    }
+    /**
+     * Signals that no more stories will be added to the queue.
+     * All waiting dequeue calls will be resolved with null.
+     */
+    close() {
+        if (this.closed) {
+            this.logger.warn('Close called on already closed ReviewQueue');
+            return;
+        }
+        this.closed = true;
+        this.logger.info({
+            remainingQueueSize: this.queue.length,
+            waitersToNotify: this.waiters.length,
+        }, 'ReviewQueue closed');
+        // Wake up all waiting dequeue calls with null
+        while (this.waiters.length > 0) {
+            const waiter = this.waiters.shift();
+            if (waiter) {
+                waiter(null);
+            }
+        }
+    }
+    /**
+     * Removes and returns the next story from the queue.
+     * If queue is empty and not closed, waits asynchronously for a story to be enqueued.
+     * If queue is closed and empty, returns null.
+     *
+     * @returns Promise that resolves to the next story, or null if queue is closed and empty
+     */
+    async dequeue() {
+        // If queue has items, return immediately
+        if (this.queue.length > 0) {
+            const story = this.queue.shift() ?? null;
+            this.logger.info({
+                remainingQueueSize: this.queue.length,
+                storyNumber: story?.fullNumber,
+                storyTitle: story?.title,
+            }, 'Story dequeued from ReviewQueue');
+            return story;
+        }
+        // If closed and empty, return null
+        if (this.closed) {
+            this.logger.debug({
+                closed: this.closed,
+                isEmpty: true,
+            }, 'ReviewQueue dequeue returning null: queue closed and empty');
+            return null;
+        }
+        // Wait for item or close
+        this.logger.debug({
+            closed: this.closed,
+            isEmpty: this.isEmpty(),
+            waiters: this.waiters.length,
+        }, 'ReviewQueue dequeue waiting for story');
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+    /**
+     * Adds a story to the queue
+     *
+     * @param story - The story to enqueue
+     * @throws Error if queue is already closed
+     */
+    enqueue(story) {
+        if (this.closed) {
+            const error = new Error('Cannot enqueue to closed ReviewQueue');
+            this.logger.error({
+                closed: this.closed,
+                storyNumber: story.fullNumber,
+            }, 'ReviewQueue enqueue failed: queue closed');
+            throw error;
+        }
+        this.queue.push(story);
+        this.logger.info({
+            queueSize: this.queue.length,
+            storyNumber: story.fullNumber,
+            storyTitle: story.title,
+            waiters: this.waiters.length,
+        }, 'Story enqueued to ReviewQueue');
+        // Wake up a waiting dequeue call if any
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            const dequeuedStory = this.queue.shift() ?? null;
+            this.logger.debug({
+                remainingQueueSize: this.queue.length,
+                storyNumber: dequeuedStory?.fullNumber,
+            }, 'Woke up waiting ReviewQueue dequeue consumer');
+            waiter(dequeuedStory);
+        }
+    }
+    /**
+     * Gets the number of pending stories in the queue
+     *
+     * @returns Number of stories waiting to be dequeued
+     */
+    getPendingCount() {
+        return this.queue.length;
+    }
+    /**
+     * Checks if the queue is empty
+     *
+     * @returns true if queue has no items, false otherwise
+     */
+    isEmpty() {
+        return this.queue.length === 0;
+    }
+}

package/dist/services/review/review-reporter.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Review Reporter
+ *
+ * Generates review report artifacts: per-story markdown appended to story files,
+ * and session-level aggregate reports (summary + tech debt backlog + per-story
+ * review files) written to the workflow session directory.
+ *
+ * Consumed by ReviewPhaseExecutor (after each story) and the standalone
+ * `stories review` command.
+ */
+import type pino from 'pino';
+import type { FileManager } from '../file-system/file-manager.js';
+import type { ReviewResult } from './types.js';
+/**
+ * Generates review report markdown for stories and session directories.
+ *
+ * Follows DI pattern from WorkflowSessionScaffolder: FileManager + Logger.
+ */
+export declare class ReviewReporter {
+    private readonly fileManager;
+    private readonly logger;
+    constructor(fileManager: FileManager, logger: pino.Logger);
+    /**
+     * Append a `## Code Review Results` section to a story markdown file.
+     * Inserts before `## Dev Agent Record` if present, otherwise appends at end.
+     *
+     * Always works regardless of session mode (AC #8).
+     *
+     * @param storyFilePath - Absolute path to the story markdown file
+     * @param result - ReviewResult from the review phase
+     */
+    appendStoryReport(storyFilePath: string, result: ReviewResult): Promise<void>;
+    /**
+     * Write all session-level review artifacts to the session directory.
+     * Creates `review/` subdirectory containing per-story files, summary, and tech debt backlog.
+     *
+     * When sessionDir is undefined/null, silently returns (AC #8 — standalone mode guard).
+     *
+     * @param sessionDir - Absolute path to the workflow session directory, or undefined
+     * @param results - Map of storyId → ReviewResult
+     */
+    writeSessionReports(sessionDir: string | undefined, results: Map<string, ReviewResult>): Promise<void>;
+    /**
+     * Format the per-story review report block to be appended to a story file.
+     *
+     * @param result - ReviewResult for the story
+     * @returns Markdown string for the review section
+     */
+    formatStoryReport(result: ReviewResult): string;
+    /**
+     * Format the session-level review summary markdown.
+     *
+     * @param results - Map of storyId → ReviewResult
+     * @returns Complete markdown content for review-summary.md
+     */
+    formatSessionSummary(results: Map<string, ReviewResult>): string;
+    /**
+     * Format the session-level tech debt backlog markdown.
+     * Aggregates all MEDIUM-severity issues across all stories, grouped by file path.
+     *
+     * @param results - Map of storyId → ReviewResult
+     * @returns Complete markdown content for tech-debt-backlog.md
+     */
+    formatTechDebtBacklog(results: Map<string, ReviewResult>): string;
+    /**
+     * Format an expanded per-story review file for the session review/ directory.
+     * More detailed than the appended story report — includes full issue details.
+     *
+     * @param storyId - Story identifier
+     * @param result - ReviewResult for the story
+     * @returns Complete markdown content for the per-story review file
+     */
+    formatStoryReviewFile(storyId: string, result: ReviewResult): string;
+    /**
+     * Group classified issues by severity.
+     */
+    private groupBySeverity;
+    /**
+     * Determine the action column text for a severity row in the findings summary table.
+     */
+    private determineSeverityAction;
+    /**
+     * Extract scanner list from a ReviewResult.
+     * Since ReviewResult doesn't carry scanner names directly, derive from issue sources
+     * or return a default.
+     */
+    private extractScannerList;
+    /**
+     * Extract the story number portion from a story ID.
+     * e.g., "PROJ-story-1.001" → "1.001"
+     * e.g., "BMAD-ENHANCED-AUTOMATED-CODE-REVIEW-story-3.006" → "3.006"
+     */
+    private extractStoryNum;
+}