@skyramp/mcp 0.4.1 → 0.4.2-rc.1

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

@@ -0,0 +1,335 @@
+import * as fs from "fs";
+import { 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 parseUtilsFile(content, spec)) {
+            if (/^test/i.test(h.name))
+                continue;
+            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;
+}

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

@@ -135,7 +135,12 @@ export declare function queryKeys(call: string): Set<string>;
  *  this is a TS/JS-only change. */
 export declare function callShape(call: string): Set<string>;
 /** The keyword names of a request call (`path=`, `method=`, `query_params=` … / TS
- *  object keys), less the liftable ones — a cheap normalised call shape. */
+ *  object keys), less the liftable ones — a cheap normalised call shape. Read from a
+ *  string-blanked copy: a value carries colons and equals signs of its own — a URL
+ *  scheme (`"https://…"`), a query string or a field expression in a path literal
+ *  (`"/search?q=name:foo"`) — and reading one as a keyword invents an entry on
+ *  whichever side spells the value that way, so two calls carrying the same keywords
+ *  compare as different shapes. */
 export declare function shapeKeys(call: string): Set<string>;
 /** Text of the parenthesised argument list starting at the `(` at `open`. */
 export declare function callText(content: string, open: number): string;

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

@@ -82,7 +82,7 @@ export async function findSiblingInlineCallSites(testFile, utilsFiles, _helpers,
             const match = byRoute.get(c.key);
             if (!match)
                 continue;
-            if (!sameShape(callShape(c.call), match.keys))
+            if (!sameShape(inlineShape(c.call), match.keys))
                 continue;
             if (!substitutable(match, {
                 fields: requestFields(content, c.call, c.start),
@@ -166,7 +166,7 @@ async function helperRoutes(utilsFiles, spec) {
             byRoute.set(`${owner.method} ${owner.normalizedPath}`, {
                 helper: owner.name,
                 utilsFile,
-                keys: callShape(call),
+                keys: inlineShape(call),
                 fields: requestFields(content, call, start),
                 query: queryKeys(call),
                 schemaChecked: hasSchemaCheck(content, owner.line, owner.endLine),
@@ -356,11 +356,25 @@ export function requestFields(content, call, callAt) {
 }
 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;
+/** The keyword a query object is written under, in either spelling. */
+const QUERY_KEYWORDS = ["query_params", "queryParams"];
+const QUERY_OBJECT_RE = new RegExp(`\\b(?:${QUERY_KEYWORDS.join("|")})\\s*[=:]\\s*\\{`, "g");
+/** An object ENTRY whose key queryKeys cannot enumerate: a spread or an unpack of
+ *  another value (`{ ...params }`, `{**params}`), or a computed key (`{ [k]: v }`).
+ *  Anchored to an entry position, so an array VALUE (`{ fields: ["id"] }`, which the
+ *  generated code writes) and a `**` exponent inside one are not mistaken for it. */
+const DYNAMIC_ENTRY_RE = /[{,]\s*(?:\.\.\.|\*\*|\[)/;
+/** The query argument however it is written — the object form above, or a reference
+ *  (`query_params=params`) whose contents are not at the call. */
+const QUERY_ARGUMENT_RE = new RegExp(`\\b(?:${QUERY_KEYWORDS.join("|")})\\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;
+/** One quoted string: a Python triple quote, or any of the three single-character
+ *  quote kinds, escapes honoured. The triple forms come FIRST — read as one quote,
+ *  a triple delimiter opens an EMPTY string at its first two characters and leaves
+ *  the payload outside any literal, where every scan that reads a blanked copy sees
+ *  its contents as code. Generated Python passes the request body this way. */
+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
@@ -408,7 +422,7 @@ function keyedObjects(call, keyRe) {
 /** `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]);
+    return text.replace(STRING_LITERAL_RE, (lit, quote) => quote + " ".repeat(Math.max(0, lit.length - 2 * quote.length)) + quote);
 }
 /** 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
@@ -422,6 +436,51 @@ function blankStringContents(text) {
 export function callShape(call) {
     return shapeKeys(withoutKeyedLiterals(call));
 }
+/**
+ * The shape the INLINE CALL-SITE scan compares: `callShape` less the query argument.
+ *
+ * A query object is a literal the merge rule lifts, exactly as a body is — a site
+ * writing `?status=paid` against a helper that sends no query differs from it by one
+ * value, and the repair is a `status` parameter. Whether the helper can stand in is
+ * the question `substitutable` answers, and it already applies the body rule to the
+ * query keys; while the keyword itself counted as shape, the two keyword sets differed
+ * by one entry, `sameShape` discarded the site, and `substitutable` never saw it.
+ *
+ * Only this scan sets it aside. findUnextractedDuplicates asks whether a helper should
+ * EXIST, where two sites that carry different options are two shapes rather than one
+ * literal to lift, so it keeps `callShape`. And LIFTABLE_KEYS is left alone: it also
+ * feeds retrofit-equivalence, which reads `shapeKeys` as an exact-match gate on an
+ * edit already made, where a dropped query IS a changed request.
+ */
+function inlineShape(call) {
+    const keys = callShape(call);
+    if (!queryIsReadable(call))
+        return keys;
+    for (const k of QUERY_KEYWORDS)
+        keys.delete(k);
+    return keys;
+}
+/** Whether every query argument the call carries is a `{…}` written at the call, so
+ *  queryKeys can read its names. A reference (`query_params=params`) yields an EMPTY
+ *  key set, which is what a call sending NO query yields: setting the keyword aside
+ *  would have substitutable compare nothing against nothing and offer the helper to a
+ *  site that sends no query, when substituting it adds whatever the reference holds.
+ *  So the keyword stays in the shape whenever its value cannot be read, and the site
+ *  is discarded as it was before — the scan only ever drops candidates. */
+function queryIsReadable(call) {
+    // Counted at OPTION level: a request field of the payload may be named
+    // `queryParams`, and reading that as a second, unreadable query argument discarded
+    // a site whose own query argument is a plain object literal. withoutKeyedLiterals
+    // blanks each keyed value's interior while keeping its own braces, which is the
+    // level callShape reads the keywords at.
+    const scan = blankStringContents(withoutKeyedLiterals(call));
+    if ([...scan.matchAll(QUERY_ARGUMENT_RE)].length !==
+        [...scan.matchAll(QUERY_OBJECT_RE)].length)
+        return false;
+    // An object literal is not the same as a readable one. The interiors are blanked in
+    // `scan`, so the entries are read from the original.
+    return !keyedObjects(call, QUERY_OBJECT_RE).some((o) => DYNAMIC_ENTRY_RE.test(blankStringContents(o)));
+}
 /** `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
@@ -469,10 +528,15 @@ const LIFTABLE_KEYS = new Set([
     "pathParams",
 ]);
 /** The keyword names of a request call (`path=`, `method=`, `query_params=` … / TS
- *  object keys), less the liftable ones — a cheap normalised call shape. */
+ *  object keys), less the liftable ones — a cheap normalised call shape. Read from a
+ *  string-blanked copy: a value carries colons and equals signs of its own — a URL
+ *  scheme (`"https://…"`), a query string or a field expression in a path literal
+ *  (`"/search?q=name:foo"`) — and reading one as a keyword invents an entry on
+ *  whichever side spells the value that way, so two calls carrying the same keywords
+ *  compare as different shapes. */
 export function shapeKeys(call) {
     const keys = new Set();
-    for (const m of call.matchAll(/\b([A-Za-z_]\w*)\s*[=:](?![=])/g)) {
+    for (const m of blankStringContents(call).matchAll(/\b([A-Za-z_]\w*)\s*[=:](?![=])/g)) {
         if (!LIFTABLE_KEYS.has(m[1]))
             keys.add(m[1]);
     }

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

@@ -0,0 +1,43 @@
+/**
+ * What a DELIVERED test file imports from the shared utils modules beside it —
+ * read from the file, with no run state and no verify pass behind it.
+ *
+ * This exists because the report's shared-helper record was keyed on the agent
+ * having called `skyramp_reuse_code` with `verify: true` on that file. A spec that
+ * imports and calls a helper from a header-bearing module reused it whether or not
+ * anything verified it, and a record keyed on the tool's own activity describes the
+ * tool rather than the product: every contract row in the 2026-09-18 cohort read
+ * `reuse: null` over a file that imported three helpers and called them.
+ *
+ * Deliberately NOT a second verifier. It runs no gate, produces no verdict, and
+ * cannot refuse a report — `verifyUtils` remains the only thing that judges a
+ * module. The one fact it establishes is which helpers the delivered file takes
+ * from which module, which is exactly the fact the record was missing.
+ *
+ * The same "imported AND defined" rule `verifyUtils` applies: a name the spec
+ * imports that the module does not define is a broken import, not reuse.
+ */
+export interface DeliveredImports {
+    /** Utils files located for the spec (absolute, sorted). Empty means no shared
+     *  module exists beside it or in its imports — which is a finding, not a failure. */
+    utilsFiles: string[];
+    /** Names the spec imports from those files that the files define, sorted and
+     *  deduplicated across files. Empty with a non-empty `utilsFiles` means a module
+     *  exists and this spec takes nothing from it. */
+    importedNames: string[];
+}
+/**
+ * Read `testFile`'s imports of its shared modules, or state why it could not be done.
+ *
+ * Returns a `reason` rather than throwing or answering an empty result, because the
+ * caller writes that reason into the report row: an empty answer and an unreadable
+ * file are different facts, and a row that cannot tell them apart is the `null` this
+ * function exists to replace.
+ */
+export declare function readDeliveredImports(params: {
+    testFile: string;
+    language?: string;
+    cwd?: string;
+}): Promise<DeliveredImports | {
+    reason: string;
+}>;

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

@@ -0,0 +1,84 @@
+import * as fs from "fs";
+import * as path from "path";
+import { logger } from "../logger.js";
+import { locateUtilsFiles } from "./locate.js";
+import { parseUtilsFile } from "./parse.js";
+import { utilsSpecFor, utilsSpecForFile } from "./language-spec.js";
+/**
+ * Read `testFile`'s imports of its shared modules, or state why it could not be done.
+ *
+ * Returns a `reason` rather than throwing or answering an empty result, because the
+ * caller writes that reason into the report row: an empty answer and an unreadable
+ * file are different facts, and a row that cannot tell them apart is the `null` this
+ * function exists to replace.
+ */
+export async function readDeliveredImports(params) {
+    const spec = utilsSpecFor(params.language) ?? utilsSpecForFile(params.testFile);
+    if (!spec)
+        return {
+            reason: `no shared-helper support for this file type (${path.extname(params.testFile) || "no extension"})`,
+        };
+    let specContent;
+    try {
+        specContent = await fs.promises.readFile(params.testFile, "utf8");
+    }
+    catch (err) {
+        return {
+            reason: `the delivered file could not be read (${err?.code ?? String(err)})`,
+        };
+    }
+    let utilsFiles;
+    try {
+        utilsFiles = await locateUtilsFiles(params);
+    }
+    catch (err) {
+        // locateUtilsFiles is documented never to throw; if that ever changes, the row
+        // says so rather than claiming the spec imports nothing.
+        logger.warning("Could not locate shared utils files for a delivered test", {
+            testFile: params.testFile,
+            error: String(err),
+        });
+        return {
+            reason: "the shared modules beside this test could not be located",
+        };
+    }
+    const importedNames = new Set();
+    // Built from the modules actually READ, never from the located list. A module that
+    // is named but whose helpers were never counted publishes "this test takes nothing
+    // from it" over an unknown — the same false zero this reader exists to stop.
+    const read = [];
+    for (const file of utilsFiles) {
+        let content;
+        try {
+            content = await fs.promises.readFile(file, "utf8");
+        }
+        catch (err) {
+            // A module that vanished between locating and reading is the ordinary race, not
+            // a fault: it leaves the list with the rest, and the others still answer.
+            if (err?.code === "ENOENT")
+                continue;
+            // Anything else means a module exists that cannot be read, so what this spec
+            // takes from it is unknown. A partial answer cannot be represented here, and
+            // a silent one would be read as a measured zero.
+            //
+            // Untested, and untestable from outside: `locateUtilsFiles` screens every
+            // candidate with `hasUtilsHeader`, which opens and reads it, so a module that
+            // cannot be read is never located and this branch is not reached. It stands as
+            // the guard that keeps `read` below honest if that screen ever changes.
+            logger.warning("Could not read a located utils file for the report", {
+                file,
+                error: String(err),
+            });
+            return {
+                reason: `a shared helper module beside this test could not be read (${path.basename(file)}: ${err?.code ?? String(err)})`,
+            };
+        }
+        read.push(file);
+        const defined = new Set(parseUtilsFile(content, spec).map((h) => h.name));
+        const stem = path.basename(file).replace(/\.[^.]+$/, "");
+        for (const n of spec.importedNames(specContent, stem))
+            if (defined.has(n))
+                importedNames.add(n);
+    }
+    return { utilsFiles: read, importedNames: [...importedNames].sort() };
+}