@skyramp/mcp 0.3.4 → 0.3.6-rc.1

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

@@ -0,0 +1,210 @@
+/** 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) {
+    return (p
+        // Absolute URLs and query strings compare as their path.
+        .replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]+/i, "")
+        .replace(/[?#].*$/, "")
+        .replace(/\$\{[^}]*\}/g, "{}")
+        .replace(/\{[^}]*\}/g, "{}")
+        // `:id` is a parameter only as a whole segment; `/users:activate` is a
+        // custom method (Google AIP style) and a different endpoint.
+        .replace(/\/:[A-Za-z_]\w*(?=\/|$)/g, "/{}")
+        .replace(/\/+$/, "") || "/");
+}
+const PYTHON = {
+    language: "python",
+    extensions: [".py"],
+    commentPrefix: "#",
+    helperStart: /^(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(/,
+    methodRe: /\bmethod\s*=\s*["']([A-Za-z]+)["']/,
+    pathRe: /\bpath\s*=\s*[frbu]{0,2}["']([^"']+)["']/,
+    assertionRe: /^\s*(?:assert\b|(?:await\s+)?expect(?:\.soft)?\s*\()/,
+    // A status assertion is any assertion about the status code and nothing else — the
+    // comparison may be reversed, `in (...)`, or carry a trailing comment. Anything that
+    // 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*\(/,
+    importedNames(spec, stem) {
+        const names = new Set();
+        const stemRe = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        // `from SkyrampUtils import a, b` — or parenthesised across lines. The two
+        // forms are separate alternatives: an optional `(` with a lazy body let `$`
+        // match at the end of the `import (` line and captured nothing.
+        const fromRe = new RegExp(`^\\s*from\\s+(?:[\\w.]*\\.)?${stemRe}\\s+import\\s+(?:\\(([^)]*)\\)|([^\\n]+))`, "gm");
+        for (const m of spec.matchAll(fromRe)) {
+            for (const raw of (m[1] ?? m[2]).split(",")) {
+                const name = raw
+                    .trim()
+                    .split(/\s+as\s+/)[0]
+                    .trim();
+                if (/^[A-Za-z_]\w*$/.test(name))
+                    names.add(name);
+            }
+        }
+        // `import SkyrampUtils` / `import SkyrampUtils as utils` — every
+        // `<module-or-alias>.<name>` use counts.
+        const mod = new RegExp(`^\\s*import\\s+(?:[\\w.]*\\.)?${stemRe}(?:\\s+as\\s+([A-Za-z_]\\w*))?\\s*$`, "m").exec(spec);
+        if (mod) {
+            const qualifier = (mod[1] ?? stem).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            for (const m of spec.matchAll(new RegExp(`\\b${qualifier}\\.([A-Za-z_]\\w*)`, "g")))
+                names.add(m[1]);
+        }
+        return [...names];
+    },
+};
+function tsImportedNames(spec, stem) {
+    const names = new Set();
+    const stemRe = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const from = `["'][^"']*\\/${stemRe}(?:\\.[cm]?[jt]s)?["']`;
+    for (const m of spec.matchAll(new RegExp(`import\\s*\\{([^}]*)\\}\\s*from\\s*${from}`, "g"))) {
+        for (const raw of m[1].split(",")) {
+            // The EXPORTED name (before `as`): the count checks what the utils file defines,
+            // so an alias would under-count. Same choice as the Python `from … import x as y`.
+            const name = raw
+                .trim()
+                .split(/\s+as\s+/)[0]
+                .trim();
+            if (/^[A-Za-z_$][\w$]*$/.test(name))
+                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")))
+            names.add(use[1]);
+    }
+    for (const m of spec.matchAll(new RegExp(`(?:const|let|var)\\s*\\{([^}]*)\\}\\s*=\\s*require\\(\\s*${from}\\s*\\)`, "g"))) {
+        for (const raw of m[1].split(",")) {
+            // `{ a: b } = require(…)` — `a` is the exported name; `b` is the local alias.
+            const name = raw.trim().split(":")[0].trim();
+            if (/^[A-Za-z_$][\w$]*$/.test(name))
+                names.add(name);
+        }
+    }
+    return [...names];
+}
+const TYPESCRIPT = {
+    language: "typescript",
+    extensions: [".ts", ".mts", ".cts"],
+    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*\(/,
+    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*\(/,
+    importedNames: tsImportedNames,
+};
+const JAVASCRIPT = {
+    ...TYPESCRIPT,
+    language: "javascript",
+    extensions: [".js", ".mjs", ".cjs"],
+};
+export const UTILS_LANGUAGE_SPECS = {
+    python: PYTHON,
+    typescript: TYPESCRIPT,
+    javascript: JAVASCRIPT,
+};
+const SCENARIO_LITERAL_RE = /["'`][^"'`]*[\d$%€£][^"'`]*["'`]/;
+/** The text inside `expect(...)`, up to the matcher. */
+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);
+}
+export const HELPER_FAMILIES = {
+    api: {
+        family: "api",
+        routeDuplicates: true,
+        allowedAssertion: (spec) => spec.allowedAssertion,
+        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",
+    },
+    browser: {
+        family: "browser",
+        routeDuplicates: false,
+        allowedAssertion: (spec) => spec.allowedBrowserAssertion,
+        // 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.
+        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",
+    },
+};
+/** 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
+ *  exists, and the browser rules are the more permissive of the two on duplicates, so
+ *  guessing "browser" would silently switch a check off. */
+export function helperFamilyFor(testType) {
+    const t = (testType ?? "").toLowerCase();
+    return HELPER_FAMILIES[t === "ui" || t === "e2e" ? "browser" : "api"];
+}
+/** The spec for a language string as the tools receive it, or `undefined` for a
+ *  language this verifier does not cover (Java: utils reuse is disabled for it). */
+export function utilsSpecFor(language) {
+    const key = (language ?? "").toLowerCase();
+    return UTILS_LANGUAGE_SPECS[key];
+}
+/** The spec whose extensions cover `file`, for callers that know a path but not a language. */
+export function utilsSpecForFile(file) {
+    const lower = file.toLowerCase();
+    return Object.values(UTILS_LANGUAGE_SPECS).find((s) => s.extensions.some((e) => lower.endsWith(e)));
+}
+/**
+ * Helper names are `<verb>_<resource>` only (`create_order`, `update_order`); scenario
+ * data belongs in arguments. A name carrying a scenario adjective or a literal is the
+ * signature of a helper that will not merge with the same step from the next test
+ * (`update_order_50_discount` beside `update_order_discount`, SKYR-4196 run 4).
+ *
+ * Tokens are matched after splitting on `_` and camelCase boundaries, so the rule
+ * applies unchanged to Python and TS/JS names.
+ */
+export const SCENARIO_NAME_RULE = {
+    // Scenario ADJECTIVES only — words that never name a resource or a REST filter.
+    // Resource nouns that describe conditions (`error`, `test`, `new`, `first`) and
+    // filter states (`expired`, `failed`, `valid`, `missing`, `positive`) are legitimate:
+    // `create_test_case`, `list_expired_subscriptions`, `get_failed_jobs`. A false hit
+    // here blocks execution, so the list stays short.
+    forbiddenTokens: new Set([
+        "invalid",
+        "wrong",
+        "bad",
+        "nonexistent",
+        "nonexisting",
+        "unauthorized",
+        "unauthenticated",
+        "forbidden",
+        "notfound",
+        "scenario",
+        "twice",
+        "again",
+    ]),
+    /** A bare number as its OWN token — `update_order_50_discount` — never a digit inside
+     *  an identifier (`s3`, `oauth2`, `ipv4`, `sha256`, `base64`, `iso8601`, `2fa`). */
+    digitToken: /^\d+$/,
+};
+/** The reason a name is scenario-flavoured, or `undefined` when it is canonical. */
+export function scenarioNameViolation(name) {
+    const tokens = name
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .toLowerCase()
+        .split(/[_$]+/)
+        .filter(Boolean);
+    const hit = tokens.find((t) => SCENARIO_NAME_RULE.digitToken.test(t) ||
+        SCENARIO_NAME_RULE.forbiddenTokens.has(t));
+    if (!hit)
+        return undefined;
+    return SCENARIO_NAME_RULE.digitToken.test(hit)
+        ? `contains the literal "${hit}" — scenario values belong in arguments, not the name`
+        : `contains the scenario word "${hit}" — name helpers by method + resource only`;
+}

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

@@ -0,0 +1,39 @@
+/** 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>`). */
+export declare const UTILS_FILE_HEADER_RE: RegExp;
+export interface LocateUtilsParams {
+    /** Absolute path of the delivered test file. */
+    testFile: string;
+    /** Tool-supplied language; inferred from the test file's extension when absent. */
+    language?: string;
+    /** Override for the git root (tests); detected from `testFile` otherwise. */
+    cwd?: string;
+}
+/**
+ * Every shared utils file relevant to `testFile`, by CONTENT, never by name.
+ *
+ * The reuse prompt names a conventional file (`SkyrampUtils.py`) but explicitly allows
+ * "a new file with a different name" once that one is large, so any scheme deriving the
+ * path from the test path or a fixed filename fails silently on exactly that branch. A
+ * utils file is instead recognised by the header the prompt makes the agent write.
+ *
+ * Two sources, unioned, both scoped to the spec:
+ *  1. files this run touched (untracked, modified, or staged) IN THE SPEC'S OWN
+ *     DIRECTORY, in the language's extensions — the file the agent just created or
+ *     extended beside the test, which is what staging needs. Not repo-wide: a monorepo
+ *     has one utils file per service directory, and one service's broken helper must
+ *     not fail — or stage — another service's verify (review finding on #792).
+ *  2. modules the delivered spec imports, resolved beside it and required to stay
+ *     inside the repository — a pre-existing utils file the spec merely imports from
+ *     (SKYR-4196 run 8: byte-identical, so absent from source 1).
+ *
+ * Never throws: outside a git repo source 1 is empty and source 2 still runs; any
+ * other failure logs and contributes nothing.
+ */
+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>;
+/** 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>;

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

@@ -0,0 +1,199 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+import * as fs from "fs";
+import * as path from "path";
+import { detectGitRoot } from "../gitStaging.js";
+import { logger } from "../logger.js";
+import { SKYRAMP_UTILS_HEADER } from "../utils.js";
+import { utilsSpecFor, utilsSpecForFile, } from "./language-spec.js";
+const execFileAsync = promisify(execFile);
+/** 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>`). */
+export const UTILS_FILE_HEADER_RE = new RegExp(`${SKYRAMP_UTILS_HEADER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s+on\\b`);
+const HEADER_SCAN_LINES = 5;
+/** Enough bytes for five header lines; a utils file is never read whole to find them. */
+const HEADER_SCAN_BYTES = 2048;
+/**
+ * Every shared utils file relevant to `testFile`, by CONTENT, never by name.
+ *
+ * The reuse prompt names a conventional file (`SkyrampUtils.py`) but explicitly allows
+ * "a new file with a different name" once that one is large, so any scheme deriving the
+ * path from the test path or a fixed filename fails silently on exactly that branch. A
+ * utils file is instead recognised by the header the prompt makes the agent write.
+ *
+ * Two sources, unioned, both scoped to the spec:
+ *  1. files this run touched (untracked, modified, or staged) IN THE SPEC'S OWN
+ *     DIRECTORY, in the language's extensions — the file the agent just created or
+ *     extended beside the test, which is what staging needs. Not repo-wide: a monorepo
+ *     has one utils file per service directory, and one service's broken helper must
+ *     not fail — or stage — another service's verify (review finding on #792).
+ *  2. modules the delivered spec imports, resolved beside it and required to stay
+ *     inside the repository — a pre-existing utils file the spec merely imports from
+ *     (SKYR-4196 run 8: byte-identical, so absent from source 1).
+ *
+ * Never throws: outside a git repo source 1 is empty and source 2 still runs; any
+ * other failure logs and contributes nothing.
+ */
+export async function locateUtilsFiles(params) {
+    const spec = utilsSpecFor(params.language) ?? utilsSpecForFile(params.testFile);
+    if (!spec)
+        return [];
+    const found = new Set();
+    const root = params.cwd ?? detectGitRoot(params.testFile);
+    // Git reports paths under the REAL root while a tool-supplied testFile may go
+    // through a symlink (macOS: /tmp → /private/tmp), so the two sources would name one
+    // file twice. Everything is compared and returned in canonical form.
+    const testFile = await realpath(params.testFile);
+    const specDir = path.dirname(testFile);
+    const realRoot = root ? await realpath(root) : undefined;
+    if (realRoot) {
+        for (const rel of await changedFiles(realRoot)) {
+            if (!spec.extensions.some((e) => rel.toLowerCase().endsWith(e)))
+                continue;
+            const abs = await realpath(path.resolve(realRoot, rel));
+            if (abs === testFile || path.dirname(abs) !== specDir)
+                continue;
+            if (await hasUtilsHeader(abs))
+                found.add(abs);
+        }
+    }
+    for (const abs of await importedModules(testFile, spec)) {
+        const real = await realpath(abs);
+        // A relative import can climb out of the repository; a file there is not this
+        // repo's artifact and must never be verified or staged from here.
+        if (realRoot && !isInside(real, realRoot))
+            continue;
+        if (await hasUtilsHeader(real))
+            found.add(real);
+    }
+    return [...found].sort();
+}
+/** Canonical path, or the input unchanged when it does not exist (yet). */
+export async function realpath(p) {
+    try {
+        return await fs.promises.realpath(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+function isInside(file, dir) {
+    const rel = path.relative(dir, file);
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+async function changedFiles(root) {
+    const out = new Set();
+    // A caller-supplied root need not be a repository (the eval fixtures are plain
+    // directories); source 1 then contributes nothing, silently.
+    try {
+        await execFileAsync("git", ["rev-parse", "--is-inside-work-tree"], {
+            cwd: root,
+            encoding: "utf8",
+        });
+    }
+    catch {
+        return [];
+    }
+    // `-z`: NUL-separated, unquoted. Without it git C-quotes any non-ASCII path
+    // (`"tests/caf\303\251_helpers.py"`), which no later step could resolve.
+    const cmds = [
+        ["ls-files", "-z", "--others", "--exclude-standard"],
+        ["diff", "-z", "--name-only"],
+        ["diff", "-z", "--cached", "--name-only"],
+    ];
+    for (const args of cmds) {
+        try {
+            const { stdout } = await execFileAsync("git", args, {
+                cwd: root,
+                encoding: "utf8",
+            });
+            for (const entry of stdout.split("\0"))
+                if (entry)
+                    out.add(entry);
+        }
+        catch (err) {
+            logger.warning("Could not list changed files while locating utils files", { root, args, error: String(err) });
+        }
+    }
+    return [...out];
+}
+/** 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 async function hasUtilsHeader(file) {
+    let fh;
+    try {
+        fh = await fs.promises.open(file, "r");
+        const buf = Buffer.alloc(HEADER_SCAN_BYTES);
+        const { bytesRead } = await fh.read(buf, 0, HEADER_SCAN_BYTES, 0);
+        const head = buf
+            .toString("utf8", 0, bytesRead)
+            .split("\n")
+            .slice(0, HEADER_SCAN_LINES)
+            .join("\n");
+        return UTILS_FILE_HEADER_RE.test(head);
+    }
+    catch (err) {
+        // A missing file is the common, silent case. Anything else means a file exists
+        // that cannot be read — it must not pass as "not a utils file" without a trace.
+        if (err?.code !== "ENOENT") {
+            logger.warning("Could not read a candidate utils file — treating it as not a utils file", {
+                file,
+                error: String(err),
+            });
+        }
+        return false;
+    }
+    finally {
+        await fh?.close();
+    }
+}
+/** Absolute paths of sibling modules `testFile` imports, for the module forms the reuse
+ *  prompt produces. Only paths that exist are returned. */
+async function importedModules(testFile, spec) {
+    let content;
+    try {
+        content = await fs.promises.readFile(testFile, "utf8");
+    }
+    catch (err) {
+        if (err?.code !== "ENOENT") {
+            logger.warning("Could not read the test file to resolve its imports", {
+                testFile,
+                error: String(err),
+            });
+        }
+        return [];
+    }
+    const dir = path.dirname(testFile);
+    const candidates = new Set();
+    if (spec.language === "python") {
+        for (const m of content.matchAll(/^\s*(?:from\s+([\w.]+)\s+import\b|import\s+([\w.]+)(?:\s+as\s+\w+)?\s*$)/gm)) {
+            const mod = (m[1] ?? m[2]).replace(/^\.+/, "");
+            if (!mod)
+                continue;
+            candidates.add(path.join(dir, ...mod.split(".")) + ".py");
+        }
+    }
+    else {
+        for (const m of content.matchAll(/(?:from\s*|require\(\s*|import\(\s*)["'](\.{1,2}\/[^"']+)["']/g)) {
+            const base = path.resolve(dir, m[1]);
+            const stripped = base.replace(/\.[cm]?[jt]sx?$/, "");
+            for (const ext of spec.extensions)
+                candidates.add(stripped + ext);
+            // A `.js` specifier in an ESM TypeScript spec resolves to the `.ts` source.
+            candidates.add(stripped + ".ts");
+            candidates.add(stripped + ".js");
+        }
+    }
+    const existing = [];
+    for (const c of candidates) {
+        try {
+            if ((await fs.promises.stat(c)).isFile())
+                existing.push(c);
+        }
+        catch {
+            /* not present */
+        }
+    }
+    return existing;
+}

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

@@ -0,0 +1,34 @@
+import { type UtilsLanguageSpec } from "./language-spec.js";
+export interface HelperAssertion {
+    line: number;
+    text: string;
+    /** True for the one permitted shape — a status-code comparison. */
+    allowed: boolean;
+}
+export interface UtilsHelper {
+    name: string;
+    /** 1-based line of the definition. */
+    line: number;
+    /** 1-based line of the last body line (inclusive). */
+    endLine: number;
+    method?: string;
+    path?: string;
+    /** `path` with every path parameter collapsed to `{}`; the duplicate key with `method`. */
+    normalizedPath?: string;
+    assertions: HelperAssertion[];
+}
+/**
+ * Structured extraction of the module-level helpers in a utils file.
+ *
+ * Not a general parser. These files are highly regular by construction — one SDK
+ * request call plus assertions per helper, authored by a prompt that forbids
+ * classes and nested structure — so line-oriented extraction is sufficient and
+ * far more robust than a per-language AST dependency. Python bodies end at the
+ * next non-blank column-0 line; TS/JS bodies end when the brace depth opened by
+ * the definition returns to zero.
+ */
+export declare function parseUtilsFile(content: string, spec: UtilsLanguageSpec, allowedAssertion?: RegExp | ((expr: string) => boolean)): UtilsHelper[];
+/** Comments and string CONTENTS blanked (quotes kept, line count preserved). Python
+ *  comments are `#…`; TS/JS go through the shared stripper. */
+/** String CONTENTS blanked (quotes kept, comments kept, line count preserved). */
+export declare function blankStrings(src: string, spec: UtilsLanguageSpec): string;

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

@@ -0,0 +1,177 @@
+import { normalizePath } from "./language-spec.js";
+import { stripCommentsAndStrings, stripStrings } from "../pom-scope/strip.js";
+/**
+ * Structured extraction of the module-level helpers in a utils file.
+ *
+ * Not a general parser. These files are highly regular by construction — one SDK
+ * request call plus assertions per helper, authored by a prompt that forbids
+ * classes and nested structure — so line-oriented extraction is sufficient and
+ * far more robust than a per-language AST dependency. Python bodies end at the
+ * next non-blank column-0 line; TS/JS bodies end when the brace depth opened by
+ * the definition returns to zero.
+ */
+export function parseUtilsFile(content, spec, allowedAssertion = spec.allowedAssertion) {
+    const isAllowed = typeof allowedAssertion === "function"
+        ? allowedAssertion
+        : (expr) => allowedAssertion.test(expr);
+    const lines = content.split("\n");
+    const helpers = [];
+    let i = 0;
+    while (i < lines.length) {
+        const m = spec.helperStart.exec(lines[i]);
+        if (!m) {
+            i++;
+            continue;
+        }
+        const name = m.slice(1).find((g) => g !== undefined) ?? "";
+        const start = i;
+        const end = spec.language === "python"
+            ? pythonBodyEnd(lines, start)
+            : braceBodyEnd(lines, start);
+        const body = lines.slice(start, end);
+        // Scan a copy with comments and string contents blanked, so a commented-out
+        // `path=` or an `expect(` inside a string never keys or flags anything; the
+        // original line is what the agent is shown.
+        const scan = blankCommentsAndStrings(body.join("\n"), spec).split("\n");
+        const helper = {
+            name,
+            line: start + 1,
+            endLine: Math.max(end, start + 1),
+            assertions: [],
+        };
+        let requests = 0;
+        for (let k = 0; k < body.length; k++) {
+            const text = body[k];
+            const code = scan[k] ?? "";
+            if (/\b(?:send_request|sendRequest)\s*\(/.test(code))
+                requests++;
+            const method = spec.methodRe.exec(text);
+            if (method && /\bmethod\b/.test(code) && !helper.method)
+                helper.method = method[1].toUpperCase();
+            const p = spec.pathRe.exec(text);
+            // Key only a path given as ONE literal (followed by `,` or `)`); a concatenation
+            // (`"/api/orders/" + str(id) + "/items"`) has no route this can name.
+            if (p &&
+                /\bpath\b/.test(code) &&
+                !helper.path &&
+                isSingleLiteral(text, p)) {
+                helper.path = p[1];
+                helper.normalizedPath = normalizePath(p[1]);
+            }
+            // The definition line itself is never an assertion, and comment lines are prose.
+            // A formatted assertion may span lines (`await expect(\n  locator\n).toBeVisible()`):
+            // collect it until its parentheses balance, classify the whole expression.
+            if (k > 0 && spec.assertionRe.test(code)) {
+                let expr = code;
+                let last = k;
+                while (depthOf(expr) > 0 && last + 1 < body.length && last - k < 8) {
+                    last++;
+                    expr += " " + (scan[last] ?? "").trim();
+                }
+                // Classified on the ORIGINAL text: the allowed patterns look inside string
+                // literals (a scenario literal in a locator disqualifies a structural wait).
+                const original = body
+                    .slice(k, last + 1)
+                    .map((l) => l.trim())
+                    .join(" ");
+                helper.assertions.push({
+                    line: start + k + 1,
+                    text: original,
+                    allowed: isAllowed(original),
+                });
+                k = last;
+            }
+        }
+        // A helper wrapping two requests is a sequence, not "one SDK call": it has no single
+        // route to be a duplicate of, and the shared-helper rules do not apply to it.
+        if (requests > 1) {
+            helper.method = undefined;
+            helper.path = undefined;
+            helper.normalizedPath = undefined;
+        }
+        helpers.push(helper);
+        i = Math.max(end, start + 1);
+    }
+    return helpers;
+}
+function depthOf(code) {
+    let d = 0;
+    for (const ch of code)
+        if (ch === "(")
+            d++;
+        else if (ch === ")")
+            d--;
+    return d;
+}
+/** True when the `path` value is a single string literal ending the argument. */
+function isSingleLiteral(line, m) {
+    const after = line.slice(m.index + m[0].length).replace(/^\s+/, "");
+    return (after === "" ||
+        after.startsWith(",") ||
+        after.startsWith(")") ||
+        after.startsWith("}"));
+}
+/** Comments and string CONTENTS blanked (quotes kept, line count preserved). Python
+ *  comments are `#…`; TS/JS go through the shared stripper. */
+/** String CONTENTS blanked (quotes kept, comments kept, line count preserved). */
+export function blankStrings(src, spec) {
+    if (spec.language !== "python")
+        return stripStrings(src);
+    return src
+        .split("\n")
+        .map((line) => line.replace(/(["'])(?:\\.|(?!\1).)*\1/g, (q) => q[0] + " ".repeat(Math.max(0, q.length - 2)) + q[0]))
+        .join("\n");
+}
+function blankCommentsAndStrings(src, spec) {
+    if (spec.language !== "python")
+        return stripCommentsAndStrings(src);
+    return src
+        .split("\n")
+        .map((line) => line
+        .replace(/(["'])(?:\\.|(?!\1).)*\1/g, (q) => q[0] + " ".repeat(Math.max(0, q.length - 2)) + q[0])
+        .replace(/#.*$/, ""))
+        .join("\n");
+}
+/** Exclusive end index of a Python def starting at `start`: the next non-blank line at
+ *  column 0 (a following def, import, or module statement). */
+function pythonBodyEnd(lines, start) {
+    let i = start + 1;
+    while (i < lines.length) {
+        const l = lines[i];
+        if (l.trim() !== "" && !/^\s/.test(l))
+            break;
+        i++;
+    }
+    return i;
+}
+/** Exclusive end index of a brace-delimited definition starting at `start`. Strings and
+ *  comments are not tracked — helper bodies contain request paths, not braces in
+ *  strings — and an unbalanced body runs to end of file rather than throwing. */
+function braceBodyEnd(lines, start) {
+    let depth = 0;
+    let opened = false;
+    for (let i = start; i < lines.length; i++) {
+        for (const ch of lines[i]) {
+            if (ch === "{") {
+                depth++;
+                opened = true;
+            }
+            else if (ch === "}") {
+                depth--;
+            }
+        }
+        if (opened && depth <= 0)
+            return i + 1;
+        // No brace yet: a wrapped signature (Prettier splits any signature over 80 columns
+        // across lines) continues until its `{`. An arrow helper with an expression body
+        // ends at the first line that closes its `=>` expression without a brace.
+        if (!opened &&
+            i > start &&
+            /=>\s*[^{\s]/.test(lines[start]) &&
+            /;\s*$/.test(lines[i - 1]))
+            return i;
+        if (!opened && i - start > 12)
+            return i;
+    }
+    return lines.length;
+}