@yasserkhanorg/e2e-agents 0.5.16 → 0.7.0

package/dist/esm/engine/impact_engine.js

@@ -0,0 +1,191 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { loadRouteFamilyManifest, bindFilesToFamilies, getSpecDirsForBinding, getCypressSpecDirsForBinding, getPriorityForBinding, getUserFlowsForBinding, } from '../knowledge/route_families.js';
+function scanDirForSpecs(baseDir, specDir, extension) {
+    const fullDir = join(baseDir, specDir);
+    if (!existsSync(fullDir)) {
+        return [];
+    }
+    const specs = [];
+    try {
+        const items = readdirSync(fullDir, { withFileTypes: true });
+        for (const item of items) {
+            const itemPath = join(fullDir, item.name);
+            if (item.isDirectory()) {
+                specs.push(...scanDirForSpecsRecursive(itemPath, extension));
+            }
+            else if (item.name.endsWith(extension)) {
+                specs.push(join(specDir, item.name));
+            }
+        }
+    }
+    catch {
+        // Directory not readable
+    }
+    return specs;
+}
+function scanDirForSpecsRecursive(dir, extension) {
+    const specs = [];
+    try {
+        const items = readdirSync(dir, { withFileTypes: true });
+        for (const item of items) {
+            const fullPath = join(dir, item.name);
+            if (item.isDirectory()) {
+                specs.push(...scanDirForSpecsRecursive(fullPath, extension));
+            }
+            else if (item.name.endsWith(extension)) {
+                specs.push(fullPath);
+            }
+        }
+    }
+    catch {
+        // Directory not readable
+    }
+    return specs;
+}
+function resolvePlaywrightSpecs(testsRoot, specDirs) {
+    const specs = [];
+    for (const dir of specDirs) {
+        specs.push(...scanDirForSpecs(testsRoot, dir, '.spec.ts'));
+    }
+    return specs;
+}
+function resolveCypressSpecs(cypressRoot, specDirs) {
+    const specs = [];
+    for (const dir of specDirs) {
+        // cypressSpecDirs are relative to testsRoot (e.g. ../cypress/tests/integration/channels/search/)
+        // Resolve them relative to the cypress root
+        const resolvedDir = join(cypressRoot, dir.replace(/^\.\.\/cypress\//, ''));
+        if (!existsSync(resolvedDir)) {
+            continue;
+        }
+        const found = scanDirForSpecsRecursive(resolvedDir, '.js');
+        const tsFound = scanDirForSpecsRecursive(resolvedDir, '.ts');
+        specs.push(...found, ...tsFound);
+    }
+    return specs;
+}
+function computeCoverageStatus(pwSpecs, cySpecs) {
+    const hasPw = pwSpecs.length > 0;
+    const hasCy = cySpecs.length > 0;
+    if (hasPw && hasCy) {
+        return 'covered';
+    }
+    if (hasPw || hasCy) {
+        return 'partial';
+    }
+    return 'uncovered';
+}
+/**
+ * Group file bindings into a deduplicated map of family/feature → changed files.
+ */
+function groupBindings(fileBindings) {
+    const groups = new Map();
+    for (const fb of fileBindings) {
+        for (const binding of fb.bindings) {
+            const key = binding.feature || binding.family;
+            const existing = groups.get(key);
+            if (existing) {
+                if (!existing.files.includes(fb.file)) {
+                    existing.files.push(fb.file);
+                }
+            }
+            else {
+                groups.set(key, {
+                    familyId: binding.family,
+                    featureId: binding.feature,
+                    files: [fb.file],
+                });
+            }
+        }
+    }
+    return groups;
+}
+export function analyzeImpact(changedFiles, options) {
+    const { testsRoot, routeFamilies } = options;
+    const warnings = [];
+    // Load manifest
+    const manifest = loadRouteFamilyManifest(testsRoot, routeFamilies);
+    if (!manifest) {
+        return {
+            changedFiles,
+            expandedFiles: options.expandedFiles || [],
+            impactedFeatures: [],
+            unboundFiles: [...changedFiles],
+            warnings: ['Route family manifest not found. All files are unbound.'],
+        };
+    }
+    // Combine original + expanded files
+    const allFiles = [...new Set([...changedFiles, ...(options.expandedFiles || [])])];
+    // Bind files to families
+    const fileBindings = bindFilesToFamilies(allFiles, manifest);
+    // Find unbound files
+    const unboundFiles = fileBindings
+        .filter((fb) => fb.bindings.length === 0)
+        .map((fb) => fb.file);
+    // Group bindings into features
+    const groups = groupBindings(fileBindings.filter((fb) => fb.bindings.length > 0));
+    // Determine cypress root
+    const cypressRoot = options.cypressRoot || inferCypressRoot(testsRoot);
+    // Resolve specs and compute coverage for each feature
+    const impactedFeatures = [];
+    for (const group of groups.values()) {
+        const binding = { family: group.familyId, feature: group.featureId };
+        const specDirs = getSpecDirsForBinding(manifest, binding);
+        const cypressSpecDirs = getCypressSpecDirsForBinding(manifest, binding);
+        const priority = getPriorityForBinding(manifest, binding);
+        const userFlows = getUserFlowsForBinding(manifest, binding);
+        const playwrightSpecs = resolvePlaywrightSpecs(testsRoot, specDirs);
+        const cypressSpecs = cypressRoot ? resolveCypressSpecs(cypressRoot, cypressSpecDirs) : [];
+        const coverageStatus = computeCoverageStatus(playwrightSpecs, cypressSpecs);
+        impactedFeatures.push({
+            familyId: group.familyId,
+            featureId: group.featureId,
+            priority,
+            changedFiles: group.files,
+            playwrightSpecs,
+            cypressSpecs,
+            userFlows,
+            coverageStatus,
+        });
+    }
+    // Sort by priority (P0 first, then P1, then P2)
+    const priorityOrder = { P0: 0, P1: 1, P2: 2 };
+    impactedFeatures.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority]);
+    if (unboundFiles.length > 0 && unboundFiles.length <= 5) {
+        warnings.push(`${unboundFiles.length} file(s) not mapped to any route family: ${unboundFiles.join(', ')}`);
+    }
+    else if (unboundFiles.length > 5) {
+        warnings.push(`${unboundFiles.length} file(s) not mapped to any route family`);
+    }
+    return {
+        changedFiles,
+        expandedFiles: options.expandedFiles || [],
+        impactedFeatures,
+        unboundFiles,
+        warnings,
+    };
+}
+function inferCypressRoot(testsRoot) {
+    // testsRoot is typically the Playwright tests directory
+    // Cypress tests are at a sibling path: e2e-tests/cypress/tests/integration/channels/
+    const candidate = join(testsRoot, '..', 'cypress');
+    if (existsSync(candidate)) {
+        return candidate;
+    }
+    return undefined;
+}
+/**
+ * Get gaps: P0/P1 features with 'uncovered' status.
+ */
+export function getGaps(result) {
+    return result.impactedFeatures.filter((f) => (f.priority === 'P0' || f.priority === 'P1') && f.coverageStatus === 'uncovered');
+}
+/**
+ * Get partial gaps: P0/P1 features with 'partial' status (advisory).
+ */
+export function getPartialGaps(result) {
+    return result.impactedFeatures.filter((f) => (f.priority === 'P0' || f.priority === 'P1') && f.coverageStatus === 'partial');
+}

package/dist/esm/engine/plan_builder.js

@@ -0,0 +1,368 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { mkdirSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { minimatch } from 'minimatch';
+import { getGaps, getPartialGaps } from './impact_engine.js';
+const DEFAULT_POLICY = {
+    minConfidenceForTargeted: 60,
+    safeMergeMinConfidence: 85,
+    forceFullOnWarningsAtOrAbove: 2,
+    forceFullOnP0WithGaps: true,
+    forceFullOnRiskyFiles: true,
+    riskyFilePatterns: [
+        '**/auth/**',
+        '**/login/**',
+        '**/permissions/**',
+        '**/admin/**',
+        '**/security/**',
+        '**/migrations/**',
+        '**/schema/**',
+        '**/*.sql',
+        '**/webhook/**',
+    ],
+    enforcementMode: 'advisory',
+    blockOnActions: ['must-add-tests'],
+};
+function featureLabel(f) {
+    return f.featureId || f.familyId;
+}
+function computeConfidence(impact) {
+    const gaps = getGaps(impact);
+    const totalFeatures = impact.impactedFeatures.length;
+    const boundRatio = totalFeatures > 0
+        ? (totalFeatures / (totalFeatures + impact.unboundFiles.length))
+        : 1;
+    // Graph-resolved bindings start at 100
+    let confidence = 100;
+    // Deduct for unbound files (not mapped to any family)
+    if (impact.unboundFiles.length > 0) {
+        const unboundPenalty = Math.min(30, impact.unboundFiles.length * 3);
+        confidence -= unboundPenalty;
+    }
+    // Deduct for gaps
+    confidence -= Math.min(20, gaps.length * 5);
+    // Deduct for warnings
+    confidence -= Math.min(15, impact.warnings.length * 5);
+    // Bonus for high bound ratio
+    if (boundRatio >= 0.9) {
+        confidence = Math.min(100, confidence + 5);
+    }
+    return Math.max(0, Math.min(100, confidence));
+}
+function findRiskyFiles(changedFiles, patterns) {
+    return [...new Set(changedFiles.filter((file) => patterns.some((pattern) => minimatch(file, pattern, { matchBase: true }))))];
+}
+function pickRunSet(impact, confidence, policy) {
+    const gaps = getGaps(impact);
+    const reasons = [];
+    const triggeredRules = [];
+    const riskyFiles = findRiskyFiles(impact.changedFiles, policy.riskyFilePatterns);
+    const hasP0 = impact.impactedFeatures.some((f) => f.priority === 'P0');
+    if (gaps.length > 0) {
+        reasons.push(`${gaps.length} uncovered P0/P1 feature(s) detected.`);
+    }
+    if (hasP0) {
+        reasons.push('P0 features are impacted by this change set.');
+    }
+    if (policy.forceFullOnRiskyFiles && riskyFiles.length > 0) {
+        triggeredRules.push('risky-files');
+        reasons.push(`Risky file patterns matched: ${riskyFiles.join(', ')}`);
+    }
+    if (confidence < policy.minConfidenceForTargeted) {
+        triggeredRules.push('low-confidence');
+    }
+    if (impact.warnings.length >= policy.forceFullOnWarningsAtOrAbove) {
+        triggeredRules.push('warning-threshold');
+        reasons.push('Warning threshold exceeded.');
+    }
+    if (policy.forceFullOnP0WithGaps && hasP0 && gaps.length > 0) {
+        triggeredRules.push('p0-with-gaps');
+    }
+    if (triggeredRules.length > 0) {
+        return {
+            runSet: 'full',
+            reasons: reasons.length > 0 ? reasons : ['Policy rules triggered full suite.'],
+            triggeredRules,
+            riskyFiles,
+        };
+    }
+    // If we have impacted features with specs, recommend targeted
+    const coveredFeatures = impact.impactedFeatures.filter((f) => f.coverageStatus !== 'uncovered');
+    if (coveredFeatures.length > 0) {
+        return {
+            runSet: 'targeted',
+            reasons: reasons.length > 0 ? reasons : ['Impacted features have test coverage.'],
+            triggeredRules,
+            riskyFiles,
+        };
+    }
+    return {
+        runSet: 'smoke',
+        reasons: reasons.length > 0 ? reasons : ['No targeted tests mapped from impacted features.'],
+        triggeredRules,
+        riskyFiles,
+    };
+}
+function buildDecision(impact, runSet, confidence, policy) {
+    const gaps = getGaps(impact);
+    if (gaps.length > 0) {
+        return {
+            action: 'must-add-tests',
+            title: 'Must add tests',
+            summary: `Detected ${gaps.length} uncovered P0/P1 feature(s). Add or update tests before merge.`,
+        };
+    }
+    if (impact.changedFiles.length === 0 && impact.impactedFeatures.length === 0) {
+        return {
+            action: 'safe-to-merge',
+            title: 'Safe to merge',
+            summary: 'No app file changes detected — no E2E coverage required for this change set.',
+        };
+    }
+    if (runSet === 'smoke' && confidence >= policy.safeMergeMinConfidence && impact.warnings.length === 0) {
+        return {
+            action: 'safe-to-merge',
+            title: 'Safe to merge',
+            summary: 'No critical coverage gaps were detected and confidence is high.',
+        };
+    }
+    const coveredCount = impact.impactedFeatures.filter((f) => f.coverageStatus !== 'uncovered').length;
+    const coveredSuffix = coveredCount > 0
+        ? ` All ${coveredCount} impacted feature(s) have test coverage.`
+        : '';
+    return {
+        action: 'run-now',
+        title: 'Run now',
+        summary: `Impacted features are covered by existing tests.${coveredSuffix} Verify with the E2E suite before merge.`,
+    };
+}
+function evaluateEnforcement(decision, policy) {
+    const blockOnActions = (policy.blockOnActions && policy.blockOnActions.length > 0)
+        ? [...policy.blockOnActions]
+        : ['must-add-tests'];
+    const matchedAction = blockOnActions.includes(decision.action);
+    if (policy.enforcementMode === 'block' && matchedAction) {
+        return {
+            mode: policy.enforcementMode,
+            blockOnActions,
+            matchedAction,
+            shouldFail: true,
+            summary: `Blocking mode active: decision "${decision.action}" is configured to fail CI.`,
+        };
+    }
+    if (policy.enforcementMode === 'warn' && matchedAction) {
+        return {
+            mode: policy.enforcementMode,
+            blockOnActions,
+            matchedAction,
+            shouldFail: false,
+            summary: `Warning mode active: decision "${decision.action}" is advisory-only for CI.`,
+        };
+    }
+    if (policy.enforcementMode === 'block') {
+        return {
+            mode: policy.enforcementMode,
+            blockOnActions,
+            matchedAction,
+            shouldFail: false,
+            summary: `Blocking mode active, but decision "${decision.action}" is not configured for CI failure.`,
+        };
+    }
+    return {
+        mode: policy.enforcementMode,
+        blockOnActions,
+        matchedAction,
+        shouldFail: false,
+        summary: 'Advisory mode active: recommendations do not fail CI by default.',
+    };
+}
+/**
+ * Build recommended test list from impacted features' Playwright specs.
+ */
+function buildRecommendedTests(impact) {
+    const tests = [];
+    for (const feature of impact.impactedFeatures) {
+        if (feature.coverageStatus !== 'uncovered') {
+            for (const spec of feature.playwrightSpecs) {
+                if (!tests.includes(spec)) {
+                    tests.push(spec);
+                }
+            }
+        }
+    }
+    return tests;
+}
+export function buildPlanFromImpact(impact, policyOverride, aiEnrichment) {
+    const policy = { ...DEFAULT_POLICY, ...(policyOverride || {}) };
+    const confidence = computeConfidence(impact);
+    const runSetResult = pickRunSet(impact, confidence, policy);
+    const decision = buildDecision(impact, runSetResult.runSet, confidence, policy);
+    const enforcement = evaluateEnforcement(decision, policy);
+    const gaps = getGaps(impact);
+    const partialGaps = getPartialGaps(impact);
+    // Build two separate lookup maps from aiEnrichment: one by featureId, one by familyId.
+    // The familyId map stores only the FIRST feature encountered to avoid last-write-wins collisions.
+    const aiFeatureByFeatureId = new Map();
+    const aiFeatureByFamilyId = new Map();
+    if (aiEnrichment) {
+        for (const ef of aiEnrichment.enrichedFeatures) {
+            if (ef.featureId) {
+                aiFeatureByFeatureId.set(ef.featureId, ef);
+            }
+            if (ef.familyId && !aiFeatureByFamilyId.has(ef.familyId)) {
+                aiFeatureByFamilyId.set(ef.familyId, ef);
+            }
+        }
+    }
+    const gapDetails = gaps.map((f) => {
+        const label = featureLabel(f);
+        const aiFeature = f.featureId
+            ? (aiFeatureByFeatureId.get(f.featureId) ?? aiFeatureByFamilyId.get(f.familyId))
+            : aiFeatureByFamilyId.get(f.familyId);
+        const baseReasons = [`No Playwright or Cypress tests found for ${label}`];
+        const reasons = aiFeature && aiFeature.aiReasons.length > 0
+            ? [...baseReasons, ...aiFeature.aiReasons]
+            : baseReasons;
+        const missingScenarios = aiFeature && aiFeature.aiMissingScenarios.length > 0
+            ? aiFeature.aiMissingScenarios
+            : (f.userFlows.length > 0 ? f.userFlows.slice(0, 5) : undefined);
+        return {
+            id: label,
+            name: label,
+            priority: f.priority,
+            reasons,
+            files: f.changedFiles.slice(0, 6),
+            missingScenarios,
+            source: aiFeature ? 'ai+deterministic' : 'deterministic',
+        };
+    });
+    // Add partial gaps as advisory info
+    for (const f of partialGaps) {
+        const coverageType = f.playwrightSpecs.length > 0 ? 'Cypress' : 'Playwright';
+        const hasOpposite = f.playwrightSpecs.length > 0 ? 'Playwright' : 'Cypress';
+        const label = featureLabel(f);
+        const aiFeature = f.featureId
+            ? (aiFeatureByFeatureId.get(f.featureId) ?? aiFeatureByFamilyId.get(f.familyId))
+            : aiFeatureByFamilyId.get(f.familyId);
+        const baseReasons = [`Missing ${coverageType} tests for ${label} (has ${hasOpposite} only)`];
+        const reasons = aiFeature && aiFeature.aiReasons.length > 0
+            ? [...baseReasons, ...aiFeature.aiReasons]
+            : baseReasons;
+        gapDetails.push({
+            id: label,
+            name: `${label} (partial)`,
+            priority: f.priority,
+            reasons,
+            files: f.changedFiles.slice(0, 6),
+            source: aiFeature ? 'ai+deterministic' : 'deterministic',
+        });
+    }
+    const coveredFlows = impact.impactedFeatures
+        .filter((f) => f.coverageStatus === 'covered')
+        .map((f) => ({
+        id: featureLabel(f),
+        name: featureLabel(f),
+        priority: f.priority,
+        coveredBy: [
+            ...(f.playwrightSpecs.length > 0 ? [`${f.playwrightSpecs.length} Playwright spec(s)`] : []),
+            ...(f.cypressSpecs.length > 0 ? [`${f.cypressSpecs.length} Cypress spec(s)`] : []),
+        ].slice(0, 3),
+    }));
+    const recommendedTests = buildRecommendedTests(impact);
+    const requiredNewTests = gaps.map((f) => `${featureLabel(f)}: Add E2E tests`);
+    const p0 = impact.impactedFeatures.filter((f) => f.priority === 'P0').length;
+    const p1 = impact.impactedFeatures.filter((f) => f.priority === 'P1').length;
+    const p2 = impact.impactedFeatures.filter((f) => f.priority === 'P2').length;
+    const runId = `plan-${Date.now().toString(36)}`;
+    const planSource = aiEnrichment ? 'ai+deterministic' : 'impact';
+    return {
+        schemaVersion: '1.0.0',
+        runId,
+        generatedAt: new Date().toISOString(),
+        source: planSource,
+        runSet: runSetResult.runSet,
+        confidence,
+        reasons: runSetResult.reasons,
+        recommendedTests,
+        requiredNewTests,
+        gapDetails,
+        coveredFlows,
+        policy: {
+            riskyFiles: runSetResult.riskyFiles,
+            triggeredRules: runSetResult.triggeredRules,
+            applied: policy,
+        },
+        decision,
+        enforcement,
+        metrics: {
+            changedFiles: impact.changedFiles.length,
+            impactedFlows: impact.impactedFeatures.length,
+            p0Flows: p0,
+            p1Flows: p1,
+            p2Flows: p2,
+            uncoveredP0P1Flows: gaps.length,
+            warnings: impact.warnings.length,
+        },
+    };
+}
+export function writePlanReport(appRoot, plan) {
+    const baseDir = join(appRoot, '.e2e-ai-agents');
+    mkdirSync(baseDir, { recursive: true });
+    const planPath = join(baseDir, 'plan.json');
+    writeFileSync(planPath, JSON.stringify(plan, null, 2), 'utf-8');
+    return planPath;
+}
+export function renderCiSummaryMarkdown(plan) {
+    const lines = [];
+    const { p0Flows, p1Flows, uncoveredP0P1Flows, changedFiles, impactedFlows } = plan.metrics;
+    const mustAddTests = plan.decision.action === 'must-add-tests';
+    const statusEmoji = mustAddTests ? '🔴' : plan.decision.action === 'safe-to-merge' ? '🟢' : '🟡';
+    lines.push(`## ${statusEmoji} E2E Coverage: ${plan.decision.title}`);
+    lines.push('');
+    lines.push(`${plan.decision.summary}`);
+    lines.push('');
+    lines.push(`**${changedFiles}** files changed → **${impactedFlows}** features impacted` +
+        (p0Flows > 0 || p1Flows > 0 ? ` (P0: ${p0Flows}, P1: ${p1Flows})` : ''));
+    if (mustAddTests && plan.requiredNewTests.length > 0) {
+        lines.push('');
+        lines.push('### ⚠️ Add E2E tests for these uncovered P0/P1 features');
+        lines.push('');
+        lines.push(`The following ${uncoveredP0P1Flows} feature(s) have no test coverage and must be covered before merge:`);
+        lines.push('');
+        for (const gap of plan.gapDetails.filter((g) => !g.name.includes('(partial)'))) {
+            const aiLabel = gap.source === 'ai+deterministic' ? ' ✦ AI-enriched' : '';
+            lines.push(`- **${gap.name}** [${gap.priority}]${aiLabel}`);
+            if (gap.missingScenarios && gap.missingScenarios.length > 0) {
+                for (const scenario of gap.missingScenarios) {
+                    lines.push(`  - ${scenario}`);
+                }
+            }
+            // Show AI-provided reasons (skip the first deterministic reason which is always included)
+            const aiReasons = gap.reasons.slice(1);
+            if (aiReasons.length > 0) {
+                lines.push(`  - *AI insight*: ${aiReasons.join('; ')}`);
+            }
+        }
+    }
+    if (plan.coveredFlows.length > 0) {
+        lines.push('');
+        lines.push('### ✅ Covered features');
+        lines.push('');
+        for (const flow of plan.coveredFlows) {
+            lines.push(`- **${flow.name}** [${flow.priority}] — ${flow.coveredBy.join(', ')}`);
+        }
+    }
+    if (plan.confidence < 100) {
+        lines.push('');
+        lines.push(`**Confidence**: ${plan.confidence}%`);
+    }
+    return lines.join('\n');
+}
+export function writeCiSummary(appRoot, markdown, relativePath = '.e2e-ai-agents/ci-summary.md') {
+    const fullPath = join(appRoot, relativePath);
+    const dir = dirname(fullPath);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(fullPath, markdown, 'utf-8');
+    return fullPath;
+}

package/dist/esm/index.js

@@ -8,8 +8,11 @@ export { OpenAIProvider, checkOpenAISetup } from './openai_provider.js';
 export { CustomProvider } from './custom_provider.js';
 // Factory
 export { LLMProviderFactory, validateProviderSetup } from './provider_factory.js';
-// Agent API (impact, gap, suggest, traceability ingest)
-export { analyzeImpact, findGaps, recommendTests, handoffGeneratedTests, ingestTraceability, captureTraceability } from './api.js';
+// Agent API (deterministic impact + plan, traceability)
+export { analyzeImpactDeterministic, recommendTestsDeterministic, handoffGeneratedTests, ingestTraceability, captureTraceability } from './api.js';
+// V2 Engine (deterministic impact + plan)
+export { analyzeImpact as analyzeImpactV2, getGaps, getPartialGaps } from './engine/impact_engine.js';
+export { buildPlanFromImpact } from './engine/plan_builder.js';
 export { appendFeedbackAndRecompute, readCalibration } from './agent/feedback.js';
 export { finalizeGeneratedTests } from './agent/handoff.js';
 export { ingestTraceabilityInput } from './agent/traceability_ingest.js';
@@ -21,6 +24,6 @@ export { buildGenerationPrompt, parseGenerationResponse, detectHallucinatedMetho
 export { runHealStage, healFromReport, resolveHealTargets, renderHealMarkdown } from './pipeline/stage4_heal.js';
 export { buildHealPrompt, buildQualityFixPrompt } from './prompts/heal.js';
 // Knowledge modules
-export { loadRouteFamilyManifest, bindFilesToFamilies } from './knowledge/route_families.js';
+export { loadRouteFamilyManifest, bindFilesToFamilies, getCypressSpecDirsForBinding, getPriorityForBinding, getUserFlowsForBinding } from './knowledge/route_families.js';
 export { buildApiSurface, loadOrBuildApiSurface } from './knowledge/api_surface.js';
 export { buildSpecIndex, getSpecsForFamily } from './knowledge/spec_index.js';

package/dist/esm/knowledge/route_families.js

@@ -63,9 +63,18 @@ function validateFamily(family) {
     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))
@@ -94,9 +103,18 @@ function validateFeature(feature) {
     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');
+    }
     return result;
 }
 export function loadRouteFamilyManifest(testsRoot, config) {
@@ -136,7 +154,8 @@ export function loadRouteFamilyManifest(testsRoot, config) {
         }
     }
     if (config?.strict) {
-        throw new Error('Route family manifest is required but not found. Create .e2e-ai-agents/route-families.json');
+        // eslint-disable-next-line no-console
+        console.warn('[e2e-agents] Route family manifest not found. The manifest is optional context for AI enrichment — create .e2e-ai-agents/route-families.json to enable family-level routing hints.');
     }
     return null;
 }
@@ -193,6 +212,45 @@ export function getSpecDirsForBinding(manifest, binding) {
     }
     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);
+        if (feature?.cypressSpecDirs && feature.cypressSpecDirs.length > 0) {
+            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) {