@yasserkhanorg/impact-gate 2.0.0

package/dist/esm/knowledge/route_families.js

@@ -0,0 +1,393 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { existsSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { logger } from '../logger.js';
+const manifestCache = new Map();
+export function matchesGlob(filePath, pattern) {
+    const normalized = filePath.replace(/\\/g, '/');
+    const parts = pattern.replace(/\\/g, '/').split('*');
+    if (parts.length === 1) {
+        return normalized === parts[0] || normalized.startsWith(parts[0]);
+    }
+    let pos = 0;
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        if (part === '') {
+            continue;
+        }
+        const idx = normalized.indexOf(part, pos);
+        if (idx < 0) {
+            return false;
+        }
+        if (i === 0 && idx !== 0) {
+            return false;
+        }
+        pos = idx + part.length;
+    }
+    return true;
+}
+export function matchesAnyPattern(filePath, patterns) {
+    return patterns.some((pattern) => matchesGlob(filePath, pattern));
+}
+function validateApiEndpoint(ep) {
+    if (!ep || typeof ep !== 'object')
+        return null;
+    const obj = ep;
+    if (typeof obj.method !== 'string' || typeof obj.path !== 'string')
+        return null;
+    const result = { method: obj.method, path: obj.path };
+    if (typeof obj.description === 'string')
+        result.description = obj.description;
+    return result;
+}
+function validateFamily(family) {
+    if (!family || typeof family !== 'object') {
+        return null;
+    }
+    const obj = family;
+    if (typeof obj.id !== 'string' || !obj.id.trim()) {
+        return null;
+    }
+    // When testType is 'api', routes may contain API paths like "GET /api/users"
+    const testType = (obj.testType === 'ui' || obj.testType === 'api' || obj.testType === 'both')
+        ? obj.testType
+        : undefined;
+    if (!Array.isArray(obj.routes) || obj.routes.length === 0) {
+        return null;
+    }
+    const routes = obj.routes.filter((r) => typeof r === 'string');
+    if (routes.length === 0) {
+        return null;
+    }
+    const result = {
+        id: obj.id.trim(),
+        routes,
+    };
+    if (Array.isArray(obj.pageObjects)) {
+        result.pageObjects = obj.pageObjects.filter((v) => typeof v === 'string');
+    }
+    if (Array.isArray(obj.components)) {
+        result.components = obj.components.filter((v) => typeof v === 'string');
+    }
+    if (Array.isArray(obj.webappPaths)) {
+        result.webappPaths = obj.webappPaths.filter((v) => typeof v === 'string');
+    }
+    if (Array.isArray(obj.serverPaths)) {
+        result.serverPaths = obj.serverPaths.filter((v) => typeof v === 'string');
+    }
+    if (Array.isArray(obj.specDirs)) {
+        result.specDirs = obj.specDirs.filter((v) => typeof v === 'string');
+    }
+    if (Array.isArray(obj.cypressSpecDirs)) {
+        result.cypressSpecDirs = obj.cypressSpecDirs.filter((v) => typeof v === 'string');
+    }
+    if (Array.isArray(obj.tags)) {
+        result.tags = obj.tags.filter((v) => typeof v === 'string');
+    }
+    if (obj.priority === 'P0' || obj.priority === 'P1' || obj.priority === 'P2') {
+        result.priority = obj.priority;
+    }
+    if (Array.isArray(obj.userFlows)) {
+        result.userFlows = obj.userFlows.filter((v) => typeof v === 'string');
+    }
+    if (Array.isArray(obj.features)) {
+        result.features = obj.features
+            .map((f) => validateFeature(f))
+            .filter((f) => f !== null);
+    }
+    if (Array.isArray(obj.apiEndpoints)) {
+        const endpoints = obj.apiEndpoints
+            .map((ep) => validateApiEndpoint(ep))
+            .filter((ep) => ep !== null);
+        if (endpoints.length > 0)
+            result.apiEndpoints = endpoints;
+    }
+    if (testType) {
+        result.testType = testType;
+    }
+    if (Array.isArray(obj.assertionPatterns)) {
+        result.assertionPatterns = validateAssertionPatterns(obj.assertionPatterns);
+    }
+    return result;
+}
+const VALID_ASSERTION_TYPES = [
+    'state-change', 'cross-user', 'persistence', 'negative',
+    'permission', 'data-integrity', 'error-handling',
+];
+function validateAssertionPatterns(patterns) {
+    return patterns
+        .filter((p) => p != null && typeof p === 'object')
+        .filter((p) => typeof p.type === 'string' && typeof p.pattern === 'string')
+        .filter((p) => VALID_ASSERTION_TYPES.includes(p.type))
+        .map((p) => ({ type: p.type, pattern: p.pattern }));
+}
+function validateFeature(feature) {
+    if (!feature || typeof feature !== 'object') {
+        return null;
+    }
+    const obj = feature;
+    if (typeof obj.id !== 'string' || !obj.id.trim()) {
+        return null;
+    }
+    const result = { id: obj.id.trim() };
+    if (Array.isArray(obj.routes)) {
+        result.routes = obj.routes.filter((v) => typeof v === 'string');
+    }
+    if (Array.isArray(obj.webappPaths)) {
+        result.webappPaths = obj.webappPaths.filter((v) => typeof v === 'string');
+    }
+    if (Array.isArray(obj.serverPaths)) {
+        result.serverPaths = obj.serverPaths.filter((v) => typeof v === 'string');
+    }
+    if (Array.isArray(obj.specDirs)) {
+        result.specDirs = obj.specDirs.filter((v) => typeof v === 'string');
+    }
+    if (Array.isArray(obj.cypressSpecDirs)) {
+        result.cypressSpecDirs = obj.cypressSpecDirs.filter((v) => typeof v === 'string');
+    }
+    if (Array.isArray(obj.tags)) {
+        result.tags = obj.tags.filter((v) => typeof v === 'string');
+    }
+    if (obj.priority === 'P0' || obj.priority === 'P1' || obj.priority === 'P2') {
+        result.priority = obj.priority;
+    }
+    if (Array.isArray(obj.userFlows)) {
+        result.userFlows = obj.userFlows.filter((v) => typeof v === 'string');
+    }
+    if (Array.isArray(obj.assertionPatterns)) {
+        result.assertionPatterns = validateAssertionPatterns(obj.assertionPatterns);
+    }
+    return result;
+}
+export function loadRouteFamilyManifest(testsRoot, config) {
+    const candidates = [];
+    if (config?.manifestPath) {
+        candidates.push(config.manifestPath);
+    }
+    candidates.push(join(testsRoot, '.e2e-ai-agents', 'route-families.json'));
+    for (const candidate of candidates) {
+        try {
+            if (!existsSync(candidate)) {
+                continue;
+            }
+            const mtimeMs = statSync(candidate).mtimeMs;
+            const cached = manifestCache.get(candidate);
+            if (cached && cached.mtimeMs === mtimeMs && cached.manifest) {
+                return cached.manifest;
+            }
+            const raw = JSON.parse(readFileSync(candidate, 'utf-8'));
+            if (!raw.families || !Array.isArray(raw.families)) {
+                manifestCache.set(candidate, { mtimeMs, manifest: null });
+                continue;
+            }
+            const families = raw.families
+                .map((f) => validateFamily(f))
+                .filter((f) => f !== null);
+            if (families.length === 0) {
+                manifestCache.set(candidate, { mtimeMs, manifest: null });
+                continue;
+            }
+            const manifest = { families, source: candidate };
+            manifestCache.set(candidate, { mtimeMs, manifest });
+            return manifest;
+        }
+        catch {
+            continue;
+        }
+    }
+    if (config?.strict) {
+        logger.warn('Route family manifest not found. Create .e2e-ai-agents/route-families.json to enable family-level routing hints.');
+    }
+    return null;
+}
+export function bindFilesToFamilies(changedFiles, manifest) {
+    return changedFiles.map((file) => {
+        const normalized = file.replace(/\\/g, '/');
+        const bindings = [];
+        for (const family of manifest.families) {
+            const featureBindings = [];
+            // Check feature-level first (more specific)
+            if (family.features) {
+                for (const feature of family.features) {
+                    const featurePatterns = [
+                        ...(feature.webappPaths || []),
+                        ...(feature.serverPaths || []),
+                        ...(feature.specDirs || []),
+                    ];
+                    if (featurePatterns.length > 0 && matchesAnyPattern(normalized, featurePatterns)) {
+                        featureBindings.push({ family: family.id, feature: feature.id });
+                    }
+                }
+            }
+            if (featureBindings.length > 0) {
+                bindings.push(...featureBindings);
+                continue;
+            }
+            // Fall back to family-level patterns
+            const familyPatterns = [
+                ...(family.webappPaths || []),
+                ...(family.serverPaths || []),
+                ...(family.specDirs || []),
+                ...(family.cypressSpecDirs || []),
+            ];
+            if (familyPatterns.length > 0 && matchesAnyPattern(normalized, familyPatterns)) {
+                bindings.push({ family: family.id });
+            }
+        }
+        return { file: normalized, bindings };
+    });
+}
+export function getFamilyById(manifest, familyId) {
+    return manifest.families.find((f) => f.id === familyId);
+}
+export function getFeatureById(family, featureId) {
+    return family.features?.find((f) => f.id === featureId);
+}
+export function getSpecDirsForBinding(manifest, binding) {
+    const family = getFamilyById(manifest, binding.family);
+    if (!family) {
+        return [];
+    }
+    if (binding.feature) {
+        const feature = getFeatureById(family, binding.feature);
+        // An explicitly declared specDirs (even []) is intentional — don't fall back to family.
+        if (feature && feature.specDirs !== undefined) {
+            return feature.specDirs;
+        }
+    }
+    return family.specDirs || [];
+}
+export function getCypressSpecDirsForBinding(manifest, binding) {
+    const family = getFamilyById(manifest, binding.family);
+    if (!family) {
+        return [];
+    }
+    if (binding.feature) {
+        const feature = getFeatureById(family, binding.feature);
+        // An explicitly declared cypressSpecDirs (even []) is intentional — don't fall back to family.
+        if (feature && feature.cypressSpecDirs !== undefined) {
+            return feature.cypressSpecDirs;
+        }
+    }
+    return family.cypressSpecDirs || [];
+}
+export function getPriorityForBinding(manifest, binding) {
+    const family = getFamilyById(manifest, binding.family);
+    if (!family) {
+        return 'P2';
+    }
+    if (binding.feature) {
+        const feature = getFeatureById(family, binding.feature);
+        if (feature?.priority) {
+            return feature.priority;
+        }
+    }
+    return family.priority || 'P2';
+}
+export function getUserFlowsForBinding(manifest, binding) {
+    const family = getFamilyById(manifest, binding.family);
+    if (!family) {
+        return [];
+    }
+    if (binding.feature) {
+        const feature = getFeatureById(family, binding.feature);
+        if (feature?.userFlows && feature.userFlows.length > 0) {
+            return feature.userFlows;
+        }
+    }
+    return family.userFlows || [];
+}
+export function getRoutesForBinding(manifest, binding) {
+    const family = getFamilyById(manifest, binding.family);
+    if (!family) {
+        return [];
+    }
+    if (binding.feature) {
+        const feature = getFeatureById(family, binding.feature);
+        if (feature?.routes && feature.routes.length > 0) {
+            return feature.routes;
+        }
+    }
+    return family.routes;
+}
+export function getAssertionPatternsForBinding(manifest, binding) {
+    const family = getFamilyById(manifest, binding.family);
+    if (!family) {
+        return [];
+    }
+    if (binding.feature) {
+        const feature = getFeatureById(family, binding.feature);
+        if (feature?.assertionPatterns && feature.assertionPatterns.length > 0) {
+            return feature.assertionPatterns;
+        }
+    }
+    return family.assertionPatterns || [];
+}
+export function clearManifestCache() {
+    manifestCache.clear();
+}
+/**
+ * Build heuristic route families from changed files when no manifest exists.
+ * Groups files by their top-level directory to create rough family groupings.
+ * Results are lower confidence but allow analysis to proceed without training.
+ */
+export function buildHeuristicFamilies(changedFiles, testsRoot) {
+    const dirGroups = new Map();
+    for (const file of changedFiles) {
+        const normalized = file.replace(/\\/g, '/');
+        const parts = normalized.split('/');
+        // Use the first meaningful directory segment as the family ID
+        // Skip common prefixes like 'src/', 'app/', 'lib/'
+        const skipDirs = new Set(['src', 'app', 'lib', 'packages', 'components']);
+        let familyDir = parts[0] || 'root';
+        if (skipDirs.has(familyDir) && parts.length > 1) {
+            familyDir = parts[1];
+        }
+        // Normalize to a clean family name
+        familyDir = familyDir.replace(/\.[^.]+$/, ''); // strip file extensions for single files
+        if (!dirGroups.has(familyDir)) {
+            dirGroups.set(familyDir, []);
+        }
+        dirGroups.get(familyDir).push(normalized);
+    }
+    const families = [];
+    for (const [dir, files] of dirGroups) {
+        families.push({
+            id: dir,
+            routes: [`/${dir}`],
+            webappPaths: files.map((f) => `${f}*`),
+        });
+    }
+    logger.info(`Built ${families.length} heuristic families from ${changedFiles.length} changed files (no route-families.json found)`);
+    logger.info('Tip: Run `impact-gate train` to generate a proper route-families manifest for better accuracy.');
+    return {
+        families,
+        source: 'heuristic',
+    };
+}
+/**
+ * Serialize a RouteFamilyManifest to clean JSON, stripping empty optional fields.
+ */
+export function serializeManifest(manifest) {
+    const output = {
+        families: manifest.families.map((f) => {
+            const cleaned = { ...f };
+            const optionalArrays = [
+                'pageObjects', 'components', 'webappPaths', 'serverPaths',
+                'specDirs', 'cypressSpecDirs', 'tags', 'userFlows', 'features', 'apiEndpoints', 'assertionPatterns',
+            ];
+            for (const key of optionalArrays) {
+                if (!cleaned[key] || (Array.isArray(cleaned[key]) && cleaned[key].length === 0)) {
+                    delete cleaned[key];
+                }
+            }
+            if (!cleaned.priority)
+                delete cleaned.priority;
+            if (!cleaned.testType)
+                delete cleaned.testType;
+            return cleaned;
+        }),
+    };
+    return JSON.stringify(output, null, 2) + '\n';
+}

package/dist/esm/knowledge/spec_index.js

@@ -0,0 +1,122 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join, relative } from '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 (!existsSync(dir)) {
+        return entries;
+    }
+    const items = readdirSync(dir, { withFileTypes: true });
+    for (const item of items) {
+        const fullPath = 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 = readFileSync(fullPath, 'utf-8');
+            entries.push({
+                path: fullPath,
+                relativePath: 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;
+        }
+    }
+}
+export function buildSpecIndex(testsRoot, _specPatterns, manifest) {
+    const specsDir = join(testsRoot, 'specs');
+    const specs = scanSpecDir(specsDir, testsRoot);
+    if (manifest) {
+        for (const spec of specs) {
+            bindSpecToFamily(spec, manifest);
+        }
+    }
+    return {
+        specs,
+        indexedAt: new Date().toISOString(),
+    };
+}
+export 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;
+    });
+}
+export function getSpecByPath(index, relativePath) {
+    return index.specs.find((s) => s.relativePath === relativePath);
+}
+export 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/esm/logger.js

@@ -0,0 +1,115 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * Structured logging system.
+ * Environment variable: LOG_LEVEL (ERROR, WARN, INFO, DEBUG)
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["ERROR"] = 0] = "ERROR";
+    LogLevel[LogLevel["WARN"] = 1] = "WARN";
+    LogLevel[LogLevel["INFO"] = 2] = "INFO";
+    LogLevel[LogLevel["DEBUG"] = 3] = "DEBUG";
+})(LogLevel || (LogLevel = {}));
+/**
+ * Get log level from environment variable
+ */
+function getLogLevelFromEnv() {
+    const level = process.env.LOG_LEVEL?.toUpperCase() || 'INFO';
+    switch (level) {
+        case 'ERROR':
+            return LogLevel.ERROR;
+        case 'WARN':
+            return LogLevel.WARN;
+        case 'INFO':
+            return LogLevel.INFO;
+        case 'DEBUG':
+            return LogLevel.DEBUG;
+        default:
+            return LogLevel.INFO;
+    }
+}
+/**
+ * Convert log level to string
+ */
+function logLevelToString(level) {
+    switch (level) {
+        case LogLevel.ERROR:
+            return 'ERROR';
+        case LogLevel.WARN:
+            return 'WARN';
+        case LogLevel.INFO:
+            return 'INFO';
+        case LogLevel.DEBUG:
+            return 'DEBUG';
+    }
+}
+export class Logger {
+    constructor(minLevel) {
+        this.level = minLevel ?? getLogLevelFromEnv();
+        this.jsonMode = process.env.LOG_FORMAT?.toLowerCase() === 'json';
+    }
+    error(message, context) {
+        if (this.level >= LogLevel.ERROR) {
+            this.log(LogLevel.ERROR, message, context);
+        }
+    }
+    warn(message, context) {
+        if (this.level >= LogLevel.WARN) {
+            this.log(LogLevel.WARN, message, context);
+        }
+    }
+    info(message, context) {
+        if (this.level >= LogLevel.INFO) {
+            this.log(LogLevel.INFO, message, context);
+        }
+    }
+    debug(message, context) {
+        if (this.level >= LogLevel.DEBUG) {
+            this.log(LogLevel.DEBUG, message, context);
+        }
+    }
+    setLevel(level) {
+        this.level = level;
+    }
+    setJsonMode(enabled) {
+        this.jsonMode = enabled;
+    }
+    /**
+     * Start a timer for measuring duration of an operation.
+     * Returns an object with `end()` that logs at DEBUG level and returns elapsed ms.
+     */
+    timer(label) {
+        const start = performance.now();
+        return {
+            end: () => {
+                const elapsed = Math.round(performance.now() - start);
+                this.debug(`${label} completed`, { durationMs: elapsed });
+                return elapsed;
+            },
+        };
+    }
+    log(level, message, context) {
+        const timestamp = new Date().toISOString();
+        const levelStr = logLevelToString(level);
+        let output;
+        if (this.jsonMode) {
+            const entry = { ts: timestamp, level: levelStr, msg: message };
+            if (context)
+                entry.ctx = context;
+            output = JSON.stringify(entry);
+        }
+        else {
+            const contextStr = context ? ` ${JSON.stringify(context)}` : '';
+            output = `[${timestamp}] [${levelStr}] ${message}${contextStr}`;
+        }
+        if (level <= LogLevel.WARN) {
+            console.error(output);
+        }
+        else {
+            console.log(output);
+        }
+    }
+}
+// Global logger instance
+export const logger = new Logger();