@hyperdrive.bot/bmad-workflow 1.0.18 → 1.0.19

package/dist/services/review/severity-classifier.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Severity Classifier
+ *
+ * Pure function that parses raw scanner output from multiple sources
+ * (structured AI, ESLint JSON, tsc errors) into a unified, deduplicated
+ * ClassifiedIssue[] array.
+ *
+ * Design: zero side effects, deterministic output, no I/O.
+ */
+import type { ClassifiedIssue, RawReviewOutput } from './types.js';
+/**
+ * Classify raw review outputs into a unified, deduplicated, deterministically-ordered array.
+ *
+ * @param outputs - Raw scanner outputs to classify
+ * @returns Deduplicated classified issues sorted by severity DESC, file ASC, line ASC
+ */
+export declare function classify(outputs: RawReviewOutput[]): ClassifiedIssue[];

package/dist/services/review/severity-classifier.js

@@ -0,0 +1,314 @@
+/**
+ * Severity Classifier
+ *
+ * Pure function that parses raw scanner output from multiple sources
+ * (structured AI, ESLint JSON, tsc errors) into a unified, deduplicated
+ * ClassifiedIssue[] array.
+ *
+ * Design: zero side effects, deterministic output, no I/O.
+ */
+import { Severity } from './types.js';
+/** Severity rank for sorting (higher = more severe) */
+const SEVERITY_RANK = {
+    [Severity.CRITICAL]: 4,
+    [Severity.HIGH]: 3,
+    [Severity.MEDIUM]: 2,
+    [Severity.LOW]: 1,
+};
+/**
+ * Classify raw review outputs into a unified, deduplicated, deterministically-ordered array.
+ *
+ * @param outputs - Raw scanner outputs to classify
+ * @returns Deduplicated classified issues sorted by severity DESC, file ASC, line ASC
+ */
+export function classify(outputs) {
+    const allIssues = [];
+    for (const output of outputs) {
+        const parsed = parseOutput(output);
+        allIssues.push(...parsed);
+    }
+    const deduped = deduplicate(allIssues);
+    return sortIssues(deduped);
+}
+/**
+ * Route a raw output to the appropriate parser based on source.
+ */
+function parseOutput(output) {
+    const source = output.source.toLowerCase();
+    if (source === 'ai' || source === 'claude-ai' || source === 'coderabbit') {
+        return parseStructuredAI(output.raw);
+    }
+    if (source === 'lint' || source === 'eslint') {
+        return parseEslintJson(output.raw);
+    }
+    if (source === 'tsc' || source === 'typescript') {
+        return parseTscErrors(output.raw);
+    }
+    // Unknown source — attempt structured AI format as fallback
+    return parseStructuredAI(output.raw);
+}
+// ─── Structured AI Format Parser ─────────────────────────────────────────────
+/**
+ * Parse structured AI review output.
+ *
+ * Format: blocks separated by `---`, each containing:
+ *   SEVERITY: HIGH
+ *   FILE: src/foo.ts
+ *   LINE: 42
+ *   ISSUE: Description
+ *   FIX: Suggested fix
+ *
+ * Special case: "REVIEW_PASS: No issues found" → empty array.
+ */
+function parseStructuredAI(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return [];
+    // Check for REVIEW_PASS sentinel
+    if (trimmed.includes('REVIEW_PASS:')) {
+        return [];
+    }
+    const blocks = trimmed.split(/^---$/m).map((b) => b.trim()).filter(Boolean);
+    const issues = [];
+    for (const block of blocks) {
+        const issue = parseStructuredBlock(block);
+        if (issue) {
+            issues.push(issue);
+        }
+    }
+    return issues;
+}
+/**
+ * Parse a single structured AI block into a ClassifiedIssue.
+ * Returns undefined for malformed blocks.
+ */
+function parseStructuredBlock(block) {
+    const severity = extractField(block, 'SEVERITY');
+    const file = extractField(block, 'FILE');
+    const lineStr = extractField(block, 'LINE');
+    const issue = extractField(block, 'ISSUE');
+    const fix = extractField(block, 'FIX');
+    if (!severity || !file || !lineStr || !issue) {
+        return undefined;
+    }
+    const line = Number.parseInt(lineStr, 10);
+    if (Number.isNaN(line)) {
+        return undefined;
+    }
+    const mappedSeverity = mapSeverityString(severity);
+    if (!mappedSeverity) {
+        return undefined;
+    }
+    return {
+        file,
+        ...(fix ? { fix } : {}),
+        issue,
+        line,
+        severity: mappedSeverity,
+    };
+}
+/**
+ * Extract a field value from a structured block line.
+ * e.g., "SEVERITY: HIGH" → "HIGH"
+ */
+function extractField(block, fieldName) {
+    const regex = new RegExp(`^${fieldName}:\\s*(.+)$`, 'mi');
+    const match = regex.exec(block);
+    return match ? match[1].trim() : undefined;
+}
+/**
+ * Map a severity string to the Severity enum.
+ */
+function mapSeverityString(value) {
+    const upper = value.toUpperCase().trim();
+    if (upper === 'CRITICAL')
+        return Severity.CRITICAL;
+    if (upper === 'HIGH')
+        return Severity.HIGH;
+    if (upper === 'MEDIUM')
+        return Severity.MEDIUM;
+    if (upper === 'LOW')
+        return Severity.LOW;
+    return undefined;
+}
+/**
+ * Parse ESLint JSON output.
+ *
+ * Format: array of { filePath, messages: [{ severity, line, message, ruleId }] }
+ * Severity mapping: 2 (error) → HIGH, 1 (warning) → MEDIUM
+ */
+function parseEslintJson(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const issues = [];
+    for (const fileResult of parsed) {
+        const filePath = fileResult.filePath ?? '';
+        const messages = fileResult.messages ?? [];
+        for (const msg of messages) {
+            const severity = mapEslintSeverity(msg.severity);
+            if (!severity)
+                continue;
+            const line = msg.line ?? 0;
+            const ruleId = msg.ruleId ? ` (${msg.ruleId})` : '';
+            const message = msg.message ?? 'Unknown ESLint issue';
+            issues.push({
+                file: filePath,
+                issue: `${message}${ruleId}`,
+                line,
+                severity,
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Map ESLint numeric severity to Severity enum.
+ */
+function mapEslintSeverity(severity) {
+    if (severity === 2)
+        return Severity.HIGH;
+    if (severity === 1)
+        return Severity.MEDIUM;
+    return undefined;
+}
+// ─── tsc Error Format Parser ─────────────────────────────────────────────────
+/**
+ * Regex for tsc error lines:
+ *   file(line,col): error TSxxxx: message
+ */
+const TSC_ERROR_REGEX = /^(.+?)\((\d+),\d+\):\s*error\s+(TS\d+):\s*(.+)$/;
+/**
+ * Parse tsc --noEmit --pretty false output.
+ *
+ * All tsc errors map to HIGH severity.
+ */
+function parseTscErrors(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return [];
+    const lines = trimmed.split('\n');
+    const issues = [];
+    for (const line of lines) {
+        const match = TSC_ERROR_REGEX.exec(line.trim());
+        if (!match)
+            continue;
+        const [, file, lineStr, errorCode, message] = match;
+        const lineNum = Number.parseInt(lineStr, 10);
+        issues.push({
+            file,
+            issue: `${errorCode}: ${message}`,
+            line: lineNum,
+            severity: Severity.HIGH,
+        });
+    }
+    return issues;
+}
+// ─── Deduplication ───────────────────────────────────────────────────────────
+/**
+ * Deduplicate issues by file + line + similar issue text.
+ * When duplicates differ in severity, keep the higher one.
+ * Preserve fix field from whichever duplicate has one.
+ */
+function deduplicate(issues) {
+    const result = [];
+    for (const issue of issues) {
+        const existingIndex = result.findIndex((existing) => existing.file === issue.file && existing.line === issue.line && isSimilarText(existing.issue, issue.issue));
+        if (existingIndex === -1) {
+            result.push({ ...issue });
+        }
+        else {
+            const existing = result[existingIndex];
+            // Keep higher severity
+            if (SEVERITY_RANK[issue.severity] > SEVERITY_RANK[existing.severity]) {
+                existing.severity = issue.severity;
+            }
+            // Preserve fix if the new one has it and existing doesn't
+            if (issue.fix && !existing.fix) {
+                existing.fix = issue.fix;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Check if two issue texts are similar enough to be considered duplicates.
+ *
+ * Strategy: normalize both strings, then check if one is a substring of the other,
+ * or if their Levenshtein distance is less than 30% of the shorter string's length.
+ */
+function isSimilarText(a, b) {
+    const normA = normalizeText(a);
+    const normB = normalizeText(b);
+    if (normA === normB)
+        return true;
+    // Substring check
+    if (normA.includes(normB) || normB.includes(normA))
+        return true;
+    // Levenshtein distance check
+    const shorter = Math.min(normA.length, normB.length);
+    if (shorter === 0)
+        return false;
+    const distance = levenshtein(normA, normB);
+    return distance < shorter * 0.3;
+}
+/**
+ * Normalize text for comparison: lowercase, collapse whitespace, trim.
+ */
+function normalizeText(text) {
+    return text.toLowerCase().replace(/\s+/g, ' ').trim();
+}
+/**
+ * Levenshtein distance between two strings.
+ */
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    // Use two rows instead of full matrix for memory efficiency
+    let prev = new Array(n + 1);
+    let curr = new Array(n + 1);
+    for (let j = 0; j <= n; j++) {
+        prev[j] = j;
+    }
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+        }
+        ;
+        [prev, curr] = [curr, prev];
+    }
+    return prev[n];
+}
+// ─── Sorting ─────────────────────────────────────────────────────────────────
+/**
+ * Sort issues deterministically: severity DESC, file ASC, line ASC.
+ */
+function sortIssues(issues) {
+    return [...issues].sort((a, b) => {
+        // Severity DESC (higher rank first)
+        const severityDiff = SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity];
+        if (severityDiff !== 0)
+            return severityDiff;
+        // File ASC
+        const fileDiff = a.file.localeCompare(b.file);
+        if (fileDiff !== 0)
+            return fileDiff;
+        // Line ASC
+        return a.line - b.line;
+    });
+}

package/dist/services/review/tech-debt-tracker.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Tech Debt Tracker
+ *
+ * Documents MEDIUM-severity issues from AI code reviews as tech debt entries.
+ * Appends entries to story markdown files and aggregates them in session-level
+ * backlog files. Deduplicates by file + line + issue text.
+ */
+import type pino from 'pino';
+import type { ClassifiedIssue } from './types.js';
+/**
+ * Documents MEDIUM-severity issues as tech debt in story files and session backlogs.
+ */
+export declare class TechDebtTracker {
+    private readonly logger;
+    constructor(logger: pino.Logger);
+    /**
+     * Append MEDIUM-severity issues to a story markdown file under a
+     * `### Tech Debt (MEDIUM)` section. Deduplicates against both the
+     * input array and entries already present in the file.
+     *
+     * @param issues - Classified issues (will be filtered to MEDIUM only)
+     * @param storyFile - Absolute path to the story markdown file
+     */
+    appendToStory(issues: ClassifiedIssue[], storyFile: string): Promise<void>;
+    /**
+     * Aggregate MEDIUM-severity issues into a session-level backlog file.
+     * Creates `{sessionDir}/review/tech-debt-backlog.md`.
+     *
+     * @param issues - Classified issues (will be filtered to MEDIUM only)
+     * @param sessionDir - Absolute path to the session directory
+     * @param storyId - Story identifier for grouping (optional)
+     */
+    appendToSession(issues: ClassifiedIssue[], sessionDir: string, storyId?: string): Promise<void>;
+    /**
+     * Remove duplicate issues from the input array.
+     * Key: file + line + issue text.
+     */
+    private deduplicateIssues;
+    /**
+     * Filter issues to only MEDIUM severity.
+     */
+    private filterMedium;
+    /**
+     * Find the end of a markdown section (up to the next heading or EOF).
+     * Returns the index position where new content can be inserted.
+     */
+    private findSectionEnd;
+    /**
+     * Update the total issue count in the backlog header.
+     */
+    private updateTotalCount;
+}

package/dist/services/review/tech-debt-tracker.js

@@ -0,0 +1,245 @@
+/**
+ * Tech Debt Tracker
+ *
+ * Documents MEDIUM-severity issues from AI code reviews as tech debt entries.
+ * Appends entries to story markdown files and aggregates them in session-level
+ * backlog files. Deduplicates by file + line + issue text.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Severity } from './types.js';
+/** Section header used in story markdown files */
+const TECH_DEBT_HEADER = '### Tech Debt (MEDIUM)';
+/** Regex to parse a tech debt entry line: `- **file:line** — description` */
+const ENTRY_REGEX = /^- \*\*(.+?):(\d+)\*\* — (.+)$/;
+/**
+ * Builds a deduplication key from an issue's identifying fields.
+ */
+function deduplicationKey(file, line, issue) {
+    return `${file}:${line}:${issue}`;
+}
+/**
+ * Formats a single ClassifiedIssue as a markdown list entry.
+ */
+function formatEntry(issue) {
+    return `- **${issue.file}:${issue.line}** — ${issue.issue}`;
+}
+/**
+ * Parses existing tech debt entries from markdown content.
+ * Scans the entire document for entry lines matching the bold-path format.
+ * Returns a Set of deduplication keys for entries already present.
+ */
+function parseExistingEntries(content) {
+    const keys = new Set();
+    const lines = content.split('\n');
+    for (const line of lines) {
+        const match = ENTRY_REGEX.exec(line.trim());
+        if (match) {
+            keys.add(deduplicationKey(match[1], Number.parseInt(match[2], 10), match[3]));
+        }
+    }
+    return keys;
+}
+/**
+ * Documents MEDIUM-severity issues as tech debt in story files and session backlogs.
+ */
+export class TechDebtTracker {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Append MEDIUM-severity issues to a story markdown file under a
+     * `### Tech Debt (MEDIUM)` section. Deduplicates against both the
+     * input array and entries already present in the file.
+     *
+     * @param issues - Classified issues (will be filtered to MEDIUM only)
+     * @param storyFile - Absolute path to the story markdown file
+     */
+    async appendToStory(issues, storyFile) {
+        const mediumIssues = this.filterMedium(issues);
+        if (mediumIssues.length === 0) {
+            this.logger.debug('No MEDIUM issues to document in story');
+            return;
+        }
+        const deduplicated = this.deduplicateIssues(mediumIssues);
+        if (deduplicated.length === 0) {
+            return;
+        }
+        let content;
+        try {
+            content = await readFile(storyFile, 'utf-8');
+        }
+        catch {
+            this.logger.warn({ storyFile }, 'Story file not found, creating new file');
+            content = '';
+        }
+        // Deduplicate against existing entries in the file
+        const existingKeys = parseExistingEntries(content);
+        const newIssues = deduplicated.filter((issue) => !existingKeys.has(deduplicationKey(issue.file, issue.line, issue.issue)));
+        if (newIssues.length === 0) {
+            this.logger.debug('All MEDIUM issues already documented in story');
+            return;
+        }
+        const entries = newIssues.map((issue) => formatEntry(issue));
+        if (content.includes(TECH_DEBT_HEADER)) {
+            // Append below existing section
+            const headerIndex = content.indexOf(TECH_DEBT_HEADER);
+            const afterHeader = headerIndex + TECH_DEBT_HEADER.length;
+            const insertionPoint = this.findSectionEnd(content, afterHeader);
+            const before = content.slice(0, insertionPoint);
+            const after = content.slice(insertionPoint);
+            content = before + entries.join('\n') + '\n' + after;
+        }
+        else {
+            // Append new section at end of file
+            const separator = content.endsWith('\n') ? '\n' : '\n\n';
+            content = content + separator + TECH_DEBT_HEADER + '\n' + entries.join('\n') + '\n';
+        }
+        await writeFile(storyFile, content, 'utf-8');
+        this.logger.info({ count: newIssues.length, storyFile }, 'Documented tech debt in story');
+    }
+    /**
+     * Aggregate MEDIUM-severity issues into a session-level backlog file.
+     * Creates `{sessionDir}/review/tech-debt-backlog.md`.
+     *
+     * @param issues - Classified issues (will be filtered to MEDIUM only)
+     * @param sessionDir - Absolute path to the session directory
+     * @param storyId - Story identifier for grouping (optional)
+     */
+    async appendToSession(issues, sessionDir, storyId) {
+        const mediumIssues = this.filterMedium(issues);
+        if (mediumIssues.length === 0) {
+            this.logger.debug('No MEDIUM issues to document in session backlog');
+            return;
+        }
+        const deduplicated = this.deduplicateIssues(mediumIssues);
+        if (deduplicated.length === 0) {
+            return;
+        }
+        const reviewDir = join(sessionDir, 'review');
+        await mkdir(reviewDir, { recursive: true });
+        const backlogPath = join(reviewDir, 'tech-debt-backlog.md');
+        let existingContent = '';
+        try {
+            existingContent = await readFile(backlogPath, 'utf-8');
+        }
+        catch {
+            // File doesn't exist yet — will create
+        }
+        // Deduplicate against existing entries
+        const existingKeys = parseExistingEntries(existingContent);
+        const newIssues = deduplicated.filter((issue) => !existingKeys.has(deduplicationKey(issue.file, issue.line, issue.issue)));
+        if (newIssues.length === 0) {
+            this.logger.debug('All MEDIUM issues already documented in session backlog');
+            return;
+        }
+        const entries = newIssues.map((issue) => formatEntry(issue));
+        let content;
+        if (existingContent.length === 0) {
+            // Create new backlog file with header
+            const timestamp = new Date().toISOString();
+            const lines = [
+                '# Tech Debt Backlog',
+                '',
+                `> Generated: ${timestamp}`,
+                `> Total issues: ${newIssues.length}`,
+                '',
+            ];
+            if (storyId) {
+                lines.push(`## ${storyId}`, '');
+            }
+            lines.push(...entries, '');
+            content = lines.join('\n');
+        }
+        else {
+            // Append to existing backlog
+            let appendContent = '';
+            if (storyId && !existingContent.includes(`## ${storyId}`)) {
+                appendContent = `\n## ${storyId}\n` + entries.join('\n') + '\n';
+            }
+            else if (storyId && existingContent.includes(`## ${storyId}`)) {
+                // Find the story section and append there
+                const sectionIndex = existingContent.indexOf(`## ${storyId}`);
+                const afterSection = sectionIndex + `## ${storyId}`.length;
+                const insertionPoint = this.findSectionEnd(existingContent, afterSection);
+                const before = existingContent.slice(0, insertionPoint);
+                const after = existingContent.slice(insertionPoint);
+                content = before + entries.join('\n') + '\n' + after;
+                // Update total count in header
+                content = this.updateTotalCount(content);
+                await writeFile(backlogPath, content, 'utf-8');
+                this.logger.info({ count: newIssues.length, sessionDir }, 'Appended tech debt to session backlog');
+                return;
+            }
+            else {
+                appendContent = entries.join('\n') + '\n';
+            }
+            content = existingContent + appendContent;
+            // Update total count in header
+            content = this.updateTotalCount(content);
+        }
+        await writeFile(backlogPath, content, 'utf-8');
+        this.logger.info({ count: newIssues.length, sessionDir }, 'Documented tech debt in session backlog');
+    }
+    /**
+     * Remove duplicate issues from the input array.
+     * Key: file + line + issue text.
+     */
+    deduplicateIssues(issues) {
+        const seen = new Set();
+        const result = [];
+        for (const issue of issues) {
+            const key = deduplicationKey(issue.file, issue.line, issue.issue);
+            if (!seen.has(key)) {
+                seen.add(key);
+                result.push(issue);
+            }
+        }
+        return result;
+    }
+    /**
+     * Filter issues to only MEDIUM severity.
+     */
+    filterMedium(issues) {
+        return issues.filter((issue) => issue.severity === Severity.MEDIUM);
+    }
+    /**
+     * Find the end of a markdown section (up to the next heading or EOF).
+     * Returns the index position where new content can be inserted.
+     */
+    findSectionEnd(content, startAfter) {
+        const remaining = content.slice(startAfter);
+        const lines = remaining.split('\n');
+        let offset = startAfter;
+        for (let i = 0; i < lines.length; i++) {
+            // Skip the first line (rest of the header line)
+            if (i === 0) {
+                offset += lines[i].length + 1; // +1 for \n
+                continue;
+            }
+            // Stop at next heading
+            if (/^#{1,3} /.test(lines[i].trim()) && lines[i].trim().length > 0) {
+                return offset;
+            }
+            offset += lines[i].length + 1;
+        }
+        return offset;
+    }
+    /**
+     * Update the total issue count in the backlog header.
+     */
+    updateTotalCount(content) {
+        // Count all entry lines
+        const entryCount = (content.match(ENTRY_REGEX) || []).length;
+        // Note: using regex globally
+        let count = 0;
+        const lines = content.split('\n');
+        for (const line of lines) {
+            if (ENTRY_REGEX.test(line.trim())) {
+                count++;
+            }
+        }
+        return content.replace(/^> Total issues: \d+$/m, `> Total issues: ${count}`);
+    }
+}