@yasserkhanorg/e2e-agents 1.8.5 → 1.10.0

package/dist/resilience/circuit_breaker.js

@@ -0,0 +1,82 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreaker = void 0;
+const DEFAULT_CONFIG = {
+    failureThreshold: 3,
+    cooldownMs: 60000,
+};
+class CircuitBreaker {
+    constructor(config = {}) {
+        this.state = 'closed';
+        this.failures = 0;
+        this.lastFailureTime = 0;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /** Returns the derived state without mutating internal state. */
+    get currentState() {
+        if (this.state === 'open' && Date.now() - this.lastFailureTime >= this.config.cooldownMs) {
+            return 'half-open';
+        }
+        return this.state;
+    }
+    get isOpen() {
+        return this.currentState === 'open';
+    }
+    /**
+     * Execute a function with circuit breaker protection.
+     * If the circuit is open, the fallback is called instead.
+     */
+    async call(fn, fallback) {
+        // Transition from open to half-open if cooldown has elapsed
+        if (this.state === 'open') {
+            if (Date.now() - this.lastFailureTime >= this.config.cooldownMs) {
+                this.state = 'half-open';
+            }
+            else {
+                return fallback();
+            }
+        }
+        // At this point state is 'closed' or 'half-open'
+        const stateBeforeCall = this.state;
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            const shouldCount = !this.config.shouldCount || this.config.shouldCount(error);
+            if (shouldCount) {
+                this.onFailure();
+            }
+            // In half-open state, a failure re-opens the circuit
+            if (stateBeforeCall === 'half-open') {
+                throw error;
+            }
+            // In closed state, if failures hit threshold the circuit opened
+            if (shouldCount && this.failures >= this.config.failureThreshold) {
+                return fallback();
+            }
+            throw error;
+        }
+    }
+    onSuccess() {
+        this.failures = 0;
+        this.state = 'closed';
+    }
+    onFailure() {
+        this.failures++;
+        this.lastFailureTime = Date.now();
+        if (this.failures >= this.config.failureThreshold) {
+            this.state = 'open';
+        }
+    }
+    /** Reset the circuit breaker to closed state */
+    reset() {
+        this.state = 'closed';
+        this.failures = 0;
+        this.lastFailureTime = 0;
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;

package/dist/resilience/retry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Retry with exponential backoff and jitter for LLM provider calls.
+ */
+export interface RetryConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitter: boolean;
+}
+export declare function withRetry<T>(fn: () => Promise<T>, config?: Partial<RetryConfig>): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/resilience/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/resilience/retry.ts"],"names":[],"mappings":"AAGA;;GAEG;AAEH,MAAM,WAAW,WAAW;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;CACnB;AAsCD,wBAAsB,SAAS,CAAC,CAAC,EAC7B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,GAClC,OAAO,CAAC,CAAC,CAAC,CAkBZ"}

package/dist/resilience/retry.js

@@ -0,0 +1,59 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = withRetry;
+const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 2,
+    baseDelayMs: 1000,
+    maxDelayMs: 10000,
+    jitter: true,
+};
+/** Errors that should be retried (transient failures) */
+function isRetryable(error) {
+    if (!(error instanceof Error))
+        return false;
+    const msg = error.message.toLowerCase();
+    // Rate limits
+    if (msg.includes('rate limit') || msg.includes('429') || msg.includes('too many requests'))
+        return true;
+    // Server errors
+    if (msg.includes('500') || msg.includes('502') || msg.includes('503') || msg.includes('504'))
+        return true;
+    if (msg.includes('internal server error') || msg.includes('bad gateway') || msg.includes('service unavailable'))
+        return true;
+    // Network errors
+    if (msg.includes('econnreset') || msg.includes('econnrefused') || msg.includes('etimedout'))
+        return true;
+    if (msg.includes('socket hang up') || msg.includes('network error'))
+        return true;
+    // Overloaded
+    if (msg.includes('overloaded') || msg.includes('capacity'))
+        return true;
+    return false;
+}
+function computeDelay(attempt, config) {
+    const exponential = Math.min(config.baseDelayMs * Math.pow(2, attempt), config.maxDelayMs);
+    if (!config.jitter)
+        return exponential;
+    // Full jitter: random between 0 and exponential
+    return Math.floor(Math.random() * exponential);
+}
+async function withRetry(fn, config = {}) {
+    const cfg = { ...DEFAULT_RETRY_CONFIG, ...config };
+    let lastError;
+    for (let attempt = 0; attempt <= cfg.maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= cfg.maxRetries || !isRetryable(error)) {
+                throw error;
+            }
+            const delay = computeDelay(attempt, cfg);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError;
+}

package/dist/sanitize.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Sanitize a string by replacing detected secrets with [REDACTED].
+ */
+export declare function sanitizeSecrets(text: string): string;
+/**
+ * Check if a string contains any detectable secrets.
+ */
+export declare function containsSecrets(text: string): boolean;
+/**
+ * Deep-sanitize a JSON-serializable object.
+ * Recursively walks all string values and sanitizes them.
+ * Tracks seen objects to prevent stack overflow on circular references.
+ */
+export declare function sanitizeObject<T>(obj: T, _seen?: WeakSet<object>): T;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AA2BA;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMpD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKrD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAepE"}

package/dist/sanitize.js

@@ -0,0 +1,71 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeSecrets = sanitizeSecrets;
+exports.containsSecrets = containsSecrets;
+exports.sanitizeObject = sanitizeObject;
+/**
+ * Secret scanning and sanitization utilities.
+ * Prevents API keys and credentials from leaking into artifacts, logs, and output.
+ *
+ * Patterns are stored WITHOUT the global flag to avoid shared mutable lastIndex state.
+ * New RegExp instances with /g are created per call for safe concurrent usage.
+ */
+const SECRET_PATTERNS = [
+    // Anthropic API keys (must be checked before generic sk- pattern)
+    /sk-ant-[a-zA-Z0-9_-]{20,}/,
+    // OpenAI API keys (negative lookahead to avoid matching Anthropic keys)
+    /sk-(?!ant-)[a-zA-Z0-9]{20,}/,
+    // Generic API key patterns
+    /(?:api[_-]?key|api[_-]?secret|access[_-]?token|auth[_-]?token)['":\s=]+['"]?([a-zA-Z0-9_\-./]{20,})['"]?/i,
+    // Bearer tokens
+    /Bearer\s+[a-zA-Z0-9_\-./]{20,}/,
+    // AWS keys
+    /AKIA[0-9A-Z]{16}/,
+    // GitHub tokens
+    /gh[ps]_[a-zA-Z0-9]{36,}/,
+    /github_pat_[a-zA-Z0-9_]{22,}/,
+];
+/**
+ * Sanitize a string by replacing detected secrets with [REDACTED].
+ */
+function sanitizeSecrets(text) {
+    let result = text;
+    for (const pattern of SECRET_PATTERNS) {
+        result = result.replace(new RegExp(pattern, 'gi'), '[REDACTED]');
+    }
+    return result;
+}
+/**
+ * Check if a string contains any detectable secrets.
+ */
+function containsSecrets(text) {
+    for (const pattern of SECRET_PATTERNS) {
+        if (new RegExp(pattern, 'i').test(text))
+            return true;
+    }
+    return false;
+}
+/**
+ * Deep-sanitize a JSON-serializable object.
+ * Recursively walks all string values and sanitizes them.
+ * Tracks seen objects to prevent stack overflow on circular references.
+ */
+function sanitizeObject(obj, _seen) {
+    if (typeof obj === 'string')
+        return sanitizeSecrets(obj);
+    if (obj === null || typeof obj !== 'object')
+        return obj;
+    const seen = _seen ?? new WeakSet();
+    if (seen.has(obj))
+        return '[Circular]';
+    seen.add(obj);
+    if (Array.isArray(obj))
+        return obj.map((item) => sanitizeObject(item, seen));
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        result[key] = sanitizeObject(value, seen);
+    }
+    return result;
+}

package/dist/training/kg_scanner.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Converts an Understand-Anything knowledge graph into the same ScanResult
+ * format produced by the filesystem scanner. This allows the existing
+ * merge/enrich/validate pipeline to work unchanged with KG input.
+ */
+import type { KnowledgeGraph } from '../knowledge/kg_types.js';
+import type { ScanResult } from './types.js';
+/**
+ * Converts KG nodes/edges into a ScanResult compatible with the filesystem scanner output.
+ * Groups nodes by their containing module/directory to form families.
+ */
+export declare function scanFromKnowledgeGraph(kg: KnowledgeGraph): ScanResult;
+//# sourceMappingURL=kg_scanner.d.ts.map

package/dist/training/kg_scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kg_scanner.d.ts","sourceRoot":"","sources":["../../src/training/kg_scanner.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,OAAO,KAAK,EAAC,cAAc,EAAS,MAAM,0BAA0B,CAAC;AAErE,OAAO,KAAK,EAAC,UAAU,EAAgC,MAAM,YAAY,CAAC;AAE1E;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,cAAc,GAAG,UAAU,CA4FrE"}

package/dist/training/kg_scanner.js

@@ -0,0 +1,118 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanFromKnowledgeGraph = scanFromKnowledgeGraph;
+const cluster_utils_js_1 = require("../knowledge/cluster_utils.js");
+/**
+ * Converts KG nodes/edges into a ScanResult compatible with the filesystem scanner output.
+ * Groups nodes by their containing module/directory to form families.
+ */
+function scanFromKnowledgeGraph(kg) {
+    const clusters = new Map();
+    // Group nodes into clusters by directory/module
+    for (const node of kg.nodes) {
+        if (node.layer === 'infra')
+            continue; // skip infrastructure nodes
+        const clusterId = (0, cluster_utils_js_1.deriveClusterId)(node, cluster_utils_js_1.SKIP_DIRS_WITH_TESTS);
+        if (!clusterId)
+            continue;
+        if (!clusters.has(clusterId)) {
+            clusters.set(clusterId, []);
+        }
+        clusters.get(clusterId).push(node);
+    }
+    let totalSourceFiles = 0;
+    let totalTestFiles = 0;
+    const families = [];
+    for (const [id, nodes] of clusters) {
+        const webappPaths = [];
+        const serverPaths = [];
+        const specDirs = [];
+        const tags = [];
+        const seenDirs = new Set();
+        for (const node of nodes) {
+            if (!node.filePath)
+                continue;
+            const normalized = node.filePath.replace(/\\/g, '/');
+            if (node.layer === 'test') {
+                totalTestFiles++;
+                const dir = normalized.split('/').slice(0, -1).join('/');
+                if (dir && !seenDirs.has(dir)) {
+                    seenDirs.add(dir);
+                    specDirs.push(dir + '/');
+                }
+                continue;
+            }
+            totalSourceFiles++;
+            const glob = buildGlobFromPath(normalized);
+            if (node.layer === 'api' || node.layer === 'service' || node.layer === 'data') {
+                serverPaths.push(glob);
+            }
+            else if (node.layer === 'ui') {
+                webappPaths.push(glob);
+            }
+            else {
+                // Default assignment based on file path heuristics
+                if (isLikelyServerPath(normalized)) {
+                    serverPaths.push(glob);
+                }
+                else {
+                    webappPaths.push(glob);
+                }
+            }
+            // Extract tags from node metadata
+            if (node.tags) {
+                tags.push(...node.tags);
+            }
+        }
+        if (webappPaths.length === 0 && serverPaths.length === 0 && specDirs.length === 0) {
+            continue;
+        }
+        families.push({
+            id,
+            routes: [`/${id}`],
+            webappPaths: [...new Set(webappPaths)],
+            serverPaths: [...new Set(serverPaths)],
+            specDirs: [...new Set(specDirs)],
+            cypressSpecDirs: [],
+            tags: [...new Set(tags)],
+            features: [],
+            routesGuessed: true,
+        });
+    }
+    return {
+        families,
+        unmatchedSourceDirs: [],
+        unmatchedTestDirs: [],
+        stats: {
+            totalSourceFiles,
+            totalTestFiles,
+            familyCount: families.length,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+// deriveClusterId and deriveClusterIdFromPath imported from cluster_utils.ts
+function buildGlobFromPath(filePath) {
+    // Reject paths with traversal or null bytes
+    if (filePath.includes('..') || filePath.includes('\0')) {
+        return '';
+    }
+    // Convert a file path to a glob pattern matching the directory
+    const dir = filePath.split('/').slice(0, -1).join('/');
+    return dir ? `${dir}/*` : `${filePath}*`;
+}
+function isLikelyServerPath(filePath) {
+    const lower = filePath.toLowerCase();
+    return lower.includes('/server/') ||
+        lower.includes('/api/') ||
+        lower.includes('/routes/') ||
+        lower.includes('/controllers/') ||
+        lower.includes('/services/') ||
+        lower.includes('/models/') ||
+        lower.endsWith('.go') ||
+        lower.endsWith('.py');
+}

package/dist/training/scanner.d.ts

@@ -1,4 +1,9 @@
 import type { DiscoveredDir, ScannedFamily, ScanResult } from './types.js';
+/** Configurable scanner options. All fields optional — defaults to Mattermost conventions. */
+export interface ScannerConfig {
+    serverInfraFiles?: Set<string>;
+    serverTiers?: readonly string[];
+}
 export declare function discoverSourceDirs(projectRoot: string): DiscoveredDir[];
 export declare function discoverTestDirs(projectRoot: string): DiscoveredDir[];
 /**
@@ -12,7 +17,7 @@ export declare function discoverTestDirs(projectRoot: string): DiscoveredDir[];
  *
  * Each domain becomes a candidate family with precise serverPaths.
  */
-export declare function discoverServerDerivedFamilies(serverRoot: string): {
+export declare function discoverServerDerivedFamilies(serverRoot: string, infraFiles?: Set<string>, tiers?: readonly string[]): {
     multiTierFamilies: ScannedFamily[];
     singleTierFamilies: ScannedFamily[];
 };
@@ -27,5 +32,5 @@ export declare function discoverTestLibPaths(testsRoot: string): Map<string, str
  * maps directly to a family ID.
  */
 export declare function discoverNameMatchedPaths(appPath: string, gitRepoRoot?: string): Map<string, string[]>;
-export declare function scanProject(projectRoot: string, testsRoot?: string, serverRoot?: string, gitRepoRoot?: string): ScanResult;
+export declare function scanProject(projectRoot: string, testsRoot?: string, serverRoot?: string, gitRepoRoot?: string, config?: ScannerConfig): ScanResult;
 //# sourceMappingURL=scanner.d.ts.map

package/dist/training/scanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../src/training/scanner.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAC,aAAa,EAAE,aAAa,EAAkB,UAAU,EAAC,MAAM,YAAY,CAAC;AAgJzF,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,EAAE,CA+BvE;AAED,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,EAAE,CA6DrE;AAuLD;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,MAAM,GAAG;IAAC,iBAAiB,EAAE,aAAa,EAAE,CAAC;IAAC,kBAAkB,EAAE,aAAa,EAAE,CAAA;CAAC,CAgI3I;AAED,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,EAAE,CAiG9E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CA8C7E;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACpC,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,GACrB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAyDvB;AAED,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU,CA0L1H"}
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../src/training/scanner.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAC,aAAa,EAAE,aAAa,EAAkB,UAAU,EAAC,MAAM,YAAY,CAAC;AAoEzF,8FAA8F;AAC9F,MAAM,WAAW,aAAa;IAC1B,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/B,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAqED,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,EAAE,CA+BvE;AAED,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,EAAE,CA6DrE;AAuLD;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CACzC,UAAU,EAAE,MAAM,EAClB,UAAU,GAAE,GAAG,CAAC,MAAM,CAA8B,EACpD,KAAK,GAAE,SAAS,MAAM,EAAyB,GAChD;IAAC,iBAAiB,EAAE,aAAa,EAAE,CAAC;IAAC,kBAAkB,EAAE,aAAa,EAAE,CAAA;CAAC,CAgI3E;AAED,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,EAAE,CAiG9E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CA8C7E;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACpC,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,GACrB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAyDvB;AAED,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,UAAU,CA8LlJ"}

package/dist/training/scanner.js

@@ -11,6 +11,7 @@ exports.discoverNameMatchedPaths = discoverNameMatchedPaths;
 exports.scanProject = scanProject;
 const fs_1 = require("fs");
 const path_1 = require("path");
+const cluster_utils_js_1 = require("../knowledge/cluster_utils.js");
 const SOURCE_MAX_DEPTH = 3;
 // One deeper than source to account for test framework wrapper dirs (e2e/, integration/)
 const TEST_MAX_DEPTH = 5;
@@ -44,10 +45,11 @@ const STRUCTURAL_DIRS = new Set([
     'middleware', 'contexts', 'providers', 'layouts', 'templates',
 ]);
 /**
- * Server Go files that are infrastructure / cross-cutting concerns,
+ * Default server Go files that are infrastructure / cross-cutting concerns,
  * not feature-specific domains.  Matched after stripping _local/_store suffixes.
+ * Override via ScannerConfig.serverInfraFiles.
  */
-const SERVER_INFRA_FILES = new Set([
+const DEFAULT_SERVER_INFRA_FILES = new Set([
     'api', 'apitestlib', 'context', 'helpers', 'params', 'swagger',
     'app', 'server', 'enterprise', 'product_service', 'security_update_check',
     'store', 'adapters', 'errors', 'integrity', 'migrate', 'doc',
@@ -57,10 +59,11 @@ const SERVER_INFRA_FILES = new Set([
     'manifest', 'permission', 'log', 'utils',
 ]);
 /**
- * Server tier directories to scan for Go domain files.
+ * Default server tier directories to scan for Go domain files.
  * Each tier represents a layer of the backend architecture.
+ * Override via ScannerConfig.serverTiers.
  */
-const SERVER_TIERS = [
+const DEFAULT_SERVER_TIERS = [
     'channels/api4',
     'channels/app',
     'channels/store/sqlstore',
@@ -73,13 +76,7 @@ const includes = (arr, v) => arr.includes(v);
 function isSkipped(name) {
     return name.startsWith('.') || SKIP_DIRS.has(name);
 }
-function normalizeId(name) {
-    return name
-        .replace(/[A-Z]/g, (c, idx) => (idx > 0 ? `_${c.toLowerCase()}` : c.toLowerCase()))
-        .replace(/[^a-z0-9_]/g, '_')
-        .replace(/_+/g, '_')
-        .replace(/^_|_$/g, '');
-}
+const normalizeId = cluster_utils_js_1.normalizeToClusterId;
 function extractFamilyHint(dirPath, projectRoot) {
     const rel = (0, path_1.relative)(projectRoot, dirPath).replace(/\\/g, '/');
     const parts = rel.split('/').filter(Boolean);
@@ -97,32 +94,25 @@ function walkDirs(root, projectRoot, category, maxDepth, results, depth = 0) {
     if (depth > maxDepth || !(0, fs_1.existsSync)(root)) {
         return;
     }
-    let entries;
+    let dirents;
     try {
-        entries = (0, fs_1.readdirSync)(root);
+        dirents = (0, fs_1.readdirSync)(root, { withFileTypes: true });
     }
     catch {
         // ENOENT or EACCES — skip inaccessible entries
         return;
     }
-    const hasSourceFiles = entries.some((e) => {
-        const ext = e.slice(e.lastIndexOf('.'));
+    const hasSourceFiles = dirents.some((d) => {
+        if (!d.isFile())
+            return false;
+        const ext = d.name.slice(d.name.lastIndexOf('.'));
         return ['.ts', '.tsx', '.js', '.jsx', '.go', '.py', '.rs'].includes(ext);
     });
-    const subdirs = entries.filter((e) => {
-        if (isSkipped(e))
+    const subdirs = dirents.filter((d) => {
+        if (!d.isDirectory() || d.isSymbolicLink())
             return false;
-        try {
-            const stat = (0, fs_1.lstatSync)((0, path_1.join)(root, e));
-            if (stat.isSymbolicLink())
-                return false;
-            return stat.isDirectory();
-        }
-        catch {
-            // ENOENT or EACCES — skip inaccessible entries
-            return false;
-        }
-    });
+        return !isSkipped(d.name);
+    }).map((d) => d.name);
     if (hasSourceFiles && depth >= 1) {
         results.push({
             path: (0, path_1.resolve)(root),
@@ -419,7 +409,7 @@ function findParentDomain(name, allDomains) {
  *
  * Each domain becomes a candidate family with precise serverPaths.
  */
-function discoverServerDerivedFamilies(serverRoot) {
+function discoverServerDerivedFamilies(serverRoot, infraFiles = DEFAULT_SERVER_INFRA_FILES, tiers = DEFAULT_SERVER_TIERS) {
     const resolved = (0, path_1.resolve)(serverRoot);
     // First pass: collect all raw domain names across tiers
     const allRawDomains = new Set();
@@ -430,7 +420,7 @@ function discoverServerDerivedFamilies(serverRoot) {
             return;
         const baseName = entry.replace('.go', '');
         const domain = normalizeServerDomain(baseName);
-        if (!domain || SERVER_INFRA_FILES.has(domain))
+        if (!domain || infraFiles.has(domain))
             return;
         allRawDomains.add(domain);
         if (!domainTierFiles.has(domain))
@@ -440,7 +430,7 @@ function discoverServerDerivedFamilies(serverRoot) {
             tierMap.set(tierRelPath, new Set());
         tierMap.get(tierRelPath).add(baseName);
     }
-    for (const tier of SERVER_TIERS) {
+    for (const tier of tiers) {
         const tierPath = (0, path_1.join)(resolved, tier);
         if (!(0, fs_1.existsSync)(tierPath))
             continue;
@@ -477,7 +467,7 @@ function discoverServerDerivedFamilies(serverRoot) {
                     if (!(0, fs_1.lstatSync)(jobPath).isDirectory() || isSkipped(entry))
                         continue;
                     const domain = normalizeId(entry);
-                    if (SERVER_INFRA_FILES.has(domain))
+                    if (infraFiles.has(domain))
                         continue;
                     allRawDomains.add(domain);
                     const jobFiles = (0, fs_1.readdirSync)(jobPath);
@@ -764,7 +754,10 @@ function discoverNameMatchedPaths(appPath, gitRepoRoot) {
     }
     return result;
 }
-function scanProject(projectRoot, testsRoot, serverRoot, gitRepoRoot) {
+function scanProject(projectRoot, testsRoot, serverRoot, gitRepoRoot, config) {
+    // Resolve scanner config for this run (passed to functions, no module-level mutation)
+    const resolvedInfraFiles = config?.serverInfraFiles || DEFAULT_SERVER_INFRA_FILES;
+    const resolvedTiers = config?.serverTiers || DEFAULT_SERVER_TIERS;
     const resolved = (0, path_1.resolve)(projectRoot);
     const resolvedTestsRoot = testsRoot ? (0, path_1.resolve)(testsRoot) : resolved;
     const sourceDirs = discoverSourceDirs(resolved);
@@ -827,7 +820,7 @@ function scanProject(projectRoot, testsRoot, serverRoot, gitRepoRoot) {
     // When a separate serverRoot is provided, discover families from Go source
     // filenames across the three-tier backend (api4, app, store).
     if (serverRoot) {
-        const { multiTierFamilies: serverMulti, singleTierFamilies: serverSingle } = discoverServerDerivedFamilies((0, path_1.resolve)(serverRoot));
+        const { multiTierFamilies: serverMulti, singleTierFamilies: serverSingle } = discoverServerDerivedFamilies((0, path_1.resolve)(serverRoot), resolvedInfraFiles, resolvedTiers);
         const existingIds = new Set(families.map((f) => f.id));
         // Merge ALL server families (multi + single tier) into existing families,
         // but only add NEW families if they span ≥2 tiers.

package/dist/validation/guardrails.d.ts

@@ -5,6 +5,8 @@ export interface EvidenceCheck {
     hasPageObject: boolean;
     hasUserAction: boolean;
     hasExistingSpecCited: boolean;
+    /** Historical failure correlation boost (0-20) from failure_history */
+    historyBoost?: number;
 }
 export type ConfidenceClass = 'high' | 'medium' | 'low';
 export declare const EVIDENCE_THRESHOLDS: {

package/dist/validation/guardrails.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guardrails.d.ts","sourceRoot":"","sources":["../../src/validation/guardrails.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,gCAAgC,CAAC;AAExE,MAAM,WAAW,aAAa;IAC1B,cAAc,EAAE,OAAO,CAAC;IACxB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,oBAAoB,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAExD,eAAO,MAAM,mBAAmB;;;;;CAKtB,CAAC;AAEX,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAkB9D;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,CAQtE;AAED,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED,wBAAgB,4BAA4B,CACxC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,mBAAmB,GAC9B,OAAO,CAwBT;AAeD,wBAAgB,2BAA2B,CACvC,SAAS,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAAC,GACnC,MAAM,CAMR;AAED,wBAAgB,wBAAwB,CACpC,SAAS,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAAC,GACvD,eAAe,CAUjB;AAGD,YAAY,EAAC,kBAAkB,EAAE,cAAc,EAAC,MAAM,8BAA8B,CAAC;AACrF,OAAO,EAAC,gBAAgB,EAAE,YAAY,EAAC,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"guardrails.d.ts","sourceRoot":"","sources":["../../src/validation/guardrails.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,gCAAgC,CAAC;AAExE,MAAM,WAAW,aAAa;IAC1B,cAAc,EAAE,OAAO,CAAC;IACxB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAExD,eAAO,MAAM,mBAAmB;;;;;CAKtB,CAAC;AAEX,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAuB9D;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,CAQtE;AAED,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED,wBAAgB,4BAA4B,CACxC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,mBAAmB,GAC9B,OAAO,CAwBT;AAeD,wBAAgB,2BAA2B,CACvC,SAAS,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAAC,GACnC,MAAM,CAMR;AAED,wBAAgB,wBAAwB,CACpC,SAAS,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAAC,GACvD,eAAe,CAUjB;AAGD,YAAY,EAAC,kBAAkB,EAAE,cAAc,EAAC,MAAM,8BAA8B,CAAC;AACrF,OAAO,EAAC,gBAAgB,EAAE,YAAY,EAAC,MAAM,8BAA8B,CAAC"}

package/dist/validation/guardrails.js

@@ -32,6 +32,11 @@ function computeConfidence(check) {
     if (check.hasExistingSpecCited) {
         score += 15;
     }
+    // Historical failure correlation: if this file historically causes test failures,
+    // we're more confident it needs testing now
+    if (check.historyBoost) {
+        score += check.historyBoost;
+    }
     return Math.min(100, score);
 }
 function classifyConfidence(confidence) {

package/dist/validation/output_schema.d.ts

@@ -9,6 +9,8 @@ export interface ExistingSpecCoverage {
     coverageLevel: CoverageLevel;
     missingScenarios?: string[];
 }
+export type { AssertionPattern } from '../knowledge/route_families.js';
+import type { AssertionPattern } from '../knowledge/route_families.js';
 export interface FlowDecision {
     flowId: string;
     flowName: string;
@@ -27,6 +29,7 @@ export interface FlowDecision {
     blockingReason?: string;
     priority: FlowPriority;
     userActions: string[];
+    assertionPatterns?: AssertionPattern[];
 }
 export interface FlowDecisionSummary {
     changedFiles: number;

package/dist/validation/output_schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output_schema.d.ts","sourceRoot":"","sources":["../../src/validation/output_schema.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,eAAe,GAAG,aAAa,GAAG,kBAAkB,CAAC;AAC/F,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,cAAc,GAAG,eAAe,CAAC;AACjF,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAC9C,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AACxD,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAExD,MAAM,WAAW,oBAAoB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,aAAa,EAAE,aAAa,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,cAAc,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,oBAAoB,EAAE,CAAC;IACtC,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,YAAY,CAAC;IACvB,WAAW,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE;QACb,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,iBAAiB,EAAE,eAAe,CAAC;CACtC;AAED,MAAM,WAAW,kBAAkB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,mBAAmB,CAAC;IAC7B,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE;QACH,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;CACL;AAMD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,GAAG;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAC,CA0C1F;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,mBAAmB,CAmC3E"}
+{"version":3,"file":"output_schema.d.ts","sourceRoot":"","sources":["../../src/validation/output_schema.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,eAAe,GAAG,aAAa,GAAG,kBAAkB,CAAC;AAC/F,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,cAAc,GAAG,eAAe,CAAC;AACjF,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAC9C,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AACxD,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAExD,MAAM,WAAW,oBAAoB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,aAAa,EAAE,aAAa,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,YAAY,EAAC,gBAAgB,EAAC,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,gCAAgC,CAAC;AAErE,MAAM,WAAW,YAAY;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,cAAc,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,oBAAoB,EAAE,CAAC;IACtC,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,YAAY,CAAC;IACvB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,mBAAmB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE;QACb,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,iBAAiB,EAAE,eAAe,CAAC;CACtC;AAED,MAAM,WAAW,kBAAkB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,mBAAmB,CAAC;IAC7B,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE;QACH,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;CACL;AAMD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,GAAG;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAC,CA0C1F;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,mBAAmB,CAmC3E"}

package/dist/version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns the package version by reading the nearest package.json.
+ * Cached after first call.
+ */
+export declare function getVersion(): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAoBnC"}