@skyramp/mcp 0.4.4 → 0.5.0-rc.10

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

@@ -1,3 +1,5 @@
+import { escapeRegExp } from "../regex.js";
+import { paramName } from "./parse.js";
 /**
  * The Playwright actions a browser helper can perform — the closed vocabulary that
  * gives the action VERB, where an API helper's method comes from the request. A
@@ -52,7 +54,10 @@ export function actionStepKeys(steps) {
  * 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") {
+export function actionStepsOf(body, language = "typescript", 
+/** A helper's parameter names: a locator argument (or `name:` option) that is
+ *  one of them keys as the wildcard `paramSlot(name)` instead of failing. */
+params) {
     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, and a `.click(` written inside
@@ -63,7 +68,7 @@ export function actionStepsOf(body, language = "typescript") {
     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 verbLine = src.slice(0, dot).split("\n").length;
         const argsOpen = dot + m[0].length - 1;
         const argsClose = matchingClose(structure, argsOpen);
         const chainStart = chainStartBefore(structure, dot);
@@ -71,16 +76,24 @@ export function actionStepsOf(body, language = "typescript") {
         // 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: "" });
+            steps.push({
+                line: verbLine,
+                gapBefore,
+                gapAfter: "",
+                endLine: verbLine,
+                value: "",
+            });
             prevEnd = argsOpen + 1;
             continue;
         }
         prevEnd = argsClose + 1;
         steps.push({
-            line,
+            line: src.slice(0, chainStart).split("\n").length,
             gapBefore,
             gapAfter: "",
-            key: stepKey(verb, src, structure, chainStart, dot, argsOpen, argsClose),
+            endLine: verbLine + (src.slice(dot, argsClose).match(/\n/g)?.length ?? 0),
+            value: firstArgument(structure, src, argsOpen + 1, argsClose),
+            key: stepKey(verb, src, structure, chainStart, dot, argsOpen, argsClose, params),
         });
     }
     for (let i = 0; i < steps.length; i++)
@@ -89,8 +102,10 @@ export function actionStepsOf(body, language = "typescript") {
     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) {
+function stepKey(verb, src, structure, chainStart, dot, argsOpen, argsClose, params) {
     let chain = src.slice(chainStart, dot);
+    if (params?.size)
+        chain = chain.replace(PARAM_LOCATOR_RE, (m, head, id) => params.has(id) ? `${head}"${paramSlot(id)}"` : m);
     const args = src.slice(argsOpen + 1, argsClose);
     let target = "";
     if (!/\(/.test(structure.slice(chainStart, dot))) {
@@ -219,6 +234,147 @@ function hasDynamicSelector(text) {
                 return true;
     return false;
 }
+/** A locator argument or `name:` option that is a bare identifier. */
+const PARAM_LOCATOR_RE = /(\.(?:getBy\w+|locator|frameLocator)\s*\(\s*|\bname\s*:\s*)([A-Za-z_$][\w$]*)(?=\s*[,)}])/g;
+/** The text a parameter-fed locator argument keys as: a string no selector holds.
+ *  A key holding SLOT_MARK holds a wildcard. */
+export const SLOT_MARK = "\u0001";
+export function paramSlot(name) {
+    return `${SLOT_MARK}${name}${SLOT_MARK}`;
+}
+const LITERAL_RE = /^(?:"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|-?\d+(?:\.\d+)?)$/;
+const GET_VALUE_RE = /^getValue\s*\(\s*([A-Za-z_$][\w$]*)\s*,\s*(["'])([\w$ .-]*)\2\s*\)((?:\s*\.\s*[A-Za-z_$][\w$]*\s*\(\s*\))*)$/;
+/**
+ * An action's value (`ActionStep.value`) as the sibling scan compares it: a bare
+ * parameter of the helper, a literal, or the generated `getValue(playwrightRequestN,
+ * "key")` — a dotted key read through nested objects, a chained `.toString()` kept
+ * as `suffix` — read through the binding that holds it (`requestBindingsOf`), to
+ * the parameter or literal stored under that key. Anything else is an expression,
+ * compared as written.
+ */
+export function resolveStepValue(raw, bindings, params = new Set()) {
+    const text = raw.trim();
+    if (params.has(text))
+        return { kind: "param", text };
+    if (LITERAL_RE.test(text))
+        return { kind: "literal", text };
+    const get = GET_VALUE_RE.exec(text);
+    const object = get ? bindings.get(get[1]) : undefined;
+    if (get && object !== undefined) {
+        let field = fieldOf(object, get[3]);
+        if (field === undefined)
+            for (const [i, part] of get[3].split(".").entries())
+                field = fieldOf(i === 0 ? object : (field ?? ""), part);
+        if (field !== undefined)
+            return {
+                ...resolveStepValue(field, new Map(), params),
+                suffix: get[4].replace(/\s+/g, ""),
+            };
+    }
+    return { kind: "expr", text };
+}
+/** The value written under the TOP-LEVEL `key` of an object literal, or undefined. */
+function fieldOf(object, key) {
+    const text = object.trim();
+    if (!text.startsWith("{") || !text.endsWith("}"))
+        return undefined;
+    const structure = blankStringContents(text);
+    let depth = 0;
+    let from = 1;
+    for (let i = 1; i < text.length; i++) {
+        const ch = structure[i];
+        if ("([{".includes(ch))
+            depth++;
+        else if (depth > 0 && ")]}".includes(ch))
+            depth--;
+        else if (depth === 0 && (ch === "," || i === text.length - 1)) {
+            const colon = structure.indexOf(":", from);
+            if (colon !== -1 && colon < i) {
+                const name = text
+                    .slice(from, colon)
+                    .trim()
+                    .replace(/^(["'])(.*)\1$/, "$2");
+                if (name === key)
+                    return text.slice(colon + 1, i).trim();
+            }
+            from = i + 1;
+        }
+    }
+    return undefined;
+}
+/** The generator's `const playwrightRequestN: Record<…> = { … }` bindings in `text`,
+ *  by name, to the object literal as written. A name bound twice is left out. */
+export function requestBindingsOf(text) {
+    const structure = blankStringContents(text);
+    const out = new Map();
+    const twice = new Set();
+    for (const m of structure.matchAll(/\bconst\s+(playwrightRequest\d+)\s*(?::\s*Record\s*<[^>]*>)?\s*=\s*\{/g)) {
+        const open = m.index + m[0].length - 1;
+        const close = matchingClose(structure, open);
+        if (close === -1 || out.has(m[1]))
+            twice.add(m[1]);
+        else
+            out.set(m[1], text.slice(open, close + 1));
+    }
+    for (const name of twice)
+        out.delete(name);
+    return out;
+}
+/** The normalised arguments of every `page.waitForResponse(…)` in `text`. */
+export function responseWaitsOf(text) {
+    const structure = blankStringContents(text);
+    const out = [];
+    for (const m of structure.matchAll(/\bwaitForResponse\s*\(/g)) {
+        const open = m.index + m[0].length - 1;
+        const close = matchingClose(structure, open);
+        if (close !== -1)
+            out.push(normalize(text.slice(open + 1, close)));
+    }
+    return out;
+}
+/** A use of the identifier `name`: not part of a longer name or a property access. */
+export function identifierUseRe(name, flags = "") {
+    return new RegExp(`(?<![\\w$.])${escapeRegExp(name)}(?![\\w$])`, flags);
+}
+/** A declared parameter's name (see paramName), or `undefined` for a rest or
+ *  destructured one: no single value a call or a wildcard can carry. */
+export function simpleParamName(raw) {
+    if (/^\s*\.\.\./.test(raw))
+        return undefined;
+    const name = paramName(raw);
+    return /^[A-Za-z_$][\w$]*$/.test(name) ? name : undefined;
+}
+/** The helper's ActionPattern, or `undefined` when a step stays unreadable with
+ *  its parameters as wildcards. `params` are the declared parameters as written. */
+export function actionPatternOf(body, language, params) {
+    // A parameter the body reassigns (`=`, `+=`, `++`, a destructuring) is not the
+    // value its caller passed.
+    const assigned = (text, name) => {
+        const id = escapeRegExp(name);
+        return [
+            `(?<![\\w$.])${id}\\s*(?:[-+*/%&|^]|\\*\\*|<<|>>>?|&&|\\|\\||\\?\\?)?(?<![!<>=])=(?![=>])`,
+            `(?:\\+\\+|--)\\s*${id}(?![\\w$])|(?<![\\w$.])${id}\\s*(?:\\+\\+|--)`,
+            `[[{][^=;]*(?<![\\w$.])${id}(?![\\w$])[^=;]*[\\]}]\\s*=(?![=>])`,
+        ].reduce((n, re) => n + (text.match(new RegExp(re, "g"))?.length ?? 0), 0);
+    };
+    const names = new Set(params
+        .map(simpleParamName)
+        .filter((n, i) => n !== undefined && assigned(body, n) <= assigned(params[i], n)));
+    const steps = actionStepsOf(body, language, names);
+    const keys = actionStepKeys(steps);
+    if (!keys)
+        return undefined;
+    const bindings = requestBindingsOf(body);
+    const uses = (text, name) => text.match(identifierUseRe(name, "g"))?.length ?? 0;
+    return {
+        steps: keys,
+        values: steps.map((s) => resolveStepValue(s.value, bindings, names)),
+        responseWaits: responseWaitsOf(body),
+        usedParams: params
+            .map(simpleParamName)
+            .filter((n, i) => n !== undefined && uses(body, n) > uses(params[i], n)),
+    };
+}
 /** Whitespace and braces dropped outside string literals, `'` normalised to `"` —
  *  the spelling a locator chain has inside a key. */
 export function normalizeChain(text) {

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

@@ -25,6 +25,13 @@ import { type InlineCallSite, type SiblingScan } from "./call-sites.js";
  *    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.
  *
+ * Two widenings (SKYR-4537), each held to boundRun's checks, so that every such
+ * site names the exact call that replaces it: the generator's own per-step bindings
+ * (`const playwrightRequestN = {…}`, `const responsePromiseN =
+ * page.waitForResponse(…)`, `const responseN = await responsePromiseN`) are
+ * transparent between two actions, and a helper whose locator argument is one of
+ * its parameters matches with the sibling's literal in that place.
+ *
  * 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.

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

@@ -1,7 +1,7 @@
 import * as path from "path";
-import { blankComments, localHelperAt, localHelpersOf, } from "./parse.js";
+import { blankComments, defaultAt, localHelperAt, localHelpersOf, } from "./parse.js";
 import { expectArgs, HELPER_FAMILIES, } from "./language-spec.js";
-import { actionStepsOf, blankStringContents, normalizeChain, statementSpans, } from "./action-key.js";
+import { actionStepsOf, blankStringContents, identifierUseRe, normalizeChain, paramSlot, requestBindingsOf, SLOT_MARK, resolveStepValue, responseWaitsOf, simpleParamName, 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
@@ -38,6 +38,13 @@ function presenceWait(text, spec) {
  *    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.
  *
+ * Two widenings (SKYR-4537), each held to boundRun's checks, so that every such
+ * site names the exact call that replaces it: the generator's own per-step bindings
+ * (`const playwrightRequestN = {…}`, `const responsePromiseN =
+ * page.waitForResponse(…)`, `const responseN = await responsePromiseN`) are
+ * transparent between two actions, and a helper whose locator argument is one of
+ * its parameters matches with the sibling's literal in that place.
+ *
  * 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.
@@ -55,25 +62,28 @@ export async function findSiblingInlineActionSites(testFile, helpersByFile, spec
         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);
+        const blanked = blankComments(content, spec);
+        const steps = actionStepsOf(blanked, spec.language);
         let i = 0;
         while (i < steps.length) {
-            const match = sequences.find((s) => runMatches(steps, i, s, spec));
-            if (!match) {
+            let run;
+            const match = sequences.find((s) => (run = runMatches(steps, i, s, spec, blanked)));
+            if (!match || !run) {
                 i++;
                 continue;
             }
-            const first = steps[i];
-            const last = steps[i + match.steps.length - 1];
-            const owner = localHelperAt(localHelpers, first.line);
+            const owner = localHelperAt(localHelpers, steps[i].line);
+            // A local helper named as the shared one: a call inside it would call itself.
+            const call = owner?.name === match.helper ? undefined : run.call;
             out.push({
                 kind: "sequence",
                 file,
-                line: first.line,
-                endLine: last.line,
-                actionKey: match.key,
+                line: run.line,
+                endLine: run.endLine,
+                actionKey: run.actionKey,
                 helper: match.helper,
                 utilsFile: match.utilsFile,
+                ...(call ? { call } : {}),
                 ...(owner ? { localHelper: owner.name } : {}),
             });
             i += match.steps.length;
@@ -81,29 +91,214 @@ export async function findSiblingInlineActionSites(testFile, helpersByFile, spec
     }
     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) {
+/** The helper's sequence as 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 — or `undefined`. A run
+ *  that matches only through a generated binding or a wildcard is held to boundRun.
+ *  `sibling` is the sibling's source, comments blanked, as `steps` were read. */
+function runMatches(steps, at, helper, spec, sibling) {
     const want = helper.steps;
     if (at + want.length > steps.length)
-        return false;
+        return undefined;
+    const args = new Map();
+    const between = [];
     for (let k = 0; k < want.length; k++) {
         const step = steps[at + k];
-        if (step.key === undefined || step.key !== want[k])
-            return false;
+        if (step.key === undefined || !stepMatches(want[k], step.key, args))
+            return undefined;
         if (k > 0) {
-            const between = transparentStatements(step.gapBefore, spec);
-            if (between === undefined)
-                return false;
-            if (contradictsWaits(between, helper.waits, spec))
-                return false;
+            const gap = transparentStatements(step.gapBefore, spec);
+            if (gap === undefined)
+                return undefined;
+            if (contradictsWaits(gap, helper.waits, spec))
+                return undefined;
+            between.push(...gap);
         }
     }
     // 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);
+    if (contradictsWaits(trailing ?? [], helper.waits, spec))
+        return undefined;
+    const run = steps.slice(at, at + want.length);
+    if (!helper.wildcard && !between.some(isGeneratedBinding)) {
+        // No call is named here, but the advisory still has the agent write one.
+        if (run.some((s, k) => liftsLiteralSecret(helper.values[k], s.value, resolveStepValue(s.value, new Map()))))
+            return undefined;
+        return {
+            line: run[0].line,
+            endLine: run[run.length - 1].endLine,
+            actionKey: helper.key,
+        };
+    }
+    return boundRun(steps[at - 1], run, between, helper, args, sibling, spec);
+}
+/** Whether a sibling step's key equals the helper's, a wildcard taking the literal
+ *  in its place — recorded in `args`, and refused when the same parameter has
+ *  already taken a different one. */
+function stepMatches(want, got, args) {
+    if (!want.includes(SLOT_MARK))
+        return want === got;
+    const parts = want.split(SLOT_RE);
+    const literal = new RegExp("^" +
+        parts
+            .map((p, i) => i % 2
+            ? '("(?:[^"\\\\]|\\\\.)*")'
+            : p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+            .join("") +
+        "$").exec(got);
+    if (!literal)
+        return false;
+    return parts
+        .filter((_, i) => i % 2)
+        .every((name, i) => bindArg(args, name, literal[i + 1]));
+}
+/** A wildcard in a key: the parameter's name between paramSlot's markers. */
+const SLOT_RE = new RegExp(`"${paramSlot("([A-Za-z_$][\\w$]*)")}"`);
+/** Records `value` as the argument for `name`; false when `name` already has a
+ *  different one — one parameter cannot carry two values. */
+function bindArg(args, name, value) {
+    const held = args.get(name);
+    if (held === undefined)
+        args.set(name, value);
+    return held === undefined || normalizeChain(held) === normalizeChain(value);
+}
+/**
+ * A run that matched through a generated binding or a wildcard: the call that
+ * replaces it, with the range that call replaces — or `undefined`, when one call
+ * cannot replace it exactly:
+ *
+ *  - **The range.** Grown back over the generated declarations right before the
+ *    first action and forward over the `await responsePromiseN` right after the
+ *    last, so a binding and its use go together.
+ *  - **No dangling name.** Every generated name the range uses is declared in it,
+ *    and no name it declares is used outside it.
+ *  - **Same response waits.** The range's `waitForResponse`s and the helper's are
+ *    equal as multisets: a wait the helper lacks would be lost, and one the range
+ *    lacks would wait for a response the sibling may never cause.
+ *  - **No lost assertion.** Between two actions, only generated bindings, waits and
+ *    the presence waits the helper itself performs: any other assertion would be
+ *    deleted with the range.
+ *  - **No lifted secret.** A password- or secret-named value is not lifted into a
+ *    literal argument of hand-maintained code.
+ *  - **Values.** A value the helper takes as a parameter becomes that argument —
+ *    a binding's literal lifted out of `getValue(playwrightRequestN, …)`; any other
+ *    value must equal the helper's. Each parameter maps to ONE value, and every
+ *    parameter but `page` and a trailing defaulted one is given one.
+ */
+function boundRun(before, run, between, helper, args, sibling, spec) {
+    for (const s of between) {
+        if (isGeneratedBinding(s))
+            continue;
+        const body = s.replace(/^await\s+/, "");
+        if (WAIT_STATEMENT_RE.test(blankStringContents(body)))
+            continue;
+        const wait = presenceWait(body, spec);
+        if (!wait || helper.waits.get(wait[0]) !== wait[1])
+            return undefined;
+    }
+    const first = run[0];
+    const last = run[run.length - 1];
+    let line = first.line;
+    let endLine = last.endLine;
+    const lead = before ? spansOf(before.gapAfter) : [];
+    let from = lead.length;
+    while (from > 0 && DECLARATION_RE.test(lead[from - 1].structure))
+        from--;
+    if (from < lead.length)
+        line = lead[from].line + before.endLine - 1;
+    const trail = spansOf(last.gapAfter);
+    let to = 0;
+    while (to < trail.length && RESPONSE_AWAIT_RE.test(trail[to].structure))
+        to++;
+    if (to > 0)
+        endLine = trail[to - 1].endLine + last.endLine - 1;
+    const range = [
+        ...lead.slice(from).map((s) => s.text),
+        ...between,
+        ...trail.slice(0, to).map((s) => s.text),
+    ];
+    const declared = new Set(range.flatMap((s) => [...s.matchAll(/\bconst\s+([A-Za-z_$][\w$]*)/g)].map((m) => m[1])));
+    const used = [...range, ...run.map((s) => s.value)].flatMap((s) => [...s.matchAll(GENERATED_NAME_RE)].map((m) => m[0]));
+    if (used.some((name) => !declared.has(name)))
+        return undefined;
+    const lines = sibling.split("\n");
+    for (const name of declared) {
+        const use = identifierUseRe(name);
+        if (lines.some((l, i) => (i + 1 < line || i + 1 > endLine) && use.test(l)))
+            return undefined;
+    }
+    const rangeWaits = range.flatMap(responseWaitsOf).sort();
+    const helperWaits = [...helper.responseWaits].sort();
+    if (rangeWaits.length !== helperWaits.length ||
+        rangeWaits.some((w, i) => w !== helperWaits[i]))
+        return undefined;
+    const bindings = requestBindingsOf(range.join("\n"));
+    for (let k = 0; k < run.length; k++) {
+        const want = helper.values[k];
+        const got = resolveStepValue(run[k].value, bindings);
+        // A value read through a generated binding this cannot resolve: the same
+        // `playwrightRequestN` text holds a different value in each spec.
+        const opaque = (v) => v.kind === "expr" && v.text.match(GENERATED_NAME_RE) !== null;
+        const ok = !liftsLiteralSecret(want, run[k].value, got) &&
+            !opaque(want) &&
+            !opaque(got) &&
+            (want.suffix ?? "") === (got.suffix ?? "") &&
+            (want.kind === "param"
+                ? ![...declared].some((n) => identifierUseRe(n).test(got.text)) &&
+                    bindArg(args, want.text, got.text)
+                : normalizeChain(want.text) === normalizeChain(got.text));
+        if (!ok)
+            return undefined;
+    }
+    const call = callOf(helper, args);
+    if (call === undefined)
+        return undefined;
+    return {
+        line,
+        endLine,
+        actionKey: helper.wildcard ? run.map((s) => s.key).join("; ") : helper.key,
+        call,
+    };
+}
+/** The statements of a gap, each with its text, its string-blanked text, and its
+ *  first and last line counted from the gap's own first line (1). */
+function spansOf(gap) {
+    const structure = blankStringContents(gap);
+    const lineAt = (i) => gap.slice(0, i).split("\n").length;
+    return statementSpans(structure)
+        .map(([from, to]) => ({
+        text: gap.slice(from, to).trim(),
+        structure: structure.slice(from, to).trim(),
+        line: lineAt(from),
+        endLine: lineAt(to),
+    }))
+        .filter((s) => s.text !== "await");
+}
+/** `await createOrder(page, "a@b.c", "option-1")`: the helper's call with each
+ *  parameter's argument, or `undefined` when a parameter has none — `page` is the
+ *  page, and a defaulted or optional parameter with nothing after it is left out —
+ *  unless the body reads it: `express = false` gating a click the sibling makes. */
+function callOf(helper, args) {
+    const out = [];
+    for (const param of helper.params) {
+        const name = simpleParamName(param);
+        if (!name)
+            return undefined;
+        const optional = /^\s*[\w$]+\s*\?/.test(param) || defaultAt(param) !== -1;
+        out.push(args.get(name) ??
+            (name === "page" || /:\s*Page\b/.test(param)
+                ? "page"
+                : optional && !helper.usedParams.includes(name)
+                    ? undefined
+                    : "\0"));
+    }
+    while (out.length > 0 && out[out.length - 1] === undefined)
+        out.pop();
+    if (out.some((a) => a === undefined || a === "\0"))
+        return undefined;
+    // The browser scan runs for TypeScript and JavaScript only (inlineCallSiteFamily).
+    return `await ${helper.helper}(${out.join(", ")})`;
 }
 /** Whether one of `statements` asserts an element the helper waits on with a
  *  different matcher or negation. */
@@ -120,8 +315,9 @@ function contradictsWaits(statements, waits, spec) {
 }
 /**
  * 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
+ * structural wait, as the verify pass judges one (`HELPER_FAMILIES.browser`), a
+ * `waitFor…`, or between two actions one of the generator's per-step bindings
+ * (isGeneratedBinding; boundRun carries it) — 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
@@ -140,6 +336,7 @@ function transparentStatements(gap, spec, opts = {}) {
             continue;
         const body = text.replace(/^await\s+/, "");
         const transparent = WAIT_STATEMENT_RE.test(blankStringContents(body)) ||
+            (!opts.prefix && isGeneratedBinding(text)) ||
             (spec.assertionRe.test(body) &&
                 HELPER_FAMILIES.browser.isAllowed(spec, body));
         if (!transparent)
@@ -161,9 +358,36 @@ function leavesBlock(structure) {
 }
 /** `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). */
+ *  statement of its own (a BOUND wait is used later: only the generator's own, see
+ *  isGeneratedBinding, is carried, by boundRun). */
 const WAIT_STATEMENT_RE = /^(?:this\.)?page(?:\s*\.\s*[\w$]+\s*\([^;]*\))*\s*\.\s*(?:waitFor\w*|wait_for\w*)\s*\([^;]*\)\s*$/;
+/** The generator's per-step declarations, string-blanked: `const playwrightRequestN:
+ *  Record<string, any> = {…}` (the value the next fill reads) and `const
+ *  responsePromiseN = page.waitForResponse(…)`. A hand-written binding is not one. */
+const DECLARATION_RE = /^const\s+(?:playwrightRequest\d+\s*(?::\s*Record\s*<[^>]*>)?\s*=\s*\{[^;]*\}|responsePromise\d+\s*=\s*(?:this\.)?page\s*\.\s*waitForResponse\s*\([^;]*\))\s*;?$/;
+/** The generator's `const responseN = await responsePromiseN`, string-blanked. */
+const RESPONSE_AWAIT_RE = /^(?:const\s+response\d+\s*=\s*)?await\s+responsePromise\d+\s*;?$/;
+/** A parameter or binding key that holds a secret: its value stays out of a call. */
+const SECRET_NAME_RE = /password|passwd|secret|token|api_?key/i;
+/** Whether a step would lift a literal secret into a call argument — a password-
+ *  or secret-named parameter (or `getValue` key) given a literal — on either path:
+ *  the literal stays out of hand-maintained code. A variable (`loginPassword`) is
+ *  no secret in itself and may be passed. */
+function liftsLiteralSecret(want, raw, got) {
+    return (want.kind === "param" &&
+        got.kind === "literal" &&
+        (SECRET_NAME_RE.test(want.text) ||
+            SECRET_NAME_RE.test(GET_VALUE_KEY_RE.exec(raw)?.[1] ?? "")));
+}
+/** The key a `getValue(binding, "key")` step value reads. */
+const GET_VALUE_KEY_RE = /^\s*getValue\s*\([^,]*,\s*["']([^"']*)["']/;
+/** A name the generator binds per step. */
+const GENERATED_NAME_RE = /\b(?:playwrightRequest|responsePromise|response)\d+\b/g;
+/** One of the generator's per-step bindings (statement text as written). */
+function isGeneratedBinding(text) {
+    const structure = blankStringContents(text);
+    return DECLARATION_RE.test(structure) || RESPONSE_AWAIT_RE.test(structure);
+}
 /** 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);
@@ -176,27 +400,45 @@ function helperSequences(helpersByFile, spec) {
     const seen = new Set();
     for (const [utilsFile, helpers] of helpersByFile)
         for (const h of helpers) {
-            if (!h.actionKey || !h.actionSteps || seen.has(h.actionKey))
+            const pattern = h.actionPattern;
+            // No key: a step whose locator is fed by a parameter is a wildcard (SKYR-4537).
+            const steps = h.actionSteps ?? pattern?.steps;
+            const key = h.actionKey ?? steps?.join("; ");
+            if (!key || !steps || !pattern || seen.has(key))
                 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))
+            if (key.split("; ").every(isElementlessStep))
+                continue;
+            // A wildcard widens what a step equals, so the sequence must still be named
+            // by its literal steps: at least two, and more than its wildcard steps — a
+            // `clickByTestId(page, id)` would otherwise equal every such click.
+            const wildcard = !h.actionSteps;
+            const literal = steps.filter((s) => !s.includes(SLOT_MARK) && !isElementlessStep(s)).length;
+            if (wildcard && (literal < 2 || literal <= steps.length - literal))
                 continue;
-            seen.add(h.actionKey);
+            seen.add(key);
             out.push({
                 helper: h.name,
                 utilsFile,
-                key: h.actionKey,
-                steps: h.actionSteps,
+                key,
+                steps,
+                wildcard,
+                params: h.params ?? [],
+                values: pattern.values,
+                responseWaits: pattern.responseWaits,
+                usedParams: pattern.usedParams,
                 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);
+    // helper that shares its opening actions; at equal length, a literal sequence
+    // before a wildcard one.
+    return out.sort((a, b) => b.steps.length - a.steps.length ||
+        Number(a.wildcard) - Number(b.wildcard));
 }

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

@@ -35,7 +35,8 @@ export declare const REQUEST_CALL_RE: RegExp;
 interface InlineSiteBase {
     /** Absolute path of the sibling test. */
     file: string;
-    /** 1-based line of the request call, or of the first action of the sequence. */
+    /** 1-based line of the request call, or of the first action of the sequence (or
+     *  of the generated declaration that precedes it, SKYR-4537). */
     line: number;
     /** The utils helper that wraps the same method+path, or performs the same
      *  action sequence. */
@@ -58,8 +59,13 @@ export type InlineCallSite = (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. */
+    /** 1-based line of the sequence's last action — or of the generated
+     *  `await responsePromiseN` that goes with it (SKYR-4537). */
     endLine: number;
+    /** The call that replaces lines `line`–`endLine`, arguments included, when
+     *  the run matched through a generated binding or a parameter-fed locator
+     *  (SKYR-4537): such a site is reported only when this can be named. */
+    call?: string;
 });
 /**
  * Inline request calls in OTHER Skyramp-generated tests beside `testFile` that a

package/build/utils/utils-verify/language-spec.js

@@ -355,7 +355,7 @@ export const HELPER_FAMILIES = {
         inlineSite: {
             noun: BROWSER_HELPERS.inlineSite.noun,
             already: "performs",
-            instruction: "Each is a candidate: the sequence's actions and locators equal the helper's, in order. Replace the sequence with a call to the helper only if the remaining differences are literals — fill values, option labels, literal arguments — which become the arguments (import the helper into that file; every assertion and the page-error guard stay in the test body where they are; change nothing else there).",
+            instruction: "Each is a candidate: the sequence's actions and locators equal the helper's, in order, except a locator the helper takes as a parameter, which becomes that argument. Replace the sequence with a call to the helper only if the remaining differences are literals — fill values, option labels, literal arguments — which become the arguments (import the helper into that file; every assertion and the page-error guard stay in the test body where they are; change nothing else there).",
             localCopy: "the sequence",
         },
     },