@jokerized/getresearchdone 0.4.1

package/dist/lib/refinement.js

@@ -0,0 +1,283 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectMetrics = collectMetrics;
+exports.detectMinima = detectMinima;
+exports.checkConvergence = checkConvergence;
+exports.classifyBranch = classifyBranch;
+exports.buildCritiquePrompt = buildCritiquePrompt;
+/**
+ * Collect quantitative metrics from npm test, tsc, and eslint output.
+ *
+ * @param testOutput - Raw stdout from `npm test` (Jest output with coverage table)
+ * @param tscOutput - Raw stdout/stderr from `tsc --noEmit`
+ * @param lintOutput - Raw stdout from `eslint`
+ * @returns RefinementMetrics with current ISO timestamp
+ */
+function collectMetrics(testOutput, tscOutput, lintOutput) {
+    // Parse test coverage from Jest output: look for "All files" line
+    // Jest coverage table format: | All files | XX.XX | XX.XX | XX.XX | ...
+    let test_coverage_pct = 0;
+    // Jest coverage table "All files" row has 5 columns: File | Stmts | Branch | Funcs | Lines
+    // We want the Lines column (4th numeric value after "All files |")
+    const coverageLineMatch = testOutput.match(/All files\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)\s*\|\s*([\d.]+)\s*\|/);
+    if (coverageLineMatch) {
+        // Group 4 = Lines coverage
+        test_coverage_pct = parseFloat(coverageLineMatch[4]) || 0;
+    }
+    else {
+        // Fallback: look for "Statements" or "Lines" percentage on a summary line
+        const statementsMatch = testOutput.match(/Statements\s*:\s*([\d.]+)%/);
+        if (statementsMatch) {
+            test_coverage_pct = parseFloat(statementsMatch[1]) || 0;
+        }
+        else {
+            // Try "Lines" percentage
+            const linesMatch = testOutput.match(/Lines\s*:\s*([\d.]+)%/);
+            if (linesMatch) {
+                test_coverage_pct = parseFloat(linesMatch[1]) || 0;
+            }
+        }
+    }
+    // Parse type error count from tsc output: count lines matching /error TS\d+/
+    const tscErrorMatches = tscOutput.match(/error TS\d+/g);
+    const type_error_count = tscErrorMatches ? tscErrorMatches.length : 0;
+    // Parse lint violation count from eslint output.
+    // Strategy: count individual violation lines AND check the "N problems" summary.
+    // Take max of both to handle cases where the summary underreports or is absent.
+    // Count individual error/warning lines (indented lines with rule names)
+    const violationLines = lintOutput
+        .split('\n')
+        .filter((line) => /^\s+\d+:\d+\s+(error|warning)\s+/.test(line));
+    const individualCount = violationLines.length;
+    // Check for summary line "N problems"
+    const problemsMatch = lintOutput.match(/(\d+)\s+problems?/);
+    const summaryCount = problemsMatch ? (parseInt(problemsMatch[1], 10) || 0) : 0;
+    const lint_violation_count = Math.max(individualCount, summaryCount);
+    return {
+        test_coverage_pct,
+        type_error_count,
+        lint_violation_count,
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * Detect metric-minima regions from a time series of MetricSnapshot objects.
+ *
+ * For test_coverage_pct: finds local minima (dips where coverage < both neighbors).
+ * For type_error_count and lint_violation_count: finds local maxima (spikes where
+ * count > both neighbors).
+ *
+ * Adapted from NERFIFY PSNR-minima ROI analysis.
+ *
+ * @param snapshots - Ordered array of metric snapshots
+ * @returns Array of MinimaRegion objects sorted by |delta| descending
+ */
+function detectMinima(snapshots) {
+    // Need at least 3 snapshots to detect local minima/maxima (requires both neighbors)
+    if (snapshots.length < 3)
+        return [];
+    const regions = [];
+    for (let i = 1; i < snapshots.length - 1; i++) {
+        const prev = snapshots[i - 1].metrics;
+        const curr = snapshots[i].metrics;
+        const next = snapshots[i + 1].metrics;
+        // Coverage: find local minima (dips)
+        if (curr.test_coverage_pct < prev.test_coverage_pct && curr.test_coverage_pct < next.test_coverage_pct) {
+            const neighborAvg = (prev.test_coverage_pct + next.test_coverage_pct) / 2;
+            const delta = Math.abs(neighborAvg - curr.test_coverage_pct);
+            regions.push({
+                dimension: 'test_coverage_pct',
+                index: i,
+                value: curr.test_coverage_pct,
+                delta,
+            });
+        }
+        // Type errors: find local maxima (spikes)
+        if (curr.type_error_count > prev.type_error_count && curr.type_error_count > next.type_error_count) {
+            const neighborAvg = (prev.type_error_count + next.type_error_count) / 2;
+            const delta = Math.abs(curr.type_error_count - neighborAvg);
+            regions.push({
+                dimension: 'type_error_count',
+                index: i,
+                value: curr.type_error_count,
+                delta,
+            });
+        }
+        // Lint violations: find local maxima (spikes)
+        if (curr.lint_violation_count > prev.lint_violation_count && curr.lint_violation_count > next.lint_violation_count) {
+            const neighborAvg = (prev.lint_violation_count + next.lint_violation_count) / 2;
+            const delta = Math.abs(curr.lint_violation_count - neighborAvg);
+            regions.push({
+                dimension: 'lint_violation_count',
+                index: i,
+                value: curr.lint_violation_count,
+                delta,
+            });
+        }
+    }
+    // Sort by absolute delta descending (worst regions first)
+    return regions.sort((a, b) => b.delta - a.delta);
+}
+/**
+ * Check whether metrics have converged (stopped improving meaningfully).
+ *
+ * @param snapshots - Ordered array of metric snapshots (newest last)
+ * @param config - Convergence thresholds and max iteration cap
+ * @returns { converged: boolean, reason: string }
+ */
+function checkConvergence(snapshots, config) {
+    if (snapshots.length < 2) {
+        return { converged: false, reason: 'insufficient data' };
+    }
+    if (snapshots.length >= config.max_iterations) {
+        return { converged: true, reason: 'max iterations reached' };
+    }
+    const last = snapshots[snapshots.length - 1].metrics;
+    const prev = snapshots[snapshots.length - 2].metrics;
+    // Codex r43 P1 #3: detect the "no real progress" sentinel — when both
+    // snapshots report all zeros, the measurement path is almost
+    // certainly broken (e.g. jest/tsc/eslint never ran, or stdout was
+    // discarded). Don't celebrate this as convergence.
+    const lastAllZero = last.test_coverage_pct === 0 &&
+        last.type_error_count === 0 &&
+        last.lint_violation_count === 0;
+    const prevAllZero = prev.test_coverage_pct === 0 &&
+        prev.type_error_count === 0 &&
+        prev.lint_violation_count === 0;
+    if (lastAllZero && prevAllZero) {
+        return {
+            converged: false,
+            reason: 'no progress (all metrics zero — measurement path likely broken)',
+        };
+    }
+    const deltaCoverage = Math.abs(last.test_coverage_pct - prev.test_coverage_pct);
+    const deltaTypeErrors = Math.abs(last.type_error_count - prev.type_error_count);
+    const deltaLint = Math.abs(last.lint_violation_count - prev.lint_violation_count);
+    const coverageConverged = deltaCoverage < config.epsilon_coverage;
+    const typeErrorsConverged = deltaTypeErrors < config.epsilon_type_errors;
+    const lintConverged = deltaLint < config.epsilon_lint;
+    if (coverageConverged && typeErrorsConverged && lintConverged) {
+        return { converged: true, reason: 'all dimensions within epsilon' };
+    }
+    const stillChanging = [];
+    if (!coverageConverged) {
+        stillChanging.push(`coverage (delta=${deltaCoverage.toFixed(2)}, epsilon=${config.epsilon_coverage})`);
+    }
+    if (!typeErrorsConverged) {
+        stillChanging.push(`type_errors (delta=${deltaTypeErrors}, epsilon=${config.epsilon_type_errors})`);
+    }
+    if (!lintConverged) {
+        stillChanging.push(`lint (delta=${deltaLint}, epsilon=${config.epsilon_lint})`);
+    }
+    return {
+        converged: false,
+        reason: `still changing: ${stillChanging.join(', ')}`,
+    };
+}
+/**
+ * Classify which refinement branch should handle the current metric state.
+ *
+ * Computes normalized gap for each dimension and routes to the branch
+ * with the largest gap to target:
+ * - 'macro': coverage gap is largest (metric-minima guided patching)
+ * - 'geometry': type error gap is largest (structural validation)
+ * - 'generative': lint gap is largest (artifact analysis)
+ *
+ * @param current - Current metric snapshot
+ * @param targets - Target metrics to reach
+ * @returns The CritiqueBranch that should handle refinement
+ */
+function classifyBranch(current, targets) {
+    // Normalized gap for coverage: (target - current) / target; higher = worse (lower coverage)
+    const coverageTarget = targets.test_coverage_pct;
+    const coverageGap = coverageTarget > 0
+        ? Math.max(0, (coverageTarget - current.test_coverage_pct) / coverageTarget)
+        : 0;
+    // Normalized gap for type errors: (current - target) / max(current, 1); higher = worse (more errors)
+    const typeErrorsGap = current.type_error_count > 0
+        ? (current.type_error_count - targets.type_error_count) / Math.max(current.type_error_count, 1)
+        : 0;
+    // Normalized gap for lint: (current - target) / max(current, 1); higher = worse (more violations)
+    const lintGap = current.lint_violation_count > 0
+        ? (current.lint_violation_count - targets.lint_violation_count) / Math.max(current.lint_violation_count, 1)
+        : 0;
+    // Tie-break order: macro > geometry > generative
+    if (coverageGap >= typeErrorsGap && coverageGap >= lintGap) {
+        return 'macro';
+    }
+    if (typeErrorsGap >= lintGap) {
+        return 'geometry';
+    }
+    return 'generative';
+}
+/**
+ * Build a structured critique prompt for the refinement agent.
+ *
+ * @param branch - Which critique branch this prompt is for
+ * @param metrics - Current metrics
+ * @param targets - Target metrics
+ * @param minimaRegions - Top minima regions to surface in the prompt
+ * @returns Formatted prompt string for the critique agent
+ */
+function buildCritiquePrompt(branch, metrics, targets, minimaRegions) {
+    const topRegions = minimaRegions.slice(0, 3);
+    const regionsText = topRegions.length > 0
+        ? topRegions
+            .map((r, i) => `  ${i + 1}. ${r.dimension} at index ${r.index}: value=${r.value}, delta=${r.delta.toFixed(2)}`)
+            .join('\n')
+        : '  (none detected — first iteration or insufficient history)';
+    const branchInstructions = {
+        macro: `Focus on coverage recovery:
+- Identify files with the lowest test coverage
+- Add test cases for uncovered branches and lines
+- Prioritize files that appear in minima regions (coverage dips)
+- High-ROI targets: frequently modified files with low coverage`,
+        geometry: `Focus on type error resolution:
+- Parse tsc error output and categorize errors by type
+- Fix errors starting from leaf modules (no dependents) toward root
+- Check export consistency: every module.exports key has a matching function/const
+- Verify import chains are correct`,
+        generative: `Focus on lint pattern analysis:
+- Cluster ESLint violations by rule
+- Fix violations by cluster (all no-unused-vars together, all no-explicit-any together)
+- Identify code patterns generating violations and refactor the pattern
+- Never disable ESLint rules — fix the code`,
+    };
+    return `CRITIQUE BRANCH: ${branch.toUpperCase()}
+
+## Current Metrics
+
+- test_coverage_pct: ${metrics.test_coverage_pct.toFixed(2)}%
+- type_error_count: ${metrics.type_error_count}
+- lint_violation_count: ${metrics.lint_violation_count}
+- collected_at: ${metrics.timestamp}
+
+## Target Metrics
+
+- test_coverage_pct: ${targets.test_coverage_pct.toFixed(2)}%
+- type_error_count: ${targets.type_error_count}
+- lint_violation_count: ${targets.lint_violation_count}
+
+## Top Minima Regions
+
+${regionsText}
+
+## Branch Instructions
+
+${branchInstructions[branch]}
+
+## Constraints
+
+- Modify at most 5 files per iteration
+- Run npm run build:check after every change to avoid regression
+- Never lower coverage thresholds in jest.config.js
+- Never disable ESLint rules`;
+}
+module.exports = {
+    collectMetrics,
+    detectMinima,
+    checkConvergence,
+    classifyBranch,
+    buildCritiquePrompt,
+};
+//# sourceMappingURL=refinement.js.map

package/dist/lib/refinement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refinement.js","sourceRoot":"","sources":["../../lib/refinement.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAkCb,wCAwDC;AAcD,oCAkDC;AASD,4CA6DC;AAeD,wCA4BC;AAWD,kDA8DC;AA1TD;;;;;;;GAOG;AACH,SAAgB,cAAc,CAC5B,UAAkB,EAClB,SAAiB,EACjB,UAAkB;IAElB,kEAAkE;IAClE,wEAAwE;IACxE,IAAI,iBAAiB,GAAG,CAAC,CAAC;IAC1B,2FAA2F;IAC3F,mEAAmE;IACnE,MAAM,iBAAiB,GAAG,UAAU,CAAC,KAAK,CACxC,gFAAgF,CACjF,CAAC;IACF,IAAI,iBAAiB,EAAE,CAAC;QACtB,2BAA2B;QAC3B,iBAAiB,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC5D,CAAC;SAAM,CAAC;QACN,0EAA0E;QAC1E,MAAM,eAAe,GAAG,UAAU,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;QACvE,IAAI,eAAe,EAAE,CAAC;YACpB,iBAAiB,GAAG,UAAU,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1D,CAAC;aAAM,CAAC;YACN,yBAAyB;YACzB,MAAM,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;YAC7D,IAAI,UAAU,EAAE,CAAC;gBACf,iBAAiB,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACrD,CAAC;QACH,CAAC;IACH,CAAC;IAED,6EAA6E;IAC7E,MAAM,eAAe,GAAG,SAAS,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IACxD,MAAM,gBAAgB,GAAG,eAAe,CAAC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAEtE,iDAAiD;IACjD,iFAAiF;IACjF,gFAAgF;IAEhF,wEAAwE;IACxE,MAAM,cAAc,GAAG,UAAU;SAC9B,KAAK,CAAC,IAAI,CAAC;SACX,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,kCAAkC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACnE,MAAM,eAAe,GAAG,cAAc,CAAC,MAAM,CAAC;IAE9C,sCAAsC;IACtC,MAAM,aAAa,GAAG,UAAU,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;IAC5D,MAAM,YAAY,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE/E,MAAM,oBAAoB,GAAG,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,YAAY,CAAC,CAAC;IAErE,OAAO;QACL,iBAAiB;QACjB,gBAAgB;QAChB,oBAAoB;QACpB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,YAAY,CAAC,SAA2B;IACtD,oFAAoF;IACpF,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,OAAO,GAAmB,EAAE,CAAC;IAEnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;QACtC,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QAClC,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;QAEtC,qCAAqC;QACrC,IAAI,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACvG,MAAM,WAAW,GAAG,CAAC,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;YAC1E,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC;YAC7D,OAAO,CAAC,IAAI,CAAC;gBACX,SAAS,EAAE,mBAAmB;gBAC9B,KAAK,EAAE,CAAC;gBACR,KAAK,EAAE,IAAI,CAAC,iBAAiB;gBAC7B,KAAK;aACN,CAAC,CAAC;QACL,CAAC;QAED,0CAA0C;QAC1C,IAAI,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,IAAI,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACnG,MAAM,WAAW,GAAG,CAAC,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;YACxE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,gBAAgB,GAAG,WAAW,CAAC,CAAC;YAC5D,OAAO,CAAC,IAAI,CAAC;gBACX,SAAS,EAAE,kBAAkB;gBAC7B,KAAK,EAAE,CAAC;gBACR,KAAK,EAAE,IAAI,CAAC,gBAAgB;gBAC5B,KAAK;aACN,CAAC,CAAC;QACL,CAAC;QAED,8CAA8C;QAC9C,IAAI,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC,oBAAoB,IAAI,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC,oBAAoB,EAAE,CAAC;YACnH,MAAM,WAAW,GAAG,CAAC,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,CAAC;YAChF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,oBAAoB,GAAG,WAAW,CAAC,CAAC;YAChE,OAAO,CAAC,IAAI,CAAC;gBACX,SAAS,EAAE,sBAAsB;gBACjC,KAAK,EAAE,CAAC;gBACR,KAAK,EAAE,IAAI,CAAC,oBAAoB;gBAChC,KAAK;aACN,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,0DAA0D;IAC1D,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,gBAAgB,CAC9B,SAA2B,EAC3B,MAAyB;IAEzB,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC3D,CAAC;IAED,IAAI,SAAS,CAAC,MAAM,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;QAC9C,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IAC/D,CAAC;IAED,MAAM,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;IACrD,MAAM,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;IAErD,sEAAsE;IACtE,6DAA6D;IAC7D,kEAAkE;IAClE,mDAAmD;IACnD,MAAM,WAAW,GACf,IAAI,CAAC,iBAAiB,KAAK,CAAC;QAC5B,IAAI,CAAC,gBAAgB,KAAK,CAAC;QAC3B,IAAI,CAAC,oBAAoB,KAAK,CAAC,CAAC;IAClC,MAAM,WAAW,GACf,IAAI,CAAC,iBAAiB,KAAK,CAAC;QAC5B,IAAI,CAAC,gBAAgB,KAAK,CAAC;QAC3B,IAAI,CAAC,oBAAoB,KAAK,CAAC,CAAC;IAClC,IAAI,WAAW,IAAI,WAAW,EAAE,CAAC;QAC/B,OAAO;YACL,SAAS,EAAE,KAAK;YAChB,MAAM,EAAE,iEAAiE;SAC1E,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAChF,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAChF,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,oBAAoB,GAAG,IAAI,CAAC,oBAAoB,CAAC,CAAC;IAElF,MAAM,iBAAiB,GAAG,aAAa,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAClE,MAAM,mBAAmB,GAAG,eAAe,GAAG,MAAM,CAAC,mBAAmB,CAAC;IACzE,MAAM,aAAa,GAAG,SAAS,GAAG,MAAM,CAAC,YAAY,CAAC;IAEtD,IAAI,iBAAiB,IAAI,mBAAmB,IAAI,aAAa,EAAE,CAAC;QAC9D,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,+BAA+B,EAAE,CAAC;IACtE,CAAC;IAED,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACvB,aAAa,CAAC,IAAI,CAAC,mBAAmB,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,MAAM,CAAC,gBAAgB,GAAG,CAAC,CAAC;IACzG,CAAC;IACD,IAAI,CAAC,mBAAmB,EAAE,CAAC;QACzB,aAAa,CAAC,IAAI,CAAC,sBAAsB,eAAe,aAAa,MAAM,CAAC,mBAAmB,GAAG,CAAC,CAAC;IACtG,CAAC;IACD,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,aAAa,CAAC,IAAI,CAAC,eAAe,SAAS,aAAa,MAAM,CAAC,YAAY,GAAG,CAAC,CAAC;IAClF,CAAC;IAED,OAAO;QACL,SAAS,EAAE,KAAK;QAChB,MAAM,EAAE,mBAAmB,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;KACtD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,cAAc,CAC5B,OAA0B,EAC1B,OAA0B;IAE1B,4FAA4F;IAC5F,MAAM,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC;IACjD,MAAM,WAAW,GAAG,cAAc,GAAG,CAAC;QACpC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC,GAAG,cAAc,CAAC;QAC5E,CAAC,CAAC,CAAC,CAAC;IAEN,qGAAqG;IACrG,MAAM,aAAa,GAAG,OAAO,CAAC,gBAAgB,GAAG,CAAC;QAChD,CAAC,CAAC,CAAC,OAAO,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;QAC/F,CAAC,CAAC,CAAC,CAAC;IAEN,kGAAkG;IAClG,MAAM,OAAO,GAAG,OAAO,CAAC,oBAAoB,GAAG,CAAC;QAC9C,CAAC,CAAC,CAAC,OAAO,CAAC,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAC;QAC3G,CAAC,CAAC,CAAC,CAAC;IAEN,iDAAiD;IACjD,IAAI,WAAW,IAAI,aAAa,IAAI,WAAW,IAAI,OAAO,EAAE,CAAC;QAC3D,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,aAAa,IAAI,OAAO,EAAE,CAAC;QAC7B,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,mBAAmB,CACjC,MAAsB,EACtB,OAA0B,EAC1B,OAA0B,EAC1B,aAA6B;IAE7B,MAAM,UAAU,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7C,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC;QACvC,CAAC,CAAC,UAAU;aACP,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,SAAS,aAAa,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9G,IAAI,CAAC,IAAI,CAAC;QACf,CAAC,CAAC,6DAA6D,CAAC;IAElE,MAAM,kBAAkB,GAAmC;QACzD,KAAK,EAAE;;;;gEAIqD;QAE5D,QAAQ,EAAE;;;;mCAIqB;QAE/B,UAAU,EAAE;;;;4CAI4B;KACzC,CAAC;IAEF,OAAO,oBAAoB,MAAM,CAAC,WAAW,EAAE;;;;uBAI1B,OAAO,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;sBACrC,OAAO,CAAC,gBAAgB;0BACpB,OAAO,CAAC,oBAAoB;kBACpC,OAAO,CAAC,SAAS;;;;uBAIZ,OAAO,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;sBACrC,OAAO,CAAC,gBAAgB;0BACpB,OAAO,CAAC,oBAAoB;;;;EAIpD,WAAW;;;;EAIX,kBAAkB,CAAC,MAAM,CAAC;;;;;;;6BAOC,CAAC;AAC9B,CAAC;AAED,MAAM,CAAC,OAAO,GAAG;IACf,cAAc;IACd,YAAY;IACZ,gBAAgB;IAChB,cAAc;IACd,mBAAmB;CACpB,CAAC"}

package/dist/lib/requirements.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=requirements.d.ts.map

package/dist/lib/requirements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirements.d.ts","sourceRoot":"","sources":["../../lib/requirements.ts"],"names":[],"mappings":""}

package/dist/lib/requirements.js

@@ -0,0 +1,355 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = require('fs');
+const path = require('path');
+const { safeReadFile, output, error } = require('./utils');
+const { milestonesDir: getMilestonesDirPath } = require('./paths');
+// Module-level cache for REQUIREMENTS.md reads across command calls.
+// Prevents redundant disk reads when multiple requirement commands access the same file in one process.
+const _reqContentCache = new Map();
+/**
+ * Read REQUIREMENTS.md with per-process caching.
+ */
+function readCachedRequirements(reqFilePath) {
+    if (!_reqContentCache.has(reqFilePath)) {
+        const content = safeReadFile(reqFilePath);
+        if (content !== null)
+            _reqContentCache.set(reqFilePath, content);
+        return content;
+    }
+    return _reqContentCache.get(reqFilePath);
+}
+/**
+ * Parse requirements from REQUIREMENTS.md content into structured array.
+ */
+function parseRequirements(content) {
+    if (!content)
+        return [];
+    const requirements = [];
+    // Split by ### REQ- headings
+    const parts = content.split(/(?=^### REQ-)/m);
+    for (const part of parts) {
+        const headingMatch = part.match(/^### (REQ-\d+):\s*(.+)/m);
+        if (!headingMatch)
+            continue;
+        const id = headingMatch[1];
+        const title = headingMatch[2].trim();
+        const priorityMatch = part.match(/\*\*Priority:\*\*\s*(\S+)/);
+        const categoryMatch = part.match(/\*\*Category:\*\*\s*(.+)/);
+        const deferredMatch = part.match(/\*\*Deferred from:\*\*\s*(.+)/);
+        const resolvesMatch = part.match(/\*\*Resolves:\*\*\s*(.+)/);
+        // Description: everything after the metadata lines, stop at next section heading or separator
+        const lines = part.split('\n');
+        const descLines = [];
+        let pastHeading = false;
+        for (const line of lines) {
+            if (/^### REQ-/.test(line)) {
+                pastHeading = true;
+                continue;
+            }
+            if (!pastHeading)
+                continue;
+            if (/^\*\*(Priority|Category|Deferred from|Resolves):\*\*/.test(line))
+                continue;
+            // Stop at next section heading or separator
+            if (/^##\s/.test(line) || /^---\s*$/.test(line))
+                break;
+            descLines.push(line);
+        }
+        const description = descLines.join('\n').trim();
+        requirements.push({
+            id,
+            title,
+            priority: priorityMatch ? priorityMatch[1].trim() : null,
+            category: categoryMatch ? categoryMatch[1].trim() : null,
+            deferred_from: deferredMatch ? deferredMatch[1].trim() : null,
+            resolves: resolvesMatch ? resolvesMatch[1].trim() : null,
+            description: description || null,
+        });
+    }
+    return requirements;
+}
+/**
+ * Parse the Traceability Matrix table from REQUIREMENTS.md content.
+ */
+function parseTraceabilityMatrix(content) {
+    if (!content)
+        return [];
+    const matrix = [];
+    // Find section starting with ## Traceability Matrix
+    const sectionMatch = content.match(/##\s*Traceability Matrix\s*\n([\s\S]*?)(?=\n---|\n##|$)/i);
+    if (!sectionMatch)
+        return [];
+    const tableContent = sectionMatch[1];
+    const rows = tableContent.split('\n').filter((r) => r.startsWith('|'));
+    // Skip header row and separator row
+    const dataRows = rows.filter((r) => !r.match(/^\|\s*REQ\s*\|/i) && !r.match(/^\|[\s-]+\|/));
+    for (const row of dataRows) {
+        const cells = row
+            .split('|')
+            .map((c) => c.trim())
+            .filter(Boolean);
+        if (cells.length >= 5) {
+            matrix.push({
+                req: cells[0],
+                feature: cells[1],
+                priority: cells[2],
+                phase: cells[3],
+                status: cells[4],
+            });
+        }
+    }
+    return matrix;
+}
+/**
+ * CLI command: Look up a single requirement by ID, returning structured JSON.
+ * Falls back to archived milestone REQUIREMENTS.md files if not in current file.
+ */
+function cmdRequirementGet(cwd, reqId, raw) {
+    const reqFilePath = path.join(cwd, '.planning', 'REQUIREMENTS.md');
+    const content = readCachedRequirements(reqFilePath);
+    // Search current file first
+    if (content) {
+        const requirements = parseRequirements(content);
+        const match = requirements.find((r) => r.id.toLowerCase() === reqId.toLowerCase());
+        if (match) {
+            // Merge status and phase from traceability matrix
+            const matrix = parseTraceabilityMatrix(content);
+            const matrixRow = matrix.find((m) => m.req.toLowerCase() === reqId.toLowerCase());
+            if (matrixRow) {
+                match.status = matrixRow.status;
+                match.phase = matrixRow.phase;
+            }
+            output(match, raw, `${match.id}: ${match.title || ''} [${match.status || 'unknown'}]`);
+            return;
+        }
+    }
+    // Fallback: scan archived milestone REQUIREMENTS.md files
+    const milestonesDir = getMilestonesDirPath(cwd);
+    try {
+        const files = fs
+            .readdirSync(milestonesDir)
+            .filter((f) => f.match(/^v[\d.]+-REQUIREMENTS\.md$/i));
+        for (const file of files) {
+            const filePath = path.join(milestonesDir, file);
+            const archiveContent = safeReadFile(filePath);
+            if (!archiveContent)
+                continue;
+            const archiveReqs = parseRequirements(archiveContent);
+            const match = archiveReqs.find((r) => r.id.toLowerCase() === reqId.toLowerCase());
+            if (match) {
+                // Merge status from archived traceability matrix
+                const matrix = parseTraceabilityMatrix(archiveContent);
+                const matrixRow = matrix.find((m) => m.req.toLowerCase() === reqId.toLowerCase());
+                if (matrixRow) {
+                    match.status = matrixRow.status;
+                    match.phase = matrixRow.phase;
+                }
+                // Extract milestone version from filename
+                const versionMatch = file.match(/^(v[\d.]+)-REQUIREMENTS\.md$/i);
+                match.milestone = versionMatch ? versionMatch[1] : file;
+                output(match, raw, `${match.id}: ${match.title || ''} [${match.status || 'unknown'}]`);
+                return;
+            }
+        }
+    }
+    catch {
+        // milestones directory may not exist
+    }
+    // Not found anywhere
+    output({ error: 'Requirement not found', id: reqId }, raw);
+}
+/**
+ * CLI command: List requirements with optional filters.
+ */
+function cmdRequirementList(cwd, filters, raw) {
+    const f = filters || {};
+    const reqFilePath = path.join(cwd, '.planning', 'REQUIREMENTS.md');
+    const content = readCachedRequirements(reqFilePath);
+    let allReqs = [];
+    if (content) {
+        allReqs = parseRequirements(content);
+        const matrix = parseTraceabilityMatrix(content);
+        // Merge status/phase from matrix into each requirement
+        for (const req of allReqs) {
+            const matrixRow = matrix.find((m) => m.req.toLowerCase() === req.id.toLowerCase());
+            if (matrixRow) {
+                req.status = matrixRow.status;
+                req.phase = matrixRow.phase;
+            }
+        }
+    }
+    // If --all, include archived milestone requirements
+    if (f.all) {
+        const milestonesDir = getMilestonesDirPath(cwd);
+        try {
+            const files = fs
+                .readdirSync(milestonesDir)
+                .filter((fname) => fname.match(/^v[\d.]+-REQUIREMENTS\.md$/i));
+            for (const file of files) {
+                const filePath = path.join(milestonesDir, file);
+                const archiveContent = safeReadFile(filePath);
+                if (!archiveContent)
+                    continue;
+                const archiveReqs = parseRequirements(archiveContent);
+                const archiveMatrix = parseTraceabilityMatrix(archiveContent);
+                const versionMatch = file.match(/^(v[\d.]+)-REQUIREMENTS\.md$/i);
+                const milestone = versionMatch ? versionMatch[1] : file;
+                for (const req of archiveReqs) {
+                    // Skip if already in current file
+                    if (allReqs.find((r) => r.id.toLowerCase() === req.id.toLowerCase()))
+                        continue;
+                    const matrixRow = archiveMatrix.find((m) => m.req.toLowerCase() === req.id.toLowerCase());
+                    if (matrixRow) {
+                        req.status = matrixRow.status;
+                        req.phase = matrixRow.phase;
+                    }
+                    req.milestone = milestone;
+                    allReqs.push(req);
+                }
+            }
+        }
+        catch {
+            // milestones directory may not exist
+        }
+    }
+    // Apply filters (AND logic)
+    let filtered = allReqs;
+    if (f.phase) {
+        filtered = filtered.filter((r) => {
+            if (!r.phase)
+                return false;
+            // Match "Phase N" where N matches filter value
+            const phaseNum = r.phase.match(/(\d+)/);
+            return phaseNum && phaseNum[1] === String(f.phase);
+        });
+    }
+    if (f.priority) {
+        filtered = filtered.filter((r) => r.priority === f.priority);
+    }
+    if (f.status) {
+        filtered = filtered.filter((r) => r.status === f.status);
+    }
+    if (f.category) {
+        filtered = filtered.filter((r) => r.category === f.category);
+    }
+    const filtersApplied = {};
+    if (f.phase)
+        filtersApplied.phase = f.phase;
+    if (f.priority)
+        filtersApplied.priority = f.priority;
+    if (f.status)
+        filtersApplied.status = f.status;
+    if (f.category)
+        filtersApplied.category = f.category;
+    if (f.all)
+        filtersApplied.all = true;
+    const result = {
+        requirements: filtered,
+        count: filtered.length,
+        filters_applied: filtersApplied,
+    };
+    output(result, raw, `${result.count} requirement(s)`);
+}
+/**
+ * CLI command: Return traceability matrix as structured JSON.
+ */
+function cmdRequirementTraceability(cwd, filters, raw) {
+    const f = filters || {};
+    const reqFilePath = path.join(cwd, '.planning', 'REQUIREMENTS.md');
+    const content = readCachedRequirements(reqFilePath);
+    let matrix = [];
+    if (content) {
+        matrix = parseTraceabilityMatrix(content);
+    }
+    // Apply phase filter
+    if (f.phase) {
+        matrix = matrix.filter((row) => {
+            const phaseNum = row.phase.match(/(\d+)/);
+            return phaseNum && phaseNum[1] === String(f.phase);
+        });
+    }
+    const result = { matrix, count: matrix.length };
+    output(result, raw, `${result.count} traceability entries`);
+}
+/** Valid requirement statuses */
+const VALID_REQUIREMENT_STATUSES = [
+    'Pending',
+    'In Progress',
+    'Done',
+    'Deferred',
+];
+/**
+ * CLI command: Update the status of a requirement in the Traceability Matrix.
+ * Validates REQ-ID exists and status is valid before writing.
+ */
+function cmdRequirementUpdateStatus(cwd, reqId, newStatus, raw, dryRun) {
+    // Validate status
+    if (!VALID_REQUIREMENT_STATUSES.includes(newStatus)) {
+        error(`Invalid status "${newStatus}". Valid statuses: ${VALID_REQUIREMENT_STATUSES.join(', ')}`);
+    }
+    const reqFilePath = path.join(cwd, '.planning', 'REQUIREMENTS.md');
+    const content = readCachedRequirements(reqFilePath);
+    if (!content) {
+        error('REQUIREMENTS.md not found');
+    }
+    // Parse traceability matrix to validate REQ-ID exists and get old status
+    const matrix = parseTraceabilityMatrix(content);
+    const matrixRow = matrix.find((m) => m.req.toLowerCase() === reqId.toLowerCase());
+    if (!matrixRow) {
+        error(`Requirement ${reqId} not found in Traceability Matrix. Run "requirement list" to see valid requirement IDs, or check .planning/REQUIREMENTS.md`);
+    }
+    // After the error() calls above (which call process.exit), TypeScript needs
+    // to know matrixRow is defined. The error() function has return type never,
+    // so execution cannot reach here if matrixRow is undefined.
+    const row = matrixRow;
+    const oldStatus = row.status;
+    // Use regex to replace the status cell in the matching row
+    // Escape special regex characters in reqId and oldStatus
+    const escapedReqId = row.req.replace(/[-]/g, '\\-');
+    const escapedOldStatus = oldStatus.replace(/\s+/g, '\\s+');
+    const reqPattern = new RegExp(`^(\\|\\s*${escapedReqId}\\s*\\|.+\\|)\\s*${escapedOldStatus}\\s*(\\|)\\s*$`, 'im');
+    // If old and new status are the same, skip the write but still report success
+    if (oldStatus === newStatus) {
+        output({
+            updated: true,
+            id: row.req,
+            old_status: oldStatus,
+            new_status: newStatus,
+        }, raw);
+        return;
+    }
+    const updatedContent = content.replace(reqPattern, `$1 ${newStatus} $2`);
+    if (updatedContent === content) {
+        error(`Failed to update status for ${reqId} in Traceability Matrix. Ensure the requirement row format matches the expected pattern in .planning/REQUIREMENTS.md`);
+    }
+    if (dryRun) {
+        output({
+            dry_run: true,
+            id: row.req,
+            old_status: oldStatus,
+            new_status: newStatus,
+        }, raw, `dry-run: would update ${reqId} from "${oldStatus}" to "${newStatus}"`);
+        return;
+    }
+    // Write updated content back to disk and invalidate the cache so subsequent reads see the new content
+    fs.writeFileSync(reqFilePath, updatedContent, 'utf-8');
+    _reqContentCache.delete(reqFilePath);
+    output({
+        updated: true,
+        id: row.req,
+        old_status: oldStatus,
+        new_status: newStatus,
+    }, raw);
+}
+module.exports = {
+    readCachedRequirements,
+    parseRequirements,
+    parseTraceabilityMatrix,
+    VALID_REQUIREMENT_STATUSES,
+    cmdRequirementGet,
+    cmdRequirementList,
+    cmdRequirementTraceability,
+    cmdRequirementUpdateStatus,
+};
+//# sourceMappingURL=requirements.js.map