@skyramp/mcp 0.4.0 → 0.4.1-rc.2

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

@@ -0,0 +1,292 @@
+/**
+ * The Playwright actions a browser helper can perform — the closed vocabulary that
+ * gives the action VERB, where an API helper's method comes from the request. A
+ * structural wait (`expect(...).toBeVisible()`) is not an action.
+ */
+const ACTION_RE = /\.(click|dblclick|fill|type|press|check|uncheck|selectOption|hover|tap|clear|focus|setInputFiles|dragTo|goto)\s*\(/g;
+/** Actions whose ARGUMENT is part of the identity: where a navigation goes, where a
+ *  drag lands. Every other action's argument is a value (`fill("50")`), and a
+ *  differing value is what the merge lifts into a parameter. */
+const TARGET_ARG = new Set(["goto", "dragTo"]);
+/**
+ * The comparison key of a browser helper: the analogue of `method + path` for a
+ * helper that sends no request. One step per action, in body order: the verb plus
+ * the LOCATOR CHAIN the action is called on, as written — the prompt's own
+ * definition of a browser duplicate is "same primitives in the same order,
+ * selectors identical", and that is a textual identity, not a set of tokens. So
+ * `getByRole("heading", { level: 1 })` and `{ level: 2 }` differ, `getByTestId("x")`
+ * and `getByText("x")` differ, `a.getByText("b")` and `b.getByText("a")` differ, and
+ * `.first()` / `.nth(2)` count. Formatting does not: whitespace and braces outside
+ * strings are dropped and quotes normalised, so a Prettier-wrapped chain and its
+ * one-line twin key the same. Argument VALUES are not part of the key, except a
+ * `goto` target and a `dragTo` destination, which are the identity of those steps.
+ * The legacy page-level form (`page.click("#save")`) is keyed on its selector
+ * argument.
+ *
+ * `undefined` when the helper performs no action, or when any action's locator is
+ * not built from plain string literals (a template literal, a variable, a regex, an
+ * f-string): a sequence with an unreadable step is not comparable. A `goto` target
+ * may be a template literal, keyed on its text with the interpolation kept: the
+ * generated `${baseUrl}/…` prefix names one module constant.
+ *
+ * `body` is the helper source with comments blanked and strings kept. Playwright for
+ * Python is read through the JavaScript spelling (see toPlaywrightJs), so the same
+ * helper in either language gets the same key.
+ */
+export function actionKeyOf(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.
+    const structure = blankStringContents(src);
+    const steps = [];
+    for (const m of src.matchAll(ACTION_RE)) {
+        const verb = m[1];
+        const dot = m.index;
+        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;
+        }
+        if (hasDynamicSelector(chain) || hasDynamicSelector(target))
+            return undefined;
+        if (!/["'`]/.test(chain) && !/["'`]/.test(target))
+            return undefined;
+        const step = [verb, normalize(chain), normalize(target)]
+            .filter(Boolean)
+            .join(" ");
+        steps.push(step);
+    }
+    return steps.length > 0 ? steps.join("; ") : undefined;
+}
+/** Index of the `)` that closes the `(` at `open`, on a string-blanked copy. */
+function matchingClose(structure, open) {
+    let depth = 0;
+    for (let i = open; i < structure.length; i++) {
+        const ch = structure[i];
+        if (ch === "(" || ch === "[" || ch === "{")
+            depth++;
+        else if (ch === ")" || ch === "]" || ch === "}") {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+/** Start of the `.`-chain that ends at `dot` (exclusive): walks back over
+ *  `identifier`, `identifier(...)`, and the `.` between them, so
+ *  `page.getByRole("b", { name: "x" }).first()` is one chain and the `await` or
+ *  `[`/`,` before it is not. */
+function chainStartBefore(structure, dot) {
+    let i = dot;
+    for (;;) {
+        // Skip whitespace before the segment.
+        while (i > 0 && /\s/.test(structure[i - 1]))
+            i--;
+        // A call's argument list, balanced.
+        if (i > 0 && structure[i - 1] === ")") {
+            let depth = 0;
+            let j = i - 1;
+            for (; j >= 0; j--) {
+                const ch = structure[j];
+                if (ch === ")" || ch === "]" || ch === "}")
+                    depth++;
+                else if (ch === "(" || ch === "[" || ch === "{") {
+                    depth--;
+                    if (depth === 0)
+                        break;
+                }
+            }
+            if (j < 0)
+                return i;
+            i = j;
+            while (i > 0 && /\s/.test(structure[i - 1]))
+                i--;
+        }
+        // The segment's identifier.
+        const idEnd = i;
+        while (i > 0 && /[\w$]/.test(structure[i - 1]))
+            i--;
+        if (i === idEnd)
+            return idEnd; // no identifier: the chain ended before this
+        // A `.` continues the chain; anything else ends it (root reached).
+        let k = i;
+        while (k > 0 && /\s/.test(structure[k - 1]))
+            k--;
+        if (k > 0 && structure[k - 1] === ".") {
+            i = k - 1;
+            continue;
+        }
+        return i;
+    }
+}
+/** The first top-level argument of a call, as written, or "" when it is empty. */
+function firstArgument(structure, src, from, to) {
+    let depth = 0;
+    for (let i = from; i < to; i++) {
+        const ch = structure[i];
+        if ("([{".includes(ch))
+            depth++;
+        else if (")]}".includes(ch))
+            depth--;
+        else if (ch === "," && depth === 0)
+            return src.slice(from, i).trim();
+    }
+    return src.slice(from, to).trim();
+}
+/** A locator built from anything but a plain string literal — a variable, a template
+ *  literal, a regex, an f-string — or a `name:` option given that way. */
+const LOCATOR_BUILDER_RE = /\.(?:getBy\w+|locator|frameLocator)\s*\(\s*([^\s)])/g;
+const NAME_OPTION_RE = /\bname\s*:\s*([^\s,}])/g;
+function hasDynamicSelector(text) {
+    if (text.trim() === "")
+        return false;
+    for (const re of [LOCATOR_BUILDER_RE, NAME_OPTION_RE])
+        for (const m of text.matchAll(re))
+            if (m[1] !== '"' && m[1] !== "'")
+                return true;
+    return false;
+}
+/** Whitespace and braces dropped outside string literals, `'` normalised to `"`. */
+function normalize(text) {
+    let out = "";
+    let quote = null;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (quote) {
+            if (ch === "\\") {
+                out += ch + (text[i + 1] ?? "");
+                i++;
+                continue;
+            }
+            if (ch === quote) {
+                quote = null;
+                out += '"';
+            }
+            else
+                out += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            quote = ch;
+            out += '"';
+        }
+        else if (!/[\s{}]/.test(ch))
+            out += ch;
+    }
+    // A trailing comma is Prettier's, not the locator's.
+    return out.replace(/,(?=[)\]])/g, "");
+}
+/** String contents replaced by spaces, delimiters kept, same length. */
+function blankStringContents(text) {
+    return text.replace(/(["'`])(?:\\.|(?!\1)[^\\])*\1/g, (q) => q[0] + " ".repeat(Math.max(0, q.length - 2)) + q[0]);
+}
+/** Playwright for Python spells the same API in snake_case, passes locator options
+ *  as keyword arguments, and exposes positional picks as properties. Rewritten to the
+ *  JavaScript spelling so one reader and one verb list serve both languages. Only a
+ *  keyword in argument position is rewritten: `[name=email]` inside a CSS string
+ *  stays as written. */
+const PY_CALLS = {
+    get_by_test_id: "getByTestId",
+    get_by_role: "getByRole",
+    get_by_text: "getByText",
+    get_by_label: "getByLabel",
+    get_by_placeholder: "getByPlaceholder",
+    get_by_alt_text: "getByAltText",
+    get_by_title: "getByTitle",
+    frame_locator: "frameLocator",
+    select_option: "selectOption",
+    set_input_files: "setInputFiles",
+    drag_to: "dragTo",
+};
+const PY_OPTIONS = {
+    name: "name",
+    has_text: "hasText",
+    has_not_text: "hasNotText",
+    exact: "exact",
+    level: "level",
+    checked: "checked",
+};
+function toPlaywrightJs(body) {
+    return body
+        .replace(/\.([a-z]+(?:_[a-z]+)+)\s*\(/g, (m, call) => PY_CALLS[call] ? `.${PY_CALLS[call]}(` : m)
+        .replace(/([(,]\s*)(name|has_text|has_not_text|exact|level|checked)\s*=(?!=)\s*/g, (_, before, key) => `${before}${PY_OPTIONS[key]}: `)
+        .replace(/\.(first|last)\b(?!\s*\()/g, ".$1()");
+}
+/** `const skip = page.getByRole(…);` followed by `await skip.click()` is the common
+ *  shape of a guarded step. The alias is replaced by its chain wherever it is used
+ *  as a receiver, so the click reads as the locator it acts on. Only a chain rooted
+ *  in `page` (or `this.page`) qualifies, read to its terminating `;` — or, without
+ *  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. */
+function resolveLocatorAliases(body) {
+    const structure = blankStringContents(body);
+    const aliases = new Map();
+    for (const m of body.matchAll(/\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?=(?:this\.)?page\s*\.)/g)) {
+        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(/;$/, ""));
+    }
+    for (const name of [...aliases.keys()]) {
+        const esc = name.replace(/\$/g, "\\$");
+        const bindings = body.match(new RegExp(`\\b(?:const|let|var)\\s+${esc}\\b`, "g"));
+        // Every `name =` — the declaration and any plain reassignment; not `==`, `!=`,
+        // `<=`, `>=` or `=>`. A reassigned alias would key its first value.
+        const assignments = body.match(new RegExp(`(?<![\\w$.])${esc}\\s*(?<![!<>=])=(?![=>])`, "g"));
+        const asParam = new RegExp(`\\(([^()]*\\b${esc}\\b[^()]*)\\)\\s*=>`).test(body) ||
+            new RegExp(`\\bfunction\\b[^(]*\\([^()]*\\b${esc}\\b[^()]*\\)`).test(body) ||
+            new RegExp(`(?<![\\w$.])${esc}\\s*=>`).test(body);
+        if ((bindings?.length ?? 0) > 1 ||
+            (assignments?.length ?? 0) > 1 ||
+            asParam)
+            aliases.delete(name);
+    }
+    if (aliases.size === 0)
+        return body;
+    return body.replace(/(?<![\w$.])([A-Za-z_$][\w$]*)(?=\s*\.)/g, (id) => aliases.get(id) ?? id);
+}
+/** 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) {
+    let depth = 0;
+    for (let i = from; i < structure.length; i++) {
+        const ch = structure[i];
+        if ("([{".includes(ch))
+            depth++;
+        else if (")]}".includes(ch))
+            depth = Math.max(0, depth - 1);
+        else if (depth === 0) {
+            if (ch === ";")
+                return i;
+            if (ch === "\n" && !/^\s*\./.test(structure.slice(i + 1)))
+                return i;
+        }
+    }
+    return structure.length;
+}

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

@@ -6,6 +6,12 @@ export type UtilsViolationKind = "duplicate-helper" | "body-assertion" | "scenar
  | "assertion-loss"
 /** A page-error/console guard present at hand-out is gone. Not marker-eligible. */
  | "guard-removed"
+/** One name defined twice in ONE utils file, whatever the parameter lists: a
+ *  TypeScript module with two top-level functions of one name does not load, and
+ *  in Python the second def silently replaces the first. Not marker-eligible — a
+ *  module that cannot load has no reason to stay as it is. (The same name in two
+ *  FILES with different parameter lists is `duplicate-helper`: drift, documentable.) */
+ | "helper-redefined"
 /** Python only: the spec imports the shared module in a form that cannot resolve
  *  in the customer's repo. Not marker-eligible — a broken import has no reason to
  *  stay. */
@@ -13,7 +19,8 @@ export type UtilsViolationKind = "duplicate-helper" | "body-assertion" | "scenar
 /** Kinds that only ever advise. Kept OUT of UtilsViolationKind so that type keeps
  *  meaning "a kind the allow grammar and the gate know about" — an advisory can
  *  never fail a verify and never needs (or accepts) an allow marker. */
-export type UtilsAdvisoryKind = "untyped-parameter";
+export declare const UTILS_ADVISORY_KINDS: readonly ["untyped-parameter", "duplicate-action"];
+export type UtilsAdvisoryKind = (typeof UTILS_ADVISORY_KINDS)[number];
 export declare const MARKERABLE_UTILS_KINDS: readonly ["duplicate-helper", "body-assertion", "scenario-name", "assertion-loss"];
 /** A kind the allow grammar accepts. `guard-removed` is a gate kind but never
  *  markerable — a guard is restored, not documented away — so the grammar itself

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

@@ -1,4 +1,15 @@
 import { blankStrings } from "./parse.js";
+/** Kinds that only ever advise. Kept OUT of UtilsViolationKind so that type keeps
+ *  meaning "a kind the allow grammar and the gate know about" — an advisory can
+ *  never fail a verify and never needs (or accepts) an allow marker. */
+export const UTILS_ADVISORY_KINDS = [
+    "untyped-parameter",
+    /** Two browser helpers perform one action sequence (see actionKeyOf) — the
+     *  browser analogue of `duplicate-helper`. Advisory, not blocking: the key is a
+     *  heuristic over selector literals, and a false positive on a customer's first
+     *  run is the worse outcome. */
+    "duplicate-action",
+];
 export const MARKERABLE_UTILS_KINDS = [
     "duplicate-helper",
     "body-assertion",
@@ -24,6 +35,8 @@ export const MARKERABLE_UTILS_KINDS = [
  */
 const ALLOW_RE = new RegExp(`reuse-verify:\\s*allow\\s+(${MARKERABLE_UTILS_KINDS.join("|")})\\s+([A-Za-z_$][\\w$]*)\\s*(?:[—–]+|\\s+-+\\s+)\\s*(?!<reason)(\\S.*?)\\s*$`);
 const ALLOW_LOOSE_RE = /reuse-verify:\s*allow\b/;
+/** A marker naming an advisory kind — inert, never malformed (see parseUtilsAllows). */
+const ADVISORY_MARKER_RE = new RegExp(`allow\\s+(?:${UTILS_ADVISORY_KINDS.join("|")})\\b`);
 /** The exact line to paste for a violation — what the failure text hands the agent. */
 export function allowMarkerLine(spec, kind, helper) {
     return `${spec.commentPrefix} reuse-verify: allow ${kind} ${helper} — <reason this helper must stay as it is>`;
@@ -59,7 +72,7 @@ export function parseUtilsAllows(content, spec) {
             // A marker naming an advisory kind is inert, not malformed: advisories never
             // block, so "documenting" one must not fail the gate either (the agent sees
             // the kind in a kind-shaped slot and reasonably tries).
-            if (/allow\s+untyped-parameter\b/.test(code))
+            if (ADVISORY_MARKER_RE.test(code))
                 continue;
             malformed.push(raw.trim());
             continue;

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

@@ -12,9 +12,10 @@ export interface SiblingFile {
 }
 /**
  * The Skyramp-generated tests in the spec's directory, each read once — THE sibling
- * walk, shared by the inline-call-site scan (which excludes the spec itself) and the
- * importer count (which includes it). Utils files carry no codegen version marker,
- * so the marker check alone excludes them. Fails open to [] on any read error.
+ * walk, shared by the two sibling call-site scans and the importer count (the inline
+ * scan excludes the spec itself; the other two include it). Utils files carry no
+ * codegen version marker, so the marker check alone excludes them. Fails open to []
+ * on any read error.
  */
 export declare function generatedSiblings(testFile: string, spec: UtilsLanguageSpec, opts: {
     includeSelf: boolean;
@@ -30,22 +31,70 @@ export interface InlineCallSite {
     path: string;
     /** The utils helper that wraps the same method+path. */
     helper: string;
+    /** Absolute path of the utils file that defines `helper` — with several modules in
+     *  scope, the advisory names this one, not the list. */
+    utilsFile: string;
+    /** The sibling's OWN module-level helper the call sits in, when it does — a local
+     *  rival to `helper`, to be deleted in favour of the import rather than replaced
+     *  block-by-block. */
+    localHelper?: string;
 }
 /**
  * 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.
+ * A call inside a module-level helper of the sibling's own counts too, named by that
+ * helper (`localHelper`): a sibling that defines `create_order` locally beside a
+ * shared `create_order` is the shared helper not used, however it is wrapped. The
+ * first design left that to STEP 4b of the prompt (helper-vs-helper) and nothing
+ * detected it across spec files, so the copies a half-done extraction leaves behind
+ * — one spec rewired, the others still defining the helper — went silent the moment
+ * the route became covered. 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 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
+ *  helper wraps — the extraction the reuse pass exists to perform and did not. */
+export interface UnextractedDuplicate {
+    method: string;
+    /** The path as written at the first site. */
+    path: string;
+    /** Every copy, in directory order, spanning two or more files. */
+    sites: UnextractedSite[];
+}
+export interface UnextractedSite {
+    /** Absolute path of the generated test. */
+    file: string;
+    /** 1-based line of the request call. */
+    line: number;
+    /** The test's OWN module-level helper the call sits in, when it does. A per-spec
+     *  helper is a copy as much as a bare call is: neither reached the shared module. */
+    localHelper?: string;
+}
+/**
+ * Request calls in the Skyramp-generated tests beside `testFile` — the delivered spec
+ * INCLUDED, since it is one of the copies — grouped by route and call shape, less the
+ * routes a utils helper covers. The same walk as findSiblingInlineCallSites keyed the
+ * other way: that scan starts from the helpers and finds a helper not USED; this one
+ * starts from the sites and finds a helper not CREATED. Every existing check takes a
+ * defined helper as one side of its comparison, so an operation never extracted was
+ * invisible to all of them (measured: four per-spec copies of the operation a PR was
+ * about, differing only in expected status, beside a module that shared two others).
+ *
+ * Two sites are one operation when they share method, normalised path and keyword
+ * shape — the API near-duplicate definition. Body fields and a schema check do not
+ * split a group: with no incumbent helper there is nothing to be substitutable FOR,
+ * a body difference is one more literal to lift, and a schema check stays in the spec
+ * after the helper call because the response variable is kept.
+ *
+ * A group must span two or more FILES: a spec repeating one request twice is a
+ * 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[]>;
 /** 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;
@@ -66,6 +115,25 @@ export declare function hasSchemaCheck(content: string, from: number, to: number
  * request.
  */
 export declare function requestFields(content: string, call: string, callAt?: number): Set<string>;
+/**
+ * The query-parameter NAMES a request call sends (`query_params={"page": 1}` /
+ * `queryParams: { page }`), or the empty set. Kept apart from requestFields, which
+ * strips `query_params` on purpose because it is shared with the retrofit gate and a
+ * query key is not a body field; here the question is the advisory's own — whether a
+ * helper can stand in for a site without ADDING a query parameter — and the rule is
+ * the body rule: every helper key must be present at the site.
+ */
+export declare function queryKeys(call: string): Set<string>;
+/** The call shape both sibling scans compare: shapeKeys of the call with the interior
+ *  of every keyed `{…}` value blanked, so the keys INSIDE a body, path-params or
+ *  query-params object never read as shape. shapeKeys sees every `name:` in the text,
+ *  and an unquoted TS object key (`body: { discountPercent: 10 }`) is one: a helper
+ *  inlining `body: { title }` never matched a site whose body added a field, and two
+ *  copies whose bodies named different fields were two operations — in both scans the
+ *  fields are the literals to lift, and `substitutable` is what judges them. Python
+ *  quoted dict keys (`{"order_id": id}`) never matched the identifier pattern, so
+ *  this is a TS/JS-only change. */
+export declare function callShape(call: string): Set<string>;
 /** The keyword names of a request call (`path=`, `method=`, `query_params=` … / TS
  *  object keys), less the liftable ones — a cheap normalised call shape. */
 export declare function shapeKeys(call: string): Set<string>;