@matware/e2e-runner 1.3.1 → 1.5.1

package/src/mcp-tools.js

@@ -23,11 +23,12 @@ import { lookupScreenshotHash, ensureProject, computeScreenshotHash, registerScr
 import { fetchIssue, checkCliAuth, detectProvider } from './issues.js';
 import { buildPrompt, hasApiKey, generateHindsightHint } from './ai-generate.js';
 import { verifyIssue } from './verify.js';
-import { listModules } from './module-resolver.js';
+import { listModules, loadModuleRegistry } from './module-resolver.js';
 import { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends, getRunInsights, getTestHistory, getPageHistory, getSelectorHistory, getHealthSnapshot, getTestCreationContext, generateImprovements, getActionHealthScores } from './learner-sqlite.js';
 import { queryGraph } from './learner-neo4j.js';
 import { startNeo4j, stopNeo4j, getNeo4jStatus } from './neo4j-pool.js';
 import { getAppPoolStatus, isAppPoolEnabled } from './app-pool.js';
+import { looksLikeBlankCapture } from './actions.js';
 
 /**
  * Resolves auth token from config: uses static authToken if set,
@@ -103,7 +104,7 @@ export const TOOLS = [
         },
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
     },
@@ -117,7 +118,7 @@ export const TOOLS = [
       properties: {
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
     },
@@ -125,60 +126,19 @@ export const TOOLS = [
   {
     name: 'e2e_create_test',
     description:
-      `Create a new E2E test JSON file. IMPORTANT: prefer built-in actions over evaluate blocks.
-
-## Action selection guide (use instead of evaluate)
-
-**Clicking elements by text** — DON'T write evaluate to find+click elements:
-  click:           { type: "click", text: "Submit" }              — searches button, a, [role=tab], span, etc.
-  click_regex:     { type: "click_regex", text: "save|guardar" }  — regex match, case-insensitive
-  click_menu_item: { type: "click_menu_item", text: "Delete" }    — [role=menuitem], .MenuItem, etc.
-  click_option:    { type: "click_option", text: "Option A" }     — [role=option] in dropdowns
-  click_chip:      { type: "click_chip", text: "Active" }         — MUI Chip / tag elements
-  click_icon:      { type: "click_icon", value: "edit" }          — SVG/icon by data-testid, aria-label, class
-  click_in_context:{ type: "click_in_context", text: "Row text", selector: "button" } — child within container
-
-**Asserting text presence/absence** — DON'T write evaluate with body.includes():
-  assert_text:     { type: "assert_text", text: "Welcome" }      — text IS on page (case-sensitive). Uses: text
-  assert_no_text:  { type: "assert_no_text", text: "Error" }     — text is NOT on page. Uses: text
-  assert_text_in:  { type: "assert_text_in", selector: "[class*='Drawer']", text: "profesional|doctor" }
-                   — scoped regex in container (case-insensitive default). Uses: selector + text (+ value:"exact")
-
-**Asserting elements** — DON'T write evaluate to count or check visibility:
-  assert_visible:      { type: "assert_visible", selector: ".modal" }           — Uses: selector (NOT text)
-  assert_not_visible:  { type: "assert_not_visible", selector: ".loader" }      — Uses: selector (NOT text)
-  assert_count:        { type: "assert_count", selector: "input", value: ">= 2" } — Uses: selector + value
-  assert_element_text: { type: "assert_element_text", selector: "h1", text: "Dashboard" } — Uses: selector + text
-  assert_matches:      { type: "assert_matches", selector: ".date", value: "\\\\d{2}/\\\\d{2}" } — Uses: selector + value (regex)
-  assert_attribute:    { type: "assert_attribute", selector: "button", value: "disabled" } — Uses: selector + value
-  assert_url:          { type: "assert_url", value: "/dashboard" }              — Uses: value
-  assert_input_value:  { type: "assert_input_value", selector: "#email", value: "@" } — Uses: selector + value
-
-IMPORTANT field rules:
-  - assert_text / assert_no_text: use "text" field only (checks full page body)
-  - assert_visible / assert_not_visible: use "selector" field only (CSS selector, NOT text)
-  - To verify text absence: use assert_no_text (NOT assert_not_visible with text)
-
-**Navigation & waiting** — DON'T write evaluate with setTimeout polling:
-  goto:            { type: "goto", value: "/login" }              — full page navigation
-  navigate:        { type: "navigate", value: "/settings" }       — SPA-friendly (won't fail if no page load)
-  wait:            { type: "wait", text: "Loading complete" }     — wait for text to appear in body
-  wait:            { type: "wait", selector: ".results" }         — wait for element to appear
-  wait:            { type: "wait", value: "2000" }                — fixed delay (avoid when possible)
-  wait_network_idle: { type: "wait_network_idle", value: "500" }  — wait until no network for N ms
-
-**Form interaction** — DON'T write evaluate with native value setters (unless React):
-  type:            { type: "type", selector: "#email", value: "a@b.com" } — clears + types
-  type_react:      { type: "type_react", selector: "#email", value: "a@b.com" } — for React controlled inputs
-  select:          { type: "select", selector: "select#country", value: "US" }
-  clear:           { type: "clear", selector: "#search" }
-  press:           { type: "press", value: "Enter" }
-  focus_autocomplete: { type: "focus_autocomplete", text: "City" } — focus MUI Autocomplete by label
-
-**When evaluate IS appropriate**: computed styles, complex conditional logic, GraphQL via window.__e2eGql, math calculations, reading window/app state.
-
-## Modules
-Use { "$use": "module-name", "params": {...} } to reference reusable modules from e2e/modules/. Modules compose — a module can $use other modules. Check e2e_list to see available modules for the project.`,
+      `Create a new E2E test JSON file. Prefer built-in actions over evaluate — more robust and readable. Full catalog: the e2e-testing skill / references/action-types.md.
+
+Action cheat-sheet:
+- Click: click (by text), click_regex, click_menu_item, click_option, click_chip, click_icon, click_in_context; in a dialog use click with scope:"dialog" (+ last/visible).
+- Select (MUI): select_combobox (open+optional filter+pick), select, focus_autocomplete.
+- Assert text: assert_text (present), assert_no_text (absent), assert_text_in (scoped regex), assert_element_text, assert_matches.
+- Assert elements (selector, NOT text): assert_visible, assert_not_visible, assert_count, assert_attribute, assert_input_value, assert_url.
+- Nav/wait: goto, navigate (SPA), wait {text|selector|gone|value(ms)}, wait_network_idle.
+- Form: type, type_react (React inputs; optional blur/waitAfter), clear, press.
+
+Field rules: assert_text/assert_no_text use "text" (whole page); assert_visible/assert_not_visible use "selector"; for text absence use assert_no_text. Use evaluate only for computed styles, complex logic, GraphQL (window.__e2eGql), or app state.
+
+Modules: { "$use": "module-name", "params": {...} } references reusable modules in e2e/modules/ (they compose). Run e2e_list to see available modules.`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -233,7 +193,7 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
         },
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
       required: ['name', 'tests'],
@@ -248,7 +208,7 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
       properties: {
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
     },
@@ -295,7 +255,7 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
         },
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
     },
@@ -321,7 +281,7 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
         },
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
     },
@@ -358,7 +318,7 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
         },
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
       required: ['url'],
@@ -406,7 +366,7 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
         },
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
       required: ['url'],
@@ -458,7 +418,7 @@ Use { "$use": "module-name", "params": {...} } to reference reusable modules fro
         },
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
       required: ['url'],
@@ -533,7 +493,7 @@ Good module candidates: auth setup, page navigation, tab clicking, opening sideb
         },
         cwd: {
           type: 'string',
-          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+          description: 'Project root directory (defaults to the current working directory).',
         },
       },
       required: ['query'],
@@ -1004,6 +964,65 @@ async function handleCreateTest(args) {
     }
   } catch { /* modules dir may not exist */ }
 
+  // ── #2/#3: nudge module reuse and flag extractable duplication ──
+  try {
+    const fullModules = [...loadModuleRegistry(config.modulesDir).values()];
+
+    // #2 — submitted actions already match an existing module verbatim
+    const matches = detectModuleMatches(args.tests, fullModules);
+    for (const h of matches) {
+      const req = h.params ? Object.entries(h.params).filter(([, d]) => d?.required).map(([n]) => n) : [];
+      const paramHint = req.length ? `, "params": { ${req.map(n => `"${n}": ...`).join(', ')} }` : '';
+      warnings.push(`♻️ Test "${h.test}" repeats the ${h.len} actions of existing module "${h.module}" inline. ` +
+        `Replace them with { "$use": "${h.module}"${paramHint} }.`);
+    }
+
+    // #3 — action sequences duplicated across tests that aren't a module yet
+    const matchedTests = new Set(matches.map(m => m.test));
+    const testsActions = args.tests
+      .filter(t => t.actions && !t.actions.some(a => a && a.$use) && !matchedTests.has(t.name))
+      .map(t => ({ name: t.name, sigs: actionsSigList(t.actions) }));
+
+    // include existing test files (excluding the one just written) for cross-file duplication
+    try {
+      if (fs.existsSync(config.testsDir)) {
+        for (const f of fs.readdirSync(config.testsDir).filter(x => x.endsWith('.json'))) {
+          const fp = path.join(config.testsDir, f);
+          if (fp === filePath) continue;
+          let parsed;
+          try { parsed = JSON.parse(fs.readFileSync(fp, 'utf-8')); } catch { continue; }
+          const list = Array.isArray(parsed) ? parsed : (parsed.tests || []);
+          for (const t of list) {
+            if (t && t.actions && !t.actions.some(a => a && a.$use)) {
+              testsActions.push({ name: `${f}:${t.name}`, sigs: actionsSigList(t.actions) });
+            }
+          }
+        }
+      }
+    } catch { /* ignore unreadable test files */ }
+
+    // windows already covered by an existing module → don't re-suggest extracting them
+    const moduleWindowSet = new Set();
+    for (const m of fullModules) {
+      const sigs = actionsSigList((m.actions || []).filter(a => a && !a.$use));
+      for (const w of sigWindows(sigs, 2, 6)) moduleWindowSet.add(w);
+    }
+
+    const extractable = detectExtractableSequences(testsActions, moduleWindowSet);
+    for (const e of extractable) {
+      const sample = e.tests.slice(0, 3).join(', ') + (e.tests.length > 3 ? '…' : '');
+      warnings.push(`🧩 A sequence of ${e.len} actions appears in ${e.count} tests (${sample}) but isn't a module yet. ` +
+        `Consider extracting it with e2e_create_module and referencing it via $use.`);
+    }
+  } catch { /* never fail test creation */ }
+
+  // ── Verification coverage: tests whose outcome is never checked ──
+  try {
+    let registry;
+    try { registry = loadModuleRegistry(config.modulesDir); } catch { registry = new Map(); }
+    warnings.push(...detectUnverifiedTests(args.tests, registry));
+  } catch { /* never fail test creation */ }
+
   const warningBlock = warnings.length > 0 ? '\n\n' + warnings.join('\n\n') : '';
 
   // Enrich with learnings context for smarter test authoring
@@ -1259,6 +1278,135 @@ function analyzeActionPatterns(tests) {
   return warnings;
 }
 
+// ── Module-reuse detection (#2 exact match, #3 extractable duplication) ──
+
+// Normalized signature of an action for sequence comparison.
+function actionSig(a) {
+  if (!a || typeof a !== 'object') return '∅';
+  if (a.$use) return `$use:${a.$use}`;
+  return `${a.type || '?'}|${a.selector || ''}|${a.text || ''}`;
+}
+function actionsSigList(actions) {
+  return (actions || []).map(actionSig);
+}
+// All contiguous sig windows of length minLen..maxLen, each joined with '»'.
+function sigWindows(sigs, minLen, maxLen) {
+  const out = [];
+  const top = Math.min(maxLen, sigs.length);
+  for (let len = minLen; len <= top; len++) {
+    for (let i = 0; i + len <= sigs.length; i++) {
+      out.push(sigs.slice(i, i + len).join('»'));
+    }
+  }
+  return out;
+}
+
+// #2 — a module field matches a concrete test field; {{param}} placeholders are wildcards.
+function moduleFieldMatch(modVal, testVal) {
+  if (modVal == null || modVal === '') return true;            // module doesn't constrain it
+  if (typeof modVal === 'string' && modVal.includes('{{')) return true; // placeholder → wildcard
+  return modVal === testVal;
+}
+function moduleActionMatch(modA, testA) {
+  if (!modA || !testA || modA.$use || testA.$use) return false;
+  return modA.type === testA.type
+    && moduleFieldMatch(modA.selector, testA.selector)
+    && moduleFieldMatch(modA.text, testA.text);
+}
+// Find modules whose full leaf-action sequence appears as a contiguous run inside a test
+// that doesn't already use modules. Returns [{ module, params, test, len }].
+function detectModuleMatches(tests, fullModules) {
+  const hits = [];
+  for (const mod of fullModules) {
+    const ma = (mod.actions || []).filter(a => a && !a.$use);
+    if (ma.length < 2) continue;
+    for (const test of tests) {
+      const ta = test.actions || [];
+      if (ta.some(a => a && a.$use)) continue; // already modular
+      for (let i = 0; i + ma.length <= ta.length; i++) {
+        let ok = true;
+        for (let j = 0; j < ma.length; j++) {
+          if (!moduleActionMatch(ma[j], ta[i + j])) { ok = false; break; }
+        }
+        if (ok) { hits.push({ module: mod.$module, params: mod.params, test: test.name, len: ma.length }); break; }
+      }
+    }
+  }
+  return hits;
+}
+// #3 — contiguous sig windows (len>=minLen) shared by >=2 distinct tests and not already a module.
+function detectExtractableSequences(testsActions, moduleWindowSet, { minLen = 3, maxLen = 6, cap = 2 } = {}) {
+  const owners = new Map(); // windowKey -> Set(testName)
+  const lenOf = new Map();  // windowKey -> action count
+  for (const t of testsActions) {
+    const seen = new Set();
+    for (const key of sigWindows(t.sigs, minLen, maxLen)) {
+      if (key.includes('$use:') || moduleWindowSet.has(key) || seen.has(key)) continue;
+      seen.add(key);
+      if (!owners.has(key)) { owners.set(key, new Set()); lenOf.set(key, key.split('»').length); }
+      owners.get(key).add(t.name);
+    }
+  }
+  const cands = [];
+  for (const [key, set] of owners) {
+    if (set.size >= 2) cands.push({ key, len: lenOf.get(key), count: set.size, tests: [...set] });
+  }
+  cands.sort((a, b) => b.len - a.len || b.count - a.count); // longest, then most frequent
+  const kept = [];
+  for (const c of cands) {
+    if (kept.some(k => k.key.includes(c.key))) continue; // subsumed by a longer kept window
+    kept.push(c);
+    if (kept.length >= cap) break;
+  }
+  return kept;
+}
+
+// Verification coverage — a test whose interactions are never followed by a check
+// can go green even when the flow silently breaks.
+function isVerifyingAction(a) {
+  if (/^assert_/.test(a.type || '')) return true;
+  if (a.type === 'evaluate' || a.type === 'gql') return true; // strict semantics / inline assertions
+  if (a.type === 'wait' && (a.selector || a.text || a.gone)) return true; // condition waits fail if unmet
+  return false;
+}
+function isInteractingAction(a) {
+  return /^(click|select|type|fill|clear|press|hover|scroll|set_storage|focus_autocomplete|goto|navigate)/.test(a.type || '');
+}
+function detectUnverifiedTests(tests, registry) {
+  const out = [];
+  for (const t of tests || []) {
+    if (!t || !Array.isArray(t.actions) || t.expect) continue; // "expect" verifies the end state visually
+    // expand $use so module-provided assertions count
+    const leaf = [];
+    let resolvable = true;
+    for (const a of t.actions) {
+      if (a && a.$use) {
+        const mod = registry.get(a.$use);
+        if (mod?.actions) leaf.push(...mod.actions.filter(x => x && !x.$use));
+        else { resolvable = false; break; }
+      } else if (a) leaf.push(a);
+    }
+    if (!resolvable) continue;
+    let lastInteract = -1;
+    leaf.forEach((a, i) => { if (isInteractingAction(a)) lastInteract = i; });
+    if (lastInteract === -1) continue; // nothing happens — nothing to verify
+    if (!leaf.some(isVerifyingAction)) {
+      out.push(`🔎 Test "${t.name}" has no assertions and no "expect" field — it can pass without verifying anything. ` +
+        `Close with assert_* actions (assert_url, assert_text, assert_visible) or add an "expect" for visual verification.`);
+    } else if (!leaf.slice(lastInteract + 1).some(isVerifyingAction)) {
+      out.push(`🔎 Test "${t.name}" keeps interacting after its last check — the final steps are unverified. ` +
+        `Close with an assert_* action so the end state is what passes the test.`);
+    } else {
+      const tail = leaf.slice(lastInteract + 1).filter(isVerifyingAction);
+      if (tail.length && tail.every(a => a.type === 'assert_text')) {
+        out.push(`📌 Test "${t.name}" closes with page-wide assert_text only — it matches anywhere on the page. ` +
+          `Scope the final check with assert_element_text or assert_text_in.`);
+      }
+    }
+  }
+  return out;
+}
+
 async function handlePoolStatus(args) {
   const config = await loadConfig({}, args.cwd);
   const poolUrls = getPoolUrls(config);
@@ -1955,7 +2103,19 @@ async function handleAnalyze(args) {
       screenshotBase64 = data.toString('base64');
     }
 
-    const result = { meta, ...structure, suggestedTests };
+    // Surface reusable modules at the decision point, so scaffolds can $use them
+    // instead of duplicating action sequences.
+    let availableModules = [];
+    try {
+      availableModules = listModules(config.modulesDir).map(m => ({
+        name: m.name,
+        params: m.params.map(p => (p.required ? p.name : `${p.name}?`)),
+        description: m.description || undefined,
+        hint: `{ "$use": "${m.name}"${m.params.some(p => p.required) ? ', "params": { ... }' : ''} }`,
+      }));
+    } catch { /* modules dir may not exist */ }
+
+    const result = { meta, ...structure, suggestedTests, availableModules };
     const content = [{ type: 'text', text: JSON.stringify(result, null, 2) }];
 
     if (screenshotBase64) {
@@ -2011,7 +2171,18 @@ async function handleCapture(args) {
     }
 
     const screenshotPath = path.join(config.screenshotsDir, filename);
-    await page.screenshot({ path: screenshotPath, fullPage: !!args.fullPage });
+    const data = await page.screenshot({ fullPage: !!args.fullPage });
+
+    // Blank frame (uniform color — page never rendered): don't save it,
+    // report what happened instead of returning a useless white PNG.
+    if (looksLikeBlankCapture(data, 'png')) {
+      return {
+        content: [
+          { type: 'text', text: `Capture skipped: ${args.url} rendered a blank (uniform-color) frame — nothing saved. The page likely failed to render (auth redirect, JS error, or slow load); try a longer delay or a selector to wait for.` },
+        ],
+      };
+    }
+    fs.writeFileSync(screenshotPath, data);
 
     // Register hash in SQLite
     const cwd = args.cwd || process.cwd();
@@ -2020,8 +2191,6 @@ async function handleCapture(args) {
     const hash = computeScreenshotHash(screenshotPath);
     registerScreenshotHash(hash, screenshotPath, projectId, null);
 
-    // Read image for response
-    const data = fs.readFileSync(screenshotPath);
     const base64 = data.toString('base64');
 
     return {

package/src/module-analysis.js

@@ -0,0 +1,247 @@
+/**
+ * Module Analysis — deterministic duplication detector.
+ *
+ * Scans every test JSON in testsDir, normalizes action sequences to
+ * signatures (literal values become placeholders, but selectors/text
+ * stay so two unrelated clicks don't collide), and reports sequences of
+ * length 3-8 that appear in 2+ different tests. These are the canonical
+ * candidates the test-improver agent would extract into a `$use` module.
+ *
+ * Also enumerates current modules and counts how often each is referenced
+ * via `$use` across the project so users can see adoption.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const MIN_SEQ_LEN = 3;
+const MAX_SEQ_LEN = 8;
+
+/** Stable signature for one action — literals → '*', identifiers kept. */
+function signatureOf(action) {
+  if (!action || typeof action !== 'object') return '?';
+  if (action.$use) return `$use:${action.$use}`;
+  const type = action.type || '?';
+  // Keep selector + text (semantic identifiers); replace `value` with `*`
+  // since values are usually parameterizable.
+  const parts = [type];
+  if (action.selector) parts.push(`@${action.selector}`);
+  if (action.text != null) parts.push(`"${String(action.text).slice(0, 40)}"`);
+  if (action.value != null) parts.push('*');
+  return parts.join('|');
+}
+
+function walkTests(testsDir) {
+  const out = [];
+  let files = [];
+  try {
+    files = fs.readdirSync(testsDir).filter(f => f.endsWith('.json')).sort();
+  } catch { return out; }
+  for (const file of files) {
+    const fp = path.join(testsDir, file);
+    let suite;
+    try { suite = JSON.parse(fs.readFileSync(fp, 'utf-8')); } catch { continue; }
+    const tests = Array.isArray(suite) ? suite : suite.tests || [];
+    for (const t of tests) {
+      if (!t || !Array.isArray(t.actions)) continue;
+      out.push({
+        file,
+        suite: file.replace(/\.json$/, ''),
+        test: t.name || '(unnamed)',
+        actions: t.actions,
+        signatures: t.actions.map(signatureOf),
+      });
+    }
+  }
+  return out;
+}
+
+function findCandidates(tests) {
+  // Map signature-sequence-string → [{testIdx, start}]
+  const seen = new Map();
+  for (let ti = 0; ti < tests.length; ti++) {
+    const sig = tests[ti].signatures;
+    for (let len = MIN_SEQ_LEN; len <= MAX_SEQ_LEN; len++) {
+      for (let i = 0; i + len <= sig.length; i++) {
+        const key = sig.slice(i, i + len).join(' >> ');
+        if (!seen.has(key)) seen.set(key, []);
+        seen.get(key).push({ testIdx: ti, start: i, len });
+      }
+    }
+  }
+
+  const candidates = [];
+  for (const [key, hits] of seen) {
+    // Distinct tests, not just same test repeated
+    const distinct = new Map();
+    for (const h of hits) {
+      const t = tests[h.testIdx];
+      const id = t.suite + '::' + t.test;
+      if (!distinct.has(id)) distinct.set(id, { test: t, hits: [] });
+      distinct.get(id).hits.push(h);
+    }
+    if (distinct.size < 2) continue;
+    candidates.push({
+      signature: key,
+      length: hits[0].len,
+      occurrenceCount: hits.length,
+      testCount: distinct.size,
+      // Best representative — first hit's actions, lifted from the test
+      sample: tests[hits[0].testIdx].actions.slice(hits[0].start, hits[0].start + hits[0].len),
+      usedBy: [...distinct.values()].map(d => ({
+        suite: d.test.suite,
+        test: d.test.test,
+        occurrences: d.hits.length,
+      })),
+    });
+  }
+
+  // Rank: maximize (savings ≈ length * (testCount - 1))
+  // Then prefer longer sequences over shorter ones.
+  candidates.sort((a, b) => {
+    const savingsA = a.length * (a.testCount - 1);
+    const savingsB = b.length * (b.testCount - 1);
+    if (savingsA !== savingsB) return savingsB - savingsA;
+    return b.length - a.length;
+  });
+
+  // Prune: drop sequences that are strict substrings of a higher-scored one
+  // covering the same set of tests (the shorter one is redundant once the
+  // longer one is extracted).
+  const kept = [];
+  for (const c of candidates) {
+    const covered = kept.find(k =>
+      k.signature.includes(c.signature) &&
+      JSON.stringify(k.usedBy.map(u => u.suite+'::'+u.test).sort()) ===
+      JSON.stringify(c.usedBy.map(u => u.suite+'::'+u.test).sort())
+    );
+    if (!covered) kept.push(c);
+  }
+
+  // Suggest a name from the dominant action types
+  for (const c of kept) {
+    c.suggestedName = suggestModuleName(c.sample);
+  }
+
+  return kept.slice(0, 30);
+}
+
+function suggestModuleName(actions) {
+  if (!actions || !actions.length) return 'module';
+  const types = actions.map(a => a?.type).filter(Boolean);
+  // Heuristics for common patterns
+  const hasGoto = types.includes('goto');
+  const hasType = types.includes('type') || types.includes('fill') || types.includes('type_react');
+  const hasClick = types.some(t => t && t.startsWith('click'));
+  const hasAssert = types.some(t => t && t.startsWith('assert'));
+  // Pull a noun-y hint from selector or text of first non-goto action
+  const hint = (function () {
+    for (const a of actions) {
+      const s = a?.text || a?.selector || a?.value;
+      if (typeof s === 'string' && s.length > 0 && s.length < 30) {
+        return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24);
+      }
+    }
+    return '';
+  })();
+  if (hasGoto && hasType && hasClick) return 'navigate-and-submit' + (hint ? '-' + hint : '');
+  if (hasType && hasClick) return 'fill-form' + (hint ? '-' + hint : '');
+  if (hasGoto && hasAssert) return 'open-and-verify' + (hint ? '-' + hint : '');
+  if (hasGoto) return 'navigate' + (hint ? '-' + hint : '');
+  if (hint) return hint;
+  return 'extracted-module';
+}
+
+function loadModules(modulesDir) {
+  if (!modulesDir || !fs.existsSync(modulesDir)) return [];
+  const files = fs.readdirSync(modulesDir).filter(f => f.endsWith('.json')).sort();
+  return files.map(f => {
+    const fp = path.join(modulesDir, f);
+    let data = {};
+    try { data = JSON.parse(fs.readFileSync(fp, 'utf-8')); } catch { /* */ }
+    return {
+      name: f.replace(/\.json$/, ''),
+      file: f,
+      description: data.description || null,
+      params: data.params || [],
+      actionCount: Array.isArray(data.actions) ? data.actions.length : 0,
+    };
+  });
+}
+
+function countModuleUsage(tests, modules) {
+  const usage = new Map(modules.map(m => [m.name, { count: 0, usedBy: new Set() }]));
+  function walk(actions, testInfo) {
+    if (!Array.isArray(actions)) return;
+    for (const a of actions) {
+      if (a && a.$use) {
+        const u = usage.get(a.$use);
+        if (u) { u.count++; u.usedBy.add(testInfo); }
+      }
+    }
+  }
+  for (const t of tests) {
+    walk(t.actions, t.suite + '::' + t.test);
+  }
+  return modules.map(m => {
+    const u = usage.get(m.name) || { count: 0, usedBy: new Set() };
+    return { ...m, usageCount: u.count, usedBy: [...u.usedBy] };
+  });
+}
+
+export function runModuleAnalysis(testsDir, modulesDir) {
+  const tests = walkTests(testsDir);
+  const modules = loadModules(modulesDir);
+  const candidates = findCandidates(tests);
+  const modulesWithUsage = countModuleUsage(tests, modules);
+
+  // Build a Claude Code prompt the user can copy verbatim.
+  const prompt = buildAgentPrompt(testsDir, modulesDir, candidates, modulesWithUsage);
+
+  return {
+    testsDir,
+    modulesDir,
+    summary: {
+      testCount: tests.length,
+      moduleCount: modulesWithUsage.length,
+      candidateCount: candidates.length,
+      unusedModules: modulesWithUsage.filter(m => m.usageCount === 0).length,
+    },
+    modules: modulesWithUsage,
+    candidates,
+    agentPrompt: prompt,
+  };
+}
+
+function buildAgentPrompt(testsDir, modulesDir, candidates, modules) {
+  const topCandidates = candidates.slice(0, 10);
+  return [
+    'Analyze E2E test modules and recommend changes.',
+    '',
+    `Tests directory: ${testsDir}`,
+    `Modules directory: ${modulesDir}`,
+    '',
+    'Use the test-improver capabilities to:',
+    '1. Review the candidate sequences below and decide which should be extracted into reusable modules via `e2e_create_module`.',
+    '2. For each extracted module, suggest the parameters needed (selectors/text that vary between usages).',
+    '3. Check the current modules list for any that are unused or could be consolidated.',
+    '4. After creating modules, Edit the affected test files to replace inline action sequences with `{ "$use": "<module-name>", "params": {...} }`.',
+    '',
+    `## Top ${topCandidates.length} extraction candidates`,
+    '',
+    ...topCandidates.map((c, i) =>
+      `${i + 1}. **${c.suggestedName}** (${c.length} actions, used in ${c.testCount} tests, ${c.occurrenceCount} total occurrences)\n` +
+      `   Signature: \`${c.signature}\`\n` +
+      `   Used by: ${c.usedBy.map(u => `${u.suite}::${u.test}`).join(', ')}`
+    ),
+    '',
+    '## Current modules',
+    '',
+    ...modules.map(m =>
+      `- **${m.name}** — ${m.actionCount} actions, ${m.params.length} params, used ${m.usageCount}x` +
+      (m.description ? `\n  > ${m.description}` : '')
+    ),
+    '',
+    'After making changes, run the affected tests to confirm nothing broke.',
+  ].join('\n');
+}