@yasserkhanorg/e2e-agents 0.3.7 → 0.4.0

package/dist/knowledge/spec_index.js

@@ -0,0 +1,128 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSpecIndex = buildSpecIndex;
+exports.getSpecsForFamily = getSpecsForFamily;
+exports.getSpecByPath = getSpecByPath;
+exports.formatSpecsForPrompt = formatSpecsForPrompt;
+const fs_1 = require("fs");
+const path_1 = require("path");
+function extractTestTitles(content) {
+    const titles = [];
+    const testRe = /\btest\s*\(\s*(['"`])((?:(?!\1).|\\.)*)\1/g;
+    let match;
+    while ((match = testRe.exec(content)) !== null) {
+        const title = match[2].trim();
+        if (title) {
+            titles.push(title);
+        }
+    }
+    return titles;
+}
+function extractTags(content) {
+    const tags = new Set();
+    const singleTagRe = /\btag:\s*['"`](@[\w-]+)['"`]/g;
+    let match;
+    while ((match = singleTagRe.exec(content)) !== null) {
+        tags.add(match[1]);
+    }
+    const arrayTagRe = /\btag:\s*\[([^\]]*)\]/g;
+    while ((match = arrayTagRe.exec(content)) !== null) {
+        const inner = match[1];
+        const tagRe = /['"`](@[\w-]+)['"`]/g;
+        let tagMatch;
+        while ((tagMatch = tagRe.exec(inner)) !== null) {
+            tags.add(tagMatch[1]);
+        }
+    }
+    return Array.from(tags);
+}
+function scanSpecDir(dir, testsRoot) {
+    const entries = [];
+    if (!(0, fs_1.existsSync)(dir)) {
+        return entries;
+    }
+    const items = (0, fs_1.readdirSync)(dir, { withFileTypes: true });
+    for (const item of items) {
+        const fullPath = (0, path_1.join)(dir, item.name);
+        if (item.isDirectory()) {
+            entries.push(...scanSpecDir(fullPath, testsRoot));
+            continue;
+        }
+        if (!item.name.endsWith('.spec.ts') && !item.name.endsWith('.spec.tsx')) {
+            continue;
+        }
+        try {
+            const content = (0, fs_1.readFileSync)(fullPath, 'utf-8');
+            entries.push({
+                path: fullPath,
+                relativePath: (0, path_1.relative)(testsRoot, fullPath).replace(/\\/g, '/'),
+                testTitles: extractTestTitles(content),
+                tags: extractTags(content),
+            });
+        }
+        catch {
+            continue;
+        }
+    }
+    return entries;
+}
+function bindSpecToFamily(spec, manifest) {
+    const specPath = spec.relativePath;
+    for (const family of manifest.families) {
+        if (family.features) {
+            for (const feature of family.features) {
+                if (feature.specDirs?.some((dir) => specPath.startsWith(dir))) {
+                    spec.familyId = family.id;
+                    spec.featureId = feature.id;
+                    return;
+                }
+            }
+        }
+        if (family.specDirs?.some((dir) => specPath.startsWith(dir))) {
+            spec.familyId = family.id;
+            return;
+        }
+        if (family.tags && spec.tags.some((t) => family.tags.includes(t))) {
+            spec.familyId = family.id;
+            return;
+        }
+    }
+}
+function buildSpecIndex(testsRoot, _specPatterns, manifest) {
+    const specsDir = (0, path_1.join)(testsRoot, 'specs');
+    const specs = scanSpecDir(specsDir, testsRoot);
+    if (manifest) {
+        for (const spec of specs) {
+            bindSpecToFamily(spec, manifest);
+        }
+    }
+    return {
+        specs,
+        indexedAt: new Date().toISOString(),
+    };
+}
+function getSpecsForFamily(index, familyId, featureId) {
+    return index.specs.filter((s) => {
+        if (s.familyId !== familyId) {
+            return false;
+        }
+        if (featureId && s.featureId && s.featureId !== featureId) {
+            return false;
+        }
+        return true;
+    });
+}
+function getSpecByPath(index, relativePath) {
+    return index.specs.find((s) => s.relativePath === relativePath);
+}
+function formatSpecsForPrompt(specs) {
+    return specs
+        .map((s) => {
+        const titles = s.testTitles.map((t) => `  - ${t}`).join('\n');
+        const tagsStr = s.tags.length > 0 ? ` [${s.tags.join(', ')}]` : '';
+        return `${s.relativePath}${tagsStr}\n${titles}`;
+    })
+        .join('\n\n');
+}

package/dist/pipeline/orchestrator.d.ts

@@ -0,0 +1,26 @@
+import { type ImpactConfig } from './stage1_impact.js';
+import { type CoverageConfig } from './stage2_coverage.js';
+import { type GenerationConfig, type GeneratedSpec } from './stage3_generation.js';
+import { type FlowDecisionReport } from '../validation/output_schema.js';
+import type { RouteFamilyConfig } from '../knowledge/route_families.js';
+import type { ApiSurfaceConfig } from '../knowledge/api_surface.js';
+export interface PipelineConfig {
+    appPath: string;
+    testsRoot: string;
+    gitSince: string;
+    gitIncludeUncommitted?: boolean;
+    routeFamilies?: RouteFamilyConfig;
+    apiSurface?: ApiSurfaceConfig;
+    impact?: ImpactConfig;
+    coverage?: CoverageConfig;
+    generation?: GenerationConfig;
+    stages?: Array<'preprocess' | 'impact' | 'coverage' | 'generation'>;
+}
+export interface PipelineResult {
+    report: FlowDecisionReport;
+    reportPath: string;
+    warnings: string[];
+    generated?: GeneratedSpec[];
+}
+export declare function runPipeline(config: PipelineConfig): Promise<PipelineResult>;
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/pipeline/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/pipeline/orchestrator.ts"],"names":[],"mappings":"AAOA,OAAO,EAAiB,KAAK,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAmB,KAAK,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAqB,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAC,MAAM,wBAAwB,CAAC;AACrG,OAAO,EAAe,KAAK,kBAAkB,EAAoB,MAAM,gCAAgC,CAAC;AAExG,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,gCAAgC,CAAC;AACtE,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,6BAA6B,CAAC;AAElE,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,MAAM,CAAC,EAAE,KAAK,CAAC,YAAY,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,cAAc;IAC3B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;CAC/B;AAoBD,wBAAsB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CA6GjF"}

package/dist/pipeline/orchestrator.js

@@ -0,0 +1,202 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPipeline = runPipeline;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const git_js_1 = require("../agent/git.js");
+const stage0_preprocess_js_1 = require("./stage0_preprocess.js");
+const stage1_impact_js_1 = require("./stage1_impact.js");
+const stage2_coverage_js_1 = require("./stage2_coverage.js");
+const stage3_generation_js_1 = require("./stage3_generation.js");
+const output_schema_js_1 = require("../validation/output_schema.js");
+const guardrails_js_1 = require("../validation/guardrails.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}`;
+}
+function isTestFile(file) {
+    const normalized = file.replace(/\\/g, '/');
+    return /\.(spec|test)\.(ts|tsx|js|jsx)$/.test(normalized) ||
+        normalized.includes('__tests__/') ||
+        normalized.includes('/tests/') ||
+        normalized.includes('/test/');
+}
+async function runPipeline(config) {
+    const runId = createRunId();
+    const startedAt = new Date().toISOString();
+    const allWarnings = [];
+    const stages = config.stages || ['preprocess', 'impact', 'coverage'];
+    let generatedSpecs;
+    // Step 1: Get changed files
+    const gitResult = (0, git_js_1.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: (0, output_schema_js_1.buildSummary)([]),
+            decisions: [],
+            warnings: allWarnings,
+            model: {},
+        };
+        const reportPath = writeReport(config.testsRoot, emptyReport);
+        return { report: emptyReport, reportPath, warnings: allWarnings };
+    }
+    // Step 2: Preprocess — deterministic file classification + route family binding
+    const preprocessResult = (0, stage0_preprocess_js_1.preprocess)(changedFiles, {
+        appPath: config.appPath,
+        testsRoot: config.testsRoot,
+        routeFamilies: config.routeFamilies,
+        apiSurface: config.apiSurface,
+    });
+    allWarnings.push(...preprocessResult.warnings);
+    let decisions = [];
+    // Step 3: Impact stage — AI-powered flow identification per family
+    if (stages.includes('impact')) {
+        const impactResult = await (0, stage1_impact_js_1.runImpactStage)(preprocessResult.familyGroups, preprocessResult.manifest, preprocessResult.specIndex, preprocessResult.apiSurface, preprocessResult.context, config.impact || {});
+        decisions = impactResult.decisions;
+        allWarnings.push(...impactResult.warnings);
+        // Check cannot_determine ratio
+        const cannotDetermineRatio = (0, guardrails_js_1.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 coverageResult = await (0, stage2_coverage_js_1.runCoverageStage)(decisions, preprocessResult.specIndex, preprocessResult.context, config.testsRoot, config.coverage || {});
+        decisions = coverageResult.decisions;
+        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 generationResult = await (0, stage3_generation_js_1.runGenerationStage)(decisions, preprocessResult.apiSurface, config.testsRoot, config.generation || {});
+        generatedSpecs = generationResult.generated;
+        allWarnings.push(...generationResult.warnings);
+    }
+    // Build report
+    const report = {
+        runId,
+        timestamp: startedAt,
+        gitRef: config.gitSince,
+        summary: (0, output_schema_js_1.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);
+    return { report, reportPath, warnings: allWarnings, generated: generatedSpecs };
+}
+function writeReport(testsRoot, report) {
+    const outputDir = (0, path_1.join)(testsRoot, '.e2e-ai-agents');
+    if (!(0, fs_1.existsSync)(outputDir)) {
+        (0, fs_1.mkdirSync)(outputDir, { recursive: true });
+    }
+    const jsonPath = (0, path_1.join)(outputDir, 'pipeline-report.json');
+    (0, fs_1.writeFileSync)(jsonPath, JSON.stringify(report, null, 2), 'utf-8');
+    const mdPath = (0, path_1.join)(outputDir, 'pipeline-report.md');
+    (0, fs_1.writeFileSync)(mdPath, renderMarkdown(report), 'utf-8');
+    return jsonPath;
+}
+function renderMarkdown(report) {
+    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 (report.warnings.length > 0) {
+        lines.push('## Warnings', '');
+        for (const w of report.warnings) {
+            lines.push(`- ${w}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/dist/pipeline/stage0_preprocess.d.ts

@@ -0,0 +1,31 @@
+import { type FileBinding, type RouteFamilyConfig, type RouteFamilyManifest } from '../knowledge/route_families.js';
+import { type ApiSurfaceCatalog, type ApiSurfaceConfig } from '../knowledge/api_surface.js';
+import { type SpecIndex } from '../knowledge/spec_index.js';
+import { type LoadedContext } from '../knowledge/context_loader.js';
+export interface PreprocessConfig {
+    appPath: string;
+    testsRoot: string;
+    routeFamilies?: RouteFamilyConfig;
+    apiSurface?: ApiSurfaceConfig;
+}
+export interface FamilyGroup {
+    familyId: string;
+    featureId?: string;
+    files: Array<{
+        path: string;
+        snippet?: string;
+    }>;
+}
+export interface PreprocessResult {
+    changedFiles: string[];
+    fileBindings: FileBinding[];
+    unboundFiles: string[];
+    familyGroups: FamilyGroup[];
+    manifest: RouteFamilyManifest | null;
+    apiSurface: ApiSurfaceCatalog;
+    specIndex: SpecIndex;
+    context: LoadedContext;
+    warnings: string[];
+}
+export declare function preprocess(changedFiles: string[], config: PreprocessConfig): PreprocessResult;
+//# sourceMappingURL=stage0_preprocess.d.ts.map

package/dist/pipeline/stage0_preprocess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage0_preprocess.d.ts","sourceRoot":"","sources":["../../src/pipeline/stage0_preprocess.ts"],"names":[],"mappings":"AAKA,OAAO,EAGH,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EAC3B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAwB,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAC,MAAM,6BAA6B,CAAC;AACjH,OAAO,EAAiB,KAAK,SAAS,EAAC,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EAAuB,KAAK,aAAa,EAAC,MAAM,gCAAgC,CAAC;AAExF,MAAM,WAAW,gBAAgB;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,gBAAgB;IAC7B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACrC,UAAU,EAAE,iBAAiB,CAAC;IAC9B,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACtB;AA0BD,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAsF7F"}

package/dist/pipeline/stage0_preprocess.js

@@ -0,0 +1,112 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preprocess = preprocess;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const route_families_js_1 = require("../knowledge/route_families.js");
+const api_surface_js_1 = require("../knowledge/api_surface.js");
+const spec_index_js_1 = require("../knowledge/spec_index.js");
+const context_loader_js_1 = require("../knowledge/context_loader.js");
+const MAX_SNIPPET_CHARS = 3000;
+const MAX_FILES_PER_GROUP = 30;
+function loadFileSnippet(appPath, filePath) {
+    const candidates = [
+        (0, path_1.join)(appPath, filePath),
+        filePath,
+    ];
+    for (const candidate of candidates) {
+        if ((0, fs_1.existsSync)(candidate)) {
+            try {
+                const content = (0, fs_1.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;
+}
+function preprocess(changedFiles, config) {
+    const warnings = [];
+    // Load route family manifest
+    const manifest = (0, route_families_js_1.loadRouteFamilyManifest)(config.testsRoot, config.routeFamilies);
+    if (!manifest) {
+        warnings.push('Route family manifest not found. File-to-family binding will be skipped; AI will operate without route constraints.');
+    }
+    // Load API surface catalog
+    const apiSurface = (0, api_surface_js_1.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 = (0, spec_index_js_1.buildSpecIndex)(config.testsRoot, undefined, manifest);
+    // Load context documents
+    const context = (0, context_loader_js_1.loadContextDocuments)(config.testsRoot, config.appPath);
+    warnings.push(...context.warnings);
+    // Bind files to families
+    let fileBindings = [];
+    let unboundFiles = [];
+    if (manifest) {
+        fileBindings = (0, route_families_js_1.bindFilesToFamilies)(changedFiles, manifest);
+        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 ? '...' : ''}`);
+        }
+    }
+    else {
+        fileBindings = changedFiles.map((f) => ({ file: f, bindings: [] }));
+        unboundFiles = changedFiles;
+    }
+    // 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,
+    };
+}

package/dist/pipeline/stage1_impact.d.ts

@@ -0,0 +1,19 @@
+import { type RouteFamilyManifest } from '../knowledge/route_families.js';
+import { type SpecIndex } from '../knowledge/spec_index.js';
+import type { ApiSurfaceCatalog } from '../knowledge/api_surface.js';
+import type { LoadedContext } from '../knowledge/context_loader.js';
+import type { FamilyGroup } from './stage0_preprocess.js';
+import type { FlowDecision } from '../validation/output_schema.js';
+export interface ImpactConfig {
+    provider?: string;
+    maxTokens?: number;
+    temperature?: number;
+    timeout?: number;
+}
+export interface ImpactResult {
+    decisions: FlowDecision[];
+    warnings: string[];
+    providerName: string;
+}
+export declare function runImpactStage(familyGroups: FamilyGroup[], manifest: RouteFamilyManifest | null, specIndex: SpecIndex, apiSurface: ApiSurfaceCatalog, context: LoadedContext, config: ImpactConfig): Promise<ImpactResult>;
+//# sourceMappingURL=stage1_impact.d.ts.map

package/dist/pipeline/stage1_impact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage1_impact.d.ts","sourceRoot":"","sources":["../../src/pipeline/stage1_impact.ts"],"names":[],"mappings":"AAOA,OAAO,EAAgB,KAAK,mBAAmB,EAAC,MAAM,gCAAgC,CAAC;AACvF,OAAO,EAAoB,KAAK,SAAS,EAAC,MAAM,4BAA4B,CAAC;AAC7E,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAC,YAAY,EAA+B,MAAM,gCAAgC,CAAC;AAG/F,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IACzB,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACxB;AAgBD,wBAAsB,cAAc,CAChC,YAAY,EAAE,WAAW,EAAE,EAC3B,QAAQ,EAAE,mBAAmB,GAAG,IAAI,EACpC,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,iBAAiB,EAC7B,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,YAAY,GACrB,OAAO,CAAC,YAAY,CAAC,CAmHvB"}

package/dist/pipeline/stage1_impact.js

@@ -0,0 +1,127 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runImpactStage = runImpactStage;
+const provider_factory_js_1 = require("../provider_factory.js");
+const impact_js_1 = require("../prompts/impact.js");
+const context_loader_js_1 = require("../knowledge/context_loader.js");
+const route_families_js_1 = require("../knowledge/route_families.js");
+const spec_index_js_1 = require("../knowledge/spec_index.js");
+const guardrails_js_1 = require("../validation/guardrails.js");
+function normalizePriority(value) {
+    if (value === 'P0' || value === 'P1' || value === 'P2') {
+        return value;
+    }
+    return 'P2';
+}
+async function getProvider(config) {
+    if (config.provider && config.provider !== 'auto') {
+        return provider_factory_js_1.LLMProviderFactory.createFromString(config.provider);
+    }
+    return provider_factory_js_1.LLMProviderFactory.createFromEnv();
+}
+async function runImpactStage(familyGroups, manifest, specIndex, apiSurface, context, config) {
+    const warnings = [];
+    const allDecisions = [];
+    if (familyGroups.length === 0) {
+        warnings.push('No family groups to analyze. All changed files were unbound.');
+        return { decisions: [], warnings, providerName: 'none' };
+    }
+    let provider;
+    try {
+        provider = await getProvider(config);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        warnings.push(`Impact agent unavailable: ${message}`);
+        return { decisions: [], warnings, providerName: 'none' };
+    }
+    const contextBlock = (0, context_loader_js_1.formatContextForPrompt)(context);
+    for (const group of familyGroups) {
+        const family = manifest ? (0, route_families_js_1.getFamilyById)(manifest, group.familyId) : null;
+        if (!family) {
+            // For unbound groups, create cannot_determine decisions
+            for (const file of group.files) {
+                allDecisions.push({
+                    flowId: `unbound_${file.path.replace(/[^a-zA-Z0-9]/g, '_')}`,
+                    flowName: `Unbound file: ${file.path}`,
+                    routeFamily: '__unbound__',
+                    changedFiles: [file.path],
+                    evidence: 'File does not match any known route family in the manifest.',
+                    evidenceSource: 'deterministic',
+                    confidence: 0,
+                    existingSpecs: [],
+                    action: 'cannot_determine',
+                    blockingReason: 'File not mapped to any route family. Update route-families.json to include this file path.',
+                    priority: 'P2',
+                    userActions: [],
+                });
+            }
+            continue;
+        }
+        const specs = (0, spec_index_js_1.getSpecsForFamily)(specIndex, group.familyId, group.featureId);
+        const promptCtx = {
+            family,
+            featureId: group.featureId,
+            changedFiles: group.files,
+            existingSpecs: specs,
+            apiSurface,
+            contextBlock,
+        };
+        const prompt = (0, impact_js_1.buildImpactPrompt)(promptCtx);
+        try {
+            const response = await provider.generateText(prompt, {
+                maxTokens: config.maxTokens || 4000,
+                temperature: config.temperature ?? 0,
+                timeout: config.timeout || 45000,
+                systemPrompt: 'Return only valid JSON. Do not include markdown fences unless necessary.',
+            });
+            const parsed = (0, impact_js_1.parseImpactResponse)(response.text);
+            if (!parsed || parsed.flows.length === 0) {
+                warnings.push(`Impact agent returned no flows for family ${group.familyId}.`);
+                continue;
+            }
+            for (const flow of parsed.flows) {
+                if (!flow.id || !flow.changedFiles || !Array.isArray(flow.changedFiles)) {
+                    continue;
+                }
+                const confidence = typeof flow.confidence === 'number'
+                    ? Math.max(0, Math.min(100, flow.confidence))
+                    : (0, guardrails_js_1.computeConfidence)({
+                        hasRouteFamily: true,
+                        hasSpecificRoute: Boolean(flow.route),
+                        hasPageObject: Boolean(flow.pageObjects && flow.pageObjects.length > 0),
+                        hasUserAction: Boolean(flow.userActions && flow.userActions.length > 0),
+                        hasExistingSpecCited: false,
+                    });
+                const decision = {
+                    flowId: flow.id,
+                    flowName: flow.name || flow.id,
+                    routeFamily: group.familyId,
+                    featureId: group.featureId,
+                    specificRoute: flow.route,
+                    changedFiles: flow.changedFiles.filter((f) => typeof f === 'string'),
+                    evidence: flow.evidence || 'AI identified this flow as impacted.',
+                    evidenceSource: 'ai',
+                    confidence,
+                    existingSpecs: [],
+                    action: (0, guardrails_js_1.shouldForceCannotDetermine)(confidence) ? 'cannot_determine' : 'run_existing',
+                    blockingReason: (0, guardrails_js_1.shouldForceCannotDetermine)(confidence) ? 'Confidence too low to determine action.' : undefined,
+                    priority: normalizePriority(flow.priority),
+                    userActions: Array.isArray(flow.userActions) ? flow.userActions.filter((a) => typeof a === 'string') : [],
+                };
+                allDecisions.push(decision);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            warnings.push(`Impact agent failed for family ${group.familyId}: ${message}`);
+        }
+    }
+    return {
+        decisions: allDecisions,
+        warnings,
+        providerName: provider.name,
+    };
+}