@skyramp/mcp 0.4.1 → 0.4.2-rc.2

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

@@ -1,5 +1,12 @@
 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
  *  than comparing (`i < 3`): a generic follows an identifier or `>` and is followed
@@ -41,8 +48,14 @@ function bracketStep(sig, i, d) {
  *  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 function signatureParams(sigLines) {
+export function signatureParams(sigLines, 
+/** The same lines with only comments blanked, offsets preserved. When given, the
+ *  parameters are SPLIT on `sigLines` (string contents blanked, so a comma inside
+ *  a default never splits) and READ from these, so a default keeps its value —
+ *  the additive gate compares that value against the body it replaced. */
+rawLines) {
     const sig = sigLines.join(" ");
+    const raw = rawLines ? rawLines.join(" ") : sig;
     // The parameter list's `(` is the first one outside a generic: a constraint may
     // hold parentheses of its own (`<T extends (a: string) => void>(page, cb)`).
     let open = -1;
@@ -71,34 +84,90 @@ export function signatureParams(sigLines) {
     if (close === -1)
         return undefined;
     const params = [];
-    let cur = "";
+    let from = open + 1;
     const e = { depth: 0, angle: 0 };
     for (let i = open + 1; i < close; i++) {
-        const ch = sig[i];
         bracketStep(sig, i, e);
-        if (ch === "," && e.depth === 0) {
-            params.push(cur);
-            cur = "";
+        if (sig[i] === "," && e.depth === 0) {
+            params.push(raw.slice(from, i));
+            from = i + 1;
         }
-        else
-            cur += ch;
     }
-    params.push(cur);
+    params.push(raw.slice(from, close));
     // Python's bare `*` and `/` are keyword-only / positional-only MARKERS, not
     // parameters.
     return params
         .map((p) => p.trim())
         .filter((p) => p !== "" && p !== "*" && p !== "/");
 }
-/** The parameter names in a TS signature that carry no `: type`. */
-export function untypedParamsOf(sigLines) {
+/** The index of the `=` that opens a parameter's default value, or -1. Depth-aware,
+ *  so an `=` inside a parenthesised type, an object type or a generic is not one;
+ *  `=>`, `==`, `!=`, `<=` and `>=` are not one either.
+ *
+ *  The ONE detection of a default: the typing advisory reads it, the status rule
+ *  reads it, and the additive gate reads the value that follows it. They must not
+ *  disagree about what a default is. */
+export function defaultAt(param) {
+    let depth = 0;
+    for (let i = 0; i < param.length; i++) {
+        const ch = param[i];
+        if ("([{<".includes(ch))
+            depth++;
+        else if (")]}>".includes(ch)) {
+            // `=>` closes nothing; the `>` of a generic does.
+            if (!(ch === ">" && param[i - 1] === "="))
+                depth = Math.max(0, depth - 1);
+        }
+        else if (ch === "=" &&
+            depth === 0 &&
+            param[i + 1] !== ">" &&
+            param[i + 1] !== "=" &&
+            !"=!<>".includes(param[i - 1] ?? ""))
+            return i;
+    }
+    return -1;
+}
+/** Whether one declared parameter carries a default value. See defaultAt. */
+export function hasDefault(param) {
+    return defaultAt(param) !== -1;
+}
+/** The declared NAME of a parameter, less its annotation, default, rest / unpack
+ *  marker and optional `?`: `...rest: T[]` → `rest`, `expected_status=200` →
+ *  `expected_status`, `expectedStatus?: number` → `expectedStatus`. A binding
+ *  pattern has no single name and returns its text unchanged. */
+export function paramName(raw) {
+    return raw
+        .split("=")[0]
+        .split(":")[0]
+        .replace(/^\s*(?:\.\.\.|\*+)/, "")
+        .replace(/\?\s*$/, "")
+        .trim();
+}
+/** The parameters of a TS signature whose type gives a caller nothing to satisfy:
+ *  no annotation (`page`), `any` (checks nothing), or `unknown` (assignable to
+ *  nothing but itself, so every use of it fails, under every compiler setting).
+ *  Each entry is the name alone when unannotated, `name: any` / `name: unknown`
+ *  otherwise. */
+export function unusableParamTypesOf(sigLines) {
     const out = [];
     for (const raw of signatureParams(sigLines) ?? []) {
         const param = raw.replace(/^\.\.\./, "");
+        // Parenthesised spans dropped: a function-type annotation's own parameters
+        // and a call in a default value are not this parameter's annotation.
+        const flat = param.replace(/\([^)]*\)/g, "");
+        // `: any` compiles clean under noImplicitAny — the customer's compiler will
+        // NEVER report it, which makes it the one case this advisory can catch that
+        // tsc cannot (and the exact legacy convention SKYR-3324 wrote). `: unknown`
+        // fails at its first use, before or after a default: the annotation, not the
+        // default, decides the type, so the inference carve-out below does not apply.
+        const weak = /^([A-Za-z_$][\w$]*)\??\s*:\s*(any|unknown)\s*(?:=(?!>)|$)/.exec(flat);
+        if (weak) {
+            out.push(`${weak[1]}: ${weak[2]}`);
+            continue;
+        }
         // A default value means TypeScript infers the type — not a finding, even
-        // unannotated (`expectedStatus = 200`). `=>` inside a function-type
-        // annotation is not a default.
-        if (/=(?!>)/.test(param.replace(/\([^)]*\)/g, "")))
+        // unannotated (`expectedStatus = 200`).
+        if (hasDefault(param))
             continue;
         // A binding pattern's inner colons are renames, not annotations:
         // `{ page: browserPage }` is implicitly any unless a `:` follows the
@@ -113,18 +182,20 @@ export function untypedParamsOf(sigLines) {
                     break;
                 }
             }
-            if (after === -1 || !param.slice(after).trimStart().startsWith(":"))
-                out.push(param.replace(/\s+/g, " "));
+            const annotation = after === -1 ? "" : param.slice(after).trimStart();
+            const pattern = (after === -1 ? param : param.slice(0, after)).replace(/\s+/g, " ");
+            if (!annotation.startsWith(":"))
+                out.push(pattern);
+            else {
+                // `{ page }: any` is annotated, and as unusable as `page: any`.
+                const weakAnnotation = /^:\s*(any|unknown)\s*$/.exec(annotation.replace(/\([^)]*\)/g, ""));
+                if (weakAnnotation)
+                    out.push(`${pattern}: ${weakAnnotation[1]}`);
+            }
             continue;
         }
-        if (param.includes(":")) {
-            // `page: any` compiles clean under noImplicitAny — the customer's compiler
-            // will NEVER report it, which makes it the one case this advisory can catch
-            // that tsc cannot. It is also the exact legacy convention SKYR-3324 wrote.
-            if (/:\s*any\s*$/.test(param))
-                out.push(param.split(":")[0].trim().replace(/\?$/, "") + ": any");
+        if (param.includes(":"))
             continue;
-        }
         out.push(param.replace(/\?$/, ""));
     }
     return out;
@@ -139,6 +210,17 @@ export function untypedParamsOf(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
@@ -146,6 +228,10 @@ export function parseUtilsFile(content, spec) {
     // (`fill("{")`) or a `#` in a Python string must not move a helper's end and
     // swallow every helper after it.
     const structure = blankCommentsAndStrings(content, spec).split("\n");
+    // What THIS file binds to a sleep — read once, from its imports (Python only).
+    const sleepBindings = spec.language === "python"
+        ? pythonSleepBindings(content)
+        : { bare: new Set(), qualified: new Set() };
     const helpers = [];
     let i = 0;
     while (i < lines.length) {
@@ -174,6 +260,9 @@ export function parseUtilsFile(content, spec) {
         // The blanked copy: a comment inside a wrapped signature must not reach the
         // agent as a "parameter", and a comma inside a default string must not split one.
         const signature = signatureLines(scan);
+        const params = signatureParams(signature, blankComments(body.join("\n"), spec)
+            .split("\n")
+            .slice(0, signature.length));
         const helper = {
             name,
             line: start + 1,
@@ -181,11 +270,17 @@ export function parseUtilsFile(content, spec) {
             wrapsRequest: false,
             hasGuard: hasPageErrorGuard(body.join("\n"), spec),
             assertions: [],
-            untypedParams: spec.language === "typescript" ? untypedParamsOf(signature) : [],
-            arity: signatureParams(signature)?.length,
+            unusableParamTypes: spec.language === "typescript" ? unusableParamTypesOf(signature) : [],
+            arity: params?.length,
+            params,
+            // Read from the body while it is in hand, like actionKey: structure off the
+            // blanked copy, the shown text off the original. Takes the parameters main
+            // already read rather than reading the signature a second time — a parameter
+            // shadows a module's sleep binding, so the two must be the same list.
+            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++) {
@@ -266,10 +361,65 @@ export function isSingleLiteral(line, m) {
 export function blankStrings(src, spec) {
     if (spec.language !== "python")
         return stripStrings(src);
-    return src
-        .split("\n")
-        .map((line) => line.replace(/(["'])(?:\\.|(?!\1).)*\1/g, (q) => q[0] + " ".repeat(Math.max(0, q.length - 2)) + q[0]))
-        .join("\n");
+    return blankPythonStrings(src);
+}
+/**
+ * Blank every Python string literal, triple-quoted ones included, preserving offsets.
+ *
+ * A line-by-line regex cannot do this: a `"""…"""` block spans lines, so a `#` inside a
+ * docstring or an embedded SQL block read as a comment. Every scanner built on this
+ * then treated quoted text as code the file executes — and the delivery-time marker
+ * strip deleted a line out of a value rather than out of a comment.
+ */
+function blankPythonStrings(src) {
+    const out = src.split("");
+    const blank = (from, to) => {
+        for (let k = from; k < to; k++)
+            if (out[k] !== "\n")
+                out[k] = " ";
+    };
+    let i = 0;
+    const n = src.length;
+    while (i < n) {
+        const c = src[i];
+        // A comment runs to the end of the line and holds no string opener.
+        if (c === "#") {
+            while (i < n && src[i] !== "\n")
+                i++;
+            continue;
+        }
+        if (c !== '"' && c !== "'") {
+            i++;
+            continue;
+        }
+        // A string prefix (r, b, f, u, rb, …) is part of the literal, not of the quote.
+        const triple = src.startsWith(c.repeat(3), i);
+        const quote = triple ? c.repeat(3) : c;
+        const start = i;
+        i += quote.length;
+        let closed = false;
+        while (i < n) {
+            if (src[i] === "\\") {
+                i += 2;
+                continue;
+            }
+            if (src.startsWith(quote, i)) {
+                i += quote.length;
+                closed = true;
+                break;
+            }
+            // Only a triple-quoted literal may hold a raw newline.
+            if (src[i] === "\n" && !triple)
+                break;
+            i++;
+        }
+        if (!closed) {
+            i = start + 1;
+            continue;
+        }
+        blank(start + quote.length, i - quote.length);
+    }
+    return out.join("");
 }
 /** Assertions in a source file: lines (Python) / occurrences (TS) matching the
  *  language's assertion pattern, with comments and string contents blanked so a
@@ -300,8 +450,10 @@ export function hasPageErrorGuard(content, spec) {
     return false;
 }
 /** Comments blanked, strings preserved, offsets kept. TS/JS use the shared stripper;
- *  Python blanks each line from its first `#` outside a string. */
-function blankComments(src, spec) {
+ *  Python blanks each line from its first `#` outside a string. Exported for the
+ *  readers that need a literal intact but a comment gone — an import's module
+ *  path is a string, and a commented-out import must not count. */
+export function blankComments(src, spec) {
     if (spec.language !== "python")
         return stripComments(src);
     const blanked = blankStrings(src, spec).split("\n");
@@ -318,14 +470,17 @@ function blankComments(src, spec) {
 export function blankCommentsAndStrings(src, spec) {
     if (spec.language !== "python")
         return stripCommentsAndStrings(src);
-    return src
+    // The same scanner `blankStrings` uses, so a docstring is hidden from BOTH. A
+    // line-by-line regex could only see a literal that opens and closes on one line, so
+    // an `expect(...)` inside a triple-quoted block counted as a delivered assertion and
+    // could hide a real loss. Comments are blanked afterwards, on the copy whose string
+    // contents are already gone, so a `#` inside a literal is not one.
+    return (blankPythonStrings(src)
         .split("\n")
-        .map((line) => line
-        .replace(/(["'])(?:\\.|(?!\1).)*\1/g, (q) => q[0] + " ".repeat(Math.max(0, q.length - 2)) + q[0])
-        // Blanked, not deleted: callers scan this copy for OFFSETS and read the text
-        // back out of the original, so every line must keep its length.
-        .replace(/#.*$/, (c) => " ".repeat(c.length)))
-        .join("\n");
+        // Blanked, not deleted: callers scan this copy for OFFSETS and read the text back
+        // out of the original, so every line must keep its length.
+        .map((line) => line.replace(/#.*$/, (c) => " ".repeat(c.length)))
+        .join("\n"));
 }
 function signatureLines(body) {
     // The signature runs until its parameter parentheses close: a `{` inside a

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

@@ -41,3 +41,8 @@ export interface RetrofitMismatch {
  * than a refusal the agent cannot act on.
  */
 export declare function retrofitMismatches(retrofitFile: string, utilsFiles: string[], spec: UtilsLanguageSpec): Promise<RetrofitMismatch[]>;
+/** The file's content at HEAD, or undefined when there is nothing to compare against
+ *  (untracked, no git root, or git unavailable). Never throws. The ONE reader of a
+ *  file's committed baseline on the utils path: the incumbent-signature gate reads
+ *  the utils module through it too. */
+export declare function committedBaseline(file: string): Promise<string | undefined>;

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

@@ -192,8 +192,10 @@ function sameSet(a, b) {
     return true;
 }
 /** The file's content at HEAD, or undefined when there is nothing to compare against
- *  (untracked, no git root, or git unavailable). Never throws. */
-async function committedBaseline(file) {
+ *  (untracked, no git root, or git unavailable). Never throws. The ONE reader of a
+ *  file's committed baseline on the utils path: the incumbent-signature gate reads
+ *  the utils module through it too. */
+export async function committedBaseline(file) {
     const root = detectGitRoot(file);
     if (!root)
         return undefined;

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

@@ -26,5 +26,10 @@ export interface StagingResult {
      *  the tests importing them will fail in the output commit, so the verify pass
      *  treats a non-empty list as a failed verification. */
     failed: string[];
+    /** The repository's own modules the spec imports that this run CHANGED (absolute)
+     *  — a helper added to the customer's file. Staged like the utils file: the module
+     *  may sit above the test directory the action sweeps, and a test importing a
+     *  helper the output commit does not carry fails for everyone else. */
+    inHouse: string[];
 }
 export declare function stageUtilsArtifacts(testFile: string, language?: string): Promise<StagingResult>;

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

@@ -6,6 +6,7 @@ import { detectGitRoot, stageGeneratedPaths } from "../gitStaging.js";
 import { logger } from "../logger.js";
 import { isTestbotEnabled } from "../featureFlags.js";
 import { locateUtilsFiles, realpath } from "./locate.js";
+import { locateInHouseModules } from "./in-house.js";
 import { CODEGEN_MARKER_RE } from "./call-sites.js";
 import { utilsSpecFor, utilsSpecForFile } from "./language-spec.js";
 const execFileAsync = promisify(execFile);
@@ -14,7 +15,14 @@ export async function stageUtilsArtifacts(testFile, language) {
     const failed = [];
     const utilsFilesOut = [];
     const retrofits = [];
-    const result = { staged, failed, utilsFiles: utilsFilesOut, retrofits };
+    const inHouse = [];
+    const result = {
+        staged,
+        failed,
+        utilsFiles: utilsFilesOut,
+        retrofits,
+        inHouse,
+    };
     // Outside a testbot run stageGeneratedPaths is a no-op; report nothing as staged
     // rather than a list of files nothing touched.
     if (!isTestbotEnabled())
@@ -42,6 +50,20 @@ export async function stageUtilsArtifacts(testFile, language) {
             failed.push(file);
         }
     }
+    for (const module of await modifiedInHouseModules(testFile, language)) {
+        inHouse.push(module);
+        try {
+            await stageGeneratedPaths(module);
+            staged.push(module);
+        }
+        catch (err) {
+            logger.warning("Could not stage an in-house module this run extended", {
+                file: module,
+                error: String(err),
+            });
+            failed.push(module);
+        }
+    }
     // Sibling generated tests this run EDITED to import from the utils file (STEP 5c, or
     // a maintenance update): tracked, modified, codegen-marked, importing a located utils
     // stem. Discovery staged only the current test and the loop above only the utils
@@ -65,9 +87,32 @@ export async function stageUtilsArtifacts(testFile, language) {
     }
     return result;
 }
-async function modifiedSiblingsImporting(testFile, utilsFiles, language) {
+/** The in-house modules the spec imports that differ from HEAD — what this run
+ *  added to. Tracked-and-modified only: an untracked module is not in-house, and an
+ *  unchanged one carries nothing of this run's. Never throws. */
+async function modifiedInHouseModules(testFile, language) {
     const spec = utilsSpecFor(language) ?? utilsSpecForFile(testFile);
     const root = detectGitRoot(testFile);
+    if (!spec || !root)
+        return [];
+    try {
+        const modules = await locateInHouseModules({ testFile, spec, cwd: root });
+        if (modules.length === 0)
+            return [];
+        const { stdout } = await execFileAsync("git", ["diff", "-z", "--name-only", "--diff-filter=M", "HEAD"], { cwd: root, encoding: "utf8" });
+        const modified = new Set();
+        for (const rel of stdout.split("\0").filter(Boolean))
+            modified.add(await realpath(path.resolve(root, rel)));
+        return modules.map((m) => m.file).filter((f) => modified.has(f));
+    }
+    catch (err) {
+        logger.warning("Could not list the in-house modules this run changed — none will be staged", { testFile, error: String(err) });
+        return [];
+    }
+}
+async function modifiedSiblingsImporting(testFile, utilsFiles, language) {
+    const spec = utilsSpecForFile(testFile) ?? utilsSpecFor(language);
+    const root = detectGitRoot(testFile);
     if (!spec || !root)
         return [];
     let modified;

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

@@ -0,0 +1,62 @@
+import { type HelperAssertion, type UtilsHelper } from "./parse.js";
+import { type UtilsLanguageSpec } from "./language-spec.js";
+/** The helper's status-only assertions, as the language spec recognises them. */
+export declare function statusAssertions(h: UtilsHelper, spec: UtilsLanguageSpec): HelperAssertion[];
+/** Whether the helper pins the status to ONE value — an equality whose operand IS
+ *  the status, not a bound or a set (`toBeLessThan(500)`, `in (200, 201)`), and not
+ *  an equality elsewhere in the same assertion (`… < 500 and attempts == 1`). Only
+ *  then is a status assertion in the spec a restatement rather than a tighter
+ *  claim. A `.not.` form pins nothing. */
+export declare function assertsStatusEquality(h: UtilsHelper, spec: UtilsLanguageSpec): boolean;
+export interface DefaultedStatusParam {
+    /** The parameter as declared — `expectedStatus = 200`, `expected_status=None`. */
+    param: string;
+    name: string;
+}
+/**
+ * The parameter the helper's status assertion READS, when it carries a default (or
+ * is optional). `undefined` when the helper asserts no status, when its status
+ * assertion reads a literal rather than a parameter, or when the parameter has no
+ * default.
+ *
+ * Keyed on the assertion, not on the parameter's name: the same cohort that produced
+ * the evidence spelled it `expectedStatus` in one module and `expectedStatusCode` in
+ * another, and a name-matched rule misses whichever spelling the next run picks. A
+ * `None` default counts — a helper whose assertion is switched off by default lets
+ * a caller read the status without verifying it.
+ */
+export declare function defaultedStatusParam(h: UtilsHelper, spec: UtilsLanguageSpec): DefaultedStatusParam | undefined;
+/** The declared parameter the helper's status assertion reads, or `undefined` when
+ *  the helper asserts no status or compares it against a literal. */
+export declare function statusParamOf(h: UtilsHelper, spec: UtilsLanguageSpec): DefaultedStatusParam | undefined;
+/** The literal a helper pins the status to (`200`), when it pins one and reads no
+ *  parameter for it — the shape whose restatement cannot be fixed by deleting the
+ *  spec's assertion alone, because the call has no status argument to keep. */
+export declare function pinnedStatusLiteral(h: UtilsHelper, spec: UtilsLanguageSpec): string | undefined;
+export interface RestatedStatus {
+    helper: string;
+    /** 1-based spec line of the first restating assertion. */
+    line: number;
+    /** That assertion, as written. */
+    text: string;
+    /** How many call sites of this helper restate the status. */
+    sites: number;
+}
+/**
+ * Call sites in the spec whose returned response the spec then asserts the status
+ * of — for helpers that already assert it. One finding per helper, with the count.
+ *
+ * The link from call to assertion is the RESPONSE VARIABLE: the call's result is
+ * bound to a name (`const r = await getOrder(…)`, `r = get_order(…)`), and a later
+ * line asserts on `<that name>.status…` before the name is assigned again. Read on
+ * a copy with comments and string contents blanked, so a commented-out call or a
+ * quoted example binds nothing, and it stops at the next function or test block,
+ * which binds its own names. What this cannot see: a destructured result
+ * (`const { statusCode } = await …`), a call passed straight into an assertion
+ * (`expect((await getOrder(…)).status)`), an alias of the status (`const s =
+ * r.status`), a helper called under an import alias, and a response threaded through
+ * a further call or a `.then`. Each is a miss, never a false finding.
+ */
+export declare function restatedStatusAssertions(specContent: string, spec: UtilsLanguageSpec, helpers: readonly string[], 
+/** Names the spec binds the utils module to — see UtilsLanguageSpec.moduleQualifiers. */
+qualifiers?: readonly string[]): RestatedStatus[];