@yasserkhanorg/impact-gate 2.0.0

package/dist/qa-agent/phase2/tools.js

@@ -0,0 +1,390 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_DEFINITIONS = void 0;
+exports.executeTool = executeTool;
+// ---------------------------------------------------------------------------
+// Tool definitions (Anthropic tool_use schema)
+// ---------------------------------------------------------------------------
+exports.TOOL_DEFINITIONS = [
+    {
+        name: 'navigate',
+        description: 'Navigate to a URL. Use absolute paths starting with / or full URLs.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'URL or path to navigate to' },
+            },
+            required: ['url'],
+        },
+    },
+    {
+        name: 'click',
+        description: 'Click an element by its accessibility ref (e.g. @e4).',
+        input_schema: {
+            type: 'object',
+            properties: {
+                ref: { type: 'string', description: 'Accessibility ref like @e4' },
+            },
+            required: ['ref'],
+        },
+    },
+    {
+        name: 'fill',
+        description: 'Clear a field and type new text into it.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                ref: { type: 'string', description: 'Accessibility ref of the input field' },
+                value: { type: 'string', description: 'Text to type' },
+            },
+            required: ['ref', 'value'],
+        },
+    },
+    {
+        name: 'press_key',
+        description: 'Press a keyboard key (e.g. Enter, Escape, Tab).',
+        input_schema: {
+            type: 'object',
+            properties: {
+                key: { type: 'string', description: 'Key name (Enter, Escape, Tab, etc.)' },
+            },
+            required: ['key'],
+        },
+    },
+    {
+        name: 'scroll',
+        description: 'Scroll the page or a specific element up or down.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                direction: { type: 'string', enum: ['up', 'down'] },
+                ref: { type: 'string', description: 'Optional element ref to scroll within' },
+            },
+            required: ['direction'],
+        },
+    },
+    {
+        name: 'go_back',
+        description: 'Go back to the previous page.',
+        input_schema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'take_screenshot',
+        description: 'Take an annotated screenshot for evidence or vision analysis. Use sparingly (costs tokens).',
+        input_schema: {
+            type: 'object',
+            properties: {
+                label: { type: 'string', description: 'Short label for the screenshot (used in filename)' },
+            },
+            required: ['label'],
+        },
+    },
+    {
+        name: 'get_text',
+        description: 'Read the text content of a specific element.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                ref: { type: 'string', description: 'Accessibility ref' },
+            },
+            required: ['ref'],
+        },
+    },
+    {
+        name: 'report_finding',
+        description: 'Report a bug, visual issue, UX problem, or gap you discovered. Include expected/actual behavior and repro steps. Take before/after screenshots before calling this.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                type: { type: 'string', enum: ['bug', 'visual-regression', 'ux-issue', 'gap'] },
+                severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low', 'info'] },
+                summary: { type: 'string', description: 'What you found' },
+                repro_steps: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Steps to reproduce',
+                },
+                screenshot_refs: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Paths to before/after screenshots (from take_screenshot)',
+                },
+                expected_behavior: { type: 'string', description: 'What should have happened' },
+                actual_behavior: { type: 'string', description: 'What actually happened' },
+            },
+            required: ['type', 'severity', 'summary', 'repro_steps'],
+        },
+    },
+    {
+        name: 'mark_flow_done',
+        description: 'Mark the current flow as verified/explored. Call when you are done testing a flow.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                flow_id: { type: 'string', description: 'ID of the flow being marked done' },
+                status: { type: 'string', enum: ['verified-ok', 'has-issues'] },
+            },
+            required: ['flow_id', 'status'],
+        },
+    },
+    {
+        name: 'switch_user',
+        description: 'Log out and log in as a different user role.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                role: { type: 'string', description: 'Role of the user to switch to (e.g. admin, regular, guest)' },
+            },
+            required: ['role'],
+        },
+    },
+    {
+        name: 'wait_for',
+        description: 'Wait for an element condition or page state. Use after actions that trigger async changes (navigation, API calls, animations).',
+        input_schema: {
+            type: 'object',
+            properties: {
+                condition: {
+                    type: 'string',
+                    enum: ['visible', 'hidden', 'stable', 'networkidle'],
+                    description: 'What to wait for: visible/hidden (element state), stable (no DOM changes for 1s), networkidle (no pending requests)',
+                },
+                ref: { type: 'string', description: 'Accessibility ref for element conditions (visible/hidden). Not needed for stable/networkidle.' },
+                timeout_ms: { type: 'number', description: 'Max wait time in ms (default 5000, max 15000)' },
+            },
+            required: ['condition'],
+        },
+    },
+];
+function executeTool(ctx, name, input) {
+    switch (name) {
+        case 'navigate': {
+            const url = String(input.url || '');
+            const fullUrl = url.startsWith('http') ? url : `${ctx.baseUrl}${url}`;
+            // Security: restrict navigation to the configured baseUrl domain
+            if (!isAllowedUrl(fullUrl, ctx.baseUrl)) {
+                return { output: `Blocked: navigation to "${fullUrl}" is outside the allowed domain (${ctx.baseUrl}).` };
+            }
+            const output = ctx.browser.open(fullUrl);
+            ctx.currentUrl = ctx.browser.getUrl();
+            return { output: output || `Navigated to ${ctx.currentUrl}`, navigated: true };
+        }
+        case 'click': {
+            const output = ctx.browser.click(String(input.ref));
+            return { output: output || `Clicked ${input.ref}` };
+        }
+        case 'fill': {
+            const ref = String(input.ref);
+            const value = String(input.value);
+            const output = ctx.browser.fill(ref, value);
+            // Redact value for password-like fields to avoid leaking credentials to LLM
+            const isSensitive = /password|passwd|pwd|secret|token/i.test(ref);
+            const displayValue = isSensitive ? '[REDACTED]' : `"${value}"`;
+            return { output: output || `Filled ${ref} with ${displayValue}` };
+        }
+        case 'press_key': {
+            const output = ctx.browser.press(String(input.key));
+            return { output: output || `Pressed ${input.key}` };
+        }
+        case 'scroll': {
+            const rawDir = String(input.direction);
+            if (rawDir !== 'up' && rawDir !== 'down') {
+                return { output: `Invalid scroll direction "${rawDir}". Must be "up" or "down".` };
+            }
+            const ref = input.ref ? String(input.ref) : undefined;
+            const output = ctx.browser.scroll(rawDir, ref);
+            return { output: output || `Scrolled ${rawDir}` };
+        }
+        case 'go_back': {
+            const output = ctx.browser.back();
+            ctx.currentUrl = ctx.browser.getUrl();
+            return { output: output || `Went back to ${ctx.currentUrl}` };
+        }
+        case 'take_screenshot': {
+            ctx.screenshotCounter++;
+            const label = String(input.label || 'evidence').replace(/[^a-zA-Z0-9_-]/g, '_');
+            const filename = `${String(ctx.screenshotCounter).padStart(3, '0')}-${label}.png`;
+            const path = `${ctx.screenshotDir}/${filename}`;
+            ctx.browser.screenshot(path);
+            return { output: `Screenshot saved: ${path}` };
+        }
+        case 'get_text': {
+            const text = ctx.browser.getText(String(input.ref));
+            return { output: text || '(empty)' };
+        }
+        case 'report_finding': {
+            const VALID_TYPES = new Set(['bug', 'visual-regression', 'ux-issue', 'gap']);
+            const VALID_SEVERITIES = new Set(['critical', 'high', 'medium', 'low', 'info']);
+            const rawType = String(input.type);
+            const rawSeverity = String(input.severity);
+            if (!VALID_TYPES.has(rawType)) {
+                return { output: `Invalid finding type "${rawType}". Must be one of: ${[...VALID_TYPES].join(', ')}.` };
+            }
+            if (!VALID_SEVERITIES.has(rawSeverity)) {
+                return { output: `Invalid severity "${rawSeverity}". Must be one of: ${[...VALID_SEVERITIES].join(', ')}.` };
+            }
+            if (!Array.isArray(input.repro_steps)) {
+                return { output: `Invalid repro_steps: expected an array of strings.` };
+            }
+            // Auto-capture console errors at time of finding
+            let autoConsoleErrors;
+            try {
+                const raw = ctx.browser.evaluateInternal('JSON.stringify(window.__consoleErrors || [])');
+                const parsed = JSON.parse(raw);
+                if (Array.isArray(parsed) && parsed.length > 0) {
+                    autoConsoleErrors = parsed.map(String).slice(-10);
+                }
+            }
+            catch {
+                // Console error capture not available
+            }
+            // Auto-take screenshot if none provided
+            let autoScreenshot;
+            const screenshotRefs = Array.isArray(input.screenshot_refs)
+                ? input.screenshot_refs.map(String)
+                : undefined;
+            if (!screenshotRefs || screenshotRefs.length === 0) {
+                try {
+                    const nextCount = ctx.screenshotCounter + 1;
+                    const filename = `${String(nextCount).padStart(3, '0')}-finding-auto.png`;
+                    const screenshotPath = `${ctx.screenshotDir}/${filename}`;
+                    ctx.browser.screenshot(screenshotPath);
+                    ctx.screenshotCounter = nextCount;
+                    autoScreenshot = screenshotPath;
+                }
+                catch {
+                    autoScreenshot = undefined;
+                }
+            }
+            const finding = {
+                id: `f-${crypto.randomUUID()}`,
+                type: rawType,
+                severity: rawSeverity,
+                summary: String(input.summary),
+                flow: ctx.currentFlow,
+                evidence: {
+                    url: ctx.currentUrl,
+                    reproSteps: input.repro_steps.map(String),
+                    screenshotRefs: screenshotRefs || (autoScreenshot ? [autoScreenshot] : undefined),
+                    screenshotPath: autoScreenshot || (screenshotRefs ? screenshotRefs[0] : undefined),
+                    consoleErrors: autoConsoleErrors,
+                    expectedBehavior: input.expected_behavior ? String(input.expected_behavior) : undefined,
+                    actualBehavior: input.actual_behavior ? String(input.actual_behavior) : undefined,
+                },
+                timestamp: Date.now(),
+            };
+            return { output: `Finding recorded: [${finding.severity}] ${finding.summary}`, finding };
+        }
+        case 'mark_flow_done': {
+            const flowId = String(input.flow_id);
+            const rawStatus = String(input.status);
+            if (rawStatus !== 'verified-ok' && rawStatus !== 'has-issues') {
+                return { output: `Invalid status "${rawStatus}". Must be "verified-ok" or "has-issues".` };
+            }
+            return {
+                output: `Flow "${flowId}" marked as ${rawStatus}`,
+                flowDone: { flowId, status: rawStatus },
+            };
+        }
+        case 'wait_for': {
+            const condition = String(input.condition || '');
+            const VALID_CONDITIONS = new Set(['visible', 'hidden', 'stable', 'networkidle']);
+            if (!VALID_CONDITIONS.has(condition)) {
+                return { output: `Invalid condition "${condition}". Must be one of: ${[...VALID_CONDITIONS].join(', ')}.` };
+            }
+            const timeoutMs = Math.min(Math.max(Number(input.timeout_ms) || 5000, 500), 15000);
+            try {
+                if (condition === 'stable' || condition === 'networkidle') {
+                    const waitMs = condition === 'networkidle' ? Math.min(timeoutMs, 3000) : 1000;
+                    ctx.browser.evaluateInternal(`new Promise(r => setTimeout(r, ${waitMs}))`);
+                    return { output: `Waited ${waitMs}ms for ${condition} (heuristic delay)` };
+                }
+                // Element-level wait: poll snapshot for ref presence/absence
+                const ref = input.ref ? String(input.ref) : undefined;
+                if (!ref) {
+                    return { output: `Element condition "${condition}" requires a ref parameter.` };
+                }
+                const start = Date.now();
+                const wantVisible = condition === 'visible';
+                // Use word-boundary regex to avoid false positives (@e1 matching @e10)
+                const refPattern = new RegExp(`(?<![\\w@])${ref.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w])`);
+                const pollIntervalMs = 300;
+                while (Date.now() - start < timeoutMs) {
+                    const snap = ctx.browser.snapshot();
+                    const found = refPattern.test(snap);
+                    if ((wantVisible && found) || (!wantVisible && !found)) {
+                        return { output: `Element ${ref} is now ${condition} (took ${Date.now() - start}ms)` };
+                    }
+                    // Synchronous in-process sleep via Atomics.wait (available in Node.js 8.10+)
+                    const buf = new SharedArrayBuffer(4);
+                    Atomics.wait(new Int32Array(buf), 0, 0, pollIntervalMs);
+                }
+                return { output: `Timeout: element ${ref} did not become ${condition} within ${timeoutMs}ms` };
+            }
+            catch (err) {
+                return { output: `wait_for error: ${String(err)}` };
+            }
+        }
+        case 'switch_user': {
+            const role = String(input.role);
+            const user = ctx.users?.find((u) => u.role === role);
+            if (!user) {
+                return { output: `No user configured for role "${role}". Available: ${(ctx.users || []).map((u) => u.role).join(', ')}` };
+            }
+            // Log out first, then log in as new user
+            try {
+                ctx.browser.open(`${ctx.baseUrl}/logout`);
+            }
+            catch {
+                // May not be logged in
+            }
+            ctx.browser.open(`${ctx.baseUrl}/login`);
+            // Use snapshot to find login fields, then fill
+            const snap = ctx.browser.snapshot();
+            const emailRef = extractRef(snap, 'email') || extractRef(snap, 'username') || '@e1';
+            const passRef = extractRef(snap, 'password') || '@e2';
+            ctx.browser.fill(emailRef, user.username);
+            ctx.browser.fill(passRef, user.password);
+            ctx.browser.press('Enter');
+            ctx.currentUrl = ctx.browser.getUrl();
+            // Redact credentials from LLM context — only expose role
+            return { output: `Switched to user role: ${user.role}` };
+        }
+        default:
+            return { output: `Unknown tool: ${name}` };
+    }
+}
+function isAllowedUrl(url, baseUrl) {
+    // Block dangerous schemes
+    const scheme = url.split(':')[0]?.toLowerCase();
+    if (scheme && !['http', 'https'].includes(scheme))
+        return false;
+    // Parse both URLs and compare origins (hostname + port)
+    try {
+        const target = new URL(url);
+        const base = new URL(baseUrl);
+        return target.origin === base.origin;
+    }
+    catch {
+        // If URL parsing fails, only allow relative paths (already prefixed with baseUrl)
+        return url.startsWith(baseUrl);
+    }
+}
+function extractRef(snapshot, fieldHint) {
+    // Look for lines containing the hint and extract the @eN ref
+    const lines = snapshot.split('\n');
+    for (const line of lines) {
+        if (line.toLowerCase().includes(fieldHint)) {
+            const match = line.match(/@e\d+/);
+            if (match)
+                return match[0];
+        }
+    }
+    return undefined;
+}

package/dist/qa-agent/phase2/vision.d.ts

@@ -0,0 +1,3 @@
+import type { Finding } from '../types.js';
+export declare function analyzeScreenshot(screenshotPath: string, url: string, flow: string): Promise<Finding[]>;
+//# sourceMappingURL=vision.d.ts.map

package/dist/qa-agent/phase2/vision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision.d.ts","sourceRoot":"","sources":["../../../src/qa-agent/phase2/vision.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAC,OAAO,EAA+B,MAAM,aAAa,CAAC;AA2BvE,wBAAsB,iBAAiB,CACnC,cAAc,EAAE,MAAM,EACtB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,EAAE,CAAC,CAoBpB"}

package/dist/qa-agent/phase2/vision.js

@@ -0,0 +1,78 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeScreenshot = analyzeScreenshot;
+const fs_1 = require("fs");
+const provider_factory_js_1 = require("../../provider_factory.js");
+const VALID_TYPES = new Set(['bug', 'visual-regression', 'ux-issue', 'gap']);
+const VALID_SEVERITIES = new Set(['critical', 'high', 'medium', 'low', 'info']);
+const VISION_PROMPT = `You are a QA engineer analyzing a screenshot of a web application.
+Look for these categories of issues:
+
+1. **Layout issues**: overlapping elements, misaligned content, broken grid, elements outside viewport
+2. **Visual issues**: truncated text, missing icons/images, broken styling, inconsistent spacing
+3. **UX issues**: unclear button labels, confusing navigation, missing feedback states, poor contrast
+4. **State issues**: loading spinners stuck, empty states without messaging, stale data indicators
+5. **Error states**: visible error messages, 404/500 pages, broken components
+
+For each issue found, respond with a JSON array of objects:
+[
+  {
+    "type": "bug" | "visual-regression" | "ux-issue",
+    "severity": "critical" | "high" | "medium" | "low" | "info",
+    "summary": "description of the issue"
+  }
+]
+
+If no issues are found, respond with an empty array: []
+
+Only report clear, actionable issues. Do not speculate about functionality you cannot see.`;
+async function analyzeScreenshot(screenshotPath, url, flow) {
+    const provider = await provider_factory_js_1.LLMProviderFactory.createFromEnv();
+    if (!provider.capabilities.vision || !provider.analyzeImage) {
+        return [];
+    }
+    let imageData;
+    try {
+        imageData = (0, fs_1.readFileSync)(screenshotPath).toString('base64');
+    }
+    catch {
+        return [];
+    }
+    const response = await provider.analyzeImage([{ base64: imageData, mediaType: 'image/png' }], VISION_PROMPT, { maxTokens: 2000, temperature: 0.1 });
+    return parseVisionResponse(response.text, url, flow, screenshotPath);
+}
+function parseVisionResponse(text, url, flow, screenshotPath) {
+    // Extract JSON array from response
+    const jsonMatch = text.match(/\[[\s\S]*\]/);
+    if (!jsonMatch)
+        return [];
+    try {
+        const items = JSON.parse(jsonMatch[0]);
+        if (!Array.isArray(items))
+            return [];
+        return items
+            .filter((item) => {
+            const t = String(item.type || '');
+            const s = String(item.severity || '');
+            return VALID_TYPES.has(t) && VALID_SEVERITIES.has(s);
+        })
+            .map((item) => ({
+            id: `v-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`,
+            type: String(item.type),
+            severity: String(item.severity),
+            summary: String(item.summary || 'Visual issue detected'),
+            flow,
+            evidence: {
+                url,
+                screenshotPath,
+                reproSteps: ['Captured via automated vision analysis'],
+            },
+            timestamp: Date.now(),
+        }));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/qa-agent/phase3/feedback.d.ts

@@ -0,0 +1,3 @@
+import type { QAConfig } from '../types.js';
+export declare function submitFeedback(config: QAConfig): void;
+//# sourceMappingURL=feedback.d.ts.map

package/dist/qa-agent/phase3/feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../../src/qa-agent/phase3/feedback.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,aAAa,CAAC;AAE1C,wBAAgB,cAAc,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CA8BrD"}

package/dist/qa-agent/phase3/feedback.js

@@ -0,0 +1,37 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.submitFeedback = submitFeedback;
+const child_process_1 = require("child_process");
+const logger_js_1 = require("../../logger.js");
+const safe_env_js_1 = require("../safe_env.js");
+function submitFeedback(config) {
+    const args = ['impact-gate', 'feedback'];
+    if (config.testsRoot) {
+        args.push('--tests-root', config.testsRoot);
+    }
+    logger_js_1.logger.info('Submitting feedback to calibration system');
+    const result = (0, child_process_1.spawnSync)('npx', args, {
+        cwd: config.testsRoot || process.cwd(),
+        encoding: 'utf-8',
+        timeout: 30000,
+        env: (0, safe_env_js_1.safeEnv)(),
+    });
+    if (result.error) {
+        logger_js_1.logger.warn('Feedback submission spawn failed', {
+            error: result.error.message,
+        });
+    }
+    else if (result.signal) {
+        logger_js_1.logger.warn('Feedback submission killed by signal', {
+            signal: result.signal,
+        });
+    }
+    else if (result.status !== 0) {
+        logger_js_1.logger.warn('Feedback submission failed', {
+            status: result.status,
+            stderr: (result.stderr || '').slice(0, 200),
+        });
+    }
+}

package/dist/qa-agent/phase3/reporter.d.ts

@@ -0,0 +1,3 @@
+import type { Phase1Result, Phase2Result, Phase3Result, QAConfig, ReleaseVerdict } from '../types.js';
+export declare function generateReport(config: QAConfig, phase1: Phase1Result, phase2: Phase2Result, verdict: ReleaseVerdict, generatedSpecs: string[]): Phase3Result;
+//# sourceMappingURL=reporter.d.ts.map

package/dist/qa-agent/phase3/reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../../../src/qa-agent/phase3/reporter.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAC,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAY,cAAc,EAAC,MAAM,aAAa,CAAC;AAE9G,wBAAgB,cAAc,CAC1B,MAAM,EAAE,QAAQ,EAChB,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,cAAc,EACvB,cAAc,EAAE,MAAM,EAAE,GACzB,YAAY,CA8Cd"}