@skyramp/mcp 0.4.1 → 0.4.2-rc.2

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

@@ -1,20 +1,69 @@
 import { blankStrings } from "./parse.js";
+import { commentSpans } from "../pom-scope/strip.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",
+    "unusable-parameter-type",
+    /** A shared helper waits for a DURATION rather than for a condition: a
+     *  `waitForTimeout`, a `time.sleep`, a promise-wrapped `setTimeout` — or one of
+     *  those as the backoff of a retry loop, where an iteration count hides the real
+     *  cost. Every test that imports the helper inherits the wait, and the call site
+     *  cannot see it. ADVISORY for its first cohort: the case for blocking rested on
+     *  the predicate being narrow enough that a false hit was unlikely, and review
+     *  falsified that three times — a helper NAMED `sleep`, a parameter shadowing the
+     *  name, and a bare call no import binds. The convergence lever is the prompt,
+     *  which states this rule in BROWSER_HELPERS' structuralNoise; the gate measures
+     *  what the prompt leaves. Promote once a cohort has counted the false-hit rate
+     *  instead of estimating it. See fixed-sleep.ts. */
+    "fixed-sleep",
+    /** A shared module this run CREATED under a name other than the one the reuse
+     *  prompt prescribes for its language, while that name was free. Two runs on one
+     *  repository then write two modules for one role and never meet. ADVISORY for its
+     *  first cohort: the convergence lever is the prompt, which states the rule, and
+     *  four of the six findings this rule's review produced were false BLOCKS — so the
+     *  false-hit rate is measured here before it is argued. Promote once a cohort has
+     *  counted it, on the same advisory-first policy as `fixed-sleep`. A module HEAD
+     *  already holds is never judged either way: renaming it breaks callers this run
+     *  cannot see. See module-name.ts. */
+    "module-name",
+    /** A shared API helper that reaches its own request body through TWO parameters at
+     *  once: a whole-body parameter, and an override parameter passed straight through.
+     *  The override can change nothing the body parameter cannot, so the second is a
+     *  choice no rule makes — which is how two runs wrote the same helper with
+     *  different arities. Advisory for the same reason as `module-name` and `fixed-sleep`,
+     *  and it carried three of that review's four false blocks. See bodyReachedTwice. */
+    "duplicate-body-reach",
     /** 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",
+    /** A compiler error present only under the repository's own tsconfig settings
+     *  (`noImplicitAny`, `strictNullChecks`, …). Whether that tsconfig is the one the
+     *  customer's build runs is their call, so this advises where `type-error` blocks. */
+    "tsconfig-type-error",
+    /** A name the compiler could not find (`process`, `describe`, `Promise`). Its
+     *  declarations come from a package the repository installs or from its `lib`
+     *  setting, neither of which the run can see — the testbot never installs the
+     *  repository's dependencies — so the customer's own `tsc` may accept it. Advised,
+     *  never blocked: a block here made an agent rewrite `process.env` into a
+     *  `globalThis` cast to get past the gate. */
+    "ambient-type-error",
+    /** A helper this run added to one of the repository's own modules performs an
+     *  action sequence a helper already in that module performs — the duplicate the
+     *  extension exists to avoid, now inside the customer's file. Advisory for the
+     *  same reason as `duplicate-action`: the key is read from selector literals. */
+    "in-house-duplicate",
 ];
 export const MARKERABLE_UTILS_KINDS = [
+    "frozen-body",
     "duplicate-helper",
     "body-assertion",
     "scenario-name",
     "assertion-loss",
+    "status-default",
+    "status-restated",
 ];
 /**
  * The documented-decline marker for a utils-file invariant, written in the utils file:
@@ -33,40 +82,115 @@ export const MARKERABLE_UTILS_KINDS = [
  * paste-ready line from the failure text when it was pasted unedited: publishing the
  * placeholder as the stated reason is worse than no marker.
  */
-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`);
+export 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*$`);
+/** Anything that announces a decline in this grammar, well-formed or not. Exported
+ *  so the delivery-time strip recognises the grammar from its one declaration here
+ *  rather than re-spelling it. */
+export const ALLOW_LOOSE_RE = /reuse-verify:\s*allow\b/;
+/** A marker at the START of what a comment says — either grammar. Anchored, because
+ *  the own-line rule is about what the comment opens with, not what it contains. */
+const MARKER_START_RE = /^(?:reuse-verify:\s*allow\b|kept inline:)/;
+/** THIS grammar at the start of what a comment says. `reuse-verify: allow` is not a
+ *  phrase a customer writes, so an own-line comment opening with it is gate-addressed
+ *  whatever follows — the delivery strip removes it without being able to READ it.
+ *  `kept inline:` cannot claim that: it opens ordinary English too. */
+export const ALLOW_START_RE = /^reuse-verify:\s*allow\b/;
+/** A marker's SHAPE, whatever kind it names: the announcement, then a subject, then
+ *  the separator and a reason. Ordinary prose that merely opens with the phrase — `//
+ *  kept inline: this loop is kept inline for performance` — carries no separator and
+ *  is not matched. Used where a line must be recognised as gate-addressed without the
+ *  grammar being able to READ it: an advisory kind is inert by design, so the verify
+ *  pass passes it and the comment would otherwise ship. */
+export const MARKER_SHAPE_RE = /^(?:reuse-verify:\s*allow\s+\S+\s+\S+|kept inline:\s*\S+)\s*(?:[—–]+|\s+-+\s+)\s*\S/;
+/** Former spellings of an advisory kind. Nothing emits them, but a utils file
+ *  delivered before the kind was renamed — and before the delivery strip of
+ *  2026-09-15 removed such lines — can still carry one, and a second run on that
+ *  repository must not refuse over a line that was inert when it shipped. */
+const LEGACY_ADVISORY_MARKER_KINDS = ["untyped-parameter"];
+/** A marker naming an advisory kind, current or former — inert, never malformed
+ *  (see parseUtilsAllows). */
+const ADVISORY_MARKER_RE = new RegExp(`allow\\s+(?:${[...UTILS_ADVISORY_KINDS, ...LEGACY_ADVISORY_MARKER_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>`;
 }
+/**
+ * The marker text, when the marker's comment OWNS its line: whitespace, the comment
+ * prefix, then the marker and nothing else.
+ *
+ * One placement, because it is the one both gates instruct and the only one that can
+ * be removed from a delivered file by deleting a line. A marker after code, inside a
+ * block comment or on a JSDoc continuation is reported as malformed instead — the
+ * decline is never dropped in silence, and the failure text gives back the line to
+ * paste in its place.
+ *
+ * A line whose first characters are the comment prefix cannot be a regex literal or a
+ * trailing comment, so this needs no lexer beyond the blanked strings. It cannot tell
+ * whether the prefix OPENS anything, though — inside `/* … *\/` a `//` opens nothing,
+ * the block does — so the caller settles that with `lineCommentOpeners` first. The
+ * parser asked the text while the strip asked the lexer, and a marker in a block
+ * comment was then read as a decline that the strip could not remove: the fault was
+ * authorised and the note shipped.
+ */
+export function markerOnOwnLine(raw, code, prefix) {
+    // Judged on the RAW line, not on the blanked copy. A blanked string leaves its
+    // quotes but loses its contents, so `"use strict" // kept inline: …` read as a line
+    // that opens with a comment — and the strip deleted the directive with it.
+    const trimmed = raw.trimStart();
+    if (!trimmed.startsWith(prefix))
+        return undefined;
+    // The comment must open the line AND the marker must open the comment. Otherwise
+    // `// Customer note; // kept inline: …` is one comment whose line the strip would
+    // delete, prose and all.
+    const body = trimmed.slice(prefix.length).trimStart();
+    return MARKER_START_RE.test(body) ? trimmed : undefined;
+}
+/**
+ * Line indices whose first non-space characters OPEN a line comment.
+ *
+ * `undefined` where the language has no block comment: every line with the prefix at
+ * its head opens one, and the caller needs no check. Stated ONCE, because the parser
+ * and the delivery strip must not disagree about which lines are comments — when they
+ * did, one authorised a decline the other refused to remove.
+ */
+export function lineCommentOpeners(content, prefix) {
+    if (prefix !== "//")
+        return undefined;
+    const starts = new Set(commentSpans(content).map((c) => c.start));
+    const opens = new Set();
+    let offset = 0;
+    content.split("\n").forEach((raw, n) => {
+        const indent = raw.length - raw.trimStart().length;
+        if (starts.has(offset + indent))
+            opens.add(n);
+        offset += raw.length + 1;
+    });
+    return opens;
+}
 export function parseUtilsAllows(content, spec) {
     const allows = [];
     const malformed = [];
-    // String contents are blanked first, so a marker (or a comment token) quoted in
-    // code can neither be read as a decline nor make one look like a comment.
+    // String contents are blanked first, so a marker quoted in code — or inside a Python
+    // docstring — can neither be read as a decline nor look like a comment.
     const rawLines = content.split("\n");
     const codeLines = blankStrings(content, spec).split("\n");
+    const opens = lineCommentOpeners(content, spec.commentPrefix);
     for (let n = 0; n < rawLines.length; n++) {
         const raw = rawLines[n];
         const code = codeLines[n] ?? "";
-        // The marker may sit in a trailing comment, a block comment or a JSDoc line — any
-        // comment form. Match from the marker itself, so the comment syntax around it does
-        // not decide whether a decline is read.
-        const at = code.search(ALLOW_LOOSE_RE);
-        if (at === -1)
+        if (!ALLOW_LOOSE_RE.test(code))
             continue;
-        const before = code.slice(0, at);
-        const inComment = spec.commentPrefix === "#"
-            ? /#/.test(before)
-            : /\/\/|\/\*|^\s*\*/.test(before);
-        if (!inComment)
+        const line = opens && !opens.has(n)
+            ? undefined
+            : markerOnOwnLine(raw, code, spec.commentPrefix);
+        if (line === undefined) {
+            // PLACEMENT is reported for every kind, the advisory kinds included. The
+            // advisory exemption says a kind never blocks; it does not say a marker may sit
+            // anywhere. Exempting placement too left a trailing advisory that the verify
+            // passed and the delivery strip could not remove — so the comment shipped.
+            malformed.push(raw.trim());
             continue;
-        const line = raw
-            .slice(at)
-            .replace(/\s*\*\/\s*$/, "")
-            .trim();
+        }
         const m = ALLOW_RE.exec(line);
         if (!m) {
             // A marker naming an advisory kind is inert, not malformed: advisories never
@@ -81,6 +205,7 @@ export function parseUtilsAllows(content, spec) {
             kind: m[1],
             helper: m[2],
             reason: m[3],
+            line: n + 1,
         });
     }
     return { allows, malformed };

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

@@ -0,0 +1,120 @@
+import type { UtilsLanguageSpec } from "./language-spec.js";
+import { type SiblingFile } from "./call-sites.js";
+/**
+ * A shared helper whose request body no parameter of its signature reaches, beside a
+ * spec that defines its OWN helper for the same route.
+ *
+ * The two halves together are the fault. A body the helper holds is not wrong on its
+ * own — on a first run there is one caller and its body is the right default. It
+ * becomes wrong the moment a second caller needs a different body, and the visible
+ * sign of that is a spec writing its own helper for a route the shared module already
+ * wraps. The advisory that names inline call sites cannot see this pair: it refuses a
+ * site whose payload the helper cannot send, which is exactly the site this looks for.
+ */
+export interface UnreachableBody {
+    /** The shared helper whose body is out of reach. */
+    helper: string;
+    /** Absolute path of the utils file that defines `helper`. */
+    utilsFile: string;
+    method: string;
+    /** The path as the helper writes it. */
+    path: string;
+    /** Absolute path of the spec that defines its own helper for the same route. */
+    rivalFile: string;
+    /** That spec's own helper — the caller the shared helper could not carry. */
+    rivalHelper: string;
+}
+/**
+ * The TOP-LEVEL options of a request call, as `name -> value text`.
+ *
+ * Both SDK spellings: the keyword arguments of `send_request(url=…, body=…)`, and the
+ * properties of the single object `sendRequest({ url: …, body })` takes. A shorthand
+ * property's value is its own name, which is what makes it a shorthand.
+ *
+ * Top-level is the whole point, and a regex could not hold it. Reading `body` or
+ * `data_override` anywhere in the call text made an option's value run to the first
+ * `)` — so an argument written AFTER the override joined its value — and made a name
+ * of the same spelling nested inside ANOTHER option read as the SDK's own, which
+ * blocks a delivery over something that is not there.
+ *
+ * Not `signatureParams`: that reads a parameter list, does not unwrap the object the
+ * TypeScript SDK takes, and expects text whose strings its caller already blanked.
+ * Here the call is raw — a path literal can carry a comma or a brace — so the
+ * structure is walked on a blanked copy and each value is cut from the original.
+ */
+export declare function requestOptions(call: string): Map<string, string>;
+/**
+ * The request's `body` option, as the text of its value, or `undefined` when the call
+ * sends no body.
+ *
+ * `shared-helper-policy` prescribes the object SHORTHAND as the canonical TypeScript
+ * form of body-form 2 — `updateOrder(client, orderId, body = DEFAULT_ORDER_BODY)`
+ * calling `sendRequest({ ..., body })` — so a reader that saw only `body:` judged the
+ * helper the prompt TEACHES as sending no body at all.
+ */
+export declare function bodyArgument(call: string): string | undefined;
+/** The request's override option, as the text of its value. Either spelling. */
+export declare function overrideArgument(call: string): string | undefined;
+/**
+ * Whether a caller can change what this request sends, through the helper's signature.
+ *
+ * The question is whether the body DERIVES from a parameter, not which mechanism
+ * carried it there. Naming the mechanisms would answer the shapes already seen and
+ * mis-judge the next one: the body as the parameter, an override map, and a local
+ * template with the parameters interpolated into it are three ways to reach the same
+ * property, and there is no reason to think they are the last three.
+ *
+ * FAILS OPEN — this feeds a blocking gate, so every answer it cannot establish is
+ * `true`. A request with no body has nothing to reach; a signature it cannot read is
+ * not judged. Only a body it can see, built from no parameter at all, is false.
+ *
+ * `before` is the helper text that precedes the request call. A body passed by name
+ * is resolved there: generated code assigns the template immediately above the call,
+ * so a parameter that reaches the body appears between that assignment and the call.
+ */
+export declare function bodyReachable(call: string, params: string[] | undefined, before?: string): boolean;
+/**
+ * The override parameter of a helper that reaches its own request body TWICE: once
+ * through a body parameter, and again through an override argument passed straight
+ * from the signature. `undefined` when the helper reaches its body through at most
+ * one of them.
+ *
+ * The prompt already states the rule — two body forms are offered and the helper
+ * takes "the FIRST one that reaches everything the callers need" — and nothing
+ * checked it. A body parameter reaches every property of the request body, so an
+ * override beside it can change nothing it cannot; carrying both is the hedge a run
+ * writes when no rule decides, and it is what made demoshop's `create_order` arity 5
+ * in one run and 4 in the other (testplan-run-9).
+ *
+ * The body must BE a parameter — form 2 as the policy states it. A body built at the
+ * call out of a parameter reaches only the properties it names, so an override beside
+ * it carries what the parameter cannot and the two are not one mechanism twice.
+ *
+ * The override must be a BARE PASS-THROUGH — the parameter and nothing else, a
+ * `or {}` / `?? {}` fallback aside. An override that BUILDS a map carries values the
+ * body parameter's default does not, which is the prompt's form 1 working; that is
+ * the shape a unique-suffix helper delivers, and it is not this fault.
+ *
+ * Reads the request call alone, never a body resolved from an assignment above it:
+ * this feeds a blocking gate, and the direct form is the one that cannot be read two
+ * ways.
+ */
+export declare function bodyReachedTwice(call: string, params: string[] | undefined): string | undefined;
+/** A helper reaching its request body through two parameters. */
+export interface DuplicateBodyReach {
+    helper: string;
+    /** Absolute path of the utils file that defines it. */
+    utilsFile: string;
+    /** 1-based line of the definition. */
+    line: number;
+    /** The override parameter the body parameter makes redundant. */
+    override: string;
+}
+/** Every helper in the located modules that reaches its request body twice. Never
+ *  throws; a file it cannot read contributes nothing. */
+export declare function findDuplicateBodyReach(utilsFiles: string[], spec: UtilsLanguageSpec): Promise<DuplicateBodyReach[]>;
+/**
+ * Shared helpers whose body no parameter reaches, each paired with a sibling spec
+ * that defines its own helper for the same route. Never throws; fails open to [].
+ */
+export declare function findUnreachableBodies(testFile: string, utilsFiles: string[], spec: UtilsLanguageSpec, preReadSiblings?: SiblingFile[]): Promise<UnreachableBody[]>;

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

@@ -0,0 +1,333 @@
+import * as fs from "fs";
+import { localHelpersOf, paramName, parseUtilsFile, signatureParams, } from "./parse.js";
+import { callText, generatedSiblings, REQUEST_CALL_RE, } from "./call-sites.js";
+/** Words a fallback idiom spells that name no value: `x or {}`, `x ?? {}`,
+ *  `x if x else None`. What remains after them is what the override actually sends. */
+const OVERRIDE_FILLER = new Set([
+    "or",
+    "and",
+    "if",
+    "else",
+    "None",
+    "null",
+    "undefined",
+    "True",
+    "False",
+    "true",
+    "false",
+]);
+/**
+ * The TOP-LEVEL options of a request call, as `name -> value text`.
+ *
+ * Both SDK spellings: the keyword arguments of `send_request(url=…, body=…)`, and the
+ * properties of the single object `sendRequest({ url: …, body })` takes. A shorthand
+ * property's value is its own name, which is what makes it a shorthand.
+ *
+ * Top-level is the whole point, and a regex could not hold it. Reading `body` or
+ * `data_override` anywhere in the call text made an option's value run to the first
+ * `)` — so an argument written AFTER the override joined its value — and made a name
+ * of the same spelling nested inside ANOTHER option read as the SDK's own, which
+ * blocks a delivery over something that is not there.
+ *
+ * Not `signatureParams`: that reads a parameter list, does not unwrap the object the
+ * TypeScript SDK takes, and expects text whose strings its caller already blanked.
+ * Here the call is raw — a path literal can carry a comma or a brace — so the
+ * structure is walked on a blanked copy and each value is cut from the original.
+ */
+export function requestOptions(call) {
+    const out = new Map();
+    const inert = blankStringContents(call);
+    let from = inert.indexOf("(");
+    if (from === -1)
+        return out;
+    let to = matching(inert, from);
+    if (to === -1)
+        return out;
+    from += 1;
+    // `sendRequest({ … })` — one object argument, whose PROPERTIES are the options.
+    const inner = inert.slice(from, to);
+    const open = inner.indexOf("{");
+    if (open !== -1 && inner.slice(0, open).trim() === "") {
+        const close = matching(inert, from + open);
+        if (close !== -1 && inert.slice(close + 1, to).trim() === "") {
+            from += open + 1;
+            to = close;
+        }
+    }
+    let depth = 0;
+    let cut = from;
+    const take = (stop) => {
+        const part = call.slice(cut, stop);
+        const named = /^\s*([A-Za-z_$][\w$]*)\s*[=:]\s*([\s\S]+)$/.exec(part);
+        if (named) {
+            if (!out.has(named[1]))
+                out.set(named[1], named[2].trim());
+            return;
+        }
+        const shorthand = /^\s*([A-Za-z_$][\w$]*)\s*$/.exec(part);
+        // First wins: a later option of one name does not replace the one in force.
+        if (shorthand && !out.has(shorthand[1]))
+            out.set(shorthand[1], shorthand[1]);
+    };
+    for (let i = from; i < to; i++) {
+        const ch = inert[i];
+        if ("([{".includes(ch))
+            depth++;
+        else if (")]}".includes(ch))
+            depth--;
+        else if (ch === "," && depth === 0) {
+            take(i);
+            cut = i + 1;
+        }
+    }
+    take(to);
+    return out;
+}
+/** Index of the bracket closing the one at `open`, or -1 when it is unbalanced. */
+function matching(text, open) {
+    let depth = 0;
+    for (let i = open; i < text.length; i++) {
+        if ("([{".includes(text[i]))
+            depth++;
+        else if (")]}".includes(text[i]) && --depth === 0)
+            return i;
+    }
+    return -1;
+}
+/** Offset-preserving blanking of string contents, so a comma or a bracket inside a
+ *  path or a body literal is never read as structure. */
+function blankStringContents(src) {
+    const out = src.split("");
+    let quote = "";
+    for (let i = 0; i < src.length; i++) {
+        const c = src[i];
+        if (quote) {
+            if (c === "\\") {
+                i++;
+                continue;
+            }
+            if (c === quote)
+                quote = "";
+            else
+                out[i] = " ";
+        }
+        else if (c === '"' || c === "'" || c === "`")
+            quote = c;
+    }
+    return out.join("");
+}
+/**
+ * The request's `body` option, as the text of its value, or `undefined` when the call
+ * sends no body.
+ *
+ * `shared-helper-policy` prescribes the object SHORTHAND as the canonical TypeScript
+ * form of body-form 2 — `updateOrder(client, orderId, body = DEFAULT_ORDER_BODY)`
+ * calling `sendRequest({ ..., body })` — so a reader that saw only `body:` judged the
+ * helper the prompt TEACHES as sending no body at all.
+ */
+export function bodyArgument(call) {
+    return requestOptions(call).get("body");
+}
+/** The request's override option, as the text of its value. Either spelling. */
+export function overrideArgument(call) {
+    const options = requestOptions(call);
+    return options.get("data_override") ?? options.get("dataOverride");
+}
+/**
+ * Whether a caller can change what this request sends, through the helper's signature.
+ *
+ * The question is whether the body DERIVES from a parameter, not which mechanism
+ * carried it there. Naming the mechanisms would answer the shapes already seen and
+ * mis-judge the next one: the body as the parameter, an override map, and a local
+ * template with the parameters interpolated into it are three ways to reach the same
+ * property, and there is no reason to think they are the last three.
+ *
+ * FAILS OPEN — this feeds a blocking gate, so every answer it cannot establish is
+ * `true`. A request with no body has nothing to reach; a signature it cannot read is
+ * not judged. Only a body it can see, built from no parameter at all, is false.
+ *
+ * `before` is the helper text that precedes the request call. A body passed by name
+ * is resolved there: generated code assigns the template immediately above the call,
+ * so a parameter that reaches the body appears between that assignment and the call.
+ */
+export function bodyReachable(call, params, before = "") {
+    if (params === undefined)
+        return true;
+    const value = bodyArgument(call);
+    if (value === undefined)
+        return true;
+    const names = new Set(params.map(paramName).filter(Boolean));
+    const mentionsParam = (text) => {
+        for (const m of text.matchAll(/[A-Za-z_$][\w$]*/g))
+            if (names.has(m[0]))
+                return true;
+        return false;
+    };
+    // The body IS a parameter.
+    if (names.has(value))
+        return true;
+    // The body is written at the call and names a parameter inside it.
+    if (mentionsParam(value))
+        return true;
+    // An override argument carries a parameter into the body.
+    const override = overrideArgument(call);
+    if (override !== undefined && mentionsParam(override))
+        return true;
+    // The body is passed by name: resolve it to its assignment in the helper and read
+    // from there to the call.
+    const assign = new RegExp(`\\b${value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b\\s*(?::[^=\\n]*)?=`).exec(before);
+    if (assign)
+        return mentionsParam(before.slice(assign.index + assign[0].length));
+    return false;
+}
+/**
+ * The override parameter of a helper that reaches its own request body TWICE: once
+ * through a body parameter, and again through an override argument passed straight
+ * from the signature. `undefined` when the helper reaches its body through at most
+ * one of them.
+ *
+ * The prompt already states the rule — two body forms are offered and the helper
+ * takes "the FIRST one that reaches everything the callers need" — and nothing
+ * checked it. A body parameter reaches every property of the request body, so an
+ * override beside it can change nothing it cannot; carrying both is the hedge a run
+ * writes when no rule decides, and it is what made demoshop's `create_order` arity 5
+ * in one run and 4 in the other (testplan-run-9).
+ *
+ * The body must BE a parameter — form 2 as the policy states it. A body built at the
+ * call out of a parameter reaches only the properties it names, so an override beside
+ * it carries what the parameter cannot and the two are not one mechanism twice.
+ *
+ * The override must be a BARE PASS-THROUGH — the parameter and nothing else, a
+ * `or {}` / `?? {}` fallback aside. An override that BUILDS a map carries values the
+ * body parameter's default does not, which is the prompt's form 1 working; that is
+ * the shape a unique-suffix helper delivers, and it is not this fault.
+ *
+ * Reads the request call alone, never a body resolved from an assignment above it:
+ * this feeds a blocking gate, and the direct form is the one that cannot be read two
+ * ways.
+ */
+export function bodyReachedTwice(call, params) {
+    if (params === undefined)
+        return undefined;
+    const bodyValue = bodyArgument(call);
+    const expr = overrideArgument(call);
+    if (bodyValue === undefined || expr === undefined)
+        return undefined;
+    const names = new Set(params.map(paramName).filter(Boolean));
+    const identifiers = (text) => [...text.matchAll(/[A-Za-z_$][\w$]*/g)].map((m) => m[0]);
+    // The body option must BE a parameter, not merely mention one. The rule's whole
+    // claim is that a whole-body parameter reaches every property the override could;
+    // a body BUILT from a parameter (`body: { title }`) reaches one property and
+    // leaves every other to the override, which is then not redundant at all — and
+    // the remediation this finding carries, delete the override, would break the
+    // helper. Anything else fails open.
+    const body = bodyValue.trim();
+    if (!names.has(body))
+        return undefined;
+    // A brace holding anything at all builds a map of its own — an object literal, a
+    // dict, or the TypeScript shorthand `{ name }`. `{}` is the empty fallback.
+    if (/\{\s*[^}\s]/.test(expr))
+        return undefined;
+    const carried = identifiers(expr).filter((id) => !OVERRIDE_FILLER.has(id));
+    if (carried.length !== 1 || !names.has(carried[0]))
+        return undefined;
+    const name = carried[0];
+    // One parameter named twice is one mechanism, not two.
+    return name === body ? undefined : name;
+}
+/** Every helper in the located modules that reaches its request body twice. Never
+ *  throws; a file it cannot read contributes nothing. */
+export async function findDuplicateBodyReach(utilsFiles, spec) {
+    const out = [];
+    for (const utilsFile of utilsFiles) {
+        let content;
+        try {
+            content = await fs.promises.readFile(utilsFile, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const h of parseUtilsFile(content, spec)) {
+            const call = helperRequest(content, h);
+            if (!call)
+                continue;
+            const override = bodyReachedTwice(call, signatureParams(helperSignature(content, h)));
+            if (override)
+                out.push({ helper: h.name, utilsFile, line: h.line, override });
+        }
+    }
+    return out;
+}
+/** The helper's own request call, or undefined when it issues none. */
+function helperRequest(content, helper) {
+    for (const m of content.matchAll(new RegExp(REQUEST_CALL_RE))) {
+        const start = m.index ?? 0;
+        const line = content.slice(0, start).split("\n").length;
+        if (line < helper.line || line > helper.endLine)
+            continue;
+        return callText(content, start + m[0].length - 1);
+    }
+    return undefined;
+}
+/** The helper's text from its definition to its request call — where a body passed
+ *  by name is assigned. */
+function helperTextBefore(content, helper, call) {
+    const body = content
+        .split("\n")
+        .slice(helper.line - 1, helper.endLine)
+        .join("\n");
+    const at = body.indexOf(call);
+    return at === -1 ? body : body.slice(0, at);
+}
+/** The signature text of a helper, as signatureParams reads it. */
+function helperSignature(content, helper) {
+    return content.split("\n").slice(helper.line - 1, helper.endLine);
+}
+/**
+ * Shared helpers whose body no parameter reaches, each paired with a sibling spec
+ * that defines its own helper for the same route. Never throws; fails open to [].
+ */
+export async function findUnreachableBodies(testFile, utilsFiles, spec, preReadSiblings) {
+    const frozen = new Map();
+    for (const utilsFile of utilsFiles) {
+        let content;
+        try {
+            content = await fs.promises.readFile(utilsFile, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const h of parseUtilsFile(content, spec)) {
+            if (!h.method || !h.normalizedPath)
+                continue;
+            const call = helperRequest(content, h);
+            if (!call)
+                continue;
+            if (bodyReachable(call, signatureParams(helperSignature(content, h)), helperTextBefore(content, h, call)))
+                continue;
+            frozen.set(`${h.method} ${h.normalizedPath}`, {
+                helper: h.name,
+                utilsFile,
+                method: h.method,
+                path: h.path ?? h.normalizedPath,
+            });
+        }
+    }
+    if (frozen.size === 0)
+        return [];
+    // The delivered spec is one of the callers, so the walk includes it.
+    const siblings = preReadSiblings ??
+        (await generatedSiblings(testFile, spec, { includeSelf: true }));
+    const out = [];
+    for (const { file, content } of siblings) {
+        for (const h of localHelpersOf(content, spec)) {
+            if (!h.method || !h.normalizedPath)
+                continue;
+            const held = frozen.get(`${h.method} ${h.normalizedPath}`);
+            if (!held)
+                continue;
+            out.push({ ...held, rivalFile: file, rivalHelper: h.name });
+        }
+    }
+    return out;
+}