@skyramp/mcp 0.3.5 → 0.3.6-rc.1

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

@@ -0,0 +1,154 @@
+import * as fs from "fs";
+import * as path from "path";
+import { SKYRAMP_UTILS_HEADER } from "../utils.js";
+import { parseUtilsFile } from "./parse.js";
+import { normalizePath } from "./language-spec.js";
+import { realpath } from "./locate.js";
+/** The codegen marker every Skyramp-GENERATED TEST carries on line 1 (`Generated by
+ *  Skyramp v<version>`), as opposed to the utils header (`Generated by Skyramp on …`).
+ *  The same discriminator STEP 4 of the reuse prompt hands the agent. */
+export const CODEGEN_MARKER_RE = new RegExp(`${SKYRAMP_UTILS_HEADER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s+v\\d`);
+const HEADER_SCAN_LINES = 5;
+const REQUEST_CALL_RE = /\b(?:send_request|sendRequest)\s*\(/g;
+/**
+ * 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
+ * perform (measured 0/2 seeded eval runs with the rule as its own mandatory step).
+ *
+ * A call is INLINE when it sits in a test function, not in a module-level helper of
+ * the sibling's own: a sibling that defines `create_order` locally is STEP 4b's
+ * helper-vs-helper case, not a call site. Equivalence is `c3b9157b`'s: same method
+ * and same 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.
+ */
+export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers, spec) {
+    // route → helper name + the keyword set of the helper's own request call, so a
+    // sibling call is reported only when its SHAPE matches too (same keywords once the
+    // liftable ones are set aside) — criterion 2 of the API near-duplicate definition.
+    const byRoute = new Map();
+    for (const utilsFile of utilsFiles) {
+        let content;
+        try {
+            content = await fs.promises.readFile(utilsFile, "utf8");
+        }
+        catch {
+            continue;
+        }
+        // Owners come from THIS file's own parse: `helpers` spans every utils file, and
+        // a line range alone would attribute file B's request to file A's helper.
+        const fileHelpers = parseUtilsFile(content, spec);
+        for (const m of content.matchAll(REQUEST_CALL_RE)) {
+            const start = m.index ?? 0;
+            const line = content.slice(0, start).split("\n").length;
+            const owner = fileHelpers.find((h) => h.line <= line && line <= h.endLine);
+            if (!owner?.method || !owner.normalizedPath)
+                continue;
+            const call = callText(content, start + m[0].length - 1);
+            byRoute.set(`${owner.method} ${owner.normalizedPath}`, {
+                helper: owner.name,
+                keys: shapeKeys(call),
+            });
+        }
+    }
+    if (byRoute.size === 0)
+        return [];
+    // Canonical, like the utils paths: otherwise a tool-supplied /tmp path and a
+    // realpath'd /private/tmp utils file look like different directories to the renderer.
+    const dir = path.dirname(await realpath(testFile));
+    // Canonical like `dir`, or a spec reached through a symlink is reported as its
+    // own sibling.
+    const exclude = new Set(await Promise.all([testFile, ...utilsFiles].map((f) => realpath(f))));
+    let entries;
+    try {
+        entries = await fs.promises.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of entries.sort()) {
+        const file = path.join(dir, name);
+        if (exclude.has(path.resolve(file)))
+            continue;
+        if (!spec.extensions.some((e) => name.toLowerCase().endsWith(e)))
+            continue;
+        let content;
+        try {
+            content = await fs.promises.readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (!CODEGEN_MARKER_RE.test(content.split("\n").slice(0, HEADER_SCAN_LINES).join("\n")))
+            continue;
+        // Line ranges of the sibling's own non-test helpers: calls inside them are not inline.
+        const localHelpers = parseUtilsFile(content, spec).filter((h) => !/^test/i.test(h.name));
+        const inLocalHelper = (line) => localHelpers.some((h) => line >= h.line && line <= h.endLine);
+        for (const m of content.matchAll(REQUEST_CALL_RE)) {
+            const start = m.index ?? 0;
+            const line = content.slice(0, start).split("\n").length;
+            if (inLocalHelper(line))
+                continue;
+            const call = callText(content, start + m[0].length - 1);
+            const method = spec.methodRe.exec(call)?.[1]?.toUpperCase();
+            const p = spec.pathRe.exec(call)?.[1];
+            if (!method || !p)
+                continue;
+            const match = byRoute.get(`${method} ${normalizePath(p)}`);
+            if (!match)
+                continue;
+            if (!sameShape(shapeKeys(call), match.keys))
+                continue;
+            out.push({ file, line, method, path: p, helper: match.helper });
+        }
+    }
+    return out;
+}
+/** Keywords whose presence differs legitimately between two versions of one request:
+ *  the literals the merge rule lifts to parameters. Everything else is call shape. */
+const LIFTABLE_KEYS = new Set([
+    "body",
+    "data",
+    "data_override",
+    "dataOverride",
+    "headers",
+    "url",
+    "path_params",
+    "pathParams",
+]);
+/** The keyword names of a request call (`path=`, `method=`, `query_params=` … / TS
+ *  object keys), less the liftable ones — a cheap normalised call shape. */
+export function shapeKeys(call) {
+    const keys = new Set();
+    for (const m of call.matchAll(/\b([A-Za-z_]\w*)\s*[=:](?![=])/g)) {
+        if (!LIFTABLE_KEYS.has(m[1]))
+            keys.add(m[1]);
+    }
+    return keys;
+}
+function sameShape(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const k of a)
+        if (!b.has(k))
+            return false;
+    return true;
+}
+/** Text of the parenthesised argument list starting at the `(` at `open`. */
+function callText(content, open) {
+    let depth = 0;
+    for (let i = open; i < content.length; i++) {
+        const ch = content[i];
+        if (ch === "(")
+            depth++;
+        else if (ch === ")") {
+            depth--;
+            if (depth === 0)
+                return content.slice(open, i + 1);
+        }
+    }
+    return content.slice(open);
+}

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

@@ -0,0 +1,7 @@
+export * from "./language-spec.js";
+export * from "./parse.js";
+export * from "./allow.js";
+export * from "./locate.js";
+export * from "./verify.js";
+export * from "./stage.js";
+export * from "./call-sites.js";

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

@@ -0,0 +1,7 @@
+export * from "./language-spec.js";
+export * from "./parse.js";
+export * from "./allow.js";
+export * from "./locate.js";
+export * from "./verify.js";
+export * from "./stage.js";
+export * from "./call-sites.js";

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

@@ -0,0 +1,91 @@
+/**
+ * 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.
+ */
+export type UtilsLanguage = "python" | "typescript" | "javascript";
+export interface UtilsLanguageSpec {
+    language: UtilsLanguage;
+    /** File extensions (with dot) a utils file in this language can carry. */
+    extensions: string[];
+    commentPrefix: "#" | "//";
+    /** Matches the FIRST line of a module-level helper definition; group 1 is the name. */
+    helperStart: RegExp;
+    /** `method="POST"` / `method: "POST"` inside a helper body; group 1 is the verb. */
+    methodRe: RegExp;
+    /** `path="/api/…"` / `path: "/…"` inside a helper body; group 1 is the path. */
+    pathRe: RegExp;
+    /** A line that is an assertion at all. */
+    assertionRe: RegExp;
+    /** The one assertion shape an API helper may carry: a status-code comparison. Any
+     *  assertion line not matching this is a body assertion — the scenario-specific
+     *  claim that fails the next scenario calling the helper. */
+    allowedAssertion: RegExp;
+    /** The assertions a BROWSER helper may carry: structural waits that an element
+     *  rendered / is interactable (`toBeVisible`, `toBeEnabled`, …). Value assertions
+     *  (`toHaveText`, `toHaveValue`, `toHaveCount`, `toHaveURL`, any `expect` on a
+     *  literal) are the browser analogue of a body assertion. Mirrors the
+     *  BROWSER_HELPERS policy the modularization and reuse prompts state. */
+    allowedBrowserAssertion: RegExp;
+    /** Names `specContent` imports from the utils module whose basename stem is `stem`. */
+    importedNames(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;
+export declare const UTILS_LANGUAGE_SPECS: Record<UtilsLanguage, UtilsLanguageSpec>;
+/**
+ * The two kinds of shared helper, keyed by the test type's substrate — the same
+ * split the modularization and reuse prompts make (API_HELPERS / BROWSER_HELPERS):
+ * - `api` (integration, contract, load …): one SDK request; equivalence is
+ *   method+path; the only assertion is the status code.
+ * - `browser` (ui, e2e): a Playwright action sequence; no route to key duplicates
+ *   on, so the duplicate check is inert; the only assertions are structural waits.
+ */
+export type HelperFamily = "api" | "browser";
+export interface HelperFamilySpec {
+    family: HelperFamily;
+    /** Whether two helpers wrapping the same method+path are a violation. */
+    routeDuplicates: boolean;
+    /** Picks the permitted-assertion pattern out of a language spec. */
+    allowedAssertion(spec: UtilsLanguageSpec): RegExp;
+    /** Whether one complete assertion expression is permitted for this family. */
+    isAllowed(spec: UtilsLanguageSpec, expr: string): boolean;
+    /** One clause for the failure text: what a helper of this family may assert. */
+    assertionRule: 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
+ *  exists, and the browser rules are the more permissive of the two on duplicates, so
+ *  guessing "browser" would silently switch a check off. */
+export declare function helperFamilyFor(testType: string | undefined): HelperFamilySpec;
+/** 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 declare function utilsSpecFor(language: string | undefined): UtilsLanguageSpec | undefined;
+/** The spec whose extensions cover `file`, for callers that know a path but not a language. */
+export declare function utilsSpecForFile(file: string): UtilsLanguageSpec | undefined;
+/**
+ * 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 declare const SCENARIO_NAME_RULE: {
+    forbiddenTokens: Set<string>;
+    /** 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: RegExp;
+};
+/** The reason a name is scenario-flavoured, or `undefined` when it is canonical. */
+export declare function scenarioNameViolation(name: string): string | undefined;

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