@yasserkhanorg/e2e-agents 0.5.16 → 0.7.0

package/dist/esm/cli.js

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 // Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
 // See LICENSE.txt for license information.
-import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'fs';
+import { appendFileSync, existsSync, readFileSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 import { resolveConfig } from './agent/config.js';
 import { AnthropicProvider } from './anthropic_provider.js';
 import { LLMProviderError } from './provider_interface.js';
-import { runGap, runImpact } from './agent/runner.js';
-import { appendPlanMetrics, attachDeveloperActions, buildPlanFromImpactReport, renderCiSummaryMarkdown, writeCiSummary, writePlanReport, } from './agent/plan.js';
-import { applyOperationalInsights } from './agent/operational_insights.js';
+import { analyzeImpact as analyzeImpactV2 } from './engine/impact_engine.js';
+import { writeCiSummary } from './engine/plan_builder.js';
+import { getChangedFiles } from './agent/git.js';
+import { recommendTestsAI, recommendTestsDeterministic } from './api.js';
 import { appendFeedbackAndRecompute } from './agent/feedback.js';
 import { finalizeGeneratedTests } from './agent/handoff.js';
 import { ingestTraceabilityInput } from './agent/traceability_ingest.js';
@@ -59,13 +60,9 @@ function printUsage() {
     console.log([
         'Usage:',
         '  e2e-ai-agents impact --path <app-root> [options]',
-        '  e2e-ai-agents gap --path <app-root> [options]',
         '  e2e-ai-agents plan --path <app-root> [options]',
-        '  e2e-ai-agents generate --path <app-root> [options]',
-        '  e2e-ai-agents heal --path <app-root> --traceability-report <json> [options]',
         '  e2e-ai-agents suggest --path <app-root> [options]',
-        '  e2e-ai-agents approve-and-generate --path <app-root> [options]',
-        '  e2e-ai-agents auto-heal-pr --path <app-root> [options]',
+        '  e2e-ai-agents heal --path <app-root> --traceability-report <json> [options]',
         '  e2e-ai-agents finalize-generated-tests --path <app-root> [options]',
         '  e2e-ai-agents feedback --path <app-root> --feedback-input <json>',
         '  e2e-ai-agents traceability-capture --path <app-root> --traceability-report <json>',
@@ -144,13 +141,9 @@ function parseArgs(argv) {
     }
     const command = argv[0];
     if (command === 'impact'
-        || command === 'gap'
         || command === 'plan'
-        || command === 'generate'
         || command === 'heal'
         || command === 'suggest'
-        || command === 'approve-and-generate'
-        || command === 'auto-heal-pr'
         || command === 'finalize-generated-tests'
         || command === 'feedback'
         || command === 'traceability-capture'
@@ -500,6 +493,10 @@ function parseArgs(argv) {
             i += 1;
             continue;
         }
+        if (arg === '--no-ai') {
+            parsed.noAi = true;
+            continue;
+        }
     }
     return parsed;
 }
@@ -759,117 +756,6 @@ async function main() {
         }
         return;
     }
-    if (args.command === 'auto-heal-pr') {
-        if (!args.path && !autoConfig) {
-            // eslint-disable-next-line no-console
-            console.error('Error: --path is required for auto-heal-pr command');
-            process.exit(1);
-        }
-        const { config } = resolveConfig(process.cwd(), autoConfig, {
-            path: args.path,
-            profile: args.profile,
-            testsRoot: args.testsRoot,
-            mode: 'gap',
-            framework: args.framework,
-            timeLimitMinutes: args.timeLimitMinutes,
-            budget: {
-                maxUSD: args.budgetUSD,
-                maxTokens: args.budgetTokens,
-            },
-            testPatterns: args.testPatterns,
-            flowPatterns: args.flowPatterns,
-            flowExclude: args.flowExclude,
-            flowCatalogPath: args.flowCatalogPath,
-            specPDF: args.specPDF,
-            gitSince: args.gitSince,
-            pipeline: {
-                enabled: true,
-                scenarios: args.pipelineScenarios,
-                outputDir: args.pipelineOutput,
-                baseUrl: args.pipelineBaseUrl,
-                browser: args.pipelineBrowser,
-                headless: args.pipelineHeadless,
-                project: args.pipelineProject,
-                parallel: args.pipelineParallel,
-                dryRun: args.pipelineDryRun,
-                mcp: args.pipelineMcp,
-                mcpAllowFallback: args.pipelineMcpAllowFallback,
-                mcpOnly: args.pipelineMcpOnly,
-            },
-            llmProvider: args.llmProvider,
-        });
-        if (args.allowFallback) {
-            config.impact.allowFallback = true;
-        }
-        await runGap(config, { apply: true });
-        const reportRoot = config.testsRoot || config.path;
-        if (args.traceabilityReportPath) {
-            const unstableSpecs = extractPlaywrightUnstableSpecs(args.traceabilityReportPath, [reportRoot, config.path]);
-            if (unstableSpecs.length > 0) {
-                const targetedSummary = runTargetedSpecHeal(reportRoot, unstableSpecs.map((spec) => ({
-                    specPath: spec.specPath,
-                    status: spec.status,
-                    reason: `Playwright report: failingTests=${spec.failingTests}, flakyTests=${spec.flakyTests}`,
-                })), {
-                    ...config.pipeline,
-                    enabled: true,
-                    heal: true,
-                });
-                const healedCount = targetedSummary.results.filter((result) => result.healStatus === 'success').length;
-                // eslint-disable-next-line no-console
-                console.log(`Auto-heal targeted unstable specs: ${unstableSpecs.length} (healed=${healedCount})`);
-                if (targetedSummary.warnings.length > 0) {
-                    // eslint-disable-next-line no-console
-                    console.log(`Auto-heal warnings: ${targetedSummary.warnings.join(' | ')}`);
-                }
-                const gapPath = join(reportRoot, '.e2e-ai-agents', 'gap.json');
-                if (existsSync(gapPath)) {
-                    const gap = JSON.parse(readFileSync(gapPath, 'utf-8'));
-                    const existingResults = Array.isArray(gap.pipeline?.results) ? gap.pipeline?.results : [];
-                    const existingWarnings = Array.isArray(gap.pipeline?.warnings) ? gap.pipeline?.warnings : [];
-                    gap.pipeline = {
-                        runner: gap.pipeline?.runner || targetedSummary.runner,
-                        results: [...existingResults, ...targetedSummary.results],
-                        warnings: Array.from(new Set([...(existingWarnings || []), ...targetedSummary.warnings])),
-                    };
-                    writeFileSync(gapPath, `${JSON.stringify(gap, null, 2)}\n`, 'utf-8');
-                }
-            }
-            else {
-                // eslint-disable-next-line no-console
-                console.log('Auto-heal targeted unstable specs: 0');
-            }
-        }
-        const branchSuffix = new Date().toISOString().replace(/[:.]/g, '-');
-        const result = finalizeGeneratedTests({
-            appPath: config.path,
-            testsRoot: reportRoot,
-            branch: args.branch || `auto-heal-${branchSuffix}`,
-            commitMessage: args.commitMessage || 'test(e2e): auto-heal generated specs',
-            createPr: true,
-            prTitle: args.prTitle || 'test(e2e): auto-heal generated specs',
-            prBody: args.prBody || 'Automated e2e-heal run generated by @yasserkhanorg/e2e-agents.',
-            baseBranch: args.prBase || 'master',
-            dryRun: args.dryRun,
-        });
-        // eslint-disable-next-line no-console
-        console.log(`Auto-heal repo root: ${result.repoRoot}`);
-        // eslint-disable-next-line no-console
-        console.log(`Auto-heal branch: ${result.branch}`);
-        // eslint-disable-next-line no-console
-        console.log(`Auto-heal staged paths: ${result.stagedPaths.join(', ') || 'none'}`);
-        // eslint-disable-next-line no-console
-        console.log(`Auto-heal commit: ${result.committed ? 'created' : 'skipped'}`);
-        if (result.commitSha) {
-            // eslint-disable-next-line no-console
-            console.log(`Auto-heal commit sha: ${result.commitSha}`);
-        }
-        if (result.prUrl) {
-            // eslint-disable-next-line no-console
-            console.log(`Auto-heal PR: ${result.prUrl}`);
-        }
-        return;
-    }
     if (args.command === 'heal') {
         if (!args.path && !autoConfig) {
             // eslint-disable-next-line no-console
@@ -934,13 +820,11 @@ async function main() {
         printUsage();
         process.exit(1);
     }
-    const forcePipelineFromApproval = args.command === 'approve-and-generate' || args.command === 'generate';
-    const forceAIPipelineFromApproval = args.command === 'approve-and-generate' || args.command === 'generate';
-    const { config, configPath } = resolveConfig(process.cwd(), autoConfig, {
+    const { config } = resolveConfig(process.cwd(), autoConfig, {
         path: args.path,
         profile: args.profile,
         testsRoot: args.testsRoot,
-        mode: (args.command === 'gap' || args.command === 'approve-and-generate' || args.command === 'generate') ? 'gap' : 'impact',
+        mode: 'impact',
         framework: args.framework,
         timeLimitMinutes: args.timeLimitMinutes,
         budget: {
@@ -954,7 +838,7 @@ async function main() {
         specPDF: args.specPDF,
         gitSince: args.gitSince,
         llmProvider: args.llmProvider,
-        pipeline: (args.pipeline || forcePipelineFromApproval)
+        pipeline: args.pipeline
             ? {
                 enabled: true,
                 scenarios: args.pipelineScenarios,
@@ -965,9 +849,9 @@ async function main() {
                 project: args.pipelineProject,
                 parallel: args.pipelineParallel,
                 dryRun: args.pipelineDryRun,
-                mcp: args.pipelineMcp !== undefined ? args.pipelineMcp : forceAIPipelineFromApproval,
+                mcp: args.pipelineMcp,
                 mcpAllowFallback: args.pipelineMcpAllowFallback,
-                mcpOnly: args.pipelineMcpOnly !== undefined ? args.pipelineMcpOnly : forceAIPipelineFromApproval,
+                mcpOnly: args.pipelineMcpOnly,
                 mcpCommandTimeoutMs: args.pipelineMcpTimeoutMs,
                 mcpRetries: args.pipelineMcpRetries,
             }
@@ -988,46 +872,81 @@ async function main() {
             }
             : undefined,
     });
-    if (args.allowFallback) {
-        config.impact.allowFallback = true;
-    }
     if (args.command === 'impact') {
-        await runImpact(config, { apply: args.apply });
+        const reportRoot = config.testsRoot || config.path;
+        const gitResult = getChangedFiles(config.path, config.git.since, { includeUncommitted: config.git.includeUncommitted });
+        const impactResult = analyzeImpactV2(gitResult.files, {
+            testsRoot: reportRoot,
+            routeFamilies: config.routeFamilies,
+        });
+        // eslint-disable-next-line no-console
+        console.log(`Impact: ${impactResult.changedFiles.length} changed files → ${impactResult.impactedFeatures.length} features impacted`);
+        // eslint-disable-next-line no-console
+        console.log(`Unbound files: ${impactResult.unboundFiles.length}`);
+        for (const f of impactResult.impactedFeatures) {
+            const label = f.featureId || f.familyId;
+            // eslint-disable-next-line no-console
+            console.log(`  [${f.priority}] ${label}: ${f.coverageStatus} (PW=${f.playwrightSpecs.length}, Cy=${f.cypressSpecs.length})`);
+        }
+        if (impactResult.warnings.length > 0) {
+            for (const w of impactResult.warnings) {
+                // eslint-disable-next-line no-console
+                console.warn(`  Warning: ${w}`);
+            }
+        }
         return;
     }
     if (args.command === 'suggest' || args.command === 'plan') {
         const reportRoot = config.testsRoot || config.path;
-        const impactPath = join(reportRoot, '.e2e-ai-agents', 'impact.json');
-        try {
-            await runImpact(config, { apply: args.apply });
-        }
-        catch (err) {
-            // If impact analysis already ran (e.g. a prior CI step wrote impact.json),
-            // fall back to that data rather than failing the plan step.
-            if (existsSync(impactPath)) {
+        const apiOptions = {
+            cwd: process.cwd(),
+            configPath: autoConfig,
+            path: args.path,
+            profile: args.profile,
+            testsRoot: args.testsRoot,
+            gitSince: args.gitSince,
+            llmProvider: args.llmProvider,
+            policy: args.policyMinConfidence !== undefined ||
+                args.policySafeMergeConfidence !== undefined ||
+                args.policyWarningsThreshold !== undefined ||
+                (args.policyRiskyPatterns && args.policyRiskyPatterns.length > 0) ||
+                args.policyEnforcementMode !== undefined ||
+                (args.policyBlockActions && args.policyBlockActions.length > 0)
+                ? {
+                    minConfidenceForTargeted: args.policyMinConfidence,
+                    safeMergeMinConfidence: args.policySafeMergeConfidence,
+                    forceFullOnWarningsAtOrAbove: args.policyWarningsThreshold,
+                    riskyFilePatterns: args.policyRiskyPatterns,
+                    enforcementMode: args.policyEnforcementMode,
+                    blockOnActions: args.policyBlockActions,
+                }
+                : undefined,
+        };
+        let result;
+        if (args.noAi) {
+            result = recommendTestsDeterministic(apiOptions);
+        }
+        else {
+            result = await recommendTestsAI(apiOptions);
+            if (result.aiEnrichment) {
+                const { aiEnrichment } = result;
                 // eslint-disable-next-line no-console
-                console.warn(`Impact re-run failed (${err instanceof Error ? err.message : String(err)}); using existing impact.json.`);
+                console.log(`AI enrichment: ${aiEnrichment.enrichedFeatures.length} features enriched (${aiEnrichment.tokenUsage.input + aiEnrichment.tokenUsage.output} tokens)`);
             }
-            else {
-                throw err;
+            else if (!process.env.ANTHROPIC_API_KEY) {
+                // eslint-disable-next-line no-console
+                console.log('Tip: set ANTHROPIC_API_KEY to enable AI-powered enrichment');
             }
         }
-        if (!existsSync(impactPath)) {
-            throw new Error(`Impact report not found at ${impactPath}`);
+        const { plan, planPath, ciSummaryMarkdown, ciSummaryPath } = result;
+        // Write CI summary to an additional path if --ci-comment-path was specified
+        if (args.ciCommentPath) {
+            writeCiSummary(reportRoot, ciSummaryMarkdown, args.ciCommentPath);
         }
-        const impact = JSON.parse(readFileSync(impactPath, 'utf-8'));
-        const basePlan = buildPlanFromImpactReport(impact, config.policy);
-        const withActions = attachDeveloperActions(basePlan, {
-            appPath: config.path,
-            testsRoot: reportRoot,
-            sinceRef: config.git.since,
-            configPath,
-        });
-        const plan = applyOperationalInsights(withActions, reportRoot);
-        const planPath = writePlanReport(reportRoot, plan);
-        const summaryMarkdown = renderCiSummaryMarkdown(plan);
-        const summaryPath = writeCiSummary(reportRoot, summaryMarkdown, args.ciCommentPath);
-        const metrics = appendPlanMetrics(reportRoot, plan);
+        const summaryPath = ciSummaryPath;
+        // Compute metrics paths (api already wrote metrics; derive paths for GHA output)
+        const metricsEventsPath = join(reportRoot, '.e2e-ai-agents/metrics.jsonl');
+        const metricsSummaryPath = join(reportRoot, '.e2e-ai-agents/metrics-summary.json');
         const ghaOutput = args.githubOutputPath || process.env.GITHUB_OUTPUT;
         if (ghaOutput) {
             appendFileSync(ghaOutput, `run_set=${plan.runSet}\n`);
@@ -1039,8 +958,8 @@ async function main() {
             appendFileSync(ghaOutput, `required_new_tests_count=${plan.requiredNewTests.length}\n`);
             appendFileSync(ghaOutput, `plan_path=${planPath}\n`);
             appendFileSync(ghaOutput, `summary_path=${summaryPath}\n`);
-            appendFileSync(ghaOutput, `metrics_events_path=${metrics.eventsPath}\n`);
-            appendFileSync(ghaOutput, `metrics_summary_path=${metrics.summaryPath}\n`);
+            appendFileSync(ghaOutput, `metrics_events_path=${metricsEventsPath}\n`);
+            appendFileSync(ghaOutput, `metrics_summary_path=${metricsSummaryPath}\n`);
         }
         // eslint-disable-next-line no-console
         console.log(`Suggested run set: ${plan.runSet} (confidence ${plan.confidence})`);
@@ -1053,26 +972,17 @@ async function main() {
         // eslint-disable-next-line no-console
         console.log(`CI summary: ${summaryPath}`);
         // eslint-disable-next-line no-console
-        console.log(`Plan metrics: ${metrics.summaryPath}`);
-        if (plan.nextActions) {
-            // eslint-disable-next-line no-console
-            console.log(`Next action (run existing): ${plan.nextActions.runRecommendedTests || plan.nextActions.runSmokeSuite}`);
-            // eslint-disable-next-line no-console
-            console.log(`Next action (approve + generate): ${plan.nextActions.approveAndGenerate || plan.nextActions.generateMissingTests}`);
-            // eslint-disable-next-line no-console
-            console.log(`Next action (heal): ${plan.nextActions.healGeneratedTests}`);
-        }
+        console.log(`Plan metrics: ${metricsSummaryPath}`);
         const failOnLegacyFlag = args.failOnMustAddTests && plan.decision.action === 'must-add-tests';
         if (failOnLegacyFlag || plan.enforcement.shouldFail) {
             process.exit(2);
         }
         return;
     }
-    if (args.command === 'approve-and-generate' || args.command === 'generate') {
-        await runGap(config, { apply: args.apply });
-        return;
-    }
-    await runGap(config, { apply: args.apply });
+    // eslint-disable-next-line no-console
+    console.error(`Unknown command: ${args.command}`);
+    printUsage();
+    process.exit(1);
 }
 async function runLlmHealth() {
     if (!process.env.ANTHROPIC_API_KEY) {

package/dist/esm/engine/ai_enrichment.js

@@ -0,0 +1,232 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { formatDiffsForPrompt } from './diff_loader.js';
+const MAX_SPEC_LIST = 50;
+function normalizePriority(value) {
+    if (value === 'P0' || value === 'P1' || value === 'P2') {
+        return value;
+    }
+    return 'P2';
+}
+function buildPrompt(options) {
+    const { deterministicImpact, diffs, specList, manifestSummary } = options;
+    const { changedFiles, impactedFeatures, unboundFiles } = deterministicImpact;
+    const lines = [];
+    // Optional manifest summary
+    if (manifestSummary) {
+        lines.push('## Application Overview');
+        lines.push(manifestSummary);
+        lines.push('');
+    }
+    // Changed files section
+    lines.push(`## Changed Files (${changedFiles.length} total)`);
+    for (const f of changedFiles) {
+        lines.push(`- ${f}`);
+    }
+    lines.push('');
+    // Diffs section
+    lines.push('## Code Diffs');
+    lines.push(formatDiffsForPrompt(diffs));
+    lines.push('');
+    // Deterministic features summary
+    lines.push('## Deterministic Impact Analysis');
+    lines.push('The following features/flows have been deterministically identified as impacted:');
+    lines.push('');
+    for (const feature of impactedFeatures) {
+        const featureIdPart = feature.featureId ? `featureId=${feature.featureId}` : 'featureId=undefined';
+        const specCount = feature.playwrightSpecs.length + feature.cypressSpecs.length;
+        const specList2 = [...feature.playwrightSpecs, ...feature.cypressSpecs];
+        const specsDisplay = specList2.length > 0 ? specList2.join(', ') : 'none';
+        lines.push(`- familyId=${feature.familyId} ${featureIdPart} (${feature.priority}): ${specCount} files, coverage=${feature.coverageStatus}, specs=[${specsDisplay}]`);
+    }
+    lines.push('');
+    // Unbound files
+    if (unboundFiles.length > 0) {
+        lines.push('## Unbound Files (not mapped to any feature)');
+        for (const f of unboundFiles) {
+            lines.push(`- ${f}`);
+        }
+        lines.push('');
+    }
+    // Spec list (capped at 50)
+    if (specList.length > 0) {
+        const cappedSpecs = specList.slice(0, MAX_SPEC_LIST);
+        lines.push(`## Available Test Specs (showing ${cappedSpecs.length} of ${specList.length})`);
+        for (const s of cappedSpecs) {
+            lines.push(`- ${s}`);
+        }
+        lines.push('');
+    }
+    // Instructions
+    lines.push('## Instructions');
+    lines.push('Return ONLY valid JSON (no markdown fences, no explanation) in this exact shape:');
+    lines.push('');
+    lines.push(JSON.stringify({
+        impactedFlows: [
+            {
+                id: '<featureId or familyId from the deterministic list above>',
+                name: '<human-readable flow name>',
+                priority: 'P0|P1|P2',
+                reasons: ['<specific reason why this flow is impacted by the changes>'],
+                coveredBy: ['<spec file paths that cover this flow>'],
+                missingScenarios: ['<specific test scenarios that are missing or should be added>'],
+            },
+        ],
+        unboundFileAnalysis: [
+            {
+                file: '<path to unbound file>',
+                likelyFeature: '<best guess at which feature/family this affects>',
+                reason: '<why you think this file belongs to that feature>',
+            },
+        ],
+    }, null, 2));
+    return lines.join('\n');
+}
+function extractJSON(text) {
+    // Try markdown fenced block first
+    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const candidates = fenced ? [fenced[1], text] : [text];
+    for (const candidate of candidates) {
+        const start = candidate.indexOf('{');
+        const end = candidate.lastIndexOf('}');
+        if (start >= 0 && end > start) {
+            return candidate.slice(start, end + 1).trim();
+        }
+    }
+    // Fallback: return trimmed text
+    return text.trim();
+}
+function toEnrichedFeature(det, aiFlow) {
+    return {
+        familyId: det.familyId,
+        featureId: det.featureId,
+        priority: normalizePriority(det.priority),
+        changedFiles: det.changedFiles,
+        coverageStatus: det.coverageStatus,
+        playwrightSpecs: det.playwrightSpecs,
+        cypressSpecs: det.cypressSpecs,
+        userFlows: det.userFlows,
+        aiReasons: aiFlow?.reasons ?? [],
+        aiMissingScenarios: aiFlow?.missingScenarios ?? [],
+        aiCoveredBy: aiFlow?.coveredBy ?? [],
+    };
+}
+/**
+ * Enriches a deterministic impact result with AI-generated reasons,
+ * missing test scenarios, and coverage insights.
+ */
+export async function enrichImpactWithAI(options) {
+    const { deterministicImpact, provider } = options;
+    const warnings = [];
+    let tokenUsage = { input: 0, output: 0 };
+    const prompt = buildPrompt(options);
+    let aiResponse = null;
+    let unboundFileInsights = [];
+    try {
+        const response = await provider.generateText(prompt, {
+            maxTokens: 4000,
+            temperature: 0,
+            timeout: 45000,
+            systemPrompt: 'You are an expert E2E test analyst. Return only valid JSON.',
+        });
+        tokenUsage = {
+            input: response.usage?.inputTokens ?? 0,
+            output: response.usage?.outputTokens ?? 0,
+        };
+        const rawJSON = extractJSON(response.text);
+        try {
+            const parsed = JSON.parse(rawJSON);
+            // Validate that impactedFlows is an array
+            if (!Array.isArray(parsed.impactedFlows)) {
+                warnings.push('AI response parsed but impactedFlows is not an array; returning empty enrichedFeatures');
+                return {
+                    enrichedFeatures: [],
+                    unboundFileInsights: [],
+                    warnings,
+                    providerName: provider.name,
+                    tokenUsage,
+                };
+            }
+            aiResponse = parsed;
+            unboundFileInsights = (parsed.unboundFileAnalysis ?? []).map((item) => ({
+                file: item.file,
+                likelyFeature: item.likelyFeature,
+                reason: item.reason,
+            }));
+        }
+        catch (parseErr) {
+            warnings.push(`Failed to parse AI response as JSON: ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`);
+            return {
+                enrichedFeatures: [],
+                unboundFileInsights: [],
+                warnings,
+                providerName: provider.name,
+                tokenUsage,
+            };
+        }
+    }
+    catch (err) {
+        warnings.push(`AI provider error: ${err instanceof Error ? err.message : String(err)}`);
+        return {
+            enrichedFeatures: [],
+            unboundFileInsights: [],
+            warnings,
+            providerName: provider.name,
+            tokenUsage,
+        };
+    }
+    // Build a map of AI flows by id (featureId or familyId)
+    const aiFlowMap = new Map();
+    if (aiResponse?.impactedFlows) {
+        for (const flow of aiResponse.impactedFlows) {
+            aiFlowMap.set(flow.id, flow);
+        }
+    }
+    // Build a set of all deterministic ids for unmatched-flow detection
+    const deterministicIds = new Set();
+    for (const det of deterministicImpact.impactedFeatures) {
+        if (det.featureId) {
+            deterministicIds.add(det.featureId);
+        }
+        deterministicIds.add(det.familyId);
+    }
+    // Warn on AI flows that don't match any deterministic feature
+    for (const flow of aiFlowMap.values()) {
+        if (!deterministicIds.has(flow.id)) {
+            warnings.push(`AI returned flow '${flow.id}' with no matching deterministic feature (using as-is)`);
+        }
+    }
+    // Merge deterministic features with AI data
+    const enrichedFeatures = deterministicImpact.impactedFeatures.map((det) => {
+        // Match by featureId first, then by familyId
+        const aiFlow = det.featureId
+            ? (aiFlowMap.get(det.featureId) ?? aiFlowMap.get(det.familyId))
+            : aiFlowMap.get(det.familyId);
+        return toEnrichedFeature(det, aiFlow);
+    });
+    // Include AI flows that had no deterministic match (as-is, with empty deterministic fields)
+    for (const flow of aiFlowMap.values()) {
+        if (!deterministicIds.has(flow.id)) {
+            enrichedFeatures.push({
+                familyId: flow.id,
+                featureId: undefined,
+                priority: normalizePriority(flow.priority),
+                changedFiles: [],
+                coverageStatus: 'uncovered',
+                playwrightSpecs: [],
+                cypressSpecs: [],
+                userFlows: [],
+                aiReasons: flow.reasons ?? [],
+                aiMissingScenarios: flow.missingScenarios ?? [],
+                aiCoveredBy: flow.coveredBy ?? [],
+            });
+        }
+    }
+    return {
+        enrichedFeatures,
+        unboundFileInsights,
+        warnings,
+        providerName: provider.name,
+        tokenUsage,
+    };
+}

package/dist/esm/engine/diff_loader.js

@@ -0,0 +1,70 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { spawnSync } from 'child_process';
+const MAX_DIFF_CHARS = 8000;
+const MAX_TOTAL_CHARS = 60000;
+const TRUNCATION_NOTICE = '\n... (diff truncated)';
+function runGitRaw(args, cwd) {
+    const result = spawnSync('git', args, {
+        cwd,
+        encoding: 'utf-8',
+        timeout: 30000,
+    });
+    if (result.error || result.status !== 0) {
+        return null;
+    }
+    return result.stdout;
+}
+/**
+ * Loads git diffs for the given changed files relative to the given since ref.
+ * Uses `git merge-base` to find the accurate base ref first.
+ * Individual diffs are truncated at 8000 chars and total output is capped at 60000 chars.
+ */
+export function loadDiffs(appRoot, since, changedFiles) {
+    const result = new Map();
+    if (changedFiles.length === 0) {
+        return result;
+    }
+    // Try to get accurate merge base
+    let baseRef = since;
+    const mergeBaseOutput = runGitRaw(['merge-base', since, 'HEAD'], appRoot);
+    if (mergeBaseOutput) {
+        const candidate = mergeBaseOutput
+            .split('\n')
+            .map((line) => line.trim())
+            .find(Boolean);
+        if (candidate) {
+            baseRef = candidate;
+        }
+    }
+    let totalChars = 0;
+    for (const file of changedFiles) {
+        if (totalChars >= MAX_TOTAL_CHARS) {
+            break;
+        }
+        const diffOutput = runGitRaw(['diff', `${baseRef}..HEAD`, '--', file], appRoot);
+        if (diffOutput === null) {
+            continue;
+        }
+        let diff = diffOutput;
+        if (diff.length > MAX_DIFF_CHARS) {
+            diff = diff.slice(0, MAX_DIFF_CHARS) + TRUNCATION_NOTICE;
+        }
+        result.set(file, diff);
+        totalChars += diff.length;
+    }
+    return result;
+}
+/**
+ * Formats a diffs map into a human-readable string suitable for an AI prompt.
+ */
+export function formatDiffsForPrompt(diffs) {
+    if (diffs.size === 0) {
+        return 'No diffs available.';
+    }
+    const sections = [];
+    for (const [file, diff] of diffs) {
+        sections.push(`--- ${file} ---\n${diff}`);
+    }
+    return sections.join('\n\n');
+}