@skyramp/mcp 0.4.2-rc.1 → 0.4.2-rc.2

package/build/utils/testExecutionRecord.js

@@ -231,6 +231,7 @@ fileHash) {
  * per-file testExecutions record (every file, keyed by canonical path — see
  * executionRecordFrom), plus the maintained-test executionBefore/After row
  * when `testFile` has one. No-op when the repo section doesn't exist yet.
+ * Returns what was written, so the caller can say what was not.
  *
  * Extracted from skyramp_execute_test's own state-write block so the
  * behavior that makes a file's result available to the post-execution
@@ -245,7 +246,7 @@ export async function persistTestExecutionResult(stateFile, repo, testType, phas
         const stateManager = StateManager.fromStatePath(stateFile);
         const stateData = await stateManager.readRepoData(repo);
         if (!stateData)
-            return;
+            return { saved: false, matchedExistingTest: false };
         const testIndex = stateData.existingTests?.findIndex((t) => canonicalTestPath(t.testFile) === canonicalTestPath(testFile)) ?? -1;
         if (testIndex >= 0) {
             if (phase === "before") {
@@ -263,5 +264,6 @@ export async function persistTestExecutionResult(stateFile, repo, testType, phas
             !options.reserved),
         };
         await stateManager.updateRepoData(stateData, { repo });
+        return { saved: true, matchedExistingTest: testIndex >= 0 };
     });
 }

package/build/utils/testFileClassification.d.ts

@@ -14,6 +14,14 @@ export declare function isDiscoveredTestFile(filePath: string): boolean;
  *  `isDiscoveredTestFile`'s rule, which also counts `tests/`, a page-object
  *  directory and `test_orders.py`. The maintenance tool wants this narrow one. */
 export declare function isTestFile(filePath: string): boolean;
+/** The file's own NAME says it is a test — `login.spec.ts`, `orders.test.js`,
+ *  `test_orders.py`, `UserDAOTest.java`. Almost entirely a NAME rule: a helper,
+ *  a fixture, a page object or a config sitting in `e2e/` or `cypress/support/`
+ *  is not a test and cannot be run as one. The one exception is `__tests__/`,
+ *  Jest's convention that everything inside it is a test whatever it is called.
+ *  Exported for callers that must not act on a file merely because of where it
+ *  lives. */
+export declare function hasTestFileName(filePath: string): boolean;
 /** Whether a path is a test file, by directory or by name. Read by the route
  *  checks: a route declared in a mock server or a spec fixture is not a surface
  *  anyone serves. */

package/build/utils/testFileClassification.js

@@ -76,10 +76,43 @@ const TEST_ROOT_DIR = /(^|[\\/])(tests?|__tests__|__mocks__|e2e|cypress|testing)
  *  `TEST_FILE_PATTERNS` rows it resembles — any extension, and `.`, `_` or `-`
  *  before `test` — so no row above can stand in for it. */
 const TEST_FILE_NAME = /[._-](test|spec)\.[a-z]+$|(^|[\\/])test_[^\\/]*$/i;
+/** The file's own NAME says it is a test — `login.spec.ts`, `orders.test.js`,
+ *  `test_orders.py`, `UserDAOTest.java`. Almost entirely a NAME rule: a helper,
+ *  a fixture, a page object or a config sitting in `e2e/` or `cypress/support/`
+ *  is not a test and cannot be run as one. The one exception is `__tests__/`,
+ *  Jest's convention that everything inside it is a test whatever it is called.
+ *  Exported for callers that must not act on a file merely because of where it
+ *  lives. */
+export function hasTestFileName(filePath) {
+    return (
+    // Discovery's own name rule, applied to the basename so it admits no
+    // directory. It carries the framework spellings the regexes below miss:
+    // `UserDAOTest.java`, `orders_smoke.py`, `checkout_e2e.ts`.
+    TEST_FILE_PATTERNS.some((p) => p.test(path.basename(filePath))) ||
+        TEST_FILE_NAME.test(filePath) ||
+        CAMEL_TEST_FILE_NAME.test(filePath) ||
+        // Surefire's default includes are `Test*.java` as well as `*Test.java`, and
+        // Failsafe's are `*IT.java`. CAMEL_TEST_FILE_NAME needs a lowercase
+        // character before the suffix, so the acronym spelling (`APIIT.java`) and
+        // the prefix spelling (`TestOrder.java`) both fall through it.
+        /(^|[\\/])Test[A-Z][A-Za-z0-9]*\.(java|kt|kts|scala)$/.test(filePath) ||
+        /[A-Za-z0-9]IT\.(java|kt|kts|scala)$/.test(filePath) ||
+        // mocha's default spec glob is `./test/*.js` — one directory level, and no
+        // name rule at all, so `test/app.js` is a test to mocha.
+        /(^|[\\/])test[\\/][^\\/]+\.(js|cjs|mjs)$/.test(filePath) ||
+        // `login.e2e.ts` and Cypress's own `login.cy.ts` — the dot forms
+        // TEST_FILE_NAME does not carry. `.cy.` is to Cypress what `.spec.` is to
+        // Playwright.
+        /\.(cy|e2e)\.[a-z]+$/i.test(filePath) ||
+        // Jest's convention: everything under `__tests__/` is a test, whatever it
+        // is called. The only directory that means that on its own.
+        /(^|[\\/])__tests__[\\/]/.test(filePath));
+}
 /** The CamelCase spellings, which carry no separator before `Test`.
- *  Case-SENSITIVE and must stay so: with `i` it also matches `Latest.java` and
- *  `Manifest.cs`, ordinary source files. That is why the case-insensitive
- *  `*Test.java` / `*Tests.cs` rows above cannot serve here. */
+ *  Case-SENSITIVE and must stay so: with `i` it also matches `Latest.java`,
+ *  `Audit.java`, `Edit.cs` and `Digit.ts`, ordinary source files. That is why
+ *  the case-insensitive `*Test.java` / `*Tests.cs` rows above cannot serve
+ *  here. */
 const CAMEL_TEST_FILE_NAME = /[a-z0-9](Tests?|IT)\.[A-Za-z0-9]+$/;
 /** Whether a path is a test file, by directory or by name. Read by the route
  *  checks: a route declared in a mock server or a spec fixture is not a surface

package/build/utils/utils-verify/action-key.d.ts

@@ -25,7 +25,49 @@ import type { UtilsLanguage } from "./language-spec.js";
  * helper in either language gets the same key.
  */
 export declare function actionKeyOf(body: string, language?: UtilsLanguage): string | undefined;
+/** The keys of every step, in order, or `undefined` when there is no step or a
+ *  step has no key — the sequence `actionKeyOf` joins, kept as steps for a caller
+ *  that matches step by step (a key is not split back: a selector may carry the
+ *  separator). */
+export declare function actionStepKeys(steps: ActionStep[]): string[] | undefined;
+/** One Playwright action in a body, in source order — the unit `actionKeyOf` joins. */
+export interface ActionStep {
+    /** The step's key (`verb chain [target]`), or `undefined` when this action cannot
+     *  be read: its locator is not built from plain string literals, or its arguments
+     *  do not balance. A helper with one such step has no key; a spec's other steps
+     *  are still read, so an unreadable step is a boundary no matched run crosses. */
+    key?: string;
+    /** 1-based line of the action verb. */
+    line: number;
+    /** The source between the previous action's closing `)` (or the start of the
+     *  body) and this action's chain: what stands between two consecutive actions.
+     *  Comments are as the caller left them; string contents are kept. Empty for
+     *  the first step. See `betweenActionsIsTransparent`. */
+    gapBefore: string;
+    /** The source after this action's closing `)` up to the next action's chain, or
+     *  to the end of the body for the last step — the next step's `gapBefore`. */
+    gapAfter: string;
+}
+/**
+ * Every action in `body`, in order, each keyed as `actionKeyOf` keys it. Where
+ * `actionKeyOf` answers "what does this helper do" with one string, this answers
+ * "which actions, where, and what sits between them" — what a scan for an inline
+ * copy of a helper's sequence needs. Lines survive the Python and alias rewrites:
+ * neither adds or removes a newline.
+ */
+export declare function actionStepsOf(body: string, language?: UtilsLanguage): ActionStep[];
+/** `click empty-cart-btn; fill qty` → `click \`empty-cart-btn\`; fill \`qty\`` — the
+ *  key as the agent reads it, selectors quoted so a `#id` never reads as prose. */
+export declare function describeActionKey(key: string): string;
 /** Index of the `)` that closes the `(` at `open`, on a string-blanked copy. */
 export declare function matchingClose(structure: string, open: number): number;
+/** Whitespace and braces dropped outside string literals, `'` normalised to `"` —
+ *  the spelling a locator chain has inside a key. */
+export declare function normalizeChain(text: string): string;
 /** String contents replaced by spaces, delimiters kept, same length. */
 export declare function blankStringContents(text: string): string;
+/** The statements of a fragment as `[start, end)` spans on `structure` (a
+ *  string-blanked copy): each cut where valueEnd cuts — a `;` at depth 0, or a line
+ *  end at depth 0 that the next line does not continue with `.` — so a
+ *  Prettier-wrapped chain is one statement, not one per line. */
+export declare function statementSpans(structure: string): [number, number][];

package/build/utils/utils-verify/action-key.js

@@ -34,52 +34,101 @@ const TARGET_ARG = new Set(["goto", "dragTo"]);
  * helper in either language gets the same key.
  */
 export function actionKeyOf(body, language = "typescript") {
+    return actionStepKeys(actionStepsOf(body, language))?.join("; ");
+}
+/** The keys of every step, in order, or `undefined` when there is no step or a
+ *  step has no key — the sequence `actionKeyOf` joins, kept as steps for a caller
+ *  that matches step by step (a key is not split back: a selector may carry the
+ *  separator). */
+export function actionStepKeys(steps) {
+    if (steps.length === 0 || steps.some((s) => s.key === undefined))
+        return undefined;
+    return steps.map((s) => s.key);
+}
+/**
+ * Every action in `body`, in order, each keyed as `actionKeyOf` keys it. Where
+ * `actionKeyOf` answers "what does this helper do" with one string, this answers
+ * "which actions, where, and what sits between them" — what a scan for an inline
+ * copy of a helper's sequence needs. Lines survive the Python and alias rewrites:
+ * neither adds or removes a newline.
+ */
+export function actionStepsOf(body, language = "typescript") {
     const src = resolveLocatorAliases(language === "python" ? toPlaywrightJs(body) : body);
     // Structure is read on a copy with string CONTENTS blanked (same length), so a
-    // `)` or `.` inside a literal never ends a chain; text is taken from the original.
+    // `)` or `.` inside a literal never ends a chain, and a `.click(` written inside
+    // a string is not an action; text is taken from the original.
     const structure = blankStringContents(src);
     const steps = [];
-    for (const m of src.matchAll(ACTION_RE)) {
+    let prevEnd = 0;
+    for (const m of structure.matchAll(ACTION_RE)) {
         const verb = m[1];
         const dot = m.index;
+        const line = src.slice(0, dot).split("\n").length;
         const argsOpen = dot + m[0].length - 1;
         const argsClose = matchingClose(structure, argsOpen);
-        if (argsClose === -1)
-            return undefined;
         const chainStart = chainStartBefore(structure, dot);
-        let chain = src.slice(chainStart, dot);
-        const args = src.slice(argsOpen + 1, argsClose);
-        let target = "";
-        if (!/\(/.test(structure.slice(chainStart, dot))) {
-            // No locator call in the chain: the legacy `page.click("#save")` form, whose
-            // first argument is the selector; or `page.goto(url)`.
-            target = firstArgument(structure, src, argsOpen + 1, argsClose);
-            if (!target)
-                return undefined;
-        }
-        else if (TARGET_ARG.has(verb))
-            target = args;
-        if (verb === "goto") {
-            chain = "";
-            // A template target is keyed on its text, `${…}` included: generated helpers
-            // prefix every path with one module constant (`${baseUrl}/login`), and
-            // `/orders/${id}` is one page whatever the id. A bare variable is not a
-            // target this can read.
-            if (/^\s*`/.test(target))
-                target = "`" + target.trim().slice(1, -1) + "`";
-            else if (!/^\s*["']/.test(target))
-                return undefined;
+        const gapBefore = steps.length === 0 ? "" : src.slice(prevEnd, chainStart);
+        // An action inside another action's arguments: its chain starts before the
+        // previous action ended, so there is no gap to judge and no run to join.
+        if (argsClose === -1 || chainStart < prevEnd) {
+            steps.push({ line, gapBefore, gapAfter: "" });
+            prevEnd = argsOpen + 1;
+            continue;
         }
-        if (hasDynamicSelector(chain) || hasDynamicSelector(target))
+        prevEnd = argsClose + 1;
+        steps.push({
+            line,
+            gapBefore,
+            gapAfter: "",
+            key: stepKey(verb, src, structure, chainStart, dot, argsOpen, argsClose),
+        });
+    }
+    for (let i = 0; i < steps.length; i++)
+        steps[i].gapAfter =
+            i + 1 < steps.length ? steps[i + 1].gapBefore : src.slice(prevEnd);
+    return steps;
+}
+/** The key of one action, or `undefined` when its locator or target is unreadable. */
+function stepKey(verb, src, structure, chainStart, dot, argsOpen, argsClose) {
+    let chain = src.slice(chainStart, dot);
+    const args = src.slice(argsOpen + 1, argsClose);
+    let target = "";
+    if (!/\(/.test(structure.slice(chainStart, dot))) {
+        // No locator call in the chain: the legacy `page.click("#save")` form, whose
+        // first argument is the selector; or `page.goto(url)`.
+        target = firstArgument(structure, src, argsOpen + 1, argsClose);
+        if (!target)
             return undefined;
-        if (!/["'`]/.test(chain) && !/["'`]/.test(target))
+    }
+    else if (TARGET_ARG.has(verb))
+        target = args;
+    if (verb === "goto") {
+        chain = "";
+        // A template target is keyed on its text, `${…}` included: generated helpers
+        // prefix every path with one module constant (`${baseUrl}/login`), and
+        // `/orders/${id}` is one page whatever the id. A bare variable is not a
+        // target this can read.
+        if (/^\s*`/.test(target))
+            target = "`" + target.trim().slice(1, -1) + "`";
+        else if (!/^\s*["']/.test(target))
             return undefined;
-        const step = [verb, normalize(chain), normalize(target)]
-            .filter(Boolean)
-            .join(" ");
-        steps.push(step);
     }
-    return steps.length > 0 ? steps.join("; ") : undefined;
+    if (hasDynamicSelector(chain) || hasDynamicSelector(target))
+        return undefined;
+    if (!/["'`]/.test(chain) && !/["'`]/.test(target))
+        return undefined;
+    return [verb, normalize(chain), normalize(target)].filter(Boolean).join(" ");
+}
+/** `click empty-cart-btn; fill qty` → `click \`empty-cart-btn\`; fill \`qty\`` — the
+ *  key as the agent reads it, selectors quoted so a `#id` never reads as prose. */
+export function describeActionKey(key) {
+    return key
+        .split("; ")
+        .map((step) => {
+        const at = step.indexOf(" ");
+        return `${step.slice(0, at)} \`${step.slice(at + 1)}\``;
+    })
+        .join("; ");
 }
 /** Index of the `)` that closes the `(` at `open`, on a string-blanked copy. */
 export function matchingClose(structure, open) {
@@ -170,7 +219,11 @@ function hasDynamicSelector(text) {
                 return true;
     return false;
 }
-/** Whitespace and braces dropped outside string literals, `'` normalised to `"`. */
+/** Whitespace and braces dropped outside string literals, `'` normalised to `"` —
+ *  the spelling a locator chain has inside a key. */
+export function normalizeChain(text) {
+    return normalize(text);
+}
 function normalize(text) {
     let out = "";
     let quote = null;
@@ -243,7 +296,12 @@ function toPlaywrightJs(body) {
  *  semicolons, to the end of its `.`-continued lines — so a Prettier-wrapped chain
  *  is kept whole. A name bound more than once (`for (const row of rows)`), reassigned
  *  (`t = page.…`), or used as a parameter is ambiguous and is left alone; a variable
- *  receiver is unreadable. */
+ *  receiver is unreadable.
+ *
+ *  Deliberately file-wide when the sibling scan hands it a whole spec: a name bound
+ *  in two `test()` blocks is then ambiguous and its steps lose their key, and the
+ *  final substitution runs on raw text, so an alias name inside a selector string
+ *  is rewritten too. Both only ever lose a match, never invent one. */
 function resolveLocatorAliases(body) {
     const structure = blankStringContents(body);
     const aliases = new Map();
@@ -251,7 +309,13 @@ function resolveLocatorAliases(body) {
         const name = m[1];
         const from = m.index + m[0].length;
         const to = valueEnd(structure, from);
-        aliases.set(name, body.slice(from, to).trim().replace(/;$/, ""));
+        // Joined onto one line: the substitution must not move the lines of the
+        // actions after it (actionStepsOf reports each action's line).
+        aliases.set(name, body
+            .slice(from, to)
+            .trim()
+            .replace(/;$/, "")
+            .replace(/\s*\n\s*/g, " "));
     }
     for (const name of [...aliases.keys()]) {
         const esc = name.replace(/\$/g, "\\$");
@@ -271,6 +335,24 @@ function resolveLocatorAliases(body) {
         return body;
     return body.replace(/(?<![\w$.])([A-Za-z_$][\w$]*)(?=\s*\.)/g, (id) => aliases.get(id) ?? id);
 }
+/** The statements of a fragment as `[start, end)` spans on `structure` (a
+ *  string-blanked copy): each cut where valueEnd cuts — a `;` at depth 0, or a line
+ *  end at depth 0 that the next line does not continue with `.` — so a
+ *  Prettier-wrapped chain is one statement, not one per line. */
+export function statementSpans(structure) {
+    const out = [];
+    let i = 0;
+    while (i < structure.length) {
+        while (i < structure.length && /[\s;]/.test(structure[i]))
+            i++;
+        if (i >= structure.length)
+            break;
+        const end = valueEnd(structure, i);
+        out.push([i, end]);
+        i = end + 1;
+    }
+    return out;
+}
 /** End of an initialiser that starts at `from`: the `;` at paren depth 0, or a
  *  newline at depth 0 whose next line does not continue the chain with `.`. */
 function valueEnd(structure, from) {

package/build/utils/utils-verify/action-sites.d.ts

@@ -0,0 +1,32 @@
+import { type UtilsHelper } from "./parse.js";
+import { type UtilsLanguageSpec } from "./language-spec.js";
+import { type InlineCallSite, type SiblingFile } from "./call-sites.js";
+/**
+ * The browser family's sibling scan: a contiguous run of actions in OTHER
+ * Skyramp-generated tests beside `testFile` whose action sequence equals a utils
+ * helper's — the inline copy of a shared step (measured: three cohorts in a row, a
+ * run created the helper, rewired the two copies it happened to read and left the
+ * third, naming it in its own report).
+ *
+ * A browser step is a SEQUENCE, so the match is a sequence match: each helper's key
+ * (verb + locator chain per action, in body order — the same key STEP 3b matches a
+ * customer's helper on) is looked for as a run of consecutive actions in the
+ * sibling. Two things stand between "consecutive" and "one call can replace it":
+ *
+ *  - **What sits between two actions of the run.** A structural wait (a presence
+ *    matcher on a structural locator, a `waitFor…`), a fixed sleep or a comment is
+ *    transparent — the helper's own body may hold the same, and the key ignores it
+ *    either way. ANYTHING ELSE breaks the run: a value assertion (it cannot move
+ *    across an action — the reuse policy's own boundary rule), a page-error guard,
+ *    another call, a binding, or the end of the block the run started in. The test
+ *    the gap is held to is the one the verify pass holds a helper body to, so a run
+ *    is matched only where a helper could have held every line of it.
+ *  - **A step this cannot read.** A helper whose key is undefined is no candidate;
+ *    a sibling action with an undefined key equals nothing, so no run crosses it.
+ *    Both fail open — no match, no finding — as STEP 3b's decline rule does.
+ *
+ * Where two helpers' keys start the same run, the longer wins; the run's actions are
+ * consumed and the scan continues after it. A run inside the sibling's own local
+ * helper is reported with that helper's name, as the API scan does.
+ */
+export declare function findSiblingInlineActionSites(testFile: string, helpersByFile: ReadonlyMap<string, UtilsHelper[]>, spec: UtilsLanguageSpec, preReadSiblings: SiblingFile[] | undefined): Promise<InlineCallSite[]>;

package/build/utils/utils-verify/action-sites.js

@@ -0,0 +1,202 @@
+import * as path from "path";
+import { blankComments, localHelperAt, localHelpersOf, } from "./parse.js";
+import { expectArgs, HELPER_FAMILIES, } from "./language-spec.js";
+import { actionStepsOf, blankStringContents, normalizeChain, statementSpans, } from "./action-key.js";
+import { realpath } from "./locate.js";
+import { nonUtilsSiblings, } from "./call-sites.js";
+/** A presence assertion as `[normalised locator, matcher]`, or undefined when the
+ *  text is not one this can read. */
+function presenceWait(text, spec) {
+    if (!spec.assertionRe.test(text))
+        return undefined;
+    const matcher = /\)\s*\.\s*((?:not[._]\s*)?to\w+)\s*\(/.exec(text);
+    if (!matcher)
+        return undefined;
+    return [normalizeChain(expectArgs(text)), matcher[1].replace(/\s+/g, "")];
+}
+/**
+ * The browser family's sibling scan: a contiguous run of actions in OTHER
+ * Skyramp-generated tests beside `testFile` whose action sequence equals a utils
+ * helper's — the inline copy of a shared step (measured: three cohorts in a row, a
+ * run created the helper, rewired the two copies it happened to read and left the
+ * third, naming it in its own report).
+ *
+ * A browser step is a SEQUENCE, so the match is a sequence match: each helper's key
+ * (verb + locator chain per action, in body order — the same key STEP 3b matches a
+ * customer's helper on) is looked for as a run of consecutive actions in the
+ * sibling. Two things stand between "consecutive" and "one call can replace it":
+ *
+ *  - **What sits between two actions of the run.** A structural wait (a presence
+ *    matcher on a structural locator, a `waitFor…`), a fixed sleep or a comment is
+ *    transparent — the helper's own body may hold the same, and the key ignores it
+ *    either way. ANYTHING ELSE breaks the run: a value assertion (it cannot move
+ *    across an action — the reuse policy's own boundary rule), a page-error guard,
+ *    another call, a binding, or the end of the block the run started in. The test
+ *    the gap is held to is the one the verify pass holds a helper body to, so a run
+ *    is matched only where a helper could have held every line of it.
+ *  - **A step this cannot read.** A helper whose key is undefined is no candidate;
+ *    a sibling action with an undefined key equals nothing, so no run crosses it.
+ *    Both fail open — no match, no finding — as STEP 3b's decline rule does.
+ *
+ * Where two helpers' keys start the same run, the longer wins; the run's actions are
+ * consumed and the scan continues after it. A run inside the sibling's own local
+ * helper is reported with that helper's name, as the API scan does.
+ */
+export async function findSiblingInlineActionSites(testFile, helpersByFile, spec, preReadSiblings) {
+    const sequences = helperSequences(helpersByFile, spec);
+    if (sequences.length === 0)
+        return [];
+    const siblings = await nonUtilsSiblings(testFile, [...helpersByFile.keys()], spec, preReadSiblings, false);
+    const self = await realpath(testFile);
+    const out = [];
+    for (const { file, content } of siblings) {
+        if (path.resolve(file) === self)
+            continue;
+        const localHelpers = localHelpersOf(content, spec);
+        // Comments blanked, strings kept — the same reading the helper's key was made
+        // from, so a commented-out click is not a step and the selectors compare.
+        const steps = actionStepsOf(blankComments(content, spec), spec.language);
+        let i = 0;
+        while (i < steps.length) {
+            const match = sequences.find((s) => runMatches(steps, i, s, spec));
+            if (!match) {
+                i++;
+                continue;
+            }
+            const first = steps[i];
+            const last = steps[i + match.steps.length - 1];
+            const owner = localHelperAt(localHelpers, first.line);
+            out.push({
+                kind: "sequence",
+                file,
+                line: first.line,
+                endLine: last.line,
+                actionKey: match.key,
+                helper: match.helper,
+                utilsFile: match.utilsFile,
+                ...(owner ? { localHelper: owner.name } : {}),
+            });
+            i += match.steps.length;
+        }
+    }
+    return out;
+}
+/** Whether the helper's sequence is the run of actions starting at `at`, with
+ *  nothing between its actions that a helper body could not hold, and no wait in
+ *  or right after the run that contradicts one of the helper's own. */
+function runMatches(steps, at, helper, spec) {
+    const want = helper.steps;
+    if (at + want.length > steps.length)
+        return false;
+    for (let k = 0; k < want.length; k++) {
+        const step = steps[at + k];
+        if (step.key === undefined || step.key !== want[k])
+            return false;
+        if (k > 0) {
+            const between = transparentStatements(step.gapBefore, spec);
+            if (between === undefined)
+                return false;
+            if (contradictsWaits(between, helper.waits, spec))
+                return false;
+        }
+    }
+    // The structural waits that follow the last action are the run's too: a wait the
+    // helper would perform, or its opposite.
+    const trailing = transparentStatements(steps[at + want.length - 1].gapAfter, spec, { prefix: true });
+    return !contradictsWaits(trailing ?? [], helper.waits, spec);
+}
+/** Whether one of `statements` asserts an element the helper waits on with a
+ *  different matcher or negation. */
+function contradictsWaits(statements, waits, spec) {
+    for (const s of statements) {
+        const wait = presenceWait(s.replace(/^await\s+/, ""), spec);
+        if (!wait)
+            continue;
+        const held = waits.get(wait[0]);
+        if (held !== undefined && held !== wait[1])
+            return true;
+    }
+    return false;
+}
+/**
+ * The statements of `gap` that a shared browser helper may hold — a permitted
+ * structural wait, as the verify pass judges one (`HELPER_FAMILIES.browser`), or a
+ * `waitFor…` — or `undefined` when one is not, or when the gap closes a bracket it
+ * did not open. With `prefix`, the leading transparent statements up to the first
+ * that is not: the waits that follow a run, read until the run's own text ends.
+ * Statements are cut as statementSpans cuts them, on a string-blanked copy, so a
+ * `;` inside a literal is not a boundary and a Prettier-wrapped chain is one
+ * statement. Conservative: an unfamiliar statement ends the run.
+ */
+function transparentStatements(gap, spec, opts = {}) {
+    const structure = blankStringContents(gap);
+    if (!opts.prefix && leavesBlock(structure))
+        return undefined;
+    const out = [];
+    for (const [from, to] of statementSpans(structure)) {
+        const text = gap.slice(from, to).trim();
+        // The `await` that precedes the next action's chain.
+        if (text === "await")
+            continue;
+        const body = text.replace(/^await\s+/, "");
+        const transparent = WAIT_STATEMENT_RE.test(blankStringContents(body)) ||
+            (spec.assertionRe.test(body) &&
+                HELPER_FAMILIES.browser.isAllowed(spec, body));
+        if (!transparent)
+            return opts.prefix ? out : undefined;
+        out.push(text);
+    }
+    return out;
+}
+/** A closing bracket the fragment did not open: the run leaves its block. */
+function leavesBlock(structure) {
+    let depth = 0;
+    for (const ch of structure) {
+        if ("([{".includes(ch))
+            depth++;
+        else if (")]}".includes(ch) && --depth < 0)
+            return true;
+    }
+    return false;
+}
+/** `page.waitForTimeout(3000)`, `page.waitForLoadState()`, `page.getByTestId("x")
+ *  .waitFor({ state: "visible" })` — a wait on the page or on a locator chain, as a
+ *  statement of its own (not bound: `const p = page.waitForResponse(…)` is used
+ *  later, and the run cannot carry it). */
+const WAIT_STATEMENT_RE = /^(?:this\.)?page(?:\s*\.\s*[\w$]+\s*\([^;]*\))*\s*\.\s*(?:waitFor\w*|wait_for\w*)\s*\([^;]*\)\s*$/;
+/** A step whose receiver is the keyboard or the mouse rather than a locator. */
+function isElementlessStep(step) {
+    return /^\w+ (?:this\.)?page\.(?:keyboard|mouse)(?:\s|$)/.test(step);
+}
+/** Every keyed browser helper across the utils files, in file then body order, from
+ *  the helpers the verify pass already parsed. The first helper to carry a key owns
+ *  it; a second (the `duplicate-action` advisory's case) is not reported twice. */
+function helperSequences(helpersByFile, spec) {
+    const out = [];
+    const seen = new Set();
+    for (const [utilsFile, helpers] of helpersByFile)
+        for (const h of helpers) {
+            if (!h.actionKey || !h.actionSteps || seen.has(h.actionKey))
+                continue;
+            // A key of bare keyboard or mouse steps names no element: `press "Escape"`
+            // is what closes a dialog in one helper and a menu in the next, and every
+            // Escape in every sibling matched it (measured: fixture 22, the advisory
+            // named a menu close for a dialog-closing helper). One locator-bearing step
+            // is enough to identify the sequence.
+            if (h.actionKey.split("; ").every(isElementlessStep))
+                continue;
+            seen.add(h.actionKey);
+            out.push({
+                helper: h.name,
+                utilsFile,
+                key: h.actionKey,
+                steps: h.actionSteps,
+                waits: new Map(h.assertions
+                    .map((a) => presenceWait(a.text, spec))
+                    .filter((w) => w !== undefined)),
+            });
+        }
+    // Longest first, so the run a longer sequence covers is not claimed by a shorter
+    // helper that shares its opening actions.
+    return out.sort((a, b) => b.steps.length - a.steps.length);
+}

package/build/utils/utils-verify/body-reach.js

@@ -1,5 +1,5 @@
 import * as fs from "fs";
-import { paramName, parseUtilsFile, signatureParams, } from "./parse.js";
+import { localHelpersOf, paramName, parseUtilsFile, signatureParams, } from "./parse.js";
 import { callText, generatedSiblings, REQUEST_CALL_RE, } from "./call-sites.js";
 /** Words a fallback idiom spells that name no value: `x or {}`, `x ?? {}`,
  *  `x if x else None`. What remains after them is what the override actually sends. */
@@ -320,9 +320,7 @@ export async function findUnreachableBodies(testFile, utilsFiles, spec, preReadS
         (await generatedSiblings(testFile, spec, { includeSelf: true }));
     const out = [];
     for (const { file, content } of siblings) {
-        for (const h of parseUtilsFile(content, spec)) {
-            if (/^test/i.test(h.name))
-                continue;
+        for (const h of localHelpersOf(content, spec)) {
             if (!h.method || !h.normalizedPath)
                 continue;
             const held = frozen.get(`${h.method} ${h.normalizedPath}`);

package/build/utils/utils-verify/call-sites.d.ts

@@ -22,14 +22,13 @@ export declare function generatedSiblings(testFile: string, spec: UtilsLanguageS
 }): Promise<SiblingFile[]>;
 /** An SDK request call. Global: clone with `new RegExp(...)` before `matchAll`. */
 export declare const REQUEST_CALL_RE: RegExp;
-export interface InlineCallSite {
+interface InlineSiteBase {
     /** Absolute path of the sibling test. */
     file: string;
-    /** 1-based line of the request call. */
+    /** 1-based line of the request call, or of the first action of the sequence. */
     line: number;
-    method: string;
-    path: string;
-    /** The utils helper that wraps the same method+path. */
+    /** The utils helper that wraps the same method+path, or performs the same
+     *  action sequence. */
     helper: string;
     /** Absolute path of the utils file that defines `helper` — with several modules in
      *  scope, the advisory names this one, not the list. */
@@ -39,6 +38,19 @@ export interface InlineCallSite {
      *  block-by-block. */
     localHelper?: string;
 }
+/** An inline copy of a shared step: one request keyed by route (the API family), or
+ *  a run of actions keyed by action sequence (the browser family). */
+export type InlineCallSite = (InlineSiteBase & {
+    kind: "request";
+    method: string;
+    path: string;
+}) | (InlineSiteBase & {
+    kind: "sequence";
+    /** The action key the sequence and the helper share (see actionKeyOf). */
+    actionKey: string;
+    /** 1-based line of the sequence's last action. */
+    endLine: number;
+});
 /**
  * Inline request calls in OTHER Skyramp-generated tests beside `testFile` that a
  * utils helper already wraps — the reuse the prompt asks for and the agent does not
@@ -54,7 +66,9 @@ export interface InlineCallSite {
  * normalised path, nothing else — literals are what the call's arguments are for.
  *
  * Advisory by design: it names a change to a PRE-EXISTING test, which the maintenance
- * flow owns, so it informs rather than gates. Never throws.
+ * flow owns, so it informs rather than gates. Never throws. The API family's scan;
+ * findSiblingInlineActionSites is the browser family's, and inlineCallSiteFamily
+ * decides which runs.
  */
 export declare function findSiblingInlineCallSites(testFile: string, utilsFiles: string[], _helpers: UtilsHelper[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingFile[]): Promise<InlineCallSite[]>;
 /** One operation written in two or more sibling generated specs that no shared
@@ -95,6 +109,10 @@ export interface UnextractedSite {
  * different question. Advisory by design — consolidation is a judgement. Never throws.
  */
 export declare function findUnextractedDuplicates(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingFile[]): Promise<UnextractedDuplicate[]>;
+/** The generated siblings less the utils files themselves (a utils file carries no
+ *  codegen marker, so this is belt and braces). Pre-read siblings are used as given —
+ *  the caller's walk decides whether the spec itself is among them. */
+export declare function nonUtilsSiblings(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings: SiblingFile[] | undefined, includeSelf: boolean): Promise<SiblingFile[]>;
 /** Lines after a call scanned for its schema assertion — the generated shape puts it
  *  immediately after the status-code assertion. */
 export declare const SCHEMA_SCAN_LINES = 12;
@@ -144,3 +162,4 @@ export declare function callShape(call: string): Set<string>;
 export declare function shapeKeys(call: string): Set<string>;
 /** Text of the parenthesised argument list starting at the `(` at `open`. */
 export declare function callText(content: string, open: number): string;
+export {};