@yasserkhanorg/impact-gate 2.0.0

package/dist/knowledge/cluster_utils.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared cluster ID derivation for knowledge graph processing.
+ * Used by both kg_bridge.ts and kg_scanner.ts.
+ */
+/** Default directories to skip when deriving cluster IDs from file paths. */
+declare const DEFAULT_SKIP_DIRS: Set<string>;
+/** Extended skip set that also excludes test directories. */
+declare const SKIP_DIRS_WITH_TESTS: Set<string>;
+/**
+ * Normalize a name to a snake_case cluster ID.
+ * Handles camelCase conversion, then strips non-alphanumeric characters.
+ */
+export declare function normalizeToClusterId(name: string): string;
+/**
+ * Derive a cluster ID from a node that has an optional filePath and name.
+ * Prefers file path grouping for consistency.
+ */
+export declare function deriveClusterId(node: {
+    filePath?: string;
+    name: string;
+}, skipDirs?: Set<string>): string | null;
+/**
+ * Derive a cluster ID from a file path by finding the first meaningful
+ * directory segment after skipping common structural prefixes.
+ */
+export declare function deriveClusterIdFromPath(filePath: string, skipDirs?: Set<string>): string | null;
+export { DEFAULT_SKIP_DIRS, SKIP_DIRS_WITH_TESTS };
+//# sourceMappingURL=cluster_utils.d.ts.map

package/dist/knowledge/cluster_utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster_utils.d.ts","sourceRoot":"","sources":["../../src/knowledge/cluster_utils.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH,6EAA6E;AAC7E,QAAA,MAAM,iBAAiB,aAGrB,CAAC;AAEH,6DAA6D;AAC7D,QAAA,MAAM,oBAAoB,aAGxB,CAAC;AAEH;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMzD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC3B,IAAI,EAAE;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,EACvC,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GACvB,MAAM,GAAG,IAAI,CAMf;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACnC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,GAAG,CAAC,MAAM,CAAqB,GAC1C,MAAM,GAAG,IAAI,CAef;AAED,OAAO,EAAC,iBAAiB,EAAE,oBAAoB,EAAC,CAAC"}

package/dist/knowledge/cluster_utils.js

@@ -0,0 +1,67 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKIP_DIRS_WITH_TESTS = exports.DEFAULT_SKIP_DIRS = void 0;
+exports.normalizeToClusterId = normalizeToClusterId;
+exports.deriveClusterId = deriveClusterId;
+exports.deriveClusterIdFromPath = deriveClusterIdFromPath;
+/**
+ * Shared cluster ID derivation for knowledge graph processing.
+ * Used by both kg_bridge.ts and kg_scanner.ts.
+ */
+/** Default directories to skip when deriving cluster IDs from file paths. */
+const DEFAULT_SKIP_DIRS = new Set([
+    'src', 'app', 'lib', 'packages', 'server', 'api', 'pages',
+    'components', 'features', 'modules',
+]);
+exports.DEFAULT_SKIP_DIRS = DEFAULT_SKIP_DIRS;
+/** Extended skip set that also excludes test directories. */
+const SKIP_DIRS_WITH_TESTS = new Set([
+    ...DEFAULT_SKIP_DIRS,
+    'test', 'tests', 'e2e', 'spec', 'specs',
+]);
+exports.SKIP_DIRS_WITH_TESTS = SKIP_DIRS_WITH_TESTS;
+/**
+ * Normalize a name to a snake_case cluster ID.
+ * Handles camelCase conversion, then strips non-alphanumeric characters.
+ */
+function normalizeToClusterId(name) {
+    return name
+        .replace(/[A-Z]/g, (c, idx) => (idx > 0 ? `_${c.toLowerCase()}` : c.toLowerCase()))
+        .replace(/[^a-z0-9_]/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_|_$/g, '');
+}
+/**
+ * Derive a cluster ID from a node that has an optional filePath and name.
+ * Prefers file path grouping for consistency.
+ */
+function deriveClusterId(node, skipDirs) {
+    if (node.filePath) {
+        return deriveClusterIdFromPath(node.filePath, skipDirs);
+    }
+    const name = normalizeToClusterId(node.name);
+    return name && name.length > 1 ? name : null;
+}
+/**
+ * Derive a cluster ID from a file path by finding the first meaningful
+ * directory segment after skipping common structural prefixes.
+ */
+function deriveClusterIdFromPath(filePath, skipDirs = DEFAULT_SKIP_DIRS) {
+    const parts = filePath.replace(/\\/g, '/').split('/').filter(Boolean);
+    for (const part of parts) {
+        if (skipDirs.has(part))
+            continue;
+        if (part.includes('.'))
+            continue; // skip files
+        const normalized = part.toLowerCase()
+            .replace(/[^a-z0-9_]/g, '_')
+            .replace(/_+/g, '_')
+            .replace(/^_|_$/g, '');
+        if (normalized && normalized.length > 1) {
+            return normalized;
+        }
+    }
+    return null;
+}

package/dist/knowledge/context_loader.d.ts

@@ -0,0 +1,13 @@
+export interface ContextDocument {
+    name: string;
+    path: string;
+    content: string;
+}
+export interface LoadedContext {
+    documents: ContextDocument[];
+    warnings: string[];
+}
+export declare function loadContextDocuments(testsRoot: string, appRoot?: string, additionalFiles?: string[]): LoadedContext;
+export declare function formatContextForPrompt(context: LoadedContext): string;
+export declare function loadSpecFileContent(testsRoot: string, relativePath: string, maxChars?: number): string | null;
+//# sourceMappingURL=context_loader.d.ts.map

package/dist/knowledge/context_loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context_loader.d.ts","sourceRoot":"","sources":["../../src/knowledge/context_loader.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC1B,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACtB;AAWD,wBAAgB,oBAAoB,CAChC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,MAAM,EAAE,GAC3B,aAAa,CA4Df;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAOrE;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,SAAQ,GAAG,MAAM,GAAG,IAAI,CAW5G"}

package/dist/knowledge/context_loader.js

@@ -0,0 +1,90 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadContextDocuments = loadContextDocuments;
+exports.formatContextForPrompt = formatContextForPrompt;
+exports.loadSpecFileContent = loadSpecFileContent;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const MAX_CHARS_PER_DOC = 15000;
+const MAX_TOTAL_CHARS = 40000;
+const DEFAULT_CONTEXT_FILES = [
+    'CLAUDE.OPTIONAL.md',
+    '.claude/CLAUDE.OPTIONAL.md',
+    'README.md',
+];
+function loadContextDocuments(testsRoot, appRoot, additionalFiles) {
+    const warnings = [];
+    const documents = [];
+    let totalChars = 0;
+    const files = [...DEFAULT_CONTEXT_FILES, ...(additionalFiles || [])];
+    const seen = new Set();
+    for (const file of files) {
+        if (totalChars >= MAX_TOTAL_CHARS) {
+            break;
+        }
+        const candidates = [
+            (0, path_1.join)(testsRoot, file),
+            ...(appRoot && appRoot !== testsRoot ? [(0, path_1.join)(appRoot, file)] : []),
+        ];
+        let found = false;
+        for (const candidate of candidates) {
+            const normalized = candidate.replace(/\\/g, '/');
+            if (seen.has(normalized)) {
+                continue;
+            }
+            seen.add(normalized);
+            if (!(0, fs_1.existsSync)(candidate)) {
+                continue;
+            }
+            try {
+                const raw = (0, fs_1.readFileSync)(candidate, 'utf-8').trim();
+                if (!raw) {
+                    continue;
+                }
+                const remaining = MAX_TOTAL_CHARS - totalChars;
+                const content = raw.slice(0, Math.min(MAX_CHARS_PER_DOC, remaining));
+                documents.push({
+                    name: file,
+                    path: normalized,
+                    content,
+                });
+                totalChars += content.length;
+                found = true;
+                break;
+            }
+            catch {
+                continue;
+            }
+        }
+        if (!found && DEFAULT_CONTEXT_FILES.includes(file)) {
+            // Only warn for default files, not user-provided ones
+        }
+    }
+    if (documents.length === 0) {
+        warnings.push('No context documents found (CLAUDE.OPTIONAL.md, README.md). AI agents will have reduced context.');
+    }
+    return { documents, warnings };
+}
+function formatContextForPrompt(context) {
+    if (context.documents.length === 0) {
+        return 'No repository context documents available.';
+    }
+    return context.documents
+        .map((doc) => `### Context: ${doc.name}\n${doc.content}`)
+        .join('\n\n');
+}
+function loadSpecFileContent(testsRoot, relativePath, maxChars = 20000) {
+    const fullPath = (0, path_1.join)(testsRoot, relativePath);
+    if (!(0, fs_1.existsSync)(fullPath)) {
+        return null;
+    }
+    try {
+        const content = (0, fs_1.readFileSync)(fullPath, 'utf-8');
+        return content.slice(0, maxChars);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/knowledge/failure_history.d.ts

@@ -0,0 +1,39 @@
+export interface FailureCorrelation {
+    /** Source file that was changed */
+    changedFile: string;
+    /** Spec file that failed */
+    specFile: string;
+    /** Number of times this correlation has been observed */
+    count: number;
+    /** ISO timestamp of last observation */
+    lastSeen: string;
+}
+export interface FailureHistory {
+    correlations: FailureCorrelation[];
+    /** Total runs recorded */
+    totalRuns: number;
+    /** ISO timestamp of last update */
+    updatedAt: string;
+}
+export declare function loadFailureHistory(testsRoot: string): FailureHistory;
+export declare function saveFailureHistory(testsRoot: string, history: FailureHistory): void;
+/**
+ * Record that a set of changed files caused a set of spec failures.
+ * Call this after a test run where failures were observed.
+ */
+export declare function recordFailures(history: FailureHistory, changedFiles: string[], failedSpecs: string[]): FailureHistory;
+/**
+ * Get a confidence boost (0-20) for a file based on historical failure patterns.
+ * A file that historically causes test failures gets a higher confidence boost
+ * when detected as impacted, meaning the system is more confident it needs testing.
+ */
+export declare function getConfidenceBoost(history: FailureHistory, changedFile: string): number;
+/**
+ * Get the most likely failing specs for a set of changed files, based on history.
+ * Returns specs sorted by correlation strength (count * recency).
+ */
+export declare function getPredictedFailures(history: FailureHistory, changedFiles: string[], limit?: number): Array<{
+    specFile: string;
+    score: number;
+}>;
+//# sourceMappingURL=failure_history.d.ts.map

package/dist/knowledge/failure_history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure_history.d.ts","sourceRoot":"","sources":["../../src/knowledge/failure_history.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,kBAAkB;IAC/B,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC3B,YAAY,EAAE,kBAAkB,EAAE,CAAC;IACnC,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;CACrB;AAQD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAcpE;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAYnF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC1B,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,MAAM,EAAE,EACtB,WAAW,EAAE,MAAM,EAAE,GACtB,cAAc,CA8BhB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAevF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAChC,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,MAAM,EAAE,EACtB,KAAK,SAAK,GACX,KAAK,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAAC,CAoB1C"}

package/dist/knowledge/failure_history.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.loadFailureHistory = loadFailureHistory;
+exports.saveFailureHistory = saveFailureHistory;
+exports.recordFailures = recordFailures;
+exports.getConfidenceBoost = getConfidenceBoost;
+exports.getPredictedFailures = getPredictedFailures;
+/**
+ * Tracks historical test failure correlations: which tests fail when certain files change.
+ * Used to boost confidence in impact analysis — if a file change historically breaks a test,
+ * future changes to that file should prioritize that test.
+ *
+ * Data is stored as a JSON file at .e2e-ai-agents/failure-history.json.
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const DEFAULT_HISTORY = {
+    correlations: [],
+    totalRuns: 0,
+    updatedAt: new Date().toISOString(),
+};
+function loadFailureHistory(testsRoot) {
+    const historyPath = (0, path_1.join)(testsRoot, '.e2e-ai-agents', 'failure-history.json');
+    if (!(0, fs_1.existsSync)(historyPath)) {
+        return { ...DEFAULT_HISTORY };
+    }
+    try {
+        const raw = JSON.parse((0, fs_1.readFileSync)(historyPath, 'utf-8'));
+        if (!Array.isArray(raw.correlations)) {
+            return { ...DEFAULT_HISTORY };
+        }
+        return raw;
+    }
+    catch {
+        return { ...DEFAULT_HISTORY };
+    }
+}
+function saveFailureHistory(testsRoot, history) {
+    const historyPath = (0, path_1.join)(testsRoot, '.e2e-ai-agents', 'failure-history.json');
+    try {
+        const dir = (0, path_1.dirname)(historyPath);
+        if (!(0, fs_1.existsSync)(dir)) {
+            (0, fs_1.mkdirSync)(dir, { recursive: true });
+        }
+        history.updatedAt = new Date().toISOString();
+        (0, fs_1.writeFileSync)(historyPath, JSON.stringify(history, null, 2), 'utf-8');
+    }
+    catch {
+        // Non-fatal — history is advisory, not required
+    }
+}
+/**
+ * Record that a set of changed files caused a set of spec failures.
+ * Call this after a test run where failures were observed.
+ */
+function recordFailures(history, changedFiles, failedSpecs) {
+    const now = new Date().toISOString();
+    const updated = { ...history, totalRuns: history.totalRuns + 1, correlations: [...history.correlations] };
+    for (const changedFile of changedFiles) {
+        for (const specFile of failedSpecs) {
+            const existing = updated.correlations.find((c) => c.changedFile === changedFile && c.specFile === specFile);
+            if (existing) {
+                existing.count++;
+                existing.lastSeen = now;
+            }
+            else {
+                updated.correlations.push({
+                    changedFile,
+                    specFile,
+                    count: 1,
+                    lastSeen: now,
+                });
+            }
+        }
+    }
+    // Prune stale correlations (not seen in 90 days)
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - 90);
+    const cutoffStr = cutoff.toISOString();
+    updated.correlations = updated.correlations.filter((c) => c.lastSeen >= cutoffStr);
+    return updated;
+}
+/**
+ * Get a confidence boost (0-20) for a file based on historical failure patterns.
+ * A file that historically causes test failures gets a higher confidence boost
+ * when detected as impacted, meaning the system is more confident it needs testing.
+ */
+function getConfidenceBoost(history, changedFile) {
+    const correlations = history.correlations.filter((c) => c.changedFile === changedFile);
+    if (correlations.length === 0) {
+        return 0;
+    }
+    // More correlations and higher counts = more confidence
+    const totalCount = correlations.reduce((sum, c) => sum + c.count, 0);
+    const uniqueSpecs = correlations.length;
+    // Scale: 1 correlation = +5, 3+ = +10, 5+ with high counts = +15, max +20
+    if (totalCount >= 10 && uniqueSpecs >= 5)
+        return 20;
+    if (totalCount >= 5 && uniqueSpecs >= 3)
+        return 15;
+    if (totalCount >= 3)
+        return 10;
+    return 5;
+}
+/**
+ * Get the most likely failing specs for a set of changed files, based on history.
+ * Returns specs sorted by correlation strength (count * recency).
+ */
+function getPredictedFailures(history, changedFiles, limit = 10) {
+    const specScores = new Map();
+    for (const changedFile of changedFiles) {
+        for (const c of history.correlations) {
+            if (c.changedFile !== changedFile)
+                continue;
+            // Score: count weighted by recency (days since last seen)
+            const daysSince = (Date.now() - new Date(c.lastSeen).getTime()) / (1000 * 60 * 60 * 24);
+            const recencyWeight = Math.max(0.1, 1 - daysSince / 90);
+            const score = c.count * recencyWeight;
+            specScores.set(c.specFile, (specScores.get(c.specFile) || 0) + score);
+        }
+    }
+    return Array.from(specScores.entries())
+        .map(([specFile, score]) => ({ specFile, score }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+}

package/dist/knowledge/kg_bridge.d.ts

@@ -0,0 +1,31 @@
+import type { KnowledgeGraph, DiffOverlay } from './kg_types.js';
+import type { RouteFamilyManifest } from './route_families.js';
+export type ProjectType = 'frontend' | 'backend' | 'fullstack';
+/**
+ * Loads the knowledge graph from .understand-anything/knowledge-graph.json
+ * or from a custom path when provided.
+ */
+export declare function loadKnowledgeGraph(projectRoot: string, customPath?: string): KnowledgeGraph | null;
+/**
+ * Classifies project type based on KG framework metadata.
+ */
+export declare function classifyProjectType(kg: KnowledgeGraph): ProjectType;
+/**
+ * Core bridge: transforms KG into a RouteFamilyManifest.
+ *
+ * Strategy:
+ * - Frontend: cluster UI-layer nodes into families by module/component groups
+ * - Backend: cluster API-layer nodes, follow calls edges into Service→Data layers
+ * - Priority: P0 = high fan-in nodes, P1 = moderate, P2 = leaf/utility
+ * - userFlows: derived from KG tour steps referencing family nodes
+ */
+export declare function transformKGToFamilies(kg: KnowledgeGraph): RouteFamilyManifest;
+/**
+ * Loads the diff overlay from .understand-anything/diff-overlay.json
+ */
+export declare function loadDiffOverlay(projectRoot: string): DiffOverlay | null;
+/**
+ * Maps diff overlay changes to file paths using KG node resolution.
+ */
+export declare function diffOverlayToChangedFiles(overlay: DiffOverlay, kg: KnowledgeGraph): string[];
+//# sourceMappingURL=kg_bridge.d.ts.map

package/dist/knowledge/kg_bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kg_bridge.d.ts","sourceRoot":"","sources":["../../src/knowledge/kg_bridge.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAC,cAAc,EAAkB,WAAW,EAAc,MAAM,eAAe,CAAC;AAE5F,OAAO,KAAK,EAAc,mBAAmB,EAAkB,MAAM,qBAAqB,CAAC;AAE3F,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;AAkB/D;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CA6DlG;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,cAAc,GAAG,WAAW,CAQnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,cAAc,GAAG,mBAAmB,CAwC7E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAevE;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,cAAc,GAAG,MAAM,EAAE,CAkB5F"}