@yasserkhanorg/e2e-agents 1.8.5 → 1.9.5

package/dist/esm/custom_provider.js

@@ -65,6 +65,7 @@ export class CustomProvider extends BaseProvider {
         };
     }
     async generateText(prompt, options) {
+        this.checkBudget();
         const startTime = Date.now();
         try {
             if (prompt.length > 10 * 1024 * 1024) {

package/dist/esm/engine/diff_loader.js

@@ -1,20 +1,9 @@
 // Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
 // See LICENSE.txt for license information.
-import { spawnSync } from 'child_process';
+import { runGitRaw } from '../agent/git.js';
 const MAX_DIFF_CHARS = 8000;
 const MAX_TOTAL_CHARS = 60000;
 const TRUNCATION_NOTICE = '\n... (diff truncated)';
-function runGitRaw(args, cwd) {
-    const result = spawnSync('git', args, {
-        cwd,
-        encoding: 'utf-8',
-        timeout: 30000,
-    });
-    if (result.error || result.status !== 0) {
-        return null;
-    }
-    return result.stdout;
-}
 /**
  * Loads git diffs for the given changed files relative to the given since ref.
  * Uses `git merge-base` to find the accurate base ref first.

package/dist/esm/engine/impact_engine.js

@@ -2,7 +2,8 @@
 // See LICENSE.txt for license information.
 import { existsSync, readdirSync, readFileSync } from 'fs';
 import { join } from 'path';
-import { loadRouteFamilyManifest, bindFilesToFamilies, getSpecDirsForBinding, getCypressSpecDirsForBinding, getPriorityForBinding, getUserFlowsForBinding, } from '../knowledge/route_families.js';
+import { loadRouteFamilyManifest, buildHeuristicFamilies, bindFilesToFamilies, getSpecDirsForBinding, getCypressSpecDirsForBinding, getPriorityForBinding, getUserFlowsForBinding, } from '../knowledge/route_families.js';
+import { isTestFile } from '../agent/git.js';
 function scanDirForSpecs(baseDir, specDir, extension) {
     const fullDir = join(baseDir, specDir);
     if (!existsSync(fullDir)) {
@@ -125,7 +126,8 @@ function groupBindings(fileBindings) {
             const key = binding.feature || binding.family;
             const existing = groups.get(key);
             if (existing) {
-                if (!existing.files.includes(fb.file)) {
+                if (!existing._seen.has(fb.file)) {
+                    existing._seen.add(fb.file);
                     existing.files.push(fb.file);
                 }
             }
@@ -134,23 +136,13 @@ function groupBindings(fileBindings) {
                     familyId: binding.family,
                     featureId: binding.feature,
                     files: [fb.file],
+                    _seen: new Set([fb.file]),
                 });
             }
         }
     }
     return groups;
 }
-/** Filter out test files that should not be treated as application changes. */
-function isTestFile(file) {
-    const normalized = file.replace(/\\/g, '/');
-    return /\.(spec|test)\.(ts|tsx|js|jsx)$/.test(normalized) ||
-        /\.snap$/.test(normalized) ||
-        /_test\.go$/.test(normalized) ||
-        normalized.includes('__tests__/') ||
-        normalized.includes('__snapshots__/') ||
-        normalized.includes('/tests/') ||
-        normalized.includes('/test/');
-}
 /** Classify filtered test files by type for downstream decision-making. */
 function classifyPrTestFiles(allFiles, sourceFiles) {
     const sourceSet = new Set(sourceFiles);
@@ -180,17 +172,11 @@ export function analyzeImpact(changedFiles, options) {
     const allOriginalFiles = [...new Set([...changedFiles, ...preFilteredTests])];
     changedFiles = changedFiles.filter((f) => !isTestFile(f));
     const prIncludedTestFiles = classifyPrTestFiles(allOriginalFiles, changedFiles);
-    // Load manifest
-    const manifest = loadRouteFamilyManifest(testsRoot, routeFamilies);
+    // Load manifest, fall back to heuristic families if not found
+    let manifest = loadRouteFamilyManifest(testsRoot, routeFamilies);
     if (!manifest) {
-        return {
-            changedFiles,
-            expandedFiles: options.expandedFiles || [],
-            impactedFeatures: [],
-            unboundFiles: [...changedFiles],
-            warnings: ['Route family manifest not found. All files are unbound.'],
-            prIncludedTestFiles,
-        };
+        manifest = buildHeuristicFamilies(changedFiles, testsRoot);
+        warnings.push('Route family manifest not found. Using directory-based heuristics (lower accuracy).', 'Tip: Run `e2e-ai-agents train` to generate a proper manifest.');
     }
     // Combine original + expanded files
     const allFiles = [...new Set([...changedFiles, ...(options.expandedFiles || [])])];

package/dist/esm/index.js

@@ -44,8 +44,29 @@ export { StrategistAgent } from './agents/strategist.js';
 export { TestDesignerAgent } from './agents/test-designer.js';
 export { CrossImpactAgent } from './agents/cross-impact.js';
 export { RegressionAdvisorAgent } from './agents/regression-advisor.js';
+// Base provider (for extending with custom providers)
+export { BaseProvider, BudgetExceededError } from './base_provider.js';
+// Budget tracking
+export { BudgetLedger } from './budget_ledger.js';
+// Model routing
+export { ModelRouter } from './model_router.js';
+// Resilience
+export { withRetry } from './resilience/retry.js';
+export { CircuitBreaker } from './resilience/circuit_breaker.js';
+// Metrics
+export { PrometheusMetrics } from './metrics/prometheus.js';
+// Secret scanning
+export { sanitizeSecrets, containsSecrets, sanitizeObject } from './sanitize.js';
+// CLI errors
+export { CliError, classifyError, EXIT_CODES } from './cli/errors.js';
 // Training (route-families bootstrap and maintenance)
 export { scanProject } from './training/scanner.js';
 export { mergeFamilies, detectStaleFamilies } from './training/merger.js';
 export { enrichFamilies } from './training/enricher.js';
 export { getCommitFiles, validateCommit, buildValidationReport, formatValidationReport } from './training/validator.js';
+export { loadKnowledgeGraph, classifyProjectType, transformKGToFamilies, loadDiffOverlay } from './knowledge/kg_bridge.js';
+export { scanFromKnowledgeGraph } from './training/kg_scanner.js';
+export { resolveGenerationProfile, isMattermostProfile } from './prompts/generation_profile.js';
+export { detectFramework, detectTestMode } from './adapters/framework_adapter.js';
+// Route families (additional)
+export { serializeManifest } from './knowledge/route_families.js';

package/dist/esm/knowledge/cluster_utils.js

@@ -0,0 +1,60 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * 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',
+]);
+/** Extended skip set that also excludes test directories. */
+const SKIP_DIRS_WITH_TESTS = new Set([
+    ...DEFAULT_SKIP_DIRS,
+    'test', 'tests', 'e2e', 'spec', 'specs',
+]);
+/**
+ * Normalize a name to a snake_case cluster ID.
+ * Handles camelCase conversion, then strips non-alphanumeric characters.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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;
+}
+export { DEFAULT_SKIP_DIRS, SKIP_DIRS_WITH_TESTS };

package/dist/esm/knowledge/kg_bridge.js

@@ -0,0 +1,381 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * Bridge between Understand-Anything's knowledge graph and e2e-agents' route families.
+ * Transforms KG nodes/edges into RouteFamilyManifest so existing pipeline works unchanged.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { logger } from '../logger.js';
+import { deriveClusterId, deriveClusterIdFromPath } from './cluster_utils.js';
+const UA_DIR = '.understand-anything';
+const KG_FILE = 'knowledge-graph.json';
+const DIFF_FILE = 'diff-overlay.json';
+const FRONTEND_FRAMEWORKS = new Set([
+    'react', 'vue', 'angular', 'svelte', 'next', 'nextjs', 'next.js',
+    'nuxt', 'nuxtjs', 'gatsby', 'remix', 'astro', 'solid', 'solidjs',
+    'preact', 'lit', 'stencil', 'qwik',
+]);
+const BACKEND_FRAMEWORKS = new Set([
+    'express', 'fastify', 'koa', 'hapi', 'nest', 'nestjs',
+    'django', 'flask', 'fastapi', 'rails', 'spring', 'gin', 'echo', 'fiber',
+    'actix', 'axum', 'rocket', 'phoenix', 'laravel',
+]);
+/**
+ * Loads the knowledge graph from .understand-anything/knowledge-graph.json
+ * or from a custom path when provided.
+ */
+export function loadKnowledgeGraph(projectRoot, customPath) {
+    const kgPath = customPath || join(projectRoot, UA_DIR, KG_FILE);
+    if (!existsSync(kgPath)) {
+        return null;
+    }
+    try {
+        const raw = JSON.parse(readFileSync(kgPath, 'utf-8'));
+        if (!raw.nodes || !Array.isArray(raw.nodes) || !raw.edges || !Array.isArray(raw.edges)) {
+            logger.warn('Knowledge graph missing required nodes/edges arrays');
+            return null;
+        }
+        if (!raw.project) {
+            logger.warn('Knowledge graph missing project metadata');
+            return null;
+        }
+        // Field-level validation: filter out invalid nodes rather than rejecting the whole graph
+        const MAX_STRING_LEN = 1000;
+        const validNodes = raw.nodes.filter((node) => {
+            if (typeof node.id !== 'string' || typeof node.name !== 'string') {
+                logger.warn(`Dropping KG node with missing/invalid id or name: ${JSON.stringify(node).slice(0, 200)}`);
+                return false;
+            }
+            if (node.filePath !== undefined) {
+                if (typeof node.filePath !== 'string') {
+                    logger.warn(`Dropping KG node "${node.id}": filePath is not a string`);
+                    return false;
+                }
+                if (node.filePath.startsWith('/')) {
+                    logger.warn(`Dropping KG node "${node.id}": absolute filePath rejected`);
+                    return false;
+                }
+                if (node.filePath.includes('..')) {
+                    logger.warn(`Dropping KG node "${node.id}": path traversal in filePath rejected`);
+                    return false;
+                }
+                if (node.filePath.includes('\0')) {
+                    logger.warn(`Dropping KG node "${node.id}": null byte in filePath rejected`);
+                    return false;
+                }
+            }
+            return true;
+        });
+        // Truncate excessively long strings
+        for (const node of validNodes) {
+            if (node.name.length > MAX_STRING_LEN) {
+                node.name = node.name.slice(0, MAX_STRING_LEN);
+            }
+            if (node.description && node.description.length > MAX_STRING_LEN) {
+                node.description = node.description.slice(0, MAX_STRING_LEN);
+            }
+        }
+        raw.nodes = validNodes;
+        return raw;
+    }
+    catch (error) {
+        logger.warn(`Failed to load knowledge graph: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+/**
+ * Classifies project type based on KG framework metadata.
+ */
+export function classifyProjectType(kg) {
+    const frameworks = kg.project.frameworks.map((f) => f.toLowerCase());
+    const hasFrontend = frameworks.some((f) => FRONTEND_FRAMEWORKS.has(f));
+    const hasBackend = frameworks.some((f) => BACKEND_FRAMEWORKS.has(f));
+    if (hasFrontend && hasBackend)
+        return 'fullstack';
+    if (hasBackend)
+        return 'backend';
+    return 'frontend';
+}
+/**
+ * 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 function transformKGToFamilies(kg) {
+    const projectType = classifyProjectType(kg);
+    const nodeMap = new Map(kg.nodes.map((n) => [n.id, n]));
+    const edgesByTarget = groupEdges(kg.edges, 'target');
+    // Build clusters based on project type
+    const clusters = buildClusters(kg, projectType, nodeMap);
+    // Transform clusters into route families
+    const families = [];
+    for (const [clusterId, nodeIds] of clusters) {
+        const nodes = nodeIds.map((id) => nodeMap.get(id)).filter((n) => n !== undefined);
+        if (nodes.length === 0)
+            continue;
+        const family = buildFamilyFromCluster(clusterId, nodes, projectType, nodeMap, edgesByTarget);
+        if (family) {
+            families.push(family);
+        }
+    }
+    // Derive userFlows from KG tour steps
+    if (kg.tour && kg.tour.length > 0) {
+        assignTourFlows(families, kg.tour, nodeMap);
+    }
+    // Sort by priority (P0 first) then alphabetically
+    families.sort((a, b) => {
+        const pOrder = { P0: 0, P1: 1, P2: 2 };
+        const pa = pOrder[a.priority || 'P2'];
+        const pb = pOrder[b.priority || 'P2'];
+        if (pa !== pb)
+            return pa - pb;
+        return a.id.localeCompare(b.id);
+    });
+    return {
+        families,
+        source: 'knowledge-graph',
+    };
+}
+/**
+ * Loads the diff overlay from .understand-anything/diff-overlay.json
+ */
+export function loadDiffOverlay(projectRoot) {
+    const overlayPath = join(projectRoot, UA_DIR, DIFF_FILE);
+    if (!existsSync(overlayPath)) {
+        return null;
+    }
+    try {
+        const raw = JSON.parse(readFileSync(overlayPath, 'utf-8'));
+        if (!raw.changes || !Array.isArray(raw.changes)) {
+            return null;
+        }
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Maps diff overlay changes to file paths using KG node resolution.
+ */
+export function diffOverlayToChangedFiles(overlay, kg) {
+    const nodeMap = new Map(kg.nodes.map((n) => [n.id, n]));
+    const files = new Set();
+    for (const change of overlay.changes) {
+        // Use filePath from change if available
+        if (change.filePath) {
+            files.add(change.filePath);
+            continue;
+        }
+        // Fall back to KG node's filePath
+        const node = nodeMap.get(change.nodeId);
+        if (node?.filePath) {
+            files.add(node.filePath);
+        }
+    }
+    return [...files];
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function groupEdges(edges, key) {
+    const map = new Map();
+    for (const edge of edges) {
+        const val = edge[key];
+        if (!map.has(val))
+            map.set(val, []);
+        map.get(val).push(edge);
+    }
+    return map;
+}
+/**
+ * Build clusters of related nodes to become families.
+ * Frontend: group by route/page/component modules
+ * Backend: group by API endpoint handlers + their service dependencies
+ */
+function buildClusters(kg, projectType, nodeMap) {
+    const clusters = new Map();
+    // Strategy 1: Use KG layers to find anchor nodes
+    const layerMap = new Map();
+    if (kg.layers) {
+        for (const layer of kg.layers) {
+            layerMap.set(layer.name, new Set(layer.nodeIds));
+        }
+    }
+    // Strategy 2: Group by module/component/route nodes
+    const anchorKinds = projectType === 'backend'
+        ? new Set(['module', 'route', 'class', 'function'])
+        : new Set(['component', 'route', 'module', 'class']);
+    const anchorLayers = projectType === 'backend'
+        ? new Set(['api', 'service'])
+        : new Set(['ui']);
+    for (const node of kg.nodes) {
+        // Skip test/infra nodes as cluster anchors
+        if (node.layer === 'test' || node.layer === 'infra')
+            continue;
+        const isAnchorKind = anchorKinds.has(node.kind);
+        const isAnchorLayer = !node.layer || anchorLayers.has(node.layer);
+        if (!isAnchorKind || !isAnchorLayer)
+            continue;
+        // Derive cluster ID from node path or name
+        const clusterId = deriveClusterId(node);
+        if (!clusterId)
+            continue;
+        if (!clusters.has(clusterId)) {
+            clusters.set(clusterId, []);
+        }
+        clusters.get(clusterId).push(node.id);
+    }
+    // If no clusters found, fall back to file-based grouping
+    if (clusters.size === 0) {
+        for (const node of kg.nodes) {
+            if (!node.filePath || node.layer === 'test' || node.layer === 'infra')
+                continue;
+            const clusterId = deriveClusterIdFromPath(node.filePath);
+            if (!clusterId)
+                continue;
+            if (!clusters.has(clusterId)) {
+                clusters.set(clusterId, []);
+            }
+            clusters.get(clusterId).push(node.id);
+        }
+    }
+    return clusters;
+}
+// deriveClusterId and deriveClusterIdFromPath imported from cluster_utils.ts
+function computePriority(nodes) {
+    const maxFanIn = Math.max(...nodes.map((n) => n.fanIn || 0));
+    if (maxFanIn >= 10)
+        return 'P0';
+    if (maxFanIn >= 4)
+        return 'P1';
+    return 'P2';
+}
+function buildFamilyFromCluster(clusterId, nodes, projectType, nodeMap, edgesByTarget) {
+    const webappPaths = new Set();
+    const serverPaths = new Set();
+    const routes = [];
+    const apiEndpoints = [];
+    for (const node of nodes) {
+        if (!node.filePath)
+            continue;
+        const layer = node.layer;
+        if (layer === 'api' || layer === 'service' || layer === 'data') {
+            serverPaths.add(`${node.filePath}*`);
+        }
+        else if (layer === 'ui') {
+            webappPaths.add(`${node.filePath}*`);
+        }
+        else {
+            // Auto-assign based on project type
+            if (projectType === 'backend') {
+                serverPaths.add(`${node.filePath}*`);
+            }
+            else {
+                webappPaths.add(`${node.filePath}*`);
+            }
+        }
+        // Extract routes from route nodes
+        if (node.kind === 'route') {
+            const routePath = node.metadata?.path;
+            if (routePath) {
+                routes.push(routePath);
+                // Extract API endpoint info
+                const method = node.metadata?.method || 'GET';
+                apiEndpoints.push({ method: method.toUpperCase(), path: routePath, description: node.description });
+            }
+            else {
+                routes.push(`/${clusterId}`);
+            }
+        }
+    }
+    // If no routes extracted, generate a default
+    if (routes.length === 0) {
+        routes.push(`/${clusterId}`);
+    }
+    // Collect related test file paths by following 'tests' edges
+    const specDirs = new Set();
+    for (const node of nodes) {
+        const testEdges = (edgesByTarget.get(node.id) || []).filter((e) => e.type === 'tests');
+        for (const edge of testEdges) {
+            const testNode = nodeMap.get(edge.source);
+            if (testNode?.filePath) {
+                // Use directory of test file
+                const dir = testNode.filePath.replace(/\\/g, '/').split('/').slice(0, -1).join('/');
+                if (dir)
+                    specDirs.add(`${dir}/*`);
+            }
+        }
+    }
+    const priority = computePriority(nodes);
+    // Determine test type based on content
+    let testType;
+    if (webappPaths.size > 0 && serverPaths.size > 0) {
+        testType = 'both';
+    }
+    else if (serverPaths.size > 0 && apiEndpoints.length > 0) {
+        testType = 'api';
+    }
+    else if (webappPaths.size > 0) {
+        testType = 'ui';
+    }
+    const family = {
+        id: clusterId,
+        routes: [...new Set(routes)],
+        priority,
+    };
+    if (webappPaths.size > 0)
+        family.webappPaths = [...webappPaths];
+    if (serverPaths.size > 0)
+        family.serverPaths = [...serverPaths];
+    if (specDirs.size > 0)
+        family.specDirs = [...specDirs];
+    if (apiEndpoints.length > 0)
+        family.apiEndpoints = apiEndpoints;
+    if (testType)
+        family.testType = testType;
+    return family;
+}
+function assignTourFlows(families, tour, nodeMap) {
+    if (!tour)
+        return;
+    // Build a map of nodeId → family for quick lookup
+    const nodeToFamily = new Map();
+    for (const family of families) {
+        // Resolve family nodes from paths
+        for (const [nodeId, node] of nodeMap) {
+            if (!node.filePath)
+                continue;
+            const matchesPaths = [
+                ...(family.webappPaths || []),
+                ...(family.serverPaths || []),
+            ];
+            for (const pattern of matchesPaths) {
+                const prefix = pattern.replace(/\*$/, '');
+                if (node.filePath.startsWith(prefix)) {
+                    nodeToFamily.set(nodeId, family);
+                    break;
+                }
+            }
+        }
+    }
+    // Assign tour steps as user flows
+    for (const step of tour.sort((a, b) => a.order - b.order)) {
+        for (const nodeId of step.nodeIds) {
+            const family = nodeToFamily.get(nodeId);
+            if (family) {
+                if (!family.userFlows)
+                    family.userFlows = [];
+                const flowDesc = `${step.title}: ${step.description}`;
+                if (!family.userFlows.includes(flowDesc)) {
+                    family.userFlows.push(flowDesc);
+                }
+            }
+        }
+    }
+}

package/dist/esm/knowledge/kg_types.js

@@ -0,0 +1,3 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+export {};

package/dist/esm/knowledge/route_families.js

@@ -30,6 +30,17 @@ export function matchesGlob(filePath, pattern) {
 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;
@@ -38,6 +49,10 @@ function validateFamily(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;
     }
@@ -81,6 +96,16 @@ function validateFamily(family) {
             .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;
+    }
     return result;
 }
 function validateFeature(feature) {
@@ -272,3 +297,67 @@ export function getRoutesForBinding(manifest, binding) {
 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 `e2e-ai-agents 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',
+            ];
+            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';
+}