@yasserkhanorg/impact-gate 2.0.0

package/dist/esm/openai_provider.js

@@ -0,0 +1,243 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import OpenAI from 'openai';
+import { LLMProviderError, UnsupportedCapabilityError } from './provider_interface.js';
+import { API_KEY_PATTERNS, sanitizeErrorMessage, withTimeout, validateAndSanitizeUrl } from './provider_utils.js';
+import { BaseProvider } from './base_provider.js';
+import { logger } from './logger.js';
+function inferVisionSupport(model) {
+    const lower = model.toLowerCase();
+    return lower.includes('vision') || lower.includes('4o') || lower.includes('omni');
+}
+export class OpenAIProvider extends BaseProvider {
+    constructor(config) {
+        super();
+        this.name = 'openai';
+        if (!API_KEY_PATTERNS.openai.test(config.apiKey)) {
+            throw new Error('Invalid API key format. Expected sk-* format.');
+        }
+        if (config.baseUrl) {
+            const validation = validateAndSanitizeUrl(config.baseUrl);
+            if (!validation.valid) {
+                throw new Error(`Invalid base URL: ${validation.warning}`);
+            }
+            if (validation.warning) {
+                logger.warn(`HTTPS required for remote URLs: ${validation.warning}`);
+            }
+        }
+        this.client = new OpenAI({
+            apiKey: config.apiKey,
+            baseURL: config.baseUrl,
+            organization: config.organizationId,
+        });
+        this.model = config.model || 'gpt-4';
+        const maxTokens = config.maxTokens || 128000;
+        const costPer1MInputTokens = config.costPer1MInputTokens ?? 0;
+        const costPer1MOutputTokens = config.costPer1MOutputTokens ?? 0;
+        this.capabilities = {
+            vision: inferVisionSupport(this.model),
+            streaming: true,
+            maxTokens,
+            costPer1MInputTokens,
+            costPer1MOutputTokens,
+            supportsTools: true,
+            supportsPromptCaching: false,
+            typicalResponseTimeMs: 1200,
+        };
+    }
+    async generateText(prompt, options) {
+        this.checkBudget();
+        const startTime = Date.now();
+        try {
+            if (prompt.length > 10 * 1024 * 1024) {
+                throw new Error('Prompt exceeds maximum size (10MB)');
+            }
+            const messages = [];
+            if (options?.systemPrompt) {
+                messages.push({ role: 'system', content: options.systemPrompt });
+            }
+            messages.push({ role: 'user', content: prompt });
+            const response = await withTimeout(this.client.chat.completions.create({
+                model: this.model,
+                messages,
+                max_tokens: options?.maxTokens,
+                temperature: options?.temperature,
+                top_p: options?.topP,
+                stop: options?.stopSequences,
+            }), options?.timeout, 'generateText');
+            const responseTime = Date.now() - startTime;
+            const text = response.choices[0]?.message?.content || '';
+            const usage = this.extractUsage(response.usage);
+            const cost = this.calculateCost(usage, this.capabilities.costPer1MInputTokens, this.capabilities.costPer1MOutputTokens);
+            this.updateStats(usage, responseTime, cost);
+            return {
+                text,
+                usage,
+                cost,
+                metadata: {
+                    model: this.model,
+                    responseTimeMs: responseTime,
+                    finishReason: response.choices[0]?.finish_reason,
+                },
+            };
+        }
+        catch (error) {
+            this.stats.failedRequests++;
+            throw new LLMProviderError(sanitizeErrorMessage(error, 'generateText'), this.name, this.extractStatusCode(error), error);
+        }
+    }
+    async analyzeImage(images, prompt, options) {
+        if (!this.capabilities.vision) {
+            throw new UnsupportedCapabilityError(this.name, 'vision');
+        }
+        const startTime = Date.now();
+        try {
+            if (images.length === 0 || images.length > 20) {
+                throw new Error('Image count must be between 1 and 20');
+            }
+            if (prompt.length > 10 * 1024 * 1024) {
+                throw new Error('Prompt exceeds maximum size (10MB)');
+            }
+            const content = [{ type: 'text', text: prompt }];
+            for (const image of images) {
+                const mediaType = (image.mimeType || image.mediaType || 'image/png');
+                if (!['image/png', 'image/jpeg', 'image/webp'].includes(mediaType)) {
+                    throw new Error(`Unsupported image type: ${mediaType}`);
+                }
+                const data = image.data || image.base64 || '';
+                if (data.length > 20 * 1024 * 1024) {
+                    throw new Error('Image data exceeds maximum size (20MB)');
+                }
+                const url = `data:${mediaType};base64,${data}`;
+                content.push({ type: 'image_url', image_url: { url } });
+                if (image.description) {
+                    content.push({ type: 'text', text: `[Image: ${image.description}]` });
+                }
+            }
+            const messages = [];
+            if (options?.systemPrompt) {
+                messages.push({ role: 'system', content: options.systemPrompt });
+            }
+            messages.push({ role: 'user', content });
+            const response = await withTimeout(this.client.chat.completions.create({
+                model: this.model,
+                messages,
+                max_tokens: options?.maxTokens,
+                temperature: options?.temperature,
+                top_p: options?.topP,
+                stop: options?.stopSequences,
+            }), options?.timeout, 'analyzeImage');
+            const responseTime = Date.now() - startTime;
+            const text = response.choices[0]?.message?.content || '';
+            const usage = this.extractUsage(response.usage);
+            const cost = this.calculateCost(usage, this.capabilities.costPer1MInputTokens, this.capabilities.costPer1MOutputTokens);
+            this.updateStats(usage, responseTime, cost);
+            return {
+                text,
+                usage,
+                cost,
+                metadata: {
+                    model: this.model,
+                    responseTimeMs: responseTime,
+                    finishReason: response.choices[0]?.finish_reason,
+                    imageCount: images.length,
+                },
+            };
+        }
+        catch (error) {
+            this.stats.failedRequests++;
+            throw new LLMProviderError(sanitizeErrorMessage(error, 'analyzeImage'), this.name, this.extractStatusCode(error), error);
+        }
+    }
+    async *streamText(prompt, options) {
+        try {
+            if (prompt.length > 10 * 1024 * 1024) {
+                throw new Error('Prompt exceeds maximum size (10MB)');
+            }
+            const messages = [];
+            if (options?.systemPrompt) {
+                messages.push({ role: 'system', content: options.systemPrompt });
+            }
+            messages.push({ role: 'user', content: prompt });
+            const stream = await withTimeout(this.client.chat.completions.create({
+                model: this.model,
+                messages,
+                max_tokens: options?.maxTokens,
+                temperature: options?.temperature,
+                top_p: options?.topP,
+                stop: options?.stopSequences,
+                stream: true,
+            }), options?.timeout, 'streamText');
+            for await (const chunk of stream) {
+                const content = chunk.choices[0]?.delta?.content;
+                if (content) {
+                    yield content;
+                }
+            }
+            this.stats.requestCount++;
+            this.stats.lastUpdated = new Date();
+        }
+        catch (error) {
+            this.stats.failedRequests++;
+            throw new LLMProviderError(sanitizeErrorMessage(error, 'streamText'), this.name, this.extractStatusCode(error), error);
+        }
+    }
+    extractUsage(usage) {
+        return {
+            inputTokens: usage?.prompt_tokens || 0,
+            outputTokens: usage?.completion_tokens || 0,
+            totalTokens: usage?.total_tokens || 0,
+        };
+    }
+    extractStatusCode(error) {
+        if (error && typeof error === 'object') {
+            const err = error;
+            const status = err.status;
+            if (typeof status === 'number') {
+                return status;
+            }
+        }
+        return undefined;
+    }
+    async checkHealth() {
+        try {
+            await withTimeout(this.client.chat.completions.create({
+                model: this.model,
+                max_tokens: 5,
+                messages: [{ role: 'user', content: 'Hi' }],
+            }), 5000, 'health check');
+            return {
+                healthy: true,
+                message: 'OpenAI API is accessible',
+            };
+        }
+        catch (error) {
+            return {
+                healthy: false,
+                message: `OpenAI API error: ${sanitizeErrorMessage(error, 'health check')}`,
+            };
+        }
+    }
+}
+export async function checkOpenAISetup(apiKey) {
+    if (!apiKey) {
+        return {
+            valid: false,
+            message: 'No API key provided',
+        };
+    }
+    try {
+        const provider = new OpenAIProvider({ apiKey });
+        const health = await provider.checkHealth();
+        return {
+            valid: health.healthy,
+            message: health.message,
+        };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            message: `Setup check failed: ${sanitizeErrorMessage(error, 'setup check')}`,
+        };
+    }
+}

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/pipeline/orchestrator.js

@@ -0,0 +1,228 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { getChangedFiles, isTestFile } from '../agent/git.js';
+import { logger } from '../logger.js';
+import { preprocess } from './stage0_preprocess.js';
+import { runImpactStage } from './stage1_impact.js';
+import { runCoverageStage } from './stage2_coverage.js';
+import { runGenerationStage } from './stage3_generation.js';
+import { runHealStage, resolveHealTargets, renderHealMarkdown } from './stage4_heal.js';
+import { buildSummary } from '../validation/output_schema.js';
+import { computeCannotDetermineRatio } from '../validation/guardrails.js';
+import { resolveGenerationProfile } from '../prompts/generation_profile.js';
+function createRunId() {
+    const ciRunId = process.env.GITHUB_RUN_ID;
+    const entropy = Math.random().toString(36).slice(2, 8);
+    const ts = Date.now().toString(36);
+    if (ciRunId) {
+        return `pipeline-gh-${ciRunId}-${ts}-${entropy}`;
+    }
+    return `pipeline-local-${ts}-${entropy}`;
+}
+export async function runPipeline(config) {
+    const runId = createRunId();
+    const startedAt = new Date().toISOString();
+    const allWarnings = [];
+    const stages = config.stages || ['preprocess', 'impact', 'coverage'];
+    const profile = config.profile || resolveGenerationProfile();
+    let generatedSpecs;
+    let healResult;
+    // Step 1: Get changed files
+    const gitResult = getChangedFiles(config.appPath, config.gitSince, {
+        includeUncommitted: config.gitIncludeUncommitted,
+    });
+    if (gitResult.error) {
+        allWarnings.push(`Git diff warning: ${gitResult.error}`);
+    }
+    const changedFiles = gitResult.files
+        .map((f) => f.replace(/\\/g, '/'))
+        .filter((f) => !isTestFile(f));
+    if (changedFiles.length === 0) {
+        allWarnings.push('No changed application files detected.');
+        const emptyReport = {
+            runId,
+            timestamp: startedAt,
+            gitRef: config.gitSince,
+            summary: buildSummary([]),
+            decisions: [],
+            warnings: allWarnings,
+            model: {},
+        };
+        const reportPath = writeReport(config.testsRoot, emptyReport);
+        return { report: emptyReport, reportPath, warnings: allWarnings };
+    }
+    const timings = {};
+    // Step 2: Preprocess — deterministic file classification + route family binding
+    const preprocessTimer = logger.timer('preprocess');
+    const preprocessResult = preprocess(changedFiles, {
+        appPath: config.appPath,
+        testsRoot: config.testsRoot,
+        routeFamilies: config.routeFamilies,
+        apiSurface: config.apiSurface,
+    });
+    timings.preprocess = preprocessTimer.end();
+    allWarnings.push(...preprocessResult.warnings);
+    let decisions = [];
+    // Step 3: Impact stage — AI-powered flow identification per family
+    if (stages.includes('impact')) {
+        const impactTimer = logger.timer('impact');
+        const impactResult = await runImpactStage(preprocessResult.familyGroups, preprocessResult.manifest, preprocessResult.specIndex, preprocessResult.apiSurface, preprocessResult.context, config.impact || {});
+        decisions = impactResult.decisions;
+        allWarnings.push(...impactResult.warnings);
+        timings.impact = impactTimer.end();
+        // Check cannot_determine ratio
+        const cannotDetermineRatio = computeCannotDetermineRatio(decisions);
+        if (cannotDetermineRatio > 0.3) {
+            allWarnings.push(`High cannot_determine ratio (${(cannotDetermineRatio * 100).toFixed(0)}%). Consider updating route-families.json or running with MCP exploration.`);
+        }
+    }
+    // Step 4: Coverage stage — AI-powered spec coverage evaluation
+    if (stages.includes('coverage') && decisions.length > 0) {
+        const coverageTimer = logger.timer('coverage');
+        const coverageResult = await runCoverageStage(decisions, preprocessResult.specIndex, preprocessResult.context, config.testsRoot, { ...(config.coverage || {}), profile });
+        decisions = coverageResult.decisions;
+        timings.coverage = coverageTimer.end();
+        allWarnings.push(...coverageResult.warnings);
+    }
+    // Step 5: Generation stage — AI-powered spec generation for create_spec / add_scenarios
+    if (stages.includes('generation') && decisions.length > 0) {
+        const generationTimer = logger.timer('generation');
+        const generationResult = await runGenerationStage(decisions, preprocessResult.apiSurface, config.testsRoot, { ...(config.generation || {}), profile });
+        generatedSpecs = generationResult.generated;
+        timings.generation = generationTimer.end();
+        allWarnings.push(...generationResult.warnings);
+    }
+    // Step 6: Heal stage — MCP-backed playwright-test-healer for failing/flaky specs
+    if (stages.includes('heal')) {
+        const healTimer = logger.timer('heal');
+        const healTargets = resolveHealTargets(config.testsRoot, {
+            playwrightReportPath: config.playwrightReportPath,
+            generatedSpecs,
+        }, decisions);
+        if (healTargets.length > 0) {
+            healResult = await runHealStage(config.testsRoot, healTargets, { ...(config.heal || { mcp: true }), profile });
+            allWarnings.push(...healResult.warnings);
+        }
+        else {
+            allWarnings.push('Heal stage: no targets found (no failing specs in report, no generated specs).');
+        }
+        timings.heal = healTimer.end();
+    }
+    // Build report
+    const report = {
+        runId,
+        timestamp: startedAt,
+        gitRef: config.gitSince,
+        summary: buildSummary(decisions),
+        decisions,
+        warnings: allWarnings,
+        model: {
+            impactAgent: config.impact?.provider || 'auto',
+            coverageAgent: config.coverage?.provider || 'auto',
+            generationAgent: stages.includes('generation') ? (config.generation?.provider || 'auto') : undefined,
+        },
+    };
+    const reportPath = writeReport(config.testsRoot, report, healResult, timings);
+    return { report, reportPath, warnings: allWarnings, generated: generatedSpecs, healResult };
+}
+function writeReport(testsRoot, report, healResult, timings) {
+    const outputDir = join(testsRoot, '.e2e-ai-agents');
+    if (!existsSync(outputDir)) {
+        mkdirSync(outputDir, { recursive: true });
+    }
+    // Include timings in the JSON report if available
+    const reportWithTimings = timings ? { ...report, timings } : report;
+    const jsonPath = join(outputDir, 'pipeline-report.json');
+    writeFileSync(jsonPath, JSON.stringify(reportWithTimings, null, 2), 'utf-8');
+    const mdPath = join(outputDir, 'pipeline-report.md');
+    writeFileSync(mdPath, renderMarkdown(report, healResult), 'utf-8');
+    return jsonPath;
+}
+function renderMarkdown(report, healResult) {
+    const lines = [
+        `# Impact Analysis Pipeline Report`,
+        '',
+        `**Run ID:** ${report.runId}`,
+        `**Timestamp:** ${report.timestamp}`,
+        `**Git Ref:** ${report.gitRef}`,
+        '',
+        `## Summary`,
+        '',
+        `| Metric | Value |`,
+        `|--------|-------|`,
+        `| Changed Files | ${report.summary.changedFiles} |`,
+        `| Route Families Impacted | ${report.summary.routeFamiliesImpacted.join(', ') || 'none'} |`,
+        `| Flows Identified | ${report.summary.flowsIdentified} |`,
+        `| Covered | ${report.summary.flowsCovered} |`,
+        `| Partial | ${report.summary.flowsPartial} |`,
+        `| Uncovered | ${report.summary.flowsUncovered} |`,
+        `| Cannot Determine | ${report.summary.actionsRequired.cannot_determine} |`,
+        `| Overall Confidence | ${report.summary.overallConfidence} |`,
+        '',
+    ];
+    if (report.decisions.length > 0) {
+        lines.push('## Decisions', '');
+        for (const d of report.decisions) {
+            lines.push(`### ${d.flowName} (${d.priority})`);
+            lines.push('');
+            lines.push(`- **Action:** ${d.action}`);
+            lines.push(`- **Route Family:** ${d.routeFamily}${d.featureId ? ` / ${d.featureId}` : ''}`);
+            if (d.specificRoute) {
+                lines.push(`- **Route:** ${d.specificRoute}`);
+            }
+            lines.push(`- **Confidence:** ${d.confidence}%`);
+            lines.push(`- **Evidence:** ${d.evidence}`);
+            lines.push(`- **Changed Files:** ${d.changedFiles.join(', ')}`);
+            if (d.userActions.length > 0) {
+                lines.push(`- **User Actions:** ${d.userActions.join('; ')}`);
+            }
+            if (d.existingSpecs.length > 0) {
+                lines.push('- **Existing Coverage:**');
+                for (const spec of d.existingSpecs) {
+                    lines.push(`  - ${spec.path} (${spec.coverageLevel})`);
+                    if (spec.testTitles.length > 0) {
+                        for (const title of spec.testTitles) {
+                            lines.push(`    - \`${title}\``);
+                        }
+                    }
+                    if (spec.missingScenarios && spec.missingScenarios.length > 0) {
+                        lines.push('    - Missing:');
+                        for (const scenario of spec.missingScenarios) {
+                            lines.push(`      - ${scenario}`);
+                        }
+                    }
+                }
+            }
+            if (d.scenariosToAdd && d.scenariosToAdd.length > 0) {
+                lines.push('- **Scenarios to Add:**');
+                for (const s of d.scenariosToAdd) {
+                    lines.push(`  - ${s}`);
+                }
+            }
+            if (d.targetSpec) {
+                lines.push(`- **Target Spec:** ${d.targetSpec}`);
+            }
+            if (d.newSpecPath) {
+                lines.push(`- **New Spec Path:** ${d.newSpecPath}`);
+            }
+            if (d.blockingReason) {
+                lines.push(`- **Blocking Reason:** ${d.blockingReason}`);
+            }
+            lines.push('');
+        }
+    }
+    if (healResult) {
+        lines.push('');
+        lines.push(renderHealMarkdown(healResult));
+    }
+    if (report.warnings.length > 0) {
+        lines.push('## Warnings', '');
+        for (const w of report.warnings) {
+            lines.push(`- ${w}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/dist/esm/pipeline/spec_verifier.js

@@ -0,0 +1,75 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { resolve } from 'path';
+import { runCommand } from '../agent/process_runner.js';
+/** Env var prefixes/names stripped when running LLM-generated specs */
+const SENSITIVE_ENV_PREFIXES = [
+    'AWS_', 'AZURE_', 'GCP_', 'GOOGLE_', 'ANTHROPIC_', 'OPENAI_',
+    'GITHUB_TOKEN', 'NPM_TOKEN', 'SSH_', 'SECRET_', 'PRIVATE_',
+    'DATABASE_URL', 'DB_', 'REDIS_', 'POSTGRES_', 'MYSQL_', 'MONGO_',
+    'API_KEY', 'API_SECRET', 'AUTH_', 'JWT_', 'STRIPE_', 'TWILIO_',
+    'SENDGRID_', 'SLACK_TOKEN', 'SLACK_BOT', 'MATTERMOST_',
+];
+/**
+ * Build a restricted environment for running LLM-generated spec files.
+ * Strips credentials and secrets to limit damage from malicious generated code.
+ */
+function buildRestrictedEnv() {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        const isSensitive = SENSITIVE_ENV_PREFIXES.some((prefix) => key.startsWith(prefix));
+        if (!isSensitive) {
+            env[key] = value;
+        }
+    }
+    return env;
+}
+/**
+ * Validate and normalize a spec path to prevent argument injection.
+ * Rejects raw input that starts with '-' (could be interpreted as flags by tsc/playwright).
+ */
+function sanitizeSpecPath(specPath) {
+    if (specPath.startsWith('-')) {
+        throw new Error(`Invalid spec path: "${specPath}" — path must not start with a dash`);
+    }
+    return resolve(specPath);
+}
+/**
+ * Compile-check a generated spec file using tsc --noEmit.
+ * Returns success: true if compilation succeeds, or errors array on failure.
+ */
+export function compileCheckSpec(specPath, testsRoot) {
+    const safeSpecPath = sanitizeSpecPath(specPath);
+    const result = runCommand('npx', ['tsc', '--noEmit', '--esModuleInterop', '--resolveJsonModule', '--moduleResolution', 'node', '--target', 'ES2020', safeSpecPath], testsRoot, 30000, buildRestrictedEnv());
+    if (result.status === 0) {
+        return { success: true, errors: [] };
+    }
+    const output = [result.stdout, result.stderr].filter(Boolean).join('\n');
+    const errorLines = output.split('\n')
+        .filter((l) => l.includes('error TS') || l.includes('Error:'))
+        .slice(0, 10);
+    return {
+        success: false,
+        errors: errorLines.length > 0 ? errorLines : [output.slice(0, 500) || 'Compilation failed'],
+    };
+}
+/**
+ * Smoke-run a generated spec against a running app.
+ * Runs in a restricted environment with sensitive env vars stripped.
+ * Returns success: true if the test passes with retries.
+ */
+export function smokeRunSpec(specPath, testsRoot, playwrightBinary) {
+    const safeSpecPath = sanitizeSpecPath(specPath);
+    const result = runCommand(playwrightBinary, ['test', safeSpecPath, '--retries', '2', '--reporter', 'list'], testsRoot, 120000, buildRestrictedEnv());
+    if (result.status === 0) {
+        return { success: true };
+    }
+    const output = [result.stdout, result.stderr].filter(Boolean).join('\n');
+    const errorLines = output.split('\n')
+        .filter((l) => l.includes('Error') || l.includes('FAILED') || l.includes('Timeout'))
+        .slice(0, 5);
+    return {
+        success: false,
+        error: errorLines.join('\n') || result.error || 'Smoke run failed',
+    };
+}

package/dist/esm/pipeline/stage0_preprocess.js

@@ -0,0 +1,102 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { bindFilesToFamilies, buildHeuristicFamilies, loadRouteFamilyManifest, } from '../knowledge/route_families.js';
+import { loadOrBuildApiSurface } from '../knowledge/api_surface.js';
+import { buildSpecIndex } from '../knowledge/spec_index.js';
+import { loadContextDocuments } from '../knowledge/context_loader.js';
+const MAX_SNIPPET_CHARS = 3000;
+const MAX_FILES_PER_GROUP = 30;
+function loadFileSnippet(appPath, filePath) {
+    const candidates = [
+        join(appPath, filePath),
+        filePath,
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            try {
+                const content = readFileSync(candidate, 'utf-8');
+                if (content.length <= MAX_SNIPPET_CHARS) {
+                    return content;
+                }
+                return content.slice(0, MAX_SNIPPET_CHARS) + '\n// ... truncated';
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return undefined;
+}
+export function preprocess(changedFiles, config) {
+    const warnings = [];
+    // Load route family manifest, fall back to heuristic families
+    let manifest = loadRouteFamilyManifest(config.testsRoot, config.routeFamilies);
+    if (!manifest) {
+        manifest = buildHeuristicFamilies(changedFiles, config.testsRoot);
+        warnings.push('Route family manifest not found. Using directory-based heuristics (lower accuracy).', 'Tip: Run `impact-gate train` to generate a proper manifest.');
+    }
+    // Load API surface catalog
+    const apiSurface = loadOrBuildApiSurface(config.testsRoot, config.apiSurface);
+    if (apiSurface.pageObjects.length === 0) {
+        warnings.push('API surface catalog is empty. Generated test validation will be limited.');
+    }
+    // Build spec index
+    const specIndex = buildSpecIndex(config.testsRoot, undefined, manifest);
+    // Load context documents
+    const context = loadContextDocuments(config.testsRoot, config.appPath);
+    warnings.push(...context.warnings);
+    // Bind files to families (manifest is always non-null now — either real or heuristic)
+    const fileBindings = bindFilesToFamilies(changedFiles, manifest);
+    const unboundFiles = fileBindings
+        .filter((fb) => fb.bindings.length === 0)
+        .map((fb) => fb.file);
+    if (unboundFiles.length > 0) {
+        warnings.push(`${unboundFiles.length} changed file(s) did not match any route family: ${unboundFiles.slice(0, 5).join(', ')}${unboundFiles.length > 5 ? '...' : ''}`);
+    }
+    // Group files by family+feature
+    const groupMap = new Map();
+    for (const binding of fileBindings) {
+        if (binding.bindings.length === 0) {
+            // Unbound files go into a special "unbound" group
+            const key = '__unbound__';
+            if (!groupMap.has(key)) {
+                groupMap.set(key, { familyId: '__unbound__', files: [] });
+            }
+            const group = groupMap.get(key);
+            if (group.files.length < MAX_FILES_PER_GROUP) {
+                group.files.push({
+                    path: binding.file,
+                    snippet: loadFileSnippet(config.appPath, binding.file),
+                });
+            }
+            continue;
+        }
+        for (const b of binding.bindings) {
+            const key = b.feature ? `${b.family}::${b.feature}` : b.family;
+            if (!groupMap.has(key)) {
+                groupMap.set(key, { familyId: b.family, featureId: b.feature, files: [] });
+            }
+            const group = groupMap.get(key);
+            if (group.files.length < MAX_FILES_PER_GROUP) {
+                group.files.push({
+                    path: binding.file,
+                    snippet: loadFileSnippet(config.appPath, binding.file),
+                });
+            }
+        }
+    }
+    const familyGroups = Array.from(groupMap.values()).filter((g) => g.familyId !== '__unbound__');
+    return {
+        changedFiles,
+        fileBindings,
+        unboundFiles,
+        familyGroups,
+        manifest,
+        apiSurface,
+        specIndex,
+        context,
+        warnings,
+    };
+}