@skyramp/mcp 0.4.0 → 0.4.1-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 { parseUtilsFile } from "./parse.js";
+import { blankCommentsAndStrings, isSingleLiteral, parseUtilsFile, } from "./parse.js";
 import { normalizePath } from "./language-spec.js";
 import { realpath } from "./locate.js";
 import { escapeRegExp } from "../regex.js";
@@ -12,9 +12,10 @@ export const CODEGEN_MARKER_RE = new RegExp(`${SKYRAMP_UTILS_HEADER.replace(/[.*
 const HEADER_SCAN_LINES = 5;
 /**
  * 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 async function generatedSiblings(testFile, spec, opts) {
     let dir;
@@ -55,21 +56,94 @@ export const REQUEST_CALL_RE = /\b(?:send_request|sendRequest)\s*\(/g;
  * 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 async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers, spec, preReadSiblings) {
-    // 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.
-    // `fields` and `schemaChecked` carry the two things keyword shape cannot see; see
-    // substitutable().
+    const byRoute = await helperRoutes(utilsFiles, spec);
+    if (byRoute.size === 0)
+        return [];
+    const siblings = await nonUtilsSiblings(testFile, utilsFiles, spec, preReadSiblings, false);
+    const self = await realpath(testFile);
+    const out = [];
+    for (const { file, content } of siblings) {
+        if (path.resolve(file) === self)
+            continue;
+        for (const c of requestCallsIn(content, spec)) {
+            const match = byRoute.get(c.key);
+            if (!match)
+                continue;
+            if (!sameShape(callShape(c.call), match.keys))
+                continue;
+            if (!substitutable(match, {
+                fields: requestFields(content, c.call, c.start),
+                query: queryKeys(c.call),
+                schemaChecked: hasSchemaCheck(content, c.line, c.line + SCHEMA_SCAN_LINES),
+            }))
+                continue;
+            out.push({
+                file,
+                line: c.line,
+                method: c.method,
+                path: c.path,
+                helper: match.helper,
+                utilsFile: match.utilsFile,
+                ...(c.localHelper ? { localHelper: c.localHelper } : {}),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * 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 async function findUnextractedDuplicates(testFile, utilsFiles, spec, preReadSiblings) {
+    const covered = new Set((await helperRoutes(utilsFiles, spec)).keys());
+    const siblings = await nonUtilsSiblings(testFile, utilsFiles, spec, preReadSiblings, true);
+    const groups = new Map();
+    for (const { file, content } of siblings) {
+        for (const c of requestCallsIn(content, spec)) {
+            if (covered.has(c.key))
+                continue;
+            const shape = [...callShape(c.call)].sort().join(",");
+            const k = `${c.key}\0${shape}`;
+            const group = groups.get(k) ?? {
+                method: c.method,
+                path: c.path,
+                sites: [],
+            };
+            group.sites.push({ file, line: c.line, localHelper: c.localHelper });
+            groups.set(k, group);
+        }
+    }
+    return [...groups.values()].filter((g) => new Set(g.sites.map((s) => s.file)).size >= 2);
+}
+async function helperRoutes(utilsFiles, spec) {
     const byRoute = new Map();
     for (const utilsFile of utilsFiles) {
         let content;
@@ -91,47 +165,56 @@ export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers,
             const call = callText(content, start + m[0].length - 1);
             byRoute.set(`${owner.method} ${owner.normalizedPath}`, {
                 helper: owner.name,
-                keys: shapeKeys(call),
+                utilsFile,
+                keys: callShape(call),
                 fields: requestFields(content, call, start),
+                query: queryKeys(call),
                 schemaChecked: hasSchemaCheck(content, owner.line, owner.endLine),
             });
         }
     }
-    if (byRoute.size === 0)
-        return [];
+    return byRoute;
+}
+/** 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) {
     const utilsSet = new Set(await Promise.all(utilsFiles.map((f) => realpath(f))));
-    const siblings = (preReadSiblings ??
-        (await generatedSiblings(testFile, spec, { includeSelf: false }))).filter((sib) => !utilsSet.has(path.resolve(sib.file)));
-    const self = await realpath(testFile);
+    return (preReadSiblings ??
+        (await generatedSiblings(testFile, spec, { includeSelf }))).filter((sib) => !utilsSet.has(path.resolve(sib.file)));
+}
+/** Every keyable request call in a generated test. Calls whose method or path cannot
+ *  be read are skipped: they have no route to compare. Calls are located, and their
+ *  parentheses balanced, on a comment/string-blanked copy (offsets preserved), so a
+ *  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 scan = blankCommentsAndStrings(content, spec);
     const out = [];
-    for (const { file, content } of siblings) {
-        if (path.resolve(file) === self)
+    for (const m of scan.matchAll(REQUEST_CALL_RE)) {
+        const start = m.index ?? 0;
+        const line = content.slice(0, start).split("\n").length;
+        const open = start + m[0].length - 1;
+        const call = content.slice(open, callEnd(scan, open));
+        const method = spec.methodRe.exec(call)?.[1]?.toUpperCase();
+        const pm = spec.pathRe.exec(call);
+        // Keyed on ONE literal, as helpers are (parseUtilsFile): a concatenated path's
+        // first literal is not the operation — it would read as copies of a route that
+        // does not exist, or match a helper for the parent route.
+        if (!method || !pm || !isSingleLiteral(call, pm))
             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;
-            if (!substitutable(match, {
-                fields: requestFields(content, call, start),
-                schemaChecked: hasSchemaCheck(content, line, line + SCHEMA_SCAN_LINES),
-            }))
-                continue;
-            out.push({ file, line, method, path: p, helper: match.helper });
-        }
+        const p = pm[1];
+        const owner = localHelpers.find((h) => line >= h.line && line <= h.endLine);
+        out.push({
+            line,
+            start,
+            call,
+            method,
+            path: p,
+            key: `${method} ${normalizePath(p)}`,
+            localHelper: owner?.name,
+        });
     }
     return out;
 }
@@ -147,6 +230,10 @@ export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers,
  *    `dataOverride` are liftable *keywords*, so their mere presence matched; their
  *    contents never got compared. (ghost `pr-scheduled-publishing`: a scheduled-post
  *    helper offered for a draft-post call, declined for exactly this reason.)
+ *  - **Query keys the site does not send.** The same as fields, for the query: a
+ *    helper sending `?page=` offered for a site sending `?status=` adds a parameter.
+ *    Query keys were in neither the shape (quoted keys never matched) nor the fields
+ *    (`query_params` is stripped there on purpose), so nothing told the two apart.
  *  - **A schema-checked site.** When the site feeds its response to `check_schema`
  *    against a per-file expected body and the helper wraps no such check, replacing
  *    the block either drops the contract assertion or redesigns the file. That is a
@@ -160,6 +247,11 @@ function substitutable(helper, site) {
     for (const f of helper.fields)
         if (!site.fields.has(f))
             return false;
+    // The body rule, applied to the query: a `?page=` helper offered for a `?status=`
+    // site would add a parameter to the sibling's request. See queryKeys().
+    for (const q of helper.query)
+        if (!site.query.has(q))
+            return false;
     return helper.schemaChecked === site.schemaChecked;
 }
 /** Lines after a call scanned for its schema assertion — the generated shape puts it
@@ -208,9 +300,18 @@ export function requestFields(content, call, callAt) {
     // TS shorthand inside an override object — `dataOverride: { status, title }` names
     // the same fields as `{ "status": status }` but carries neither quotes nor a colon,
     // so the pattern above cannot see it and the field would compare as absent.
-    for (const region of overrideObjects(body))
-        for (const m of region.matchAll(/(?:^|[{,])\s*([A-Za-z_$][\w$]*)\s*(?=[,}])/g))
+    for (const region of keyedObjects(body, OVERRIDE_OBJECT_RE))
+        for (const m of region.matchAll(SHORTHAND_KEY_RE))
             add(m[1]);
+    // An inline TS body literal — `body: { title: t, status: "draft", tags }` — carries
+    // UNQUOTED keys (and shorthand), which the quoted pattern above cannot see either.
+    // With no fields read, `substitutable` had nothing to compare and offered a helper
+    // whose substitution would ADD a field to the sibling's request — the very case it
+    // exists to refuse. Python passes `body=IDENT` (read below) or a quoted dict, so
+    // nothing changes there.
+    for (const region of keyedObjects(body, BODY_OBJECT_RE))
+        for (const k of literalKeys(region))
+            add(k);
     // `body=IDENT` / `body: IDENT` → the identifier's assignment elsewhere in the file.
     const ref = /\bbody\s*[=:]\s*([A-Za-z_$][\w$]*)/.exec(call);
     if (ref) {
@@ -253,26 +354,108 @@ export function requestFields(content, call, callAt) {
     }
     return out;
 }
-/** The `{…}` text of each `data_override` / `dataOverride` argument in a call. */
-function overrideObjects(call) {
+const OVERRIDE_OBJECT_RE = /\b(?:data_override|dataOverride)\s*[=:]\s*\{/g;
+const BODY_OBJECT_RE = /\b(?:body|data)\s*[=:]\s*\{/g;
+const QUERY_OBJECT_RE = /\b(?:query_params|queryParams)\s*[=:]\s*\{/g;
+/** A bare identifier between `{`/`,` and `,`/`}` — TS object shorthand. */
+const SHORTHAND_KEY_RE = /(?:^|[{,])\s*([A-Za-z_$][\w$]*)\s*(?=[,}])/g;
+/** One quoted string, any of the three quote kinds, escapes honoured. */
+const STRING_LITERAL_RE = /(["'`])(?:\\.|(?!\1)[^\\])*\1/g;
+/** The key names written in one `{…}` object literal: quoted (`"page":`, either
+ *  language), unquoted (`page:`, TS) and shorthand (`page,`, TS). The unquoted and
+ *  shorthand passes run with string CONTENTS blanked, so `q: "a, b: c"` names one
+ *  key, not two. Nested keys are included; callers decide leaf semantics. */
+function literalKeys(region) {
+    const out = [];
+    for (const m of region.matchAll(/["'`]([A-Za-z_][\w.]*)["'`]\s*:/g))
+        out.push(m[1]);
+    const code = blankStringContents(region);
+    for (const m of code.matchAll(/(?:^|[{,])\s*([A-Za-z_$][\w$]*)\s*:(?!=)/g))
+        out.push(m[1]);
+    for (const m of code.matchAll(SHORTHAND_KEY_RE))
+        out.push(m[1]);
+    return out;
+}
+/**
+ * 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 function queryKeys(call) {
+    const out = new Set();
+    for (const region of keyedObjects(call, QUERY_OBJECT_RE))
+        for (const k of literalKeys(region))
+            out.add(k);
+    return out;
+}
+/** The `{…}` text of each argument in a call whose opener `keyRe` matches (a
+ *  `KEY: {` / `KEY={` pattern ending at the brace). */
+function keyedObjects(call, keyRe) {
+    // Boundaries come from the string-blanked copy (offsets preserved): a `{` inside
+    // a value (`q: "{"`) is payload, and counting it would run the object into the
+    // next argument. The text itself is taken from the original.
+    const scan = blankStringContents(call);
     const out = [];
-    for (const m of call.matchAll(/\b(?:data_override|dataOverride)\s*[=:]\s*\{/g)) {
+    for (const m of scan.matchAll(keyRe)) {
         const open = (m.index ?? 0) + m[0].length - 1;
-        let depth = 0;
-        for (let i = open; i < call.length; i++) {
-            if (call[i] === "{")
-                depth++;
-            else if (call[i] === "}") {
-                depth--;
-                if (depth === 0) {
-                    out.push(call.slice(open, i + 1));
-                    break;
-                }
-            }
-        }
+        out.push(call.slice(open, braceEnd(scan, open)));
+    }
+    return out;
+}
+/** `text` with the CONTENTS of every string literal replaced by spaces, quotes kept,
+ *  length preserved — so offsets found on the copy index into the original. */
+function blankStringContents(text) {
+    return text.replace(STRING_LITERAL_RE, (q) => q[0] + " ".repeat(Math.max(0, q.length - 2)) + q[0]);
+}
+/** 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 function callShape(call) {
+    return shapeKeys(withoutKeyedLiterals(call));
+}
+/** `call` with the interior of every keyed `{…}` value blanked, offsets kept. */
+function withoutKeyedLiterals(call) {
+    // Balanced on the string-blanked copy (see keyedObjects); the copy and the output
+    // are the same length, so one offset serves both.
+    let scan = blankStringContents(call);
+    let out = call;
+    const re = /\b[A-Za-z_$][\w$]*\s*[=:]\s*\{/g;
+    let m;
+    while ((m = re.exec(scan)) !== null) {
+        const open = m.index + m[0].length - 1;
+        const end = braceEnd(scan, open);
+        const blank = (t) => t.slice(0, open + 1) +
+            " ".repeat(Math.max(0, end - open - 2)) +
+            t.slice(Math.max(open + 1, end - 1));
+        out = blank(out);
+        scan = blank(scan);
+        re.lastIndex = end;
     }
     return out;
 }
+/** Index just past the `}` balancing the `{` at `open` (the text's end if unbalanced). */
+function braceEnd(text, open) {
+    let depth = 0;
+    for (let i = open; i < text.length; i++) {
+        if (text[i] === "{")
+            depth++;
+        else if (text[i] === "}") {
+            depth--;
+            if (depth === 0)
+                return i + 1;
+        }
+    }
+    return text.length;
+}
 /** 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([
@@ -305,16 +488,19 @@ function sameShape(a, b) {
 }
 /** Text of the parenthesised argument list starting at the `(` at `open`. */
 export function callText(content, open) {
+    return content.slice(open, callEnd(content, open));
+}
+/** Index just past the `)` balancing the `(` at `open` (the text's end if unbalanced). */
+function callEnd(text, open) {
     let depth = 0;
-    for (let i = open; i < content.length; i++) {
-        const ch = content[i];
-        if (ch === "(")
+    for (let i = open; i < text.length; i++) {
+        if (text[i] === "(")
             depth++;
-        else if (ch === ")") {
+        else if (text[i] === ")") {
             depth--;
             if (depth === 0)
-                return content.slice(open, i + 1);
+                return i + 1;
         }
     }
-    return content.slice(open);
+    return text.length;
 }

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

@@ -46,8 +46,9 @@ export declare const UTILS_LANGUAGE_SPECS: Record<UtilsLanguage, UtilsLanguageSp
  * 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.
+ * - `browser` (ui, e2e): a Playwright action sequence; equivalence is the action
+ *   sequence itself (verb + selector per step, see actionKeyOf) and is advised,
+ *   not enforced; the only assertions are structural waits.
  */
 export type HelperFamily = "api" | "browser";
 export interface HelperFamilySpec {

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

@@ -25,10 +25,26 @@ export interface UtilsHelper {
     /** TypeScript only: signature parameters with no type annotation (`page`, not
      *  `page: Page`). Empty for other languages. */
     untypedParams: string[];
+    /** Declared parameter count — defaulted and rest parameters included. Two
+     *  definitions of one name with different arities are the collision a caller
+     *  written against either signature hits. `undefined` when no signature could
+     *  be read. */
+    arity?: number;
+    /** 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. */
+    actionKey?: string;
 }
-/** The parameter names in a TS signature that carry no `: type`. Reads the signature
- *  from the definition line to its `{` (Prettier wraps long signatures), takes the
- *  first balanced `(...)`, and splits it on top-level commas. */
+/** 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
+ *  opener (Prettier wraps long signatures), takes the first balanced `(...)`, and
+ *  splits it on top-level commas — so a comma inside a default value, a generic, or
+ *  a binding pattern never splits. `undefined` when the text holds no readable
+ *  parameter list. Language-neutral: both a TS `{` and a Python `:` terminator lie
+ *  outside the parentheses this reads. */
+export declare function signatureParams(sigLines: string[]): string[] | undefined;
+/** The parameter names in a TS signature that carry no `: type`. */
 export declare function untypedParamsOf(sigLines: string[]): string[];
 /**
  * Structured extraction of the module-level helpers in a utils file.
@@ -41,6 +57,9 @@ export declare function untypedParamsOf(sigLines: string[]): string[];
  * the definition returns to zero.
  */
 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. */
+export declare function isSingleLiteral(line: string, m: RegExpExecArray): boolean;
 /** 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). */