@skyramp/mcp 0.4.1 → 0.4.2-rc.2

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

@@ -0,0 +1,3 @@
+import { type UtilsHelper } from "./parse.js";
+import type { UtilsViolation } from "./verify.js";
+export declare function incumbentSignatureViolations(headHelpers: readonly UtilsHelper[], workHelpers: readonly UtilsHelper[], file: string): UtilsViolation[];

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

@@ -0,0 +1,75 @@
+import { hasDefault, paramName } from "./parse.js";
+/**
+ * A helper defined at HEAD keeps the signature it has. Callers this run cannot see
+ * depend on it — the earlier run's tests, and anything the customer wrote against
+ * the module since — so the reuse step may ADD a parameter that carries a default
+ * and nothing else. Stated for Skyramp's own module because the status rule gave a
+ * run a reason to break it: told the expected status takes no default, one run
+ * stripped the defaults from three incumbents and rewrote their parameter lists to
+ * satisfy the rule, while two others left the incumbents alone. The status rule
+ * governs helpers this run writes; this is the gate that makes the other answer
+ * impossible.
+ *
+ * The same policy — a signature at HEAD is frozen, and widening by an appended
+ * defaulted parameter is the one permitted change — is enforced for the CUSTOMER's
+ * own module by `additiveChanges` in in-house.ts, under the `in-house-modified`
+ * kind. Two mechanisms encode one rule today: that one compares helper BODIES as
+ * well, and reads its own HEAD copy. They should converge.
+ *
+ * Read from the two parameter lists, by position: an incumbent parameter keeps its
+ * name and, when it had a default (or was optional), keeps one; a parameter beyond
+ * the count at HEAD carries a default. A helper HEAD does not hold is this run's and
+ * is not judged here. The body is not compared — that is the retrofit-equivalence
+ * gate's question, asked from the caller's side.
+ */
+const OPTIONAL_RE = /^[A-Za-z_$][\w$]*\s*\?(?:\s*:|$)/;
+const omittable = (p) => hasDefault(p) || OPTIONAL_RE.test(p) || /^(?:\.\.\.|\*)/.test(p);
+/** A parameter list as the agent should READ it: each name, and whether it carries a
+ *  default. The default's VALUE is deliberately left out, not unavailable: `params`
+ *  keeps string contents (see signatureParams), so `fields = "id,email"` is there to
+ *  quote. Eliding it keeps the finding short and sends the agent to the file at HEAD,
+ *  which is where the signature is restored from either way. Quoting the value would
+ *  need a length cap — a default can be a whole request body. */
+function describe(params) {
+    return params
+        .map((p) => (omittable(p) ? `${paramName(p)} = …` : paramName(p)))
+        .join(", ");
+}
+export function incumbentSignatureViolations(headHelpers, workHelpers, file) {
+    const out = [];
+    const workByName = new Map(workHelpers.map((h) => [h.name, h]));
+    for (const head of headHelpers) {
+        const work = workByName.get(head.name);
+        if (!work || !head.params || !work.params)
+            continue;
+        const faults = [];
+        head.params.forEach((was, i) => {
+            const now = work.params[i];
+            const wasName = paramName(was);
+            if (now === undefined) {
+                faults.push(`parameter ${i + 1} (\`${wasName}\`) was removed`);
+                return;
+            }
+            const nowName = paramName(now);
+            if (nowName !== wasName) {
+                faults.push(`parameter ${i + 1} is \`${nowName}\` and was \`${wasName}\``);
+                return;
+            }
+            if (omittable(was) && !omittable(now))
+                faults.push(`\`${wasName}\` lost its default`);
+        });
+        for (const added of work.params.slice(head.params.length))
+            if (!omittable(added))
+                faults.push(`\`${paramName(added)}\` was added without a default`);
+        if (faults.length === 0)
+            continue;
+        out.push({
+            kind: "incumbent-signature",
+            file,
+            helper: head.name,
+            line: work.line,
+            detail: `\`${head.name}\` is defined at HEAD as \`(${describe(head.params)})\` and now as \`(${describe(work.params)})\` — ${faults.join("; ")}. Callers this run cannot see depend on the signature at HEAD: restore it as it was. Add what you need as a new parameter with a default, or as a new helper. The expected-status rule governs helpers this run writes, never an incumbent's default`,
+        });
+    }
+    return out;
+}

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

@@ -5,4 +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,4 +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

@@ -1,20 +1,27 @@
+export type UtilsLanguage = "python" | "typescript" | "javascript";
 /**
- * Language-parametric description of a shared SkyrampUtils file, and the invariants
- * every helper in it must hold. Encoded as DATA rather than as per-language checks so
- * that adding a language (or a helper family with a different assertion rule, e.g.
- * browser helpers) is a table entry, not a second verifier.
+ * A Playwright name as the language SPELLS it: camelCase unchanged, Python
+ * snake_case. `toBeVisible` → `to_be_visible`, `waitForLoadState` →
+ * `wait_for_load_state`. Stated ONCE, so a caller that shows a name to the agent and
+ * a caller that matches one in source cannot disagree about how Python spells it.
  *
- * The invariants come from the prompts that author these files — the HELPER SHAPE
- * block in the integration modularization prompt and the API near-duplicate rules in
- * the reuse prompt — and exist here because prompt rules are LLM-enforced only:
- * SKYR-4196 Part B runs 5 and 11 leaked a scenario-literal body assertion into a shared
- * helper despite both rules being in the prompt.
+ * SPELLING ONLY — this is not a JavaScript-to-Python API map, and a name whose
+ * Python form differs in SHAPE is not its business. `waitForResponse` is the one to
+ * remember: Playwright Python has no `wait_for_response`, only the
+ * `expect_response(...)` context manager, so converting that name yields a call that
+ * does not exist. It did, and the agent was told to make it. Where the two APIs
+ * differ by more than case, the caller names each language's form itself.
  */
-export type UtilsLanguage = "python" | "typescript" | "javascript";
+export declare function playwrightSpelling(name: string, language: UtilsLanguage): string;
 export interface UtilsLanguageSpec {
     language: UtilsLanguage;
     /** File extensions (with dot) a utils file in this language can carry. */
     extensions: string[];
+    /** The basename the reuse prompt prescribes for a shared module in this language.
+     *  ONE declaration: the prompts render it into the instructions and the gate checks
+     *  the delivered file against it, so the name the agent is told and the name the
+     *  pass demands cannot drift apart. */
+    fileName: string;
     commentPrefix: "#" | "//";
     /** Matches the FIRST line of a module-level helper definition; group 1 is the name. */
     helperStart: RegExp;
@@ -36,10 +43,19 @@ export interface UtilsLanguageSpec {
     allowedBrowserAssertion: RegExp;
     /** Names `specContent` imports from the utils module whose basename stem is `stem`. */
     importedNames(specContent: string, stem: string): string[];
+    /** The local names `specContent` binds the utils MODULE itself to — `import * as
+     *  utils`, `const utils = require(…)`, `import SkyrampUtils as utils` — under
+     *  which a helper is called as `<qualifier>.<name>(`. Empty for named imports.
+     *  A call qualified by anything else (`client.getOrder(`) is another object's
+     *  method, whatever the helper's name. */
+    moduleQualifiers(specContent: string, stem: string): string[];
 }
 /** Path parameters spelled `{id}`, `${id}`, `:id` all normalise to `{}` so two helpers
  *  for `/orders/{order_id}` and `/orders/{id}` compare equal. */
 export declare function normalizePath(p: string): string;
+/** The status of a response as the assertion's RECEIVER — `r.status`, `r.statusCode`,
+ *  `res.status_code`, `res.status()` — and never a body/json/data field of it. */
+export declare const STATUS_RECEIVER = "(?![\\w.]*\\.(?:body|json|data|payload)\\b)[\\w.]+\\.status(?:_?[cC]ode)?(?:\\(\\))?";
 export declare const UTILS_LANGUAGE_SPECS: Record<UtilsLanguage, UtilsLanguageSpec>;
 /**
  * The two kinds of shared helper, keyed by the test type's substrate — the same
@@ -62,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

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

@@ -1,3 +1,51 @@
+/**
+ * Language-parametric description of a shared SkyrampUtils file, and the invariants
+ * every helper in it must hold. Encoded as DATA rather than as per-language checks so
+ * that adding a language (or a helper family with a different assertion rule, e.g.
+ * browser helpers) is a table entry, not a second verifier.
+ *
+ * The invariants come from the prompts that author these files — the HELPER SHAPE
+ * block in the integration modularization prompt and the API near-duplicate rules in
+ * the reuse prompt — and exist here because prompt rules are LLM-enforced only:
+ * SKYR-4196 Part B runs 5 and 11 leaked a scenario-literal body assertion into a shared
+ * helper despite both rules being in the prompt.
+ */
+import { API_HELPERS, BROWSER_HELPERS, HELPER_ASSERTION_POLICIES, CONTENT_ROLES, } from "../../prompts/shared-helper-policy.js";
+import { escapeRegExp } from "../regex.js";
+/**
+ * A Playwright name as the language SPELLS it: camelCase unchanged, Python
+ * snake_case. `toBeVisible` → `to_be_visible`, `waitForLoadState` →
+ * `wait_for_load_state`. Stated ONCE, so a caller that shows a name to the agent and
+ * a caller that matches one in source cannot disagree about how Python spells it.
+ *
+ * SPELLING ONLY — this is not a JavaScript-to-Python API map, and a name whose
+ * Python form differs in SHAPE is not its business. `waitForResponse` is the one to
+ * remember: Playwright Python has no `wait_for_response`, only the
+ * `expect_response(...)` context manager, so converting that name yields a call that
+ * does not exist. It did, and the agent was told to make it. Where the two APIs
+ * differ by more than case, the caller names each language's form itself.
+ */
+export function playwrightSpelling(name, language) {
+    return language === "python"
+        ? name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase()
+        : name;
+}
+function matcherAlternation(names, language) {
+    return names.map((n) => playwrightSpelling(n, language)).join("|");
+}
+/** `expect(<anything, one level of nesting>).<negation?><one permitted matcher>(`
+ *
+ *  The negation is spelled per language, like the matcher itself: TypeScript chains
+ *  it (`expect(x).not.toBeVisible()`), Python folds it into the method name
+ *  (`expect(x).not_to_be_visible()` — there is no `.not` object to chain through).
+ *  Reading `.not.` for Python rejected every negated Python assertion the policy
+ *  permits, and accepted a form Python cannot run. */
+function browserAssertionRe(language) {
+    const python = language === "python";
+    const expectCall = python ? "\\bexpect\\s*" : "\\bexpect(?:\\.soft)?\\s*";
+    const negation = python ? "(?:not_)?" : "(?:not\\.)?";
+    return new RegExp(`${expectCall}\\((?:[^()]|\\((?:[^()]|\\([^()]*\\))*\\))*\\)\\s*\\.\\s*${negation}(?:${matcherAlternation(HELPER_ASSERTION_POLICIES.browser.permittedMatchers, language)})\\s*\\(`);
+}
 /** Path parameters spelled `{id}`, `${id}`, `:id` all normalise to `{}` so two helpers
  *  for `/orders/{order_id}` and `/orders/{id}` compare equal. */
 export function normalizePath(p) {
@@ -15,6 +63,7 @@ export function normalizePath(p) {
 const PYTHON = {
     language: "python",
     extensions: [".py"],
+    fileName: "SkyrampUtils.py",
     commentPrefix: "#",
     helperStart: /^(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(/,
     methodRe: /\bmethod\s*=\s*["']([A-Za-z]+)["']/,
@@ -25,8 +74,7 @@ const PYTHON = {
     // reads the body (`json()`, `get_response_value`, `.text`, subscripts) is a body
     // assertion whatever else the line says.
     allowedAssertion: /^\s*assert\b(?=.*\bstatus_code\b)(?!.*(?:\.json\(|get_response_value|\.text\b|\.content\b|\[["']))/,
-    // Playwright for Python spells the structural matchers in snake_case.
-    allowedBrowserAssertion: /\bexpect\s*\((?:[^()]|\((?:[^()]|\([^()]*\))*\))*\)\s*\.\s*(?:not\.)?to_be_(?:visible|hidden|attached|enabled|disabled|editable|focused|in_viewport)\s*\(/,
+    allowedBrowserAssertion: browserAssertionRe("python"),
     importedNames(spec, stem) {
         const names = new Set();
         const stemRe = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -54,7 +102,25 @@ const PYTHON = {
         }
         return [...names];
     },
+    moduleQualifiers(spec, stem) {
+        const stemRe = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const mod = new RegExp(`^\\s*import\\s+(?:[\\w.]*\\.)?${stemRe}(?:\\s+as\\s+([A-Za-z_]\\w*))?\\s*$`, "m").exec(spec);
+        return mod ? [mod[1] ?? stem] : [];
+    },
 };
+/** The status of a response as the assertion's RECEIVER — `r.status`, `r.statusCode`,
+ *  `res.status_code`, `res.status()` — and never a body/json/data field of it. */
+export const STATUS_RECEIVER = "(?![\\w.]*\\.(?:body|json|data|payload)\\b)[\\w.]+\\.status(?:_?[cC]ode)?(?:\\(\\))?";
+function tsModuleQualifiers(spec, stem) {
+    const stemRe = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const from = `["'][^"']*\\/${stemRe}(?:\\.[cm]?[jt]s)?["']`;
+    const out = new Set();
+    for (const m of spec.matchAll(new RegExp(`import\\s*\\*\\s*as\\s+([A-Za-z_$][\\w$]*)\\s*from\\s*${from}`, "g")))
+        out.add(m[1]);
+    for (const m of spec.matchAll(new RegExp(`(?:const|let|var)\\s+([A-Za-z_$][\\w$]*)\\s*=\\s*require\\(\\s*${from}\\s*\\)`, "g")))
+        out.add(m[1]);
+    return [...out];
+}
 function tsImportedNames(spec, stem) {
     const names = new Set();
     const stemRe = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -71,8 +137,13 @@ function tsImportedNames(spec, stem) {
                 names.add(name);
         }
     }
-    for (const m of spec.matchAll(new RegExp(`import\\s*\\*\\s*as\\s+([A-Za-z_$][\\w$]*)\\s*from\\s*${from}`, "g"))) {
-        for (const use of spec.matchAll(new RegExp(`\\b${m[1]}\\.([A-Za-z_$][\\w$]*)`, "g")))
+    // Every name the spec binds the MODULE to — `import * as utils`, `const utils =
+    // require(…)` — and each `<qualifier>.<name>` use under it. Read from the one
+    // declaration of those forms: the two lists disagreed, so a helper called through
+    // a module-object require counted as a qualifier and never as an import, and its
+    // contract was never read.
+    for (const qualifier of tsModuleQualifiers(spec, stem)) {
+        for (const use of spec.matchAll(new RegExp(`\\b${escapeRegExp(qualifier)}\\.([A-Za-z_$][\\w$]*)`, "g")))
             names.add(use[1]);
     }
     for (const m of spec.matchAll(new RegExp(`(?:const|let|var)\\s*\\{([^}]*)\\}\\s*=\\s*require\\(\\s*${from}\\s*\\)`, "g"))) {
@@ -87,27 +158,41 @@ function tsImportedNames(spec, stem) {
 }
 const TYPESCRIPT = {
     language: "typescript",
-    extensions: [".ts", ".mts", ".cts"],
+    fileName: "skyrampUtils.ts",
+    // `.tsx` too: a Playwright spec in a React repository carries that extension, and a
+    // file this cannot name is a file the delivery-time strip skips.
+    extensions: [".ts", ".mts", ".cts", ".tsx"],
     commentPrefix: "//",
     // `function f(`, `const f = (…) =>`, `const f = async function (`, `const f = <T,>(…) =>`
     // — and a signature Prettier wrapped, whose `(` still opens on the definition line.
     helperStart: /^(?:export\s+)?(?:(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*[<(]|(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]*)?=\s*(?:async\s*)?(?:function\b|<[^>]*>\s*\(|\(|[A-Za-z_$][\w$]*\s*=>))/,
     methodRe: /\bmethod\s*:\s*["'`]([A-Za-z]+)["'`]/,
     pathRe: /\bpath\s*:\s*["'`]([^"'`]+)["'`]/,
-    assertionRe: /\bexpect(?:\.soft)?\s*\(/,
+    // `expect(…)` and the `node:assert` idiom a JavaScript suite may use instead
+    // (`assert.strictEqual(…)`, `assert(…)`). A helper written in the second was
+    // invisible — no assertion recorded, so neither the body rule nor the status
+    // rules could see it — while the spec beside it was read. Neither name may
+    // follow an identifier or a dot: `console.assert(…)` logs on failure and
+    // asserts nothing, and `\b` alone matches after the dot.
+    assertionRe: /(?<![\w$.])(?:expect(?:\.soft)?|assert(?:\.\w+)?)\s*\(/,
     allowedAssertion: 
     // The receiver is the response itself, never a body/json/data field of it:
     // `expect(res.body.status).toBe("paid")` is a body assertion. An optional
     // string message argument (`expect(r.statusCode, 'status code')`) is the
-    // form codegen emits and still a status-only assertion.
-    /\bexpect(?:\.soft)?\s*\(\s*(?![\w.]*\.(?:body|json|data|payload)\b)[\w.]+\.status(?:_?[cC]ode)?(?:\(\))?\s*(?:,\s*(?:"[^"]*"|'[^']*'|`[^`]*`)\s*)?\)\s*\.\s*(?:not\.)?(?:toBe|toEqual|toStrictEqual|toBeGreaterThan|toBeLessThan|toBeOneOf)\s*\(/,
-    allowedBrowserAssertion: /\bexpect(?:\.soft)?\s*\((?:[^()]|\((?:[^()]|\([^()]*\))*\))*\)\s*\.\s*(?:not\.)?toBe(?:Visible|Hidden|Attached|Enabled|Disabled|Editable|Focused|InViewport)\s*\(/,
+    // form codegen emits and still a status-only assertion. The assert form takes
+    // the same receiver as its first argument (`assert.strictEqual(r.statusCode,
+    // 200)`) or inside a comparison (`assert(r.status === 200)`).
+    new RegExp(`(?<![\\w$.])expect(?:\\.soft)?\\s*\\(\\s*${STATUS_RECEIVER}\\s*(?:,\\s*(?:"[^"]*"|'[^']*'|\`[^\`]*\`)\\s*)?\\)\\s*\\.\\s*(?:not\\.)?(?:toBe|toEqual|toStrictEqual|toBeGreaterThan|toBeLessThan|toBeOneOf)\\s*\\(` +
+        `|(?<![\\w$.])assert(?:\\.(?:strictEqual|equal|deepStrictEqual|deepEqual|notStrictEqual|notEqual|ok))?\\s*\\(\\s*${STATUS_RECEIVER}\\s*(?:,|[=!]==?|[<>]=?|\\))`),
+    allowedBrowserAssertion: browserAssertionRe("typescript"),
     importedNames: tsImportedNames,
+    moduleQualifiers: tsModuleQualifiers,
 };
 const JAVASCRIPT = {
     ...TYPESCRIPT,
     language: "javascript",
-    extensions: [".js", ".mjs", ".cjs"],
+    fileName: "skyrampUtils.js",
+    extensions: [".js", ".mjs", ".cjs", ".jsx"],
 };
 export const UTILS_LANGUAGE_SPECS = {
     python: PYTHON,
@@ -115,30 +200,156 @@ export const UTILS_LANGUAGE_SPECS = {
     javascript: JAVASCRIPT,
 };
 const SCENARIO_LITERAL_RE = /["'`][^"'`]*[\d$%€£][^"'`]*["'`]/;
-/** The text inside `expect(...)`, up to the matcher. */
-function expectArgs(expr) {
+/** The literal a text-matching locator is given: `getByText("…")`, `hasText: "…"`. */
+const TEXT_ARGUMENT_RE = /\b(?:getByText|get_by_text|getByAltText|get_by_alt_text|hasText|has_text)\s*[(:=]\s*["'`]([^"'`]*)["'`]/g;
+/** The literal a test id is given. */
+const TEST_ID_ARGUMENT_RE = /\b(?:getByTestId|get_by_test_id)\s*\(\s*["'`]([^"'`]*)["'`]/g;
+/** A test id an author WROTE, rather than one a scenario's data was interpolated into.
+ *  An identifier has no spaces and no address in it: `step-2-panel` and `otp-1` are
+ *  names, `order-def@mail.com - 2 items` is the row it points at. */
+const IDENTIFIER_RE = /^[^\s@]+$/;
+/** A locator built from the page's rendered TEXT rather than from an element's
+ *  identity. One pattern covers both languages: a TypeScript file does not contain
+ *  `get_by_text` and a Python one does not contain `getByText`. Playwright's own text
+ *  engines count too — `text=` and `:has-text()` select by content as surely as
+ *  `getByText` does. */
+const TEXT_LOCATOR_RE = /\b(?:getByText|get_by_text|getByAltText|get_by_alt_text)\s*\(|\b(?:hasText|has_text)\s*[:=]|\blocator\s*\(\s*["'`]\s*text=|>>\s*text=|:has-text\s*\(/;
+/** Every `getByRole("<role>"` in the locator chain, with the accessible name that
+ *  follows it when there is one. A chain holds more than one: a control role can be
+ *  filtered by a content role, and reading only the first compared the wrong one. */
+const ROLE_WITH_NAME_RE = /\b(?:getByRole|get_by_role)\s*\(\s*["'`]([A-Za-z]+)["'`]\s*(?:,\s*(?:\{[^{}]*?["'`]?\bname["'`]?\s*(?::\s*(?:["'`]([^"'`]*)["'`]|\/([^/]*)\/|([A-Za-z_$][\w$.]*))|(?=\s*[,}]))|[^()]*?\bname\s*=\s*(?:["'`]([^"'`]*)["'`]|\/([^/]*)\/|([A-Za-z_$][\w$.]*))))?/g;
+/**
+ * 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 function expectArgs(expr) {
     const open = expr.indexOf("(", expr.indexOf("expect"));
-    const close = expr.search(/\)\s*\.\s*(?:not\.)?to/);
-    return open === -1 || close === -1 ? expr : expr.slice(open + 1, close);
+    // `.not.to…` in TypeScript, `.not_to_…` in Python. Reading only the first left a
+    // negated Python assertion with no end, so the whole source line — a trailing
+    // comment included — was scanned as the locator's arguments.
+    const close = expr.search(/\)\s*\.\s*(?:not[._])?to/);
+    if (open === -1 || close === -1)
+        return expr;
+    const args = expr.slice(open + 1, close);
+    const inert = blankStringContents(args);
+    let depth = 0;
+    for (let i = 0; i < inert.length; i++) {
+        const c = inert[i];
+        if (c === "(" || c === "[" || c === "{")
+            depth++;
+        else if (c === ")" || c === "]" || c === "}")
+            depth--;
+        else if (c === "," && depth === 0)
+            return args.slice(0, i);
+    }
+    return args;
+}
+/** Offset-preserving blanking of string contents, so a comma or a bracket inside a
+ *  literal is not read as structure. Local and deliberately small: this walks ONE
+ *  expression already cut from its line, not a source file. */
+function blankStringContents(src) {
+    const out = src.split("");
+    let quote = "";
+    for (let i = 0; i < src.length; i++) {
+        const c = src[i];
+        if (quote) {
+            if (c === "\\") {
+                i++;
+                continue;
+            }
+            if (c === quote)
+                quote = "";
+            else
+                out[i] = " ";
+        }
+        else if (c === '"' || c === "'" || c === "`")
+            quote = c;
+    }
+    return out.join("");
+}
+/**
+ * Whether the locator inside `expect(...)` selects by what the page SAYS rather than
+ * by what an element IS. A permitted matcher on such a locator is a value assertion
+ * in disguise: `expect(page.getByText("Order deleted")).toBeVisible()` asserts the
+ * scenario's outcome, and the helper that holds it fails the next scenario.
+ *
+ * Positively recognised forms only — a locator shape this does not know is ALLOWED.
+ * This predicate blocks a customer's run, so an unfamiliar locator must pass rather
+ * than fail: the cost of a miss is an assertion in the wrong place, the cost of a
+ * false hit is a run that cannot finish.
+ */
+function selectsByRenderedText(args) {
+    // A CSS attribute selector can quote anything, Playwright's own engine names
+    // included: `locator('[data-note=":has-text(foo)"]')` selects by an attribute, not
+    // by text. The bracketed part is blanked before the engines are looked for, the same
+    // reason `text=` is anchored to where a selector begins.
+    if (TEXT_LOCATOR_RE.test(args.replace(/\[[^\]]*\]/g, "[]")))
+        return true;
+    // A role is NAMED whether or not the name is a literal. A parameterised name
+    // (`{ name: headingText }`) selects by the page's text just as surely; the value is
+    // simply not one this pass can read.
+    // A role is NAMED whether or not the name is a literal, and whether it is written
+    // `name: x`, `"name": x`, the shorthand `{ name }`, or Python's `name=x`. A
+    // parameterised or shorthand name selects by the page's text just as surely; the
+    // value is simply not one this pass can read.
+    const named = [...args.matchAll(ROLE_WITH_NAME_RE)].filter((m) => m.slice(2).some((g) => g !== undefined) || /\bname\b/.test(m[0]));
+    // A role with no accessible name selects a kind of element, not a string. A role
+    // whose name IS the page's content is a value assertion whatever the name says, and
+    // ANY such role in the chain decides: an inner one names the element just as much.
+    if (named.some((m) => CONTENT_ROLES.includes(m[1].toLowerCase())))
+        return true;
+    // Digits and currency, applied to the TEXT a locator matches rather than to every
+    // string in it. A step number in a test id, a heading level and a street-address
+    // label are not scenario data, and blocking them stops a customer's run over a
+    // selector that names nothing.
+    const matched = [
+        ...named.map((m) => m[2] ?? m[3] ?? m[5] ?? m[6]),
+        ...[...args.matchAll(TEXT_ARGUMENT_RE)].map((m) => m[1]),
+        // A test id counts only when it reads as content rather than as a name.
+        ...[...args.matchAll(TEST_ID_ARGUMENT_RE)]
+            .map((m) => m[1])
+            .filter((t) => !IDENTIFIER_RE.test(t)),
+    ].filter((t) => t !== undefined);
+    return matched.some((t) => SCENARIO_LITERAL_RE.test(`"${t}"`));
 }
 export const HELPER_FAMILIES = {
     api: {
         family: "api",
         routeDuplicates: true,
         isAllowed: (spec, expr) => spec.allowedAssertion.test(expr),
-        assertionRule: "a shared API helper asserts only the status code; move this assertion to the test body, applied to the response the helper returns",
-        fixRule: "a helper that wraps an SDK request asserts only the status code — one helper per method+path, extended with defaulted parameters, named method + resource",
+        assertionRule: HELPER_ASSERTION_POLICIES.api.boundary,
+        fixRule: "a helper that wraps an SDK request asserts only the status code — one helper per method+path, extended with defaulted parameters (the expected status excepted: it has no default and every call passes it), named method + resource",
+        inlineSite: {
+            // The prompt's word for the same thing, read from the policy so the advisory
+            // and the rule the agent followed name the site alike.
+            noun: API_HELPERS.inlineSite.noun,
+            already: "wraps",
+            instruction: "Each is a candidate: the request's method, path and call shape match the helper's. Replace the block with a call to the helper only if the remaining differences are literals (they become the arguments; keep the block's response variable; import the helper into that file; change nothing else there).",
+            localCopy: "that request",
+        },
     },
     browser: {
         family: "browser",
         routeDuplicates: false,
-        // A structural wait on a locator that carries a scenario LITERAL
-        // (`getByText("Total: $899.98")`) is a value assertion in disguise: digits or
-        // currency in any string inside the expect(...) arguments disqualify it.
+        // Two halves of one boundary, both declared in shared-helper-policy: the MATCHER
+        // must be one that asks whether the element rendered, and the LOCATOR must select
+        // the element by its identity rather than by the text the page shows.
         isAllowed: (spec, expr) => spec.allowedBrowserAssertion.test(expr) &&
-            !SCENARIO_LITERAL_RE.test(expectArgs(expr)),
-        assertionRule: "a shared browser helper holds actions and structural waits only (toBeVisible, toBeEnabled, …); move this value assertion to the test body immediately after the helper call, selector verbatim",
+            !selectsByRenderedText(expectArgs(expr)),
+        assertionRule: `${HELPER_ASSERTION_POLICIES.browser.boundary}. Move this value assertion to the test body immediately after the helper call, selector verbatim`,
         fixRule: "every other helper holds actions and structural waits only, named for the user intent",
+        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).",
+            localCopy: "the sequence",
+        },
     },
 };
 /** The helper family a test type's shared helpers follow. Unlike `isBrowserTestType`,

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

@@ -1,3 +1,4 @@
+import { type UtilsLanguageSpec } from "./language-spec.js";
 /** The header `generateSkyrampHeader` writes into a utils file: `Generated by Skyramp on
  *  <timestamp>`. Deliberately NOT the bare `SKYRAMP_UTILS_HEADER`, which every generated
  *  TEST also carries as its codegen marker (`Generated by Skyramp v<version>`). */
@@ -34,6 +35,31 @@ export interface LocateUtilsParams {
 export declare function locateUtilsFiles(params: LocateUtilsParams): Promise<string[]>;
 /** Canonical path, or the input unchanged when it does not exist (yet). */
 export declare function realpath(p: string): Promise<string>;
+export declare function isInside(file: string, dir: string): boolean;
 /** True when the first lines of `file` carry the utils header. Reads only the head of
  *  the file — a utils file is small, but nothing here should depend on that. */
 export declare function hasUtilsHeader(file: string): Promise<boolean>;
+/** Absolute paths of sibling modules `testFile` imports, for the module forms the reuse
+ *  prompt produces. Only paths that exist are returned. Shared with the in-house
+ *  module locator: the customer's helper module is found through the same import. */
+export declare function importedModules(testFile: string, spec: UtilsLanguageSpec, 
+/** `existing` (default) returns only files on disk; `all` returns every candidate
+ *  path the imports could resolve to, so a caller can ask HEAD about a module the
+ *  working tree no longer holds. */
+which?: "existing" | "all"): Promise<string[]>;
+/** One relative import a TypeScript/JavaScript spec makes, and where it could
+ *  resolve. Package imports are not here: a package the sandbox lacks is a
+ *  missing-node_modules trap the gate must fail OPEN on, and the spec's own
+ *  relative imports are the evidence it can check. */
+export interface SpecImport {
+    /** As written: `./skyrampUtils`, `../helpers/auth.js`. */
+    specifier: string;
+    /** Every file the specifier could resolve to, in resolution order. */
+    candidates: string[];
+    /** The first candidate that exists, canonical, or `undefined`. */
+    resolved?: string;
+}
+/** The relative imports of a TypeScript/JavaScript spec, each resolved against the
+ *  files beside it. Empty for Python, where a relative import and a package import
+ *  are spelled the same and cannot be told apart. Never throws. */
+export declare function resolveSpecImports(testFile: string, spec: UtilsLanguageSpec): Promise<SpecImport[]>;