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

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

@@ -1,7 +1,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import { SKYRAMP_UTILS_HEADER } from "../utils.js";
-import { blankCommentsAndStrings, isSingleLiteral, parseUtilsFile, } from "./parse.js";
+import { blankCommentsAndStrings, isSingleLiteral, localHelperAt, localHelpersOf, parseUtilsFile, } from "./parse.js";
 import { normalizePath } from "./language-spec.js";
 import { realpath } from "./locate.js";
 import { escapeRegExp } from "../regex.js";
@@ -66,7 +66,9 @@ export const REQUEST_CALL_RE = /\b(?:send_request|sendRequest)\s*\(/g;
  * normalised path, nothing else — literals are what the call's arguments are for.
  *
  * Advisory by design: it names a change to a PRE-EXISTING test, which the maintenance
- * flow owns, so it informs rather than gates. Never throws.
+ * flow owns, so it informs rather than gates. Never throws. The API family's scan;
+ * findSiblingInlineActionSites is the browser family's, and inlineCallSiteFamily
+ * decides which runs.
  */
 export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers, spec, preReadSiblings) {
     const byRoute = await helperRoutes(utilsFiles, spec);
@@ -91,6 +93,7 @@ export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers,
             }))
                 continue;
             out.push({
+                kind: "request",
                 file,
                 line: c.line,
                 method: c.method,
@@ -178,7 +181,7 @@ async function helperRoutes(utilsFiles, spec) {
 /** The generated siblings less the utils files themselves (a utils file carries no
  *  codegen marker, so this is belt and braces). Pre-read siblings are used as given —
  *  the caller's walk decides whether the spec itself is among them. */
-async function nonUtilsSiblings(testFile, utilsFiles, spec, preReadSiblings, includeSelf) {
+export async function nonUtilsSiblings(testFile, utilsFiles, spec, preReadSiblings, includeSelf) {
     const utilsSet = new Set(await Promise.all(utilsFiles.map((f) => realpath(f))));
     return (preReadSiblings ??
         (await generatedSiblings(testFile, spec, { includeSelf }))).filter((sib) => !utilsSet.has(path.resolve(sib.file)));
@@ -189,7 +192,7 @@ async function nonUtilsSiblings(testFile, utilsFiles, spec, preReadSiblings, inc
  *  commented-out or quoted request is never a site and a `)` inside a string never
  *  truncates the argument text, which is read from the original. */
 function requestCallsIn(content, spec) {
-    const localHelpers = parseUtilsFile(content, spec).filter((h) => !/^test/i.test(h.name));
+    const localHelpers = localHelpersOf(content, spec);
     const scan = blankCommentsAndStrings(content, spec);
     const out = [];
     for (const m of scan.matchAll(REQUEST_CALL_RE)) {
@@ -205,7 +208,7 @@ function requestCallsIn(content, spec) {
         if (!method || !pm || !isSingleLiteral(call, pm))
             continue;
         const p = pm[1];
-        const owner = localHelpers.find((h) => line >= h.line && line <= h.endLine);
+        const owner = localHelperAt(localHelpers, line);
         out.push({
             line,
             start,

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

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

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

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

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

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

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

@@ -10,7 +10,7 @@
  * 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 { HELPER_ASSERTION_POLICIES, CONTENT_ROLES, } from "../../prompts/shared-helper-policy.js";
+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
@@ -228,7 +228,7 @@ const ROLE_WITH_NAME_RE = /\b(?:getByRole|get_by_role)\s*\(\s*["'`]([A-Za-z]+)["
  * 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.
  */
-function expectArgs(expr) {
+export function expectArgs(expr) {
     const open = expr.indexOf("(", expr.indexOf("expect"));
     // `.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
@@ -325,6 +325,14 @@ export const HELPER_FAMILIES = {
         isAllowed: (spec, expr) => spec.allowedAssertion.test(expr),
         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",
@@ -336,6 +344,12 @@ export const HELPER_FAMILIES = {
             !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/parse.d.ts

@@ -44,8 +44,10 @@ export interface UtilsHelper {
     /** The helper's Playwright action sequence — the duplicate key of a browser
      *  helper, where an API helper has method+path. See actionKeyOf. Read for
      *  TypeScript, JavaScript and Python (through the JavaScript spelling); absent
-     *  for a helper with no readable action. */
+     *  for a helper with no readable action. `actionSteps` is the same sequence one
+     *  step per entry, for the sibling scan that matches step by step. */
     actionKey?: string;
+    actionSteps?: string[];
 }
 /** The declared parameters of a signature, raw text trimmed, empty entries dropped
  *  (a trailing comma). Reads the signature from the definition line to its body
@@ -91,6 +93,13 @@ export declare function unusableParamTypesOf(sigLines: string[]): string[];
  * next non-blank column-0 line; TS/JS bodies end when the brace depth opened by
  * the definition returns to zero.
  */
+/** A generated TEST's own module-level helpers: what parseUtilsFile reads from it,
+ *  less the test functions themselves (`test_…` / `testUi`), which are not helpers a
+ *  call can sit "inside" in the sense the sibling scans and the body-reach check
+ *  report. */
+export declare function localHelpersOf(content: string, spec: UtilsLanguageSpec): UtilsHelper[];
+/** The helper whose body holds `line` (1-based), if any. */
+export declare function localHelperAt(helpers: UtilsHelper[], line: number): UtilsHelper | undefined;
 export declare function parseUtilsFile(content: string, spec: UtilsLanguageSpec): UtilsHelper[];
 /** True when the `path` value is a single string literal ending the argument — a
  *  concatenation (`"/api/orders/" + str(id) + "/items"`) has no route this can name. */

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

@@ -1,5 +1,11 @@
 import { normalizePath } from "./language-spec.js";
-import { actionKeyOf } from "./action-key.js";
+import { actionStepKeys, actionStepsOf, } from "./action-key.js";
+/** A helper's action steps and their joined key, read once from its body. */
+function actionSequence(body, language) {
+    const steps = actionStepsOf(body, language);
+    const keys = actionStepKeys(steps);
+    return keys ? { actionKey: keys.join("; "), actionSteps: keys } : {};
+}
 import { fixedSleepsIn, pythonSleepBindings, } from "./fixed-sleep.js";
 import { stripComments, stripCommentsAndStrings, stripStrings, } from "../pom-scope/strip.js";
 /** Whether the `<` at `i` opens a generic (`Record<string, …>`, `Array<{…}>`) rather
@@ -204,6 +210,17 @@ export function unusableParamTypesOf(sigLines) {
  * next non-blank column-0 line; TS/JS bodies end when the brace depth opened by
  * the definition returns to zero.
  */
+/** A generated TEST's own module-level helpers: what parseUtilsFile reads from it,
+ *  less the test functions themselves (`test_…` / `testUi`), which are not helpers a
+ *  call can sit "inside" in the sense the sibling scans and the body-reach check
+ *  report. */
+export function localHelpersOf(content, spec) {
+    return parseUtilsFile(content, spec).filter((h) => !/^test/i.test(h.name));
+}
+/** The helper whose body holds `line` (1-based), if any. */
+export function localHelperAt(helpers, line) {
+    return helpers.find((h) => line >= h.line && line <= h.endLine);
+}
 export function parseUtilsFile(content, spec) {
     const lines = content.split("\n");
     // Structure — where a body ends — is read on a copy with comments and string
@@ -263,7 +280,7 @@ export function parseUtilsFile(content, spec) {
             fixedSleeps: fixedSleepsIn(body, scan, spec.language, params ?? [], start + 1, sleepBindings),
             // Comments blanked, strings kept: a commented-out click is not a step, and
             // the selector literals are the key.
-            actionKey: actionKeyOf(blankComments(body.join("\n"), spec), spec.language),
+            ...actionSequence(blankComments(body.join("\n"), spec), spec.language),
         };
         let requests = 0;
         for (let k = 0; k < body.length; k++) {

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

@@ -50,8 +50,9 @@ export interface UtilsVerifyResult {
      *  a helper that issues an SDK request is judged by the api rules regardless. See
      *  helperFamilyOf. */
     fallbackFamily: HelperFamilySpec;
-    /** Advisory (does not affect `ok`): inline request calls in sibling generated tests
-     *  that a utils helper already wraps — see findSiblingInlineCallSites. API family only. */
+    /** Advisory (does not affect `ok`): inline request calls (integration) or inline
+     *  action sequences (seeded UI) in sibling generated tests that a utils helper
+     *  already wraps — see findSiblingInlineCallSites. */
     inlineCallSites: InlineCallSite[];
     /** Advisory (does not affect `ok`): operations written in two or more sibling
      *  generated tests (this one included) that NO utils helper wraps — the extraction

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

@@ -7,10 +7,12 @@ import { typecheckDelivered } from "./typecheck.js";
 import { blankComments, blankCommentsAndStrings, countAssertions, hasPageErrorGuard, parseUtilsFile, } from "./parse.js";
 import { escapeRegExp } from "../regex.js";
 import { detectGitRoot } from "../gitStaging.js";
-import { isModularizeFirstTarget } from "../reuseRouting.js";
+import { inlineCallSiteFamily, isModularizeFirstTarget, } from "../reuseRouting.js";
+import { describeActionKey } from "./action-key.js";
 import { findDuplicateBodyReach, findUnreachableBodies } from "./body-reach.js";
 import { misnamedNewModules } from "./module-name.js";
 import { additiveChanges, locateInHouseModules, resolveInHouseCalls, } from "./in-house.js";
+import { findSiblingInlineActionSites } from "./action-sites.js";
 import { findSiblingInlineCallSites, findUnextractedDuplicates, generatedSiblings, } from "./call-sites.js";
 import { parseUtilsAllows, } from "./allow.js";
 import { describeFixedSleeps, fixedSleepReplacement } from "./fixed-sleep.js";
@@ -633,17 +635,24 @@ export async function verifyUtils(params) {
             });
     result.ok =
         result.violations.length === 0 && result.malformedAllows.length === 0;
-    // Integration only — the same gate as the prompt rule. `contract`, `load` and an
-    // absent type also resolve to the API family, but the reuse flow never targets them,
-    // so an advisory (and a report count) there would describe reuse the feature could
-    // not have taken.
-    if ((params.testType ?? "").toLowerCase() === "integration") {
+    // The gate the prompt renders the rule on: one predicate, so the advisory can
+    // never describe a rewiring the prompt did not ask for.
+    const scanFamily = inlineCallSiteFamily(params.testType, spec.language);
+    if (scanFamily) {
         try {
-            result.inlineCallSites = await findSiblingInlineCallSites(params.testFile, utilsFiles, allHelpers, spec, siblings);
+            result.inlineCallSites =
+                scanFamily === "api"
+                    ? await findSiblingInlineCallSites(params.testFile, utilsFiles, allHelpers, spec, siblings)
+                    : await findSiblingInlineActionSites(params.testFile, helpersByFile, spec, siblings);
         }
         catch {
             /* advisory only — never fails a verify */
         }
+    }
+    // Integration only — `contract`, `load` and an absent type also resolve to the API
+    // family, but the reuse flow never targets them.
+    const integration = (params.testType ?? "").toLowerCase() === "integration";
+    if (integration) {
         try {
             result.unextractedDuplicates = await findUnextractedDuplicates(params.testFile, utilsFiles, spec, siblings);
         }
@@ -953,14 +962,3 @@ incumbents = new Set()) {
     }
     return out;
 }
-/** `click empty-cart-btn; fill qty` → `click \`empty-cart-btn\`; fill \`qty\`` — the
- *  key as the agent reads it, selectors quoted so a `#id` never reads as prose. */
-function describeActionKey(key) {
-    return key
-        .split("; ")
-        .map((step) => {
-        const at = step.indexOf(" ");
-        return `${step.slice(0, at)} \`${step.slice(at + 1)}\``;
-    })
-        .join("; ");
-}