@yasserkhanorg/e2e-agents 0.6.0 → 0.7.1

package/dist/engine/plan_builder.js

@@ -199,7 +199,7 @@ function buildRecommendedTests(impact) {
     }
     return tests;
 }
-function buildPlanFromImpact(impact, policyOverride) {
+function buildPlanFromImpact(impact, policyOverride, aiEnrichment) {
     const policy = { ...DEFAULT_POLICY, ...(policyOverride || {}) };
     const confidence = computeConfidence(impact);
     const runSetResult = pickRunSet(impact, confidence, policy);
@@ -207,23 +207,61 @@ function buildPlanFromImpact(impact, policyOverride) {
     const enforcement = evaluateEnforcement(decision, policy);
     const gaps = (0, impact_engine_js_1.getGaps)(impact);
     const partialGaps = (0, impact_engine_js_1.getPartialGaps)(impact);
-    const gapDetails = gaps.map((f) => ({
-        id: featureLabel(f),
-        name: featureLabel(f),
-        priority: f.priority,
-        reasons: [`No Playwright or Cypress tests found for ${featureLabel(f)}`],
-        files: f.changedFiles.slice(0, 6),
-        missingScenarios: f.userFlows.length > 0 ? f.userFlows.slice(0, 5) : undefined,
-    }));
+    // Build two separate lookup maps from aiEnrichment: one by featureId, one by familyId.
+    // The familyId map stores only the FIRST feature encountered to avoid last-write-wins collisions.
+    const aiFeatureByFeatureId = new Map();
+    const aiFeatureByFamilyId = new Map();
+    if (aiEnrichment) {
+        for (const ef of aiEnrichment.enrichedFeatures) {
+            if (ef.featureId) {
+                aiFeatureByFeatureId.set(ef.featureId, ef);
+            }
+            if (ef.familyId && !aiFeatureByFamilyId.has(ef.familyId)) {
+                aiFeatureByFamilyId.set(ef.familyId, ef);
+            }
+        }
+    }
+    const gapDetails = gaps.map((f) => {
+        const label = featureLabel(f);
+        const aiFeature = f.featureId
+            ? (aiFeatureByFeatureId.get(f.featureId) ?? aiFeatureByFamilyId.get(f.familyId))
+            : aiFeatureByFamilyId.get(f.familyId);
+        const baseReasons = [`No Playwright or Cypress tests found for ${label}`];
+        const reasons = aiFeature && aiFeature.aiReasons.length > 0
+            ? [...baseReasons, ...aiFeature.aiReasons]
+            : baseReasons;
+        const missingScenarios = aiFeature && aiFeature.aiMissingScenarios.length > 0
+            ? aiFeature.aiMissingScenarios
+            : (f.userFlows.length > 0 ? f.userFlows.slice(0, 5) : undefined);
+        return {
+            id: label,
+            name: label,
+            priority: f.priority,
+            reasons,
+            files: f.changedFiles.slice(0, 6),
+            missingScenarios,
+            source: aiFeature ? 'ai+deterministic' : 'deterministic',
+        };
+    });
     // Add partial gaps as advisory info
     for (const f of partialGaps) {
-        const source = f.playwrightSpecs.length > 0 ? 'Cypress' : 'Playwright';
+        const coverageType = f.playwrightSpecs.length > 0 ? 'Cypress' : 'Playwright';
+        const hasOpposite = f.playwrightSpecs.length > 0 ? 'Playwright' : 'Cypress';
+        const label = featureLabel(f);
+        const aiFeature = f.featureId
+            ? (aiFeatureByFeatureId.get(f.featureId) ?? aiFeatureByFamilyId.get(f.familyId))
+            : aiFeatureByFamilyId.get(f.familyId);
+        const baseReasons = [`Missing ${coverageType} tests for ${label} (has ${hasOpposite} only)`];
+        const reasons = aiFeature && aiFeature.aiReasons.length > 0
+            ? [...baseReasons, ...aiFeature.aiReasons]
+            : baseReasons;
         gapDetails.push({
-            id: featureLabel(f),
-            name: `${featureLabel(f)} (partial)`,
+            id: label,
+            name: `${label} (partial)`,
             priority: f.priority,
-            reasons: [`Missing ${source} tests for ${featureLabel(f)} (has ${f.playwrightSpecs.length > 0 ? 'Playwright' : 'Cypress'} only)`],
+            reasons,
             files: f.changedFiles.slice(0, 6),
+            source: aiFeature ? 'ai+deterministic' : 'deterministic',
         });
     }
     const coveredFlows = impact.impactedFeatures
@@ -243,11 +281,12 @@ function buildPlanFromImpact(impact, policyOverride) {
     const p1 = impact.impactedFeatures.filter((f) => f.priority === 'P1').length;
     const p2 = impact.impactedFeatures.filter((f) => f.priority === 'P2').length;
     const runId = `plan-${Date.now().toString(36)}`;
+    const planSource = aiEnrichment ? 'ai+deterministic' : 'impact';
     return {
         schemaVersion: '1.0.0',
         runId,
         generatedAt: new Date().toISOString(),
-        source: 'impact',
+        source: planSource,
         runSet: runSetResult.runSet,
         confidence,
         reasons: runSetResult.reasons,
@@ -298,12 +337,18 @@ function renderCiSummaryMarkdown(plan) {
         lines.push(`The following ${uncoveredP0P1Flows} feature(s) have no test coverage and must be covered before merge:`);
         lines.push('');
         for (const gap of plan.gapDetails.filter((g) => !g.name.includes('(partial)'))) {
-            lines.push(`- **${gap.name}** [${gap.priority}]`);
+            const aiLabel = gap.source === 'ai+deterministic' ? ' ✦ AI-enriched' : '';
+            lines.push(`- **${gap.name}** [${gap.priority}]${aiLabel}`);
             if (gap.missingScenarios && gap.missingScenarios.length > 0) {
                 for (const scenario of gap.missingScenarios) {
                     lines.push(`  - ${scenario}`);
                 }
             }
+            // Show AI-provided reasons (skip the first deterministic reason which is always included)
+            const aiReasons = gap.reasons.slice(1);
+            if (aiReasons.length > 0) {
+                lines.push(`  - *AI insight*: ${aiReasons.join('; ')}`);
+            }
         }
     }
     if (plan.coveredFlows.length > 0) {

package/dist/esm/api.js

@@ -5,6 +5,9 @@ import { appendPlanMetrics, } from './agent/plan.js';
 import { analyzeImpact as analyzeImpactV2 } from './engine/impact_engine.js';
 import { buildPlanFromImpact, renderCiSummaryMarkdown, writeCiSummary, writePlanReport, } from './engine/plan_builder.js';
 import { getChangedFiles } from './agent/git.js';
+import { loadDiffs } from './engine/diff_loader.js';
+import { enrichImpactWithAI } from './engine/ai_enrichment.js';
+import { AnthropicProvider } from './anthropic_provider.js';
 import { finalizeGeneratedTests } from './agent/handoff.js';
 import { ingestTraceabilityInput, } from './agent/traceability_ingest.js';
 import { captureTraceabilityInput, } from './agent/traceability_capture.js';
@@ -56,6 +59,40 @@ export function recommendTestsDeterministic(options = {}) {
     appendPlanMetrics(reportRoot, plan);
     return { impact, plan, planPath, ciSummaryMarkdown, ciSummaryPath };
 }
+export async function recommendTestsAI(options = {}) {
+    const config = resolveAgent(options, 'impact');
+    const reportRoot = config.testsRoot || config.path;
+    const gitResult = getChangedFiles(config.path, config.git.since, { includeUncommitted: config.git.includeUncommitted });
+    const impact = analyzeImpactV2(gitResult.files, {
+        testsRoot: reportRoot,
+        routeFamilies: config.routeFamilies,
+    });
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    let aiEnrichment;
+    if (apiKey) {
+        const diffs = loadDiffs(config.path, config.git.since, gitResult.files);
+        const provider = new AnthropicProvider({ apiKey });
+        // Collect all known spec paths from impacted features
+        const specSet = new Set();
+        for (const feature of impact.impactedFeatures) {
+            for (const s of feature.playwrightSpecs) {
+                specSet.add(s);
+            }
+        }
+        aiEnrichment = await enrichImpactWithAI({
+            deterministicImpact: impact,
+            diffs,
+            provider,
+            specList: [...specSet],
+        });
+    }
+    const plan = buildPlanFromImpact(impact, config.policy, aiEnrichment);
+    const planPath = writePlanReport(reportRoot, plan);
+    const ciSummaryMarkdown = renderCiSummaryMarkdown(plan);
+    const ciSummaryPath = writeCiSummary(reportRoot, ciSummaryMarkdown);
+    appendPlanMetrics(reportRoot, plan);
+    return { impact, plan, planPath, ciSummaryMarkdown, ciSummaryPath, aiEnrichment };
+}
 export function captureTraceability(options) {
     const cwd = options.cwd || process.cwd();
     const { config } = resolveConfig(cwd, options.configPath, {

package/dist/esm/cli.js

@@ -6,10 +6,10 @@ 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 { appendPlanMetrics } from './agent/plan.js';
 import { analyzeImpact as analyzeImpactV2 } from './engine/impact_engine.js';
-import { buildPlanFromImpact, renderCiSummaryMarkdown, writeCiSummary, writePlanReport, } from './engine/plan_builder.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';
@@ -493,6 +493,10 @@ function parseArgs(argv) {
             i += 1;
             continue;
         }
+        if (arg === '--no-ai') {
+            parsed.noAi = true;
+            continue;
+        }
     }
     return parsed;
 }
@@ -894,16 +898,55 @@ async function main() {
     }
     if (args.command === 'suggest' || args.command === 'plan') {
         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,
-        });
-        const plan = buildPlanFromImpact(impactResult, config.policy);
-        const planPath = writePlanReport(reportRoot, plan);
-        const summaryMarkdown = renderCiSummaryMarkdown(plan);
-        const summaryPath = writeCiSummary(reportRoot, summaryMarkdown, args.ciCommentPath);
-        const metrics = appendPlanMetrics(reportRoot, plan);
+        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.log(`AI enrichment: ${aiEnrichment.enrichedFeatures.length} features enriched (${aiEnrichment.tokenUsage.input + aiEnrichment.tokenUsage.output} tokens)`);
+            }
+            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');
+            }
+        }
+        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 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`);
@@ -915,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})`);
@@ -929,7 +972,7 @@ 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}`);
+        console.log(`Plan metrics: ${metricsSummaryPath}`);
         const failOnLegacyFlag = args.failOnMustAddTests && plan.decision.action === 'must-add-tests';
         if (failOnLegacyFlag || plan.enforcement.shouldFail) {
             process.exit(2);

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');
+}