@gate-forge/pack-http 0.7.1 → 0.9.0

package/dist/client-calls.js

@@ -134,6 +134,491 @@ export function activeClientSymbolNamesIn(config, file) {
     }
     return [...names].sort();
 }
+/**
+ * The one payload property this model follows: the axios/kit response
+ * envelope whose `data` member carries the decoded body.
+ */
+const PAYLOAD_PROPERTY = 'data';
+/**
+ * Members of `Response`, of the collection prototypes and of `Object`
+ * itself. A read of one of these is a JavaScript member, never a
+ * response-model field, so it is never collected — without this a
+ * `res.data.map(...)` on a list endpoint would read as a missing field.
+ */
+const NEVER_MODEL_FIELDS = {
+    at: true, catch: true, concat: true, constructor: true, entries: true, every: true,
+    filter: true, find: true, findIndex: true, flat: true, flatMap: true, finally: true,
+    forEach: true, get: true, has: true, headers: true, includes: true, indexOf: true,
+    join: true, keys: true, length: true, map: true, message: true, name: true, ok: true,
+    prototype: true, push: true, reduce: true, shift: true, slice: true, some: true,
+    sort: true, status: true, statusText: true, then: true, toJSON: true, toString: true,
+    unshift: true, values: true, valueOf: true,
+};
+/**
+ * Members of the response envelope that decide whether the call
+ * SUCCEEDED. A branch that opens on one of them of the call's own result
+ * is a guard: the error body a failure branch reads is the framework's,
+ * never the success model.
+ */
+const ENVELOPE_MEMBERS = {
+    ok: true,
+    status: true,
+    statusText: true,
+};
+/** The `ok` envelope member; its polarity is the whole verdict. */
+const OK_MEMBER = 'ok';
+/** The last status a successful call answers with (2xx/3xx). */
+const SUCCESS_STATUS = 299;
+/** The first status a failing call answers with. */
+const FAILURE_STATUS = 400;
+/** `||` and `??` are the two ways code writes a fallback chain. */
+function chainOperator(kind) {
+    return kind === ts.SyntaxKind.BarBarToken || kind === ts.SyntaxKind.QuestionQuestionToken;
+}
+/** The numeric value of a boolean or numeric literal, else null. */
+function literalValue(node) {
+    const expression = unwrapExpression(node);
+    if (expression.kind === ts.SyntaxKind.TrueKeyword)
+        return 1;
+    if (expression.kind === ts.SyntaxKind.FalseKeyword)
+        return 0;
+    if (ts.isNumericLiteral(expression)) {
+        const value = Number(expression.text);
+        return Number.isFinite(value) ? value : null;
+    }
+    return null;
+}
+/** The names a binding pattern binds, in source order. */
+function bindingNames(name) {
+    if (ts.isIdentifier(name))
+        return [name.text];
+    const names = [];
+    for (const element of name.elements) {
+        if (ts.isOmittedExpression(element) || element.dotDotDotToken !== undefined)
+            continue;
+        names.push(...bindingNames(element.name));
+    }
+    return names;
+}
+/** The literal key a binding element or property names, or `''`. */
+function propertyNameText(name) {
+    if (name === undefined)
+        return '';
+    if (ts.isIdentifier(name) || ts.isStringLiteralLike(name))
+        return name.text;
+    return '';
+}
+/** Strips `await`, parentheses and non-null assertions from an expression. */
+function unwrapExpression(node) {
+    let current = node;
+    for (;;) {
+        const parent = current.parent;
+        if (parent === undefined)
+            return current;
+        if (ts.isAwaitExpression(parent) ||
+            ts.isParenthesizedExpression(parent) ||
+            parent.kind === ts.SyntaxKind.AsExpression ||
+            parent.kind === ts.SyntaxKind.NonNullExpression ||
+            parent.kind === ts.SyntaxKind.SatisfiesExpression) {
+            current = parent;
+            continue;
+        }
+        return current;
+    }
+}
+/**
+ * The node ITSELF with its own wrapping peeled: parentheses, `as T`,
+ * `!`. {@link unwrapExpression} walks the other way (from an inner node
+ * out to the wrapper around it), which is what a value-table lookup
+ * needs; the concise arrow body `=> ({ ... })` IS that wrapper, so the
+ * request-options model has to look through it.
+ */
+function unwrapOwnExpression(node) {
+    let current = node;
+    for (;;) {
+        if (ts.isParenthesizedExpression(current)) {
+            current = current.expression;
+            continue;
+        }
+        if (ts.isAsExpression(current) || ts.isNonNullExpression(current)) {
+            current = current.expression;
+            continue;
+        }
+        return current;
+    }
+}
+/**
+ * The bounded static read of the response fields one detected call is
+ * consumed through (plan 2026-09-25 Phase 4b item 5).
+ *
+ * The model is deliberately small and file-local, and it never guesses:
+ *
+ * - the call's own awaited result is followed through `await` and
+ *   parentheses; `<result>.data` is the payload (axios/kit envelope) and
+ *   `<result>` alone is the envelope;
+ * - a name bound from either of those (`const r = await call`,
+ *   `const { data: d } = await call`, `const d = (await call).data`) is
+ *   followed by NAME inside the enclosing function-like (nested
+ *   function-likes included, so a `useEffect` callback still counts);
+ * - every `holder.<field>`, `holder.data.<field>`, `holder.data['<field>']`
+ *   and `holder['<field>']` is a read, and so is each key of an object
+ *   destructuring of a holder or of `<holder>.data`;
+ * - computed access (`d[key]`), a reassigned (`let`) holder, and a read
+ *   of a JavaScript member (`data.map`, `data.length`, …) yield nothing;
+ * - a branch that opens on the call's OWN envelope (`if (res.ok)`,
+ *   `if (!res.ok)`, `if (res.status >= 400)`, `res.ok ? … : …`) is read
+ *   for its POLARITY, and only its FAILURE arm is not collected: the
+ *   body a failure branch reads is the error envelope, not the success
+ *   model. An undecidable condition (a compound test, a comparison this
+ *   pass cannot read) drops BOTH arms. A read AFTER the guard is
+ *   collected as usual;
+ * - a read that is one operand of a `||` / `??` chain carries the chain's
+ *   index, so the response-model check can judge the whole chain at once
+ *   instead of flagging a defensive fallback.
+ *
+ * A read is recorded once per field and location, in source order.
+ */
+function responseReadsOf(file, call, source) {
+    const reads = new Map();
+    const chainRoots = [];
+    // Reads the BINDING pass already saw (an inline `(await call).data.x`).
+    // They are recorded first and replayed once `add` knows the holders,
+    // which the binding pass is what discovers.
+    const bound = [];
+    let add = (field, node) => {
+        bound.push({ field, node });
+    };
+    const awaited = unwrapExpression(call);
+    const envelopeAccess = awaited.parent !== undefined &&
+        ts.isPropertyAccessExpression(awaited.parent) &&
+        awaited.parent.expression === awaited &&
+        awaited.parent.name.text === PAYLOAD_PROPERTY
+        ? awaited.parent
+        : undefined;
+    const payload = envelopeAccess;
+    const holders = [];
+    bindHolder(awaited, false, holders, add);
+    if (payload !== undefined)
+        bindHolder(payload, true, holders, add);
+    const responseNames = new Set(holders.filter((h) => !h.payload).map((h) => h.name));
+    const payloadNames = new Set(holders.filter((h) => h.payload).map((h) => h.name));
+    /** Whether an expression IS the decoded payload of this call. */
+    const isPayload = (node) => {
+        const expression = unwrapExpression(node);
+        if (ts.isIdentifier(expression))
+            return payloadNames.has(expression.text);
+        return (ts.isPropertyAccessExpression(expression) &&
+            expression.name.text === PAYLOAD_PROPERTY &&
+            ts.isIdentifier(expression.expression) &&
+            responseNames.has(expression.expression.text));
+    };
+    let scope = source;
+    for (let node = call; node !== undefined; node = node.parent) {
+        if (ts.isFunctionLike(node)) {
+            scope = node;
+            break;
+        }
+    }
+    // A branch that opens on the call's OWN envelope (`if (!res.ok)`,
+    // `if (res.status >= 400)`, `res.ok ? … : …`) is a guard: which side
+    // runs is not statically known, and the error body a failure branch
+    // reads is the framework's, not the success model. Nothing inside such a
+    // branch is a proven read of the success model — see the failure-path
+    // note in the module doc.
+    const guarded = new Set();
+    const isHolderName = (node) => ts.isIdentifier(node) && responseNames.has(node.text);
+    /** The envelope member of this call's own result an expression reads. */
+    const envelopeMember = (node) => ts.isPropertyAccessExpression(node) &&
+        isHolderName(node.expression) &&
+        ENVELOPE_MEMBERS[node.name.text] === true
+        ? node.name.text
+        : null;
+    const mentionsEnvelope = (node) => {
+        if (envelopeMember(node) !== null)
+            return true;
+        let found = false;
+        const inspect = (at) => {
+            if (found)
+                return;
+            if (envelopeMember(at) !== null) {
+                found = true;
+                return;
+            }
+            ts.forEachChild(at, inspect);
+        };
+        ts.forEachChild(node, inspect);
+        return found;
+    };
+    /**
+     * The polarity of an envelope guard, or null when the condition does not
+     * test this call's envelope at all.
+     *
+     * `if (res.ok)` / `if (res.ok === true)` / `if (res.status >= 400)` /
+     * `if (res.status !== 201)` and their negations are decided here, so the
+     * SUCCESS arm keeps its reads — the error envelope belongs to the
+     * failure arm only. A compound condition, a comparison this cannot
+     * read, or a `statusText`/`headers` test is `unknown`: neither arm is a
+     * proven read of the success model.
+     */
+    const guardPolarity = (condition) => {
+        const expression = unwrapExpression(condition);
+        if (ts.isPrefixUnaryExpression(expression) && expression.operator === ts.SyntaxKind.ExclamationToken) {
+            const inner = guardPolarity(expression.operand);
+            if (inner === null || inner === 'unknown')
+                return inner;
+            return inner === 'success' ? 'failure' : 'success';
+        }
+        const bare = envelopeMember(expression);
+        if (bare !== null)
+            return bare === OK_MEMBER ? 'success' : 'unknown';
+        if (!ts.isBinaryExpression(expression)) {
+            return mentionsEnvelope(expression) ? 'unknown' : null;
+        }
+        const member = envelopeMember(expression.left);
+        if (member === null)
+            return mentionsEnvelope(expression) ? 'unknown' : null;
+        const expected = literalValue(expression.right);
+        if (expected === null)
+            return 'unknown';
+        const isOk = member === OK_MEMBER;
+        const kind = expression.operatorToken.kind;
+        const equality = kind === ts.SyntaxKind.EqualsEqualsToken || kind === ts.SyntaxKind.EqualsEqualsEqualsToken;
+        const inequality = kind === ts.SyntaxKind.ExclamationEqualsToken || kind === ts.SyntaxKind.ExclamationEqualsEqualsToken;
+        if (isOk) {
+            // A boolean compared with a boolean literal: `!==` is the negated
+            // equality, so `ok !== true` is the failure arm.
+            if (!equality && !inequality)
+                return 'unknown';
+            const satisfied = (succeeded) => {
+                const same = (succeeded ? 1 : 0) === expected;
+                return inequality ? !same : same;
+            };
+            if (satisfied(true) && !satisfied(false))
+                return 'success';
+            if (!satisfied(true) && satisfied(false))
+                return 'failure';
+            return 'unknown';
+        }
+        if (inequality) {
+            // `status !== 200` reads as "not the success I expected", which is
+            // the failure arm even though a 404 satisfies it too.
+            if (expected >= 200 && expected <= SUCCESS_STATUS)
+                return 'failure';
+            if (expected >= FAILURE_STATUS)
+                return 'success';
+            return 'unknown';
+        }
+        const succeeded = expected >= 200 && expected <= SUCCESS_STATUS;
+        const failed = expected >= FAILURE_STATUS;
+        switch (kind) {
+            case ts.SyntaxKind.EqualsEqualsToken:
+            case ts.SyntaxKind.EqualsEqualsEqualsToken:
+                if (succeeded)
+                    return 'success';
+                if (failed)
+                    return 'failure';
+                return 'unknown';
+            case ts.SyntaxKind.LessThanToken:
+                return SUCCESS_STATUS < expected ? 'success' : FAILURE_STATUS < expected ? 'failure' : 'unknown';
+            case ts.SyntaxKind.LessThanEqualsToken:
+                return SUCCESS_STATUS <= expected ? 'success' : FAILURE_STATUS <= expected ? 'failure' : 'unknown';
+            case ts.SyntaxKind.GreaterThanToken:
+                return SUCCESS_STATUS > expected ? 'success' : FAILURE_STATUS > expected ? 'failure' : 'unknown';
+            case ts.SyntaxKind.GreaterThanEqualsToken:
+                return SUCCESS_STATUS >= expected ? 'success' : FAILURE_STATUS >= expected ? 'failure' : 'unknown';
+            default:
+                return 'unknown';
+        }
+    };
+    const markGuards = (node) => {
+        if (ts.isIfStatement(node)) {
+            const polarity = guardPolarity(node.expression);
+            if (polarity === 'failure')
+                guarded.add(node.thenStatement);
+            else if (polarity === 'success' && node.elseStatement !== undefined) {
+                guarded.add(node.elseStatement);
+            }
+            else if (polarity === 'unknown') {
+                guarded.add(node.thenStatement);
+                if (node.elseStatement !== undefined)
+                    guarded.add(node.elseStatement);
+            }
+        }
+        if (ts.isConditionalExpression(node)) {
+            // A ternary on the envelope is the same guard as an `if`: only its
+            // failure arm is the error envelope.
+            const polarity = guardPolarity(node.condition);
+            if (polarity === 'failure')
+                guarded.add(node.whenTrue);
+            else if (polarity === 'success')
+                guarded.add(node.whenFalse);
+            else if (polarity === 'unknown') {
+                guarded.add(node.whenTrue);
+                guarded.add(node.whenFalse);
+            }
+        }
+        ts.forEachChild(node, markGuards);
+    };
+    markGuards(scope);
+    /** Whether a node sits inside one of the guarded branch bodies. */
+    const insideGuard = (node) => {
+        for (let at = node; at !== undefined && at !== scope; at = at.parent) {
+            if (guarded.has(at))
+                return true;
+        }
+        return false;
+    };
+    /** The outermost `||` / `??` chain an operand belongs to, if any. */
+    const chainOf = (node) => {
+        for (let at = node; at !== undefined && at !== scope; at = at.parent) {
+            if (ts.isBinaryExpression(at) && chainOperator(at.operatorToken.kind))
+                return at;
+        }
+        return undefined;
+    };
+    add = (field, node) => {
+        if (field.length === 0 || NEVER_MODEL_FIELDS[field] === true)
+            return;
+        if (insideGuard(node))
+            return;
+        const location = locationOf(file, source, node);
+        const key = `${field}@${String(location.line)}:${String(location.col)}`;
+        if (reads.has(key))
+            return;
+        const root = chainOf(node);
+        if (root === undefined) {
+            reads.set(key, { field, location });
+            return;
+        }
+        let index = chainRoots.indexOf(root);
+        if (index < 0) {
+            chainRoots.push(root);
+            index = chainRoots.length - 1;
+        }
+        reads.set(key, { field, location, chain: index });
+    };
+    for (const read of bound)
+        add(read.field, read.node);
+    const visit = (node) => {
+        if (ts.isPropertyAccessExpression(node) && isPayload(node.expression)) {
+            add(node.name.text, node);
+        }
+        else if (ts.isElementAccessExpression(node) &&
+            ts.isStringLiteralLike(node.argumentExpression) &&
+            isPayload(node.expression)) {
+            add(node.argumentExpression.text, node);
+        }
+        else if (ts.isVariableDeclaration(node) &&
+            node.initializer !== undefined &&
+            ts.isObjectBindingPattern(node.name) &&
+            isPayload(node.initializer)) {
+            for (const element of node.name.elements) {
+                const field = bindingKey(element);
+                if (field.length > 0)
+                    add(field, element);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(scope);
+    const ordered = [...reads.values()].sort((left, right) => {
+        const where = (left.location.file < right.location.file ? -1 : left.location.file > right.location.file ? 1 : 0) ||
+            left.location.line - right.location.line ||
+            left.location.col - right.location.col ||
+            (left.field < right.field ? -1 : left.field > right.field ? 1 : 0);
+        return where;
+    });
+    // Chain numbers are handed out in discovery order; renumber them by
+    // where each chain FIRST appears in source, so the fact is independent
+    // of the traversal.
+    const firstOf = (index) => ordered.find((read) => read.chain === index);
+    const chains = [...new Set(ordered.map((read) => read.chain))]
+        .filter((index) => index !== undefined)
+        .sort((left, right) => firstOf(left).location.line - firstOf(right).location.line ||
+        firstOf(left).location.col - firstOf(right).location.col);
+    const renumbered = new Map(chains.map((index, position) => [index, position]));
+    return ordered.map((read) => read.chain === undefined ? read : { ...read, chain: renumbered.get(read.chain) ?? read.chain });
+    /** The key a binding element pulls off the object it destructures. */
+    function bindingKey(element) {
+        const declared = propertyNameText(element.propertyName);
+        if (declared.length > 0)
+            return declared;
+        return ts.isIdentifier(element.name) ? element.name.text : '';
+    }
+    /**
+     * Records what the awaited result (or its `.data` payload) binds to:
+     * a name to follow, or — for a destructured payload — the field keys
+     * that destructuring itself reads. `status`/`headers` and every other
+     * envelope member are not response-model fields, so they are ignored.
+     */
+    function bindHolder(node, isPayloadNode, into, addRead) {
+        const parent = node.parent;
+        if (parent === undefined)
+            return;
+        if (ts.isVariableDeclaration(parent) && parent.initializer === node) {
+            // A `let` holder can be reassigned before the read, so the name no
+            // longer provably holds this call's response; a `const` one does.
+            const declarationList = parent.parent;
+            const isConst = ts.isVariableDeclarationList(declarationList) &&
+                (ts.getCombinedNodeFlags(declarationList) & ts.NodeFlags.Const) !== 0;
+            if (!isConst)
+                return;
+            if (ts.isIdentifier(parent.name)) {
+                into.push({ name: parent.name.text, payload: isPayloadNode });
+                return;
+            }
+            // An array destructuring pulls ELEMENTS, not named fields, out of a
+            // response: there is no field name to compare against a model.
+            if (!ts.isObjectBindingPattern(parent.name))
+                return;
+            // `const { data: d } = await call` — the payload is one level in;
+            // every other envelope key is not a response-model field.
+            if (!isPayloadNode) {
+                for (const element of parent.name.elements) {
+                    if (bindingKey(element) !== PAYLOAD_PROPERTY)
+                        continue;
+                    for (const name of bindingNames(element.name))
+                        into.push({ name, payload: true });
+                }
+                return;
+            }
+            for (const element of parent.name.elements) {
+                const field = bindingKey(element);
+                if (field.length > 0)
+                    addRead(field, element);
+            }
+            return;
+        }
+        if (ts.isBindingElement(parent) && parent.initializer === node) {
+            if (!isPayloadNode) {
+                if (bindingKey(parent) === PAYLOAD_PROPERTY && ts.isObjectBindingPattern(parent.name)) {
+                    for (const name of bindingNames(parent.name))
+                        into.push({ name, payload: true });
+                }
+                return;
+            }
+            if (ts.isObjectBindingPattern(parent.name)) {
+                // `const { data: { dueDate } } = await call` — the nested keys
+                // are the fields the body is read through.
+                for (const element of parent.name.elements) {
+                    const field = bindingKey(element);
+                    if (field.length > 0)
+                        addRead(field, element);
+                }
+                return;
+            }
+            const key = bindingKey(parent);
+            if (key.length > 0)
+                addRead(key, parent);
+            return;
+        }
+        if (ts.isPropertyAccessExpression(parent) && parent.expression === node) {
+            // `(await call).data.<field>` reads one field of the body inline.
+            if (isPayloadNode)
+                addRead(parent.name.text, parent);
+        }
+    }
+}
 const VERB_METHODS = new Map([
     ['get', 'GET'],
     ['post', 'POST'],
@@ -143,6 +628,14 @@ const VERB_METHODS = new Map([
     ['head', 'HEAD'],
     ['options', 'OPTIONS'],
 ]);
+const ABSENT_OPTIONS = { kind: 'absent' };
+const UNPROVEN_OPTIONS = { kind: 'unproven' };
+/**
+ * Bound hops of the request-options model (an options object, a constant
+ * naming one, or a single-return function that forwards its argument), so
+ * a chain of wrappers is reported, never followed forever.
+ */
+const MAX_OPTIONS_HOPS = 4;
 const UNRESOLVED_VALUE = { kind: 'unresolved', text: '' };
 function languageKindFor(file) {
     if (file.endsWith('.tsx'))
@@ -162,6 +655,7 @@ function modelFile(source, config, file) {
     const constants = new Map();
     const clientFunctions = new Set();
     const wrappers = new Map();
+    const functions = new Map();
     const isModuleScope = (node) => {
         let current = node.parent;
         while (current !== undefined) {
@@ -186,23 +680,26 @@ function modelFile(source, config, file) {
                 // One-declaration wrapper: `const apiGet = (path) => fetch(...)`.
                 const init = declaration.initializer;
                 if (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) {
+                    functions.set(declaration.name.text, init);
                     modelWrapper(declaration.name.text, init, wrappers);
                     if (containsClientCall(init, config, file))
                         clientFunctions.add(declaration.name.text);
                 }
             }
         }
-        if ((ts.isFunctionDeclaration(node) && node.name !== undefined && node.body !== undefined) ||
-            (ts.isVariableStatement(node))) {
-            // Named function declarations can be client wrappers too.
-            if (ts.isFunctionDeclaration(node) && node.name !== undefined && containsClientCall(node, config, file)) {
+        if (ts.isFunctionDeclaration(node) && node.name !== undefined) {
+            // Named function declarations can be client wrappers too, and the
+            // request-options model reads their single returned expression.
+            if (isModuleScope(node))
+                functions.set(node.name.text, node);
+            if (node.body !== undefined && containsClientCall(node, config, file)) {
                 clientFunctions.add(node.name.text);
             }
         }
         ts.forEachChild(node, visit);
     };
     visit(source);
-    return { source, constants, clientFunctions, wrappers };
+    return { source, constants, clientFunctions, functions, wrappers };
 }
 /** True when the subtree contains a direct fetch/axios/client call. */
 function containsClientCall(node, config, file) {
@@ -323,10 +820,14 @@ function extractCall(call, file, config, table, model, calls, unresolved) {
     if (source === undefined)
         return;
     const location = locationOf(file, source, call);
+    // The response fields THIS call site reads (plan 2026-09-25 Phase 4b
+    // item 5) — the same bounded, file-local pass, attached to whichever
+    // call shape below is recognized.
+    const reads = responseReadsOf(file, call, source);
     const expression = call.expression;
     // fetch(url[, {method}])
     if (ts.isIdentifier(expression) && expression.text === 'fetch') {
-        extractClientCall(call, 'fetch', 'GET', file, config, table, calls, unresolved, location);
+        extractClientCall(call, 'fetch', 'GET', file, config, table, calls, unresolved, location, undefined, reads);
         return;
     }
     // axios.get(url), apiClient.post(url), window.fetch(url)
@@ -335,7 +836,7 @@ function extractCall(call, file, config, table, model, calls, unresolved) {
         const verb = expression.name.text.toLowerCase();
         const isFetchObject = objectName === 'window' && expression.name.text === 'fetch';
         if (isFetchObject) {
-            extractClientCall(call, 'fetch', 'GET', file, config, table, calls, unresolved, location);
+            extractClientCall(call, 'fetch', 'GET', file, config, table, calls, unresolved, location, undefined, reads);
             return;
         }
         // Per-symbol scoping (phase 3): the symbol counts only where its
@@ -347,7 +848,7 @@ function extractCall(call, file, config, table, model, calls, unresolved) {
             // proven literal baseURL joins into the emitted path (fetch has no
             // instance and never joins).
             const baseURL = table.instanceBaseURL(objectName, file);
-            extractClientCall(call, objectName, method, file, config, table, calls, unresolved, location, baseURL);
+            extractClientCall(call, objectName, method, file, config, table, calls, unresolved, location, baseURL, reads);
             return;
         }
     }
@@ -368,7 +869,7 @@ function extractCall(call, file, config, table, model, calls, unresolved) {
     }
     if (configCall !== null && framework !== null) {
         const baseURL = table.instanceBaseURL(framework, file);
-        extractConfiguredCall(configCall, framework, file, config, table, calls, unresolved, location, baseURL);
+        extractConfiguredCall(configCall, framework, file, config, table, calls, unresolved, location, baseURL, reads);
         return;
     }
     // Configured wrapper: the declaration must exist in the scanned set as
@@ -408,7 +909,7 @@ function extractCall(call, file, config, table, model, calls, unresolved) {
             });
             return;
         }
-        resolveAndRecord(urlNode, wrapperConfig.name, wrapperConfig.method, file, config, bound, calls, unresolved, location);
+        resolveAndRecord(urlNode, wrapperConfig.name, wrapperConfig.method, file, config, bound, calls, unresolved, location, reads);
         return;
     }
     // A module-scope function whose body issues client calls IS a client
@@ -467,8 +968,16 @@ class BoundTable {
         }
         return this.inner.evaluate(node, file);
     }
+    optionsMethod(node, file, bindings, depth = 0) {
+        if (ts.isIdentifier(node) &&
+            node.text === this.parameter &&
+            this.argument !== undefined) {
+            return this.inner.optionsMethod(this.argument, this.argumentFile, bindings, depth + 1);
+        }
+        return this.inner.optionsMethod(node, file, bindings, depth);
+    }
 }
-function extractClientCall(call, framework, defaultMethod, file, config, table, calls, unresolved, location, baseURL) {
+function extractClientCall(call, framework, defaultMethod, file, config, table, calls, unresolved, location, baseURL, reads = []) {
     const urlNode = call.arguments[0];
     if (urlNode === undefined) {
         unresolved.push({
@@ -513,11 +1022,31 @@ function extractClientCall(call, framework, defaultMethod, file, config, table,
             }
         }
     }
+    if (framework === 'fetch' &&
+        optionsNode !== undefined &&
+        !ts.isObjectLiteralExpression(optionsNode)) {
+        // `fetch(url, options)` with options built elsewhere: the verb is
+        // whatever that object carries, and until the bounded options model
+        // proves it, assuming GET invents a route the server never serves.
+        const resolved = table.optionsMethod(optionsNode, file);
+        if (resolved.kind === 'unproven') {
+            unresolved.push({
+                code: HTTP_METHOD_DYNAMIC,
+                detail: 'fetch call passes request options that are not a provable object literal ' +
+                    '(they are built by another function or a computed expression); the method ' +
+                    'cannot be proven statically and is never assumed to be GET',
+                location,
+            });
+            return;
+        }
+        if (resolved.kind === 'proven')
+            method = resolved.method;
+    }
     if (method === null)
         return;
-    resolveAndRecord(urlNode, framework, method, file, config, table, calls, unresolved, location, baseURL);
+    resolveAndRecord(urlNode, framework, method, file, config, table, calls, unresolved, location, reads, baseURL);
 }
-function extractConfiguredCall(call, framework, file, config, table, calls, unresolved, location, baseURL) {
+function extractConfiguredCall(call, framework, file, config, table, calls, unresolved, location, baseURL, reads = []) {
     const configNode = call.arguments[0];
     if (configNode === undefined || !ts.isObjectLiteralExpression(configNode)) {
         unresolved.push({
@@ -564,7 +1093,7 @@ function extractConfiguredCall(call, framework, file, config, table, calls, unre
         });
         return;
     }
-    resolveAndRecord(urlNode, framework, method, file, config, table, calls, unresolved, location, baseURL);
+    resolveAndRecord(urlNode, framework, method, file, config, table, calls, unresolved, location, reads, baseURL);
 }
 /**
  * axios `isAbsoluteURL`: a call URL beginning `<scheme>://` or a
@@ -596,7 +1125,7 @@ function joinInstanceBaseURL(baseURL, callPath) {
         joined: baseURL,
     };
 }
-function resolveAndRecord(urlNode, framework, method, file, config, table, calls, unresolved, location, baseURL) {
+function resolveAndRecord(urlNode, framework, method, file, config, table, calls, unresolved, location, reads = [], baseURL) {
     const resolved = table.evaluate(urlNode, file);
     if (resolved.kind === 'unresolved') {
         unresolved.push({
@@ -623,8 +1152,28 @@ function resolveAndRecord(urlNode, framework, method, file, config, table, calls
         ...(joined.joined !== undefined ? { joinedBaseURL: joined.joined } : {}),
         framework,
         location,
+        ...(reads.length > 0 ? { responseReads: reads } : {}),
     });
 }
+/**
+ * The ONE expression a function-like returns, or undefined when it
+ * returns none or branches: two return paths can set the verb
+ * differently, and an unprovable options object must not be guessed.
+ */
+function returnedExpression(fn) {
+    // A concise arrow body IS its returned expression: `(o) => ({ ...o })`.
+    if (ts.isArrowFunction(fn) && !ts.isBlock(fn.body))
+        return fn.body;
+    const body = ts.isArrowFunction(fn)
+        ? ts.isBlock(fn.body)
+            ? fn.body
+            : undefined
+        : fn.body;
+    if (body === undefined)
+        return undefined;
+    const returns = body.statements.filter((statement) => ts.isReturnStatement(statement));
+    return returns.length === 1 ? returns[0]?.expression : undefined;
+}
 function normalizeHttpMethodValue(raw) {
     const upper = raw.trim().toUpperCase();
     if (upper === 'GET' || upper === 'HEAD' || upper === 'POST' || upper === 'PUT' || upper === 'PATCH' || upper === 'DELETE' || upper === 'OPTIONS') {
@@ -940,6 +1489,106 @@ class ValueTable {
             return UNRESOLVED_VALUE;
         return this.evaluate(initializer, targetFile);
     }
+    /**
+     * The verb one request-options expression provably carries.
+     *
+     * Bounded and deterministic, three shapes only:
+     *  - an inline object literal: `method` is read with JavaScript's
+     *    last-writer-wins order, and a spread of another resolvable options
+     *    expression participates equally (`{...base, method:'POST'}`);
+     *  - a name: a module-scope constant in the scanned set (same file or
+     *    relative import), followed at most {@link MAX_OPTIONS_HOPS} hops;
+     *  - a call to a plain-named function whose declaration is in the
+     *    scanned set and whose body is a SINGLE `return <expression>`:
+     *    the first parameter binds to this call's first argument, so a
+     *    forwarder (`(options) => ({ ...options })`) resolves to whatever
+     *    its argument proves.
+     * Everything else — a computed member, an attribute, a member call, a
+     * function this scan cannot see — is `unproven`, and the caller turns
+     * that into a typed `HTTP_METHOD_DYNAMIC` entry instead of a GET.
+     */
+    optionsMethod(node, file, bindings = new Map(), depth = 0) {
+        if (depth > MAX_OPTIONS_HOPS)
+            return UNPROVEN_OPTIONS;
+        const expression = unwrapOwnExpression(node);
+        if (ts.isObjectLiteralExpression(expression)) {
+            return this.optionsMethodOfObject(expression, file, bindings, depth);
+        }
+        if (ts.isIdentifier(expression)) {
+            const bound = bindings.get(expression.text);
+            if (bound !== undefined)
+                return this.optionsMethod(bound[0], bound[1], bindings, depth + 1);
+            const constant = this.resolveConstantInitializer(expression.text, file, new Set());
+            if (constant === undefined)
+                return UNPROVEN_OPTIONS;
+            return this.optionsMethod(constant[0], constant[1], bindings, depth + 1);
+        }
+        if (ts.isCallExpression(expression) && ts.isIdentifier(expression.expression)) {
+            return this.optionsMethodThroughCall(expression, file, bindings, depth);
+        }
+        return UNPROVEN_OPTIONS;
+    }
+    /** The verb one options object literal carries, spreads included. */
+    optionsMethodOfObject(object, file, bindings, depth) {
+        let result = ABSENT_OPTIONS;
+        for (const property of object.properties) {
+            if (ts.isSpreadAssignment(property)) {
+                result = this.optionsMethod(property.expression, file, bindings, depth + 1);
+            }
+            else if ((ts.isPropertyAssignment(property) || ts.isShorthandPropertyAssignment(property)) &&
+                ts.isIdentifier(property.name) &&
+                property.name.text === 'method') {
+                const initializer = ts.isPropertyAssignment(property) ? property.initializer : property.name;
+                result = this.verbOfLiteral(initializer, file, bindings);
+            }
+            else {
+                continue;
+            }
+            if (result.kind === 'unproven')
+                return UNPROVEN_OPTIONS;
+        }
+        return result;
+    }
+    /** A `method:` member whose value provably is one concrete verb. */
+    verbOfLiteral(node, file, bindings) {
+        const bound = ts.isIdentifier(node) ? bindings.get(node.text) : undefined;
+        const resolved = bound === undefined ? this.evaluate(node, file) : this.evaluate(bound[0], bound[1]);
+        if (resolved.kind !== 'literal')
+            return UNPROVEN_OPTIONS;
+        const verb = normalizeHttpMethodValue(resolved.text);
+        return verb === null ? UNPROVEN_OPTIONS : { kind: 'proven', method: verb };
+    }
+    /** Options returned by a single-return function declared in the scan. */
+    optionsMethodThroughCall(call, file, bindings, depth) {
+        const name = ts.isIdentifier(call.expression) ? call.expression.text : '';
+        if (name.length === 0)
+            return UNPROVEN_OPTIONS;
+        const declared = this.functionOf(name, file);
+        if (declared === undefined)
+            return UNPROVEN_OPTIONS;
+        const returned = returnedExpression(declared);
+        if (returned === undefined)
+            return UNPROVEN_OPTIONS;
+        const next = new Map(bindings);
+        const parameter = declared.parameters[0];
+        const argument = call.arguments[0];
+        if (parameter !== undefined &&
+            argument !== undefined &&
+            ts.isIdentifier(parameter.name)) {
+            next.set(parameter.name.text, [argument, file]);
+        }
+        return this.optionsMethod(returned, file, next, depth + 1);
+    }
+    /** A module-scope function declaration, same file or relative import. */
+    functionOf(name, file) {
+        const own = this.modelOf(file)?.functions.get(name);
+        if (own !== undefined)
+            return own;
+        const imported = this.importedFrom(file, name);
+        if (imported === null)
+            return undefined;
+        return this.modelOf(imported)?.functions.get(name);
+    }
     resolveSpecifier(fromFile, specifier) {
         const base = posix.dirname(fromFile.split('\\').join('/'));
         const joined = posix.normalize(posix.join(base, specifier));