@yasserkhanorg/impact-gate 2.0.0

package/dist/engine/ai_enrichment.js

@@ -0,0 +1,267 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enrichImpactWithAI = enrichImpactWithAI;
+const diff_loader_js_1 = require("./diff_loader.js");
+const MAX_SPEC_LIST = 50;
+function normalizePriority(value) {
+    if (value === 'P0' || value === 'P1' || value === 'P2') {
+        return value;
+    }
+    return 'P2';
+}
+const MAX_SCENARIOS_PER_SPEC = 20;
+function buildPrompt(options) {
+    const { deterministicImpact, diffs, specList, specDetails, 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((0, diff_loader_js_1.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';
+        const userFlowsDisplay = feature.userFlows.length > 0 ? ` userFlows=[${feature.userFlows.slice(0, 5).join(', ')}]` : '';
+        lines.push(`- familyId=${feature.familyId} ${featureIdPart} (${feature.priority}): ${specCount} specs, coverage=${feature.coverageStatus}, specs=[${specsDisplay}]${userFlowsDisplay}`);
+    }
+    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 coverage with scenario titles (when available) or bare file paths
+    if (specDetails && specDetails.length > 0) {
+        const cappedDetails = specDetails.slice(0, MAX_SPEC_LIST);
+        const totalScenarios = cappedDetails.reduce((sum, s) => sum + s.scenarios.length, 0);
+        lines.push(`## Existing Test Coverage (${cappedDetails.length} specs, ${totalScenarios} scenarios)`);
+        lines.push('Use this to avoid suggesting scenarios that already exist.');
+        lines.push('');
+        for (const spec of cappedDetails) {
+            lines.push(`- ${spec.file}`);
+            const cappedScenarios = spec.scenarios.slice(0, MAX_SCENARIOS_PER_SPEC);
+            for (const scenario of cappedScenarios) {
+                lines.push(`  • "${scenario}"`);
+            }
+            if (spec.scenarios.length > MAX_SCENARIOS_PER_SPEC) {
+                lines.push(`  • ... and ${spec.scenarios.length - MAX_SCENARIOS_PER_SPEC} more`);
+            }
+        }
+        lines.push('');
+    }
+    else 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('Rules for coveredBy:');
+    lines.push('- Reference SPECIFIC scenario titles from the Existing Test Coverage section when possible.');
+    lines.push('- Format: "file.spec.ts → scenario title"');
+    lines.push('');
+    lines.push('Rules for missingScenarios:');
+    lines.push('- Cross-reference the scenario titles in Existing Test Coverage. If a scenario already exists that covers the behavior, do NOT suggest it — instead list it in coveredBy.');
+    lines.push('- For coverage=uncovered: list ONLY scenarios that test the SPECIFIC behavior change in this diff — NOT generic scenarios for the entire feature. A permission check fix needs permission-denial test scenarios, not general CRUD tests.');
+    lines.push('- For coverage=covered or coverage=partial: ONLY list scenarios introduced by THIS diff that have NO matching scenario in existing coverage. If the diff adds no new user-visible behavior, return []. Do not pad with generic scenarios.');
+    lines.push('- If the source code diff is trivial (single-line fix, type change, field rename, or the PR is primarily adding tests), return missingScenarios=[] and explain in reasons that no new user-visible behavior was introduced.');
+    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: [
+                    '<EXACTLY 1-2 sentences explaining what SPECIFICALLY changed for users in THIS diff. Reference the actual behavior modification — NOT a general description of what the feature does. BAD: "Users can create and view posts." GOOD: "Users editing posts now require create_post permission, which may block edits for restricted roles.">',
+                ],
+                coveredBy: ['<spec file paths that cover this flow>'],
+                missingScenarios: ['<concrete scenario title for a NEW or CHANGED behavior in THIS diff. Must be SPECIFIC to the code change — never generic feature tests. BAD: "User can create a new post". GOOD: "User without create_post permission sees error when editing a post". If the diff is trivial (typo, field rename, test-only) return [].>'],
+            },
+        ],
+        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.
+ */
+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/engine/diff_loader.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare function loadDiffs(appRoot: string, since: string, changedFiles: string[]): Map<string, string>;
+/**
+ * Formats a diffs map into a human-readable string suitable for an AI prompt.
+ */
+export declare function formatDiffsForPrompt(diffs: Map<string, string>): string;
+//# sourceMappingURL=diff_loader.d.ts.map

package/dist/engine/diff_loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff_loader.d.ts","sourceRoot":"","sources":["../../src/engine/diff_loader.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CA0CrG;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAUvE"}

package/dist/engine/diff_loader.js

@@ -0,0 +1,63 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadDiffs = loadDiffs;
+exports.formatDiffsForPrompt = formatDiffsForPrompt;
+const git_js_1 = require("../agent/git.js");
+const MAX_DIFF_CHARS = 8000;
+const MAX_TOTAL_CHARS = 60000;
+const TRUNCATION_NOTICE = '\n... (diff truncated)';
+/**
+ * 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.
+ */
+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 = (0, git_js_1.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 = (0, git_js_1.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.
+ */
+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');
+}

package/dist/engine/impact_engine.d.ts

@@ -0,0 +1,72 @@
+import type { FeaturePriority } from '../knowledge/route_families.js';
+import type { RouteFamiliesConfig } from '../agent/config.js';
+export type CoverageStatus = 'covered' | 'partial' | 'uncovered';
+export interface SpecWithScenarios {
+    file: string;
+    scenarios: string[];
+}
+export interface ImpactedFeature {
+    familyId: string;
+    featureId?: string;
+    priority: FeaturePriority;
+    changedFiles: string[];
+    playwrightSpecs: string[];
+    cypressSpecs: string[];
+    playwrightSpecDetails: SpecWithScenarios[];
+    cypressSpecDetails: SpecWithScenarios[];
+    userFlows: string[];
+    coverageStatus: CoverageStatus;
+}
+export type PrTestFileType = 'playwright' | 'cypress' | 'unit' | 'snapshot';
+export interface PrTestFile {
+    file: string;
+    type: PrTestFileType;
+}
+export interface ImpactResult {
+    changedFiles: string[];
+    expandedFiles: string[];
+    impactedFeatures: ImpactedFeature[];
+    unboundFiles: string[];
+    warnings: string[];
+    /** Test files that were in the original PR changeset but filtered from analysis. */
+    prIncludedTestFiles: PrTestFile[];
+}
+export interface ImpactEngineOptions {
+    testsRoot: string;
+    cypressRoot?: string;
+    routeFamilies?: RouteFamiliesConfig;
+    expandedFiles?: string[];
+    /** Test files that were filtered by the caller (e.g. isRelevantFile in git.ts). Used to detect PR-included E2E specs. */
+    filteredTestFiles?: string[];
+}
+/**
+ * Extract describe/test/it titles from a spec file using regex.
+ * Returns an empty array if the file cannot be read.
+ */
+export declare function extractScenarios(filePath: string, framework: 'playwright' | 'cypress'): string[];
+export declare function analyzeImpact(changedFiles: string[], options: ImpactEngineOptions): ImpactResult;
+export interface GapResult {
+    /** Active gaps that should be reported/enforced. */
+    gaps: ImpactedFeature[];
+    /** Family-level gaps suppressed because all their files are covered by specific feature matches. These should be promoted to advisory. */
+    suppressedGaps: ImpactedFeature[];
+}
+/**
+ * Get gaps: P0/P1 features with 'uncovered' status.
+ *
+ * Suppresses family-level (generic) gaps when ALL their changed files are
+ * already covered by feature-level (specific) matches in other families.
+ * Suppressed gaps are returned separately so the plan builder can promote
+ * them to advisory ("new behavior detected") on covered flows.
+ */
+export declare function getGapsWithSuppressed(result: ImpactResult): GapResult;
+/**
+ * Get gaps: P0/P1 features with 'uncovered' status.
+ * Convenience wrapper that returns only active gaps (backward-compatible).
+ */
+export declare function getGaps(result: ImpactResult): ImpactedFeature[];
+/**
+ * Get partial gaps: P0/P1 features with 'partial' status (advisory).
+ */
+export declare function getPartialGaps(result: ImpactResult): ImpactedFeature[];
+//# sourceMappingURL=impact_engine.d.ts.map

package/dist/engine/impact_engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact_engine.d.ts","sourceRoot":"","sources":["../../src/engine/impact_engine.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAGR,eAAe,EAClB,MAAM,gCAAgC,CAAC;AAUxC,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,oBAAoB,CAAC;AAG5D,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;AAEjE,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,eAAe,CAAC;IAC1B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,qBAAqB,EAAE,iBAAiB,EAAE,CAAC;IAC3C,kBAAkB,EAAE,iBAAiB,EAAE,CAAC;IACxC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,cAAc,EAAE,cAAc,CAAC;CAClC;AAED,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAE5E,MAAM,WAAW,UAAU;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,eAAe,EAAE,CAAC;IACpC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oFAAoF;IACpF,mBAAmB,EAAE,UAAU,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,yHAAyH;IACzH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AA+CD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,GAAG,SAAS,GAAG,MAAM,EAAE,CAgBhG;AAgGD,wBAAgB,aAAa,CACzB,YAAY,EAAE,MAAM,EAAE,EACtB,OAAO,EAAE,mBAAmB,GAC7B,YAAY,CAoFd;AAYD,MAAM,WAAW,SAAS;IACtB,oDAAoD;IACpD,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,0IAA0I;IAC1I,cAAc,EAAE,eAAe,EAAE,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CA2BrE;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe,EAAE,CAE/D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe,EAAE,CAItE"}