@yasserkhanorg/e2e-agents 1.5.0 → 1.7.0

package/dist/logger.js

@@ -51,6 +51,7 @@ function logLevelToString(level) {
 class Logger {
     constructor(minLevel) {
         this.level = minLevel ?? getLogLevelFromEnv();
+        this.jsonMode = process.env.LOG_FORMAT?.toLowerCase() === 'json';
     }
     error(message, context) {
         if (this.level >= LogLevel.ERROR) {
@@ -75,11 +76,37 @@ class Logger {
     setLevel(level) {
         this.level = level;
     }
+    setJsonMode(enabled) {
+        this.jsonMode = enabled;
+    }
+    /**
+     * Start a timer for measuring duration of an operation.
+     * Returns an object with `end()` that logs at DEBUG level and returns elapsed ms.
+     */
+    timer(label) {
+        const start = performance.now();
+        return {
+            end: () => {
+                const elapsed = Math.round(performance.now() - start);
+                this.debug(`${label} completed`, { durationMs: elapsed });
+                return elapsed;
+            },
+        };
+    }
     log(level, message, context) {
         const timestamp = new Date().toISOString();
         const levelStr = logLevelToString(level);
-        const contextStr = context ? ` ${JSON.stringify(context)}` : '';
-        const output = `[${timestamp}] [${levelStr}] ${message}${contextStr}`;
+        let output;
+        if (this.jsonMode) {
+            const entry = { ts: timestamp, level: levelStr, msg: message };
+            if (context)
+                entry.ctx = context;
+            output = JSON.stringify(entry);
+        }
+        else {
+            const contextStr = context ? ` ${JSON.stringify(context)}` : '';
+            output = `[${timestamp}] [${levelStr}] ${message}${contextStr}`;
+        }
         if (level <= LogLevel.WARN) {
             console.error(output);
         }

package/dist/pipeline/orchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/pipeline/orchestrator.ts"],"names":[],"mappings":"AAQA,OAAO,EAAiB,KAAK,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAmB,KAAK,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAqB,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAC,MAAM,wBAAwB,CAAC;AACrG,OAAO,EAAuD,KAAK,UAAU,EAAE,KAAK,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACxH,OAAO,EAAe,KAAK,kBAAkB,EAAoB,MAAM,gCAAgC,CAAC;AAExG,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,gCAAgC,CAAC;AACtE,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,6BAA6B,CAAC;AAElE,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,iEAAiE;IACjE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,MAAM,CAAC,EAAE,KAAK,CAAC,YAAY,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,GAAG,MAAM,CAAC,CAAC;CAChF;AAED,MAAM,WAAW,cAAc;IAC3B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAC;CAC3B;AAqBD,wBAAsB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAgIjF"}
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/pipeline/orchestrator.ts"],"names":[],"mappings":"AAQA,OAAO,EAAiB,KAAK,YAAY,EAAC,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAmB,KAAK,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAqB,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAC,MAAM,wBAAwB,CAAC;AACrG,OAAO,EAAuD,KAAK,UAAU,EAAE,KAAK,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACxH,OAAO,EAAe,KAAK,kBAAkB,EAAoB,MAAM,gCAAgC,CAAC;AAExG,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,gCAAgC,CAAC;AACtE,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,6BAA6B,CAAC;AAElE,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,iEAAiE;IACjE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,MAAM,CAAC,EAAE,KAAK,CAAC,YAAY,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,GAAG,MAAM,CAAC,CAAC;CAChF;AAED,MAAM,WAAW,cAAc;IAC3B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAC;CAC3B;AAqBD,wBAAsB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CA6IjF"}

package/dist/pipeline/orchestrator.js

@@ -6,6 +6,7 @@ exports.runPipeline = runPipeline;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const git_js_1 = require("../agent/git.js");
+const logger_js_1 = require("../logger.js");
 const stage0_preprocess_js_1 = require("./stage0_preprocess.js");
 const stage1_impact_js_1 = require("./stage1_impact.js");
 const stage2_coverage_js_1 = require("./stage2_coverage.js");
@@ -61,20 +62,25 @@ async function runPipeline(config) {
         const reportPath = writeReport(config.testsRoot, emptyReport);
         return { report: emptyReport, reportPath, warnings: allWarnings };
     }
+    const timings = {};
     // Step 2: Preprocess — deterministic file classification + route family binding
+    const preprocessTimer = logger_js_1.logger.timer('preprocess');
     const preprocessResult = (0, stage0_preprocess_js_1.preprocess)(changedFiles, {
         appPath: config.appPath,
         testsRoot: config.testsRoot,
         routeFamilies: config.routeFamilies,
         apiSurface: config.apiSurface,
     });
+    timings.preprocess = preprocessTimer.end();
     allWarnings.push(...preprocessResult.warnings);
     let decisions = [];
     // Step 3: Impact stage — AI-powered flow identification per family
     if (stages.includes('impact')) {
+        const impactTimer = logger_js_1.logger.timer('impact');
         const impactResult = await (0, stage1_impact_js_1.runImpactStage)(preprocessResult.familyGroups, preprocessResult.manifest, preprocessResult.specIndex, preprocessResult.apiSurface, preprocessResult.context, config.impact || {});
         decisions = impactResult.decisions;
         allWarnings.push(...impactResult.warnings);
+        timings.impact = impactTimer.end();
         // Check cannot_determine ratio
         const cannotDetermineRatio = (0, guardrails_js_1.computeCannotDetermineRatio)(decisions);
         if (cannotDetermineRatio > 0.3) {
@@ -83,18 +89,23 @@ async function runPipeline(config) {
     }
     // Step 4: Coverage stage — AI-powered spec coverage evaluation
     if (stages.includes('coverage') && decisions.length > 0) {
+        const coverageTimer = logger_js_1.logger.timer('coverage');
         const coverageResult = await (0, stage2_coverage_js_1.runCoverageStage)(decisions, preprocessResult.specIndex, preprocessResult.context, config.testsRoot, config.coverage || {});
         decisions = coverageResult.decisions;
+        timings.coverage = coverageTimer.end();
         allWarnings.push(...coverageResult.warnings);
     }
     // Step 5: Generation stage — AI-powered spec generation for create_spec / add_scenarios
     if (stages.includes('generation') && decisions.length > 0) {
+        const generationTimer = logger_js_1.logger.timer('generation');
         const generationResult = await (0, stage3_generation_js_1.runGenerationStage)(decisions, preprocessResult.apiSurface, config.testsRoot, config.generation || {});
         generatedSpecs = generationResult.generated;
+        timings.generation = generationTimer.end();
         allWarnings.push(...generationResult.warnings);
     }
     // Step 6: Heal stage — MCP-backed playwright-test-healer for failing/flaky specs
     if (stages.includes('heal')) {
+        const healTimer = logger_js_1.logger.timer('heal');
         const healTargets = (0, stage4_heal_js_1.resolveHealTargets)(config.testsRoot, {
             playwrightReportPath: config.playwrightReportPath,
             generatedSpecs,
@@ -106,6 +117,7 @@ async function runPipeline(config) {
         else {
             allWarnings.push('Heal stage: no targets found (no failing specs in report, no generated specs).');
         }
+        timings.heal = healTimer.end();
     }
     // Build report
     const report = {
@@ -121,16 +133,18 @@ async function runPipeline(config) {
             generationAgent: stages.includes('generation') ? (config.generation?.provider || 'auto') : undefined,
         },
     };
-    const reportPath = writeReport(config.testsRoot, report, healResult);
+    const reportPath = writeReport(config.testsRoot, report, healResult, timings);
     return { report, reportPath, warnings: allWarnings, generated: generatedSpecs, healResult };
 }
-function writeReport(testsRoot, report, healResult) {
+function writeReport(testsRoot, report, healResult, timings) {
     const outputDir = (0, path_1.join)(testsRoot, '.e2e-ai-agents');
     if (!(0, fs_1.existsSync)(outputDir)) {
         (0, fs_1.mkdirSync)(outputDir, { recursive: true });
     }
+    // Include timings in the JSON report if available
+    const reportWithTimings = timings ? { ...report, timings } : report;
     const jsonPath = (0, path_1.join)(outputDir, 'pipeline-report.json');
-    (0, fs_1.writeFileSync)(jsonPath, JSON.stringify(report, null, 2), 'utf-8');
+    (0, fs_1.writeFileSync)(jsonPath, JSON.stringify(reportWithTimings, null, 2), 'utf-8');
     const mdPath = (0, path_1.join)(outputDir, 'pipeline-report.md');
     (0, fs_1.writeFileSync)(mdPath, renderMarkdown(report, healResult), 'utf-8');
     return jsonPath;

package/dist/training/enricher.d.ts

@@ -8,8 +8,10 @@ export interface EnrichedEntry {
     routes?: string[];
     pageObjects?: string[];
     components?: string[];
+    webappPaths?: string[];
+    serverPaths?: string[];
 }
 export declare function validateEntries(parsed: unknown[]): EnrichedEntry[];
 export declare function parseEnrichResponse(response: string): EnrichedEntry[];
-export declare function enrichFamilies(families: RouteFamily[], scanned: ScannedFamily[], projectRoot: string, provider: LLMProvider, budgetUSD: number): Promise<EnrichmentResult>;
+export declare function enrichFamilies(families: RouteFamily[], scanned: ScannedFamily[], projectRoot: string, provider: LLMProvider, budgetUSD: number, testsRoot?: string): Promise<EnrichmentResult>;
 //# sourceMappingURL=enricher.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"enricher.d.ts","sourceRoot":"","sources":["../../src/training/enricher.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gCAAgC,CAAC;AAGhE,OAAO,KAAK,EAAC,gBAAgB,EAAE,aAAa,EAAC,MAAM,YAAY,CAAC;AAmIhE,MAAM,WAAW,aAAa;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,aAAa,EAAE,CAiBlE;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,EAAE,CAwBrE;AA2BD,wBAAsB,cAAc,CAChC,QAAQ,EAAE,WAAW,EAAE,EACvB,OAAO,EAAE,aAAa,EAAE,EACxB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,WAAW,EACrB,SAAS,EAAE,MAAM,GAClB,OAAO,CAAC,gBAAgB,CAAC,CAgF3B"}
+{"version":3,"file":"enricher.d.ts","sourceRoot":"","sources":["../../src/training/enricher.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gCAAgC,CAAC;AAGhE,OAAO,KAAK,EAAC,gBAAgB,EAAE,aAAa,EAAC,MAAM,YAAY,CAAC;AAkLhE,MAAM,WAAW,aAAa;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,aAAa,EAAE,CAmBlE;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,EAAE,CAwBrE;AAkCD,wBAAsB,cAAc,CAChC,QAAQ,EAAE,WAAW,EAAE,EACvB,OAAO,EAAE,aAAa,EAAE,EACxB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,WAAW,EACrB,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,gBAAgB,CAAC,CAuF3B"}

package/dist/training/enricher.js

@@ -64,9 +64,47 @@ function sampleFiles(dir, maxFiles) {
     walk(dir);
     return files;
 }
-function buildEnrichPrompt(families, projectRoot) {
+/**
+ * Build a shallow directory listing of the source tree (depth 2-3) so the LLM
+ * can suggest accurate webappPaths / serverPaths for test-derived families.
+ */
+function getSourceTreeListing(projectRoot, maxDepth = 3) {
+    const lines = [];
+    function walk(dir, depth, prefix) {
+        if (depth > maxDepth || lines.length > 200)
+            return;
+        let entries;
+        try {
+            entries = (0, fs_1.readdirSync)(dir).sort();
+        }
+        catch {
+            return;
+        }
+        const dirs = entries.filter((e) => {
+            if (e.startsWith('.') || SKIP_DIRS.has(e))
+                return false;
+            try {
+                const stat = (0, fs_1.lstatSync)((0, path_1.join)(dir, e));
+                return !stat.isSymbolicLink() && stat.isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+        for (const d of dirs) {
+            lines.push(`${prefix}${d}/`);
+            walk((0, path_1.join)(dir, d), depth + 1, prefix + '  ');
+        }
+    }
+    walk((0, path_1.resolve)(projectRoot), 0, '');
+    return lines.join('\n');
+}
+function buildEnrichPrompt(families, projectRoot, testsRoot) {
     const sections = [];
+    const hasTestOnlyFamilies = families.some((f) => f.webappPaths.length === 0 && f.serverPaths.length === 0);
+    const resolvedTestsRoot = testsRoot ? (0, path_1.resolve)(testsRoot) : (0, path_1.resolve)(projectRoot);
     for (const family of families) {
+        const isTestOnly = family.webappPaths.length === 0 && family.serverPaths.length === 0;
         const allDirs = [
             ...family.webappPaths.map((p) => p.replace(/\/?\*.*$/, '')),
             ...family.serverPaths.map((p) => p.replace(/\/?\*.*$/, '')),
@@ -80,10 +118,19 @@ function buildEnrichPrompt(families, projectRoot) {
             if (samples.length >= MAX_FILES_PER_FAMILY)
                 break;
         }
+        // For test-only families, sample the test files themselves for richer context
+        if (isTestOnly) {
+            for (const specDir of family.specDirs) {
+                if (samples.length >= MAX_FILES_PER_FAMILY)
+                    break;
+                const fullDir = (0, path_1.join)(resolvedTestsRoot, specDir);
+                samples.push(...sampleFiles(fullDir, MAX_FILES_PER_FAMILY - samples.length));
+            }
+        }
         // Sample spec descriptions
         const specSamples = [];
         for (const specDir of family.specDirs) {
-            const fullDir = (0, path_1.join)((0, path_1.resolve)(projectRoot), specDir);
+            const fullDir = (0, path_1.join)(resolvedTestsRoot, specDir);
             const specFiles = sampleFiles(fullDir, 5);
             for (const sf of specFiles) {
                 const matches = sf.content.match(/(?:test|it|describe)\s*\(\s*['"`]([^'"`]+)/g);
@@ -92,7 +139,7 @@ function buildEnrichPrompt(families, projectRoot) {
                 }
             }
         }
-        sections.push(`## Family: ${family.id}
+        sections.push(`## Family: ${family.id}${isTestOnly ? ' [TEST-ONLY — needs webappPaths/serverPaths]' : ''}
 Routes (guessed): ${JSON.stringify(family.routes)}
 Webapp paths: ${JSON.stringify(family.webappPaths)}
 Server paths: ${JSON.stringify(family.serverPaths)}
@@ -107,6 +154,10 @@ Test descriptions:
 ${specSamples.length > 0 ? specSamples.map((d) => `- ${d}`).join('\n') : '(none found)'}
 `);
     }
+    // Include source tree listing when we have test-only families
+    const sourceTreeSection = hasTestOnlyFamilies
+        ? `\n## Source Directory Structure\nUse this to suggest accurate webappPaths and serverPaths for test-only families:\n\`\`\`\n${getSourceTreeListing(projectRoot)}\n\`\`\`\n`
+        : '';
     return `You are analyzing a codebase to enrich route-family definitions for an E2E test impact analysis tool.
 
 For each family below, provide:
@@ -115,6 +166,8 @@ For each family below, provide:
 3. **routes**: Improved URL patterns (e.g., "/{team}/channels/{channel}" instead of "/channels")
 4. **pageObjects**: Array of page object class names found in the code
 5. **components**: Array of UI component names relevant to this family
+6. **webappPaths**: Array of glob patterns for frontend source directories (e.g., "src/components/drafts/**"). REQUIRED for families marked [TEST-ONLY].
+7. **serverPaths**: Array of glob patterns for backend source directories. REQUIRED for families marked [TEST-ONLY].
 
 Respond in JSON format:
 \`\`\`json
@@ -125,11 +178,13 @@ Respond in JSON format:
     "userFlows": ["Flow name 1", "Flow name 2"],
     "routes": ["/improved/route/{param}"],
     "pageObjects": ["PageName"],
-    "components": ["ComponentName"]
+    "components": ["ComponentName"],
+    "webappPaths": ["src/components/feature_name/**"],
+    "serverPaths": ["server/channels/api4/feature.go"]
   }
 ]
 \`\`\`
-
+${sourceTreeSection}
 ${sections.join('\n---\n')}`;
 }
 function validateEntries(parsed) {
@@ -148,6 +203,8 @@ function validateEntries(parsed) {
         userFlows: filterStrings(entry.userFlows, 500),
         pageObjects: filterStrings(entry.pageObjects, 200),
         components: filterStrings(entry.components, 200),
+        webappPaths: filterStrings(entry.webappPaths, 300),
+        serverPaths: filterStrings(entry.serverPaths, 300),
     }));
 }
 function parseEnrichResponse(response) {
@@ -197,13 +254,22 @@ function applyEnrichment(family, enriched) {
     if (enriched.components && (!family.components || family.components.length === 0)) {
         result.components = enriched.components;
     }
+    // Only fill source paths when the family has none (test-derived families)
+    if (enriched.webappPaths && (!family.webappPaths || family.webappPaths.length === 0)) {
+        result.webappPaths = enriched.webappPaths;
+    }
+    if (enriched.serverPaths && (!family.serverPaths || family.serverPaths.length === 0)) {
+        result.serverPaths = enriched.serverPaths;
+    }
     return result;
 }
-async function enrichFamilies(families, scanned, projectRoot, provider, budgetUSD) {
+async function enrichFamilies(families, scanned, projectRoot, provider, budgetUSD, testsRoot) {
     const scannedMap = new Map(scanned.map((s) => [s.id, s]));
     const enriched = [];
     let totalTokens = 0;
     let totalCost = 0;
+    let requestCount = 0;
+    let totalResponseMs = 0;
     const skipped = [];
     // Process in chunks of 4 families
     const chunkSize = 4;
@@ -223,7 +289,7 @@ async function enrichFamilies(families, scanned, projectRoot, provider, budgetUS
             enriched.push(...chunk);
             continue;
         }
-        let prompt = buildEnrichPrompt(scannedChunk, projectRoot);
+        let prompt = buildEnrichPrompt(scannedChunk, projectRoot, testsRoot);
         if (prompt.length > MAX_PROMPT_CHARS) {
             // Truncate at the last complete section boundary to avoid malformed input
             const lastSectionEnd = prompt.lastIndexOf('\n---\n', MAX_PROMPT_CHARS);
@@ -236,15 +302,18 @@ async function enrichFamilies(families, scanned, projectRoot, provider, budgetUS
                 prompt = prompt.slice(0, MAX_PROMPT_CHARS);
             }
         }
-        let timer;
+        let timeoutTimer;
         try {
             const timeoutPromise = new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new Error('LLM request timed out')), LLM_TIMEOUT_MS);
+                timeoutTimer = setTimeout(() => reject(new Error('LLM request timed out')), LLM_TIMEOUT_MS);
             });
+            const reqStart = performance.now();
             const response = await Promise.race([
                 provider.generateText(prompt, { maxTokens: 4096, temperature: 0.3 }),
                 timeoutPromise,
             ]);
+            totalResponseMs += performance.now() - reqStart;
+            requestCount++;
             totalTokens += (response.usage?.inputTokens ?? 0) + (response.usage?.outputTokens ?? 0);
             totalCost += response.cost ?? 0;
             const entries = parseEnrichResponse(response.text);
@@ -265,8 +334,8 @@ async function enrichFamilies(families, scanned, projectRoot, provider, budgetUS
             enriched.push(...chunk);
         }
         finally {
-            if (timer)
-                clearTimeout(timer);
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
         }
     }
     return {
@@ -274,5 +343,7 @@ async function enrichFamilies(families, scanned, projectRoot, provider, budgetUS
         tokensUsed: totalTokens,
         costUSD: Math.round(totalCost * 100) / 100,
         skippedFamilies: skipped,
+        requestCount,
+        avgResponseMs: requestCount > 0 ? Math.round(totalResponseMs / requestCount) : 0,
     };
 }

package/dist/training/merger.d.ts

@@ -1,5 +1,15 @@
 import type { RouteFamilyManifest } from '../knowledge/route_families.js';
 import type { MergeResult, ScannedFamily } from './types.js';
 export declare function mergeFamilies(existing: RouteFamilyManifest | null, scanned: ScannedFamily[]): MergeResult;
-export declare function detectStaleFamilies(manifest: RouteFamilyManifest, projectRoot: string): string[];
+/**
+ * Detect families whose paths no longer exist on disk.
+ *
+ * Paths in the manifest may be relative to different roots:
+ * - webappPaths / serverPaths are typically relative to the repo root
+ * - specDirs may be relative to the tests root
+ *
+ * We try each pattern against all provided roots (and the git repo root
+ * if discoverable) to avoid false positives from path-prefix mismatches.
+ */
+export declare function detectStaleFamilies(manifest: RouteFamilyManifest, projectRoot: string, testsRoot?: string): string[];
 //# sourceMappingURL=merger.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"merger.d.ts","sourceRoot":"","sources":["../../src/training/merger.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAc,mBAAmB,EAAC,MAAM,gCAAgC,CAAC;AAGrF,OAAO,KAAK,EAAC,WAAW,EAAE,aAAa,EAAC,MAAM,YAAY,CAAC;AAqE3D,wBAAgB,aAAa,CACzB,QAAQ,EAAE,mBAAmB,GAAG,IAAI,EACpC,OAAO,EAAE,aAAa,EAAE,GACzB,WAAW,CAyCb;AAED,wBAAgB,mBAAmB,CAC/B,QAAQ,EAAE,mBAAmB,EAC7B,WAAW,EAAE,MAAM,GACpB,MAAM,EAAE,CA8BV"}
+{"version":3,"file":"merger.d.ts","sourceRoot":"","sources":["../../src/training/merger.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAc,mBAAmB,EAAC,MAAM,gCAAgC,CAAC;AAGrF,OAAO,KAAK,EAAC,WAAW,EAAE,aAAa,EAAC,MAAM,YAAY,CAAC;AAkF3D,wBAAgB,aAAa,CACzB,QAAQ,EAAE,mBAAmB,GAAG,IAAI,EACpC,OAAO,EAAE,aAAa,EAAE,GACzB,WAAW,CA+Cb;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAC/B,QAAQ,EAAE,mBAAmB,EAC7B,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACnB,MAAM,EAAE,CA6DV"}

package/dist/training/merger.js

@@ -4,6 +4,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mergeFamilies = mergeFamilies;
 exports.detectStaleFamilies = detectStaleFamilies;
+const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const types_js_1 = require("./types.js");
@@ -71,6 +72,21 @@ function scannedToRouteFamily(scanned) {
     }
     return family;
 }
+/**
+ * Try to find a matching family ID with singular/plural normalization.
+ * "team" matches "teams", "emoji" matches "emoji", etc.
+ */
+function findFuzzyMatch(id, idMap) {
+    if (idMap.has(id))
+        return id;
+    // Try adding 's'
+    if (!id.endsWith('s') && idMap.has(id + 's'))
+        return id + 's';
+    // Try removing 's'
+    if (id.endsWith('s') && idMap.has(id.slice(0, -1)))
+        return id.slice(0, -1);
+    return undefined;
+}
 function mergeFamilies(existing, scanned) {
     const existingFamilies = existing?.families || [];
     const existingMap = new Map(existingFamilies.map((f) => [f.id, f]));
@@ -78,9 +94,15 @@ function mergeFamilies(existing, scanned) {
     const newFamilies = [];
     const updatedFamilies = [];
     const mergedFamilies = [];
-    // Process existing families
+    // Process existing families — match scanned by exact or fuzzy ID
     for (const ef of existingFamilies) {
-        const sf = scannedMap.get(ef.id);
+        let sf = scannedMap.get(ef.id);
+        // Try singular/plural match if exact match failed
+        if (!sf) {
+            const fuzzyId = findFuzzyMatch(ef.id, scannedMap);
+            if (fuzzyId)
+                sf = scannedMap.get(fuzzyId);
+        }
         if (sf) {
             mergedFamilies.push(mergeFamily(ef, sf));
             updatedFamilies.push(ef.id);
@@ -90,9 +112,10 @@ function mergeFamilies(existing, scanned) {
             mergedFamilies.push({ ...ef });
         }
     }
-    // Add new families from scanner
+    // Add new families from scanner (if no existing family matched)
     for (const sf of scanned) {
-        if (!existingMap.has(sf.id)) {
+        const matchedExisting = findFuzzyMatch(sf.id, existingMap);
+        if (!matchedExisting) {
             mergedFamilies.push(scannedToRouteFamily(sf));
             newFamilies.push(sf.id);
         }
@@ -112,8 +135,33 @@ function mergeFamilies(existing, scanned) {
         summary: parts.join(', '),
     };
 }
-function detectStaleFamilies(manifest, projectRoot) {
-    const resolved = (0, path_1.resolve)(projectRoot);
+/**
+ * Detect families whose paths no longer exist on disk.
+ *
+ * Paths in the manifest may be relative to different roots:
+ * - webappPaths / serverPaths are typically relative to the repo root
+ * - specDirs may be relative to the tests root
+ *
+ * We try each pattern against all provided roots (and the git repo root
+ * if discoverable) to avoid false positives from path-prefix mismatches.
+ */
+function detectStaleFamilies(manifest, projectRoot, testsRoot) {
+    const roots = new Set([(0, path_1.resolve)(projectRoot)]);
+    if (testsRoot)
+        roots.add((0, path_1.resolve)(testsRoot));
+    // Also try to discover the git repo root — manifest paths may be repo-relative
+    try {
+        const gitRoot = (0, child_process_1.execFileSync)('git', ['rev-parse', '--show-toplevel'], {
+            cwd: projectRoot,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (gitRoot)
+            roots.add((0, path_1.resolve)(gitRoot));
+    }
+    catch {
+        // Not a git repo or git not available — that's fine
+    }
     const stale = [];
     for (const family of manifest.families) {
         const allPatterns = [
@@ -123,15 +171,34 @@ function detectStaleFamilies(manifest, projectRoot) {
         ];
         if (allPatterns.length === 0)
             continue;
-        // Check if any pattern resolves to existing files/dirs
+        // Check if any pattern resolves to existing files/dirs in any root
         let hasAny = false;
         for (const pattern of allPatterns) {
             // Strip trailing glob (* or **) to get the directory
             const dirPart = pattern.replace(/\/?\*.*$/, '');
-            if (dirPart && (0, fs_1.existsSync)((0, path_1.join)(resolved, dirPart))) {
-                hasAny = true;
-                break;
+            if (!dirPart)
+                continue;
+            // For file-level patterns like "server/channels/api4/draft*.go",
+            // dirPart is "server/channels/api4/draft" — check the parent dir instead
+            const isFileGlob = /\.\w+$/.test(pattern);
+            const pathsToCheck = [dirPart];
+            if (isFileGlob) {
+                const parentDir = dirPart.split('/').slice(0, -1).join('/');
+                if (parentDir)
+                    pathsToCheck.push(parentDir);
+            }
+            for (const checkPath of pathsToCheck) {
+                for (const root of roots) {
+                    if ((0, fs_1.existsSync)((0, path_1.join)(root, checkPath))) {
+                        hasAny = true;
+                        break;
+                    }
+                }
+                if (hasAny)
+                    break;
             }
+            if (hasAny)
+                break;
         }
         if (!hasAny) {
             stale.push(family.id);

package/dist/training/scanner.d.ts

@@ -1,5 +1,31 @@
-import type { DiscoveredDir, ScanResult } from './types.js';
+import type { DiscoveredDir, ScannedFamily, ScanResult } from './types.js';
 export declare function discoverSourceDirs(projectRoot: string): DiscoveredDir[];
 export declare function discoverTestDirs(projectRoot: string): DiscoveredDir[];
-export declare function scanProject(projectRoot: string): ScanResult;
+/**
+ * Discover families by scanning server Go source files.
+ *
+ * The backend follows a three-tier pattern:
+ *   api4/draft.go + app/draft.go + store/sqlstore/draft_store.go
+ *
+ * Related files are grouped under parent domains:
+ *   channel.go, channel_bookmark.go, channel_category.go → "channel" family
+ *
+ * Each domain becomes a candidate family with precise serverPaths.
+ */
+export declare function discoverServerDerivedFamilies(serverRoot: string): {
+    multiTierFamilies: ScannedFamily[];
+    singleTierFamilies: ScannedFamily[];
+};
+export declare function discoverTestDerivedFamilies(testsRoot: string): ScannedFamily[];
+/**
+ * Discover test library paths (page objects, helpers) organized by feature.
+ * Walks well-known test lib directories and maps subdirectories to family IDs.
+ */
+export declare function discoverTestLibPaths(testsRoot: string): Map<string, string[]>;
+/**
+ * Discover files in well-known directories (types, utils) whose basename
+ * 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;
 //# 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,EAAiC,UAAU,EAAC,MAAM,YAAY,CAAC;AAgGzF,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,EAAE,CA+BvE;AAED,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,EAAE,CA6DrE;AA6ID,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,CA+E3D"}
+{"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,CAmC7E;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACpC,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,GACrB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAmDvB;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"}