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

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 {};

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

@@ -1,7 +1,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import { SKYRAMP_UTILS_HEADER } from "../utils.js";
-import { blankCommentsAndStrings, isSingleLiteral, parseUtilsFile, } from "./parse.js";
+import { blankCommentsAndStrings, isSingleLiteral, localHelperAt, localHelpersOf, parseUtilsFile, } from "./parse.js";
 import { normalizePath } from "./language-spec.js";
 import { realpath } from "./locate.js";
 import { escapeRegExp } from "../regex.js";
@@ -66,7 +66,9 @@ export const REQUEST_CALL_RE = /\b(?:send_request|sendRequest)\s*\(/g;
  * 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 async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers, spec, preReadSiblings) {
     const byRoute = await helperRoutes(utilsFiles, spec);
@@ -91,6 +93,7 @@ export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers,
             }))
                 continue;
             out.push({
+                kind: "request",
                 file,
                 line: c.line,
                 method: c.method,
@@ -178,7 +181,7 @@ async function helperRoutes(utilsFiles, spec) {
 /** 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. */
-async function nonUtilsSiblings(testFile, utilsFiles, spec, preReadSiblings, includeSelf) {
+export async function nonUtilsSiblings(testFile, utilsFiles, spec, preReadSiblings, includeSelf) {
     const utilsSet = new Set(await Promise.all(utilsFiles.map((f) => realpath(f))));
     return (preReadSiblings ??
         (await generatedSiblings(testFile, spec, { includeSelf }))).filter((sib) => !utilsSet.has(path.resolve(sib.file)));
@@ -189,7 +192,7 @@ async function nonUtilsSiblings(testFile, utilsFiles, spec, preReadSiblings, inc
  *  commented-out or quoted request is never a site and a `)` inside a string never
  *  truncates the argument text, which is read from the original. */
 function requestCallsIn(content, spec) {
-    const localHelpers = parseUtilsFile(content, spec).filter((h) => !/^test/i.test(h.name));
+    const localHelpers = localHelpersOf(content, spec);
     const scan = blankCommentsAndStrings(content, spec);
     const out = [];
     for (const m of scan.matchAll(REQUEST_CALL_RE)) {
@@ -205,7 +208,7 @@ function requestCallsIn(content, spec) {
         if (!method || !pm || !isSingleLiteral(call, pm))
             continue;
         const p = pm[1];
-        const owner = localHelpers.find((h) => line >= h.line && line <= h.endLine);
+        const owner = localHelperAt(localHelpers, line);
         out.push({
             line,
             start,

package/build/utils/utils-verify/index.d.ts

@@ -5,5 +5,6 @@ export * from "./locate.js";
 export * from "./verify.js";
 export * from "./stage.js";
 export * from "./call-sites.js";
+export * from "./action-sites.js";
 export * from "./retrofit-equivalence.js";
 export * from "./in-house.js";

package/build/utils/utils-verify/index.js

@@ -5,5 +5,6 @@ export * from "./locate.js";
 export * from "./verify.js";
 export * from "./stage.js";
 export * from "./call-sites.js";
+export * from "./action-sites.js";
 export * from "./retrofit-equivalence.js";
 export * from "./in-house.js";

package/build/utils/utils-verify/language-spec.d.ts

@@ -78,7 +78,32 @@ export interface HelperFamilySpec {
     /** One clause for the fix-instruction sentence — composed by the gate, never
      *  restated there (the browser clause reads as a continuation of the api one). */
     fixRule: string;
+    /** The sibling inline call-site advisory's family-specific half: what a site is
+     *  called, what the helper already does with it, and how to replace it. The gate
+     *  appends the tail both families share. */
+    inlineSite: {
+        /** The prompt's noun for a site — `HelperPolicy.inlineSite.noun`. */
+        noun: string;
+        /** `… that a shared helper already <verb>:` */
+        already: string;
+        /** What makes a site a candidate, and what the replacement keeps. */
+        instruction: string;
+        /** The copy as the shared tail names it inside a local helper: `that request`
+         *  / `the sequence`. */
+        localCopy: string;
+    };
 }
+/**
+ * The RECEIVED value inside `expect(...)` — its first argument, up to the matcher.
+ *
+ * Only the first, because Playwright takes a message as the second: `expect(locator,
+ * "why this matters")`. Reading every argument let that message decide, so a
+ * structural wait whose message merely NAMED a text-selecting form was refused — and
+ * a refusal blocks a delivery that is right, which is worse than missing one that is
+ * wrong. The split walks bracket depth on a copy whose strings are blanked, so a comma
+ * inside a selector or a message does not end the argument.
+ */
+export declare function expectArgs(expr: string): string;
 export declare const HELPER_FAMILIES: Record<HelperFamily, HelperFamilySpec>;
 /** The helper family a test type's shared helpers follow. Unlike `isBrowserTestType`,
  *  an ABSENT test type resolves to `api`: this runs against a utils file that already