carrick 0.3.114 → 0.3.116

package/sidecar/dist/src/type-inferrer.js

@@ -21,6 +21,8 @@ import * as path from 'node:path';
 import { Node, SyntaxKind, VariableDeclarationKind, ts, } from 'ts-morph';
 import { typeToStringAsDeclared } from './print-type.js';
 import { validateInferRequestItem } from './validators.js';
+import { declarationSite } from './bundler.js';
+import { printedTypeHoldsTopType, relateSymbolToRead } from './symbol-relation.js';
 import { notePrintedType, PrintedTypes } from './printed-names.js';
 import { externalImportsOf, isExternalOrigin } from './origin.js';
 import { reachedOnlyOnFailure } from './failure-path.js';
@@ -28,7 +30,7 @@ import { readResponseModes } from './response-modes.js';
 import { functionAtLine } from './function-line-index.js';
 import { endLineOf, startLineOf } from './line-index.js';
 import { elapsedMs, inferTiming, phaseClock, timedPhase } from './infer-timing.js';
-import { classifyStatusCodes, constituents, httpStatus, statesNoBody, statusKeyCode, statusTableOf, successEntries, } from './capture/index.js';
+import { classifyStatusCodes, constituents, httpStatus, statesNoBody, statesNoShape, statusKeyCode, statusTableOf, successEntries, } from './capture/index.js';
 import { addedDiagnostics, applyInsertions, fileDiagnostics, literalInsertions, mapBack, mapForward, normalise, pathOf, } from './unwidened.js';
 import { expandTypeStructural, jsonWireType, } from './type-structural-expander.js';
 /**
@@ -240,6 +242,12 @@ const BODY_MEMBER_NAMES = new Set(['data', 'body', 'json']);
  * JSON, or as raw text (carrick#1842).
  */
 const WHOLE_BODY_READS = new Set(['json', 'text']);
+/**
+ * The other zero-argument reads the platform `Response` takes its whole body
+ * out with, in a form that is neither JSON nor text. The expression that
+ * holds one holds the body the call answered with (carrick#2112).
+ */
+const BINARY_BODY_READS = new Set(['arrayBuffer', 'blob', 'bytes', 'formData']);
 /** The body format a caller names to read a response as raw text (carrick#1842). */
 const RAW_TEXT_FORMAT = 'text';
 /**
@@ -415,8 +423,9 @@ export class TypeInferrer {
      * @param onRequestDone - Called once per request, as the batch is done with it
      * @returns InferResult with inferred types or errors
      */
-    infer(requests, extractionConfig, onRequestDone) {
+    infer(requests, extractionConfig, onRequestDone, modelSymbols) {
         const started = performance.now();
+        this.modelSymbols = new Map((modelSymbols ?? []).map((symbol) => [symbol.alias, symbol]));
         const inferredTypes = [];
         const errors = [];
         /** Response inferences the unwidened reading re-reads (carrick#1516). */
@@ -500,6 +509,74 @@ export class TypeInferrer {
             errors: errors.length > 0 ? errors : undefined,
         };
     }
+    /** The types the model named, by the alias of the row each is for (carrick#2111). */
+    modelSymbols = new Map();
+    /**
+     * carrick#2111: where the model named a type for the response this request
+     * reads, record on `inferred` how that type relates to the compiler's type
+     * of what the handler sends (`read`, one type per surviving branch). The
+     * driver keeps, re-depths or drops the model's symbol on the answer.
+     *
+     * Nothing is recorded, and the symbol stands, where there is nothing to
+     * compare: the symbol does not resolve in this program, or the published
+     * read holds `any` or `unknown` somewhere.
+     */
+    relateModelSymbol(request, inferred, read) {
+        if (request.infer_kind !== 'response_body' && request.infer_kind !== 'function_return')
+            return;
+        const named = this.modelSymbols.get(inferred.alias);
+        if (!named)
+            return;
+        const types = read.filter((type) => type !== undefined);
+        if (types.length !== read.length || types.length === 0)
+            return;
+        if (printedTypeHoldsTopType(inferred.type_string))
+            return;
+        try {
+            const symbolType = this.modelSymbolType(named);
+            if (!symbolType)
+                return;
+            const answer = relateSymbolToRead(this.project.getTypeChecker().compilerObject, symbolType.compilerType, types.map((type) => type.compilerType));
+            if (answer)
+                inferred.model_symbol_relation = answer;
+        }
+        catch (err) {
+            // The relation only ever adds an answer; it never costs one.
+            this.logError(`Model symbol relation failed for ${inferred.alias}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * `func` is the function the row's line names: it opens on that line (a
+     * method under its decorators, an exported handler), or it is the handler
+     * of the registration that opens there (`app.post<…>(\n '/path',\n async
+     * (request) => { … })`, or a named handler declared elsewhere).
+     */
+    isTheRowsOwnFunction(request, func) {
+        if (startLineOf(func) === request.line_number)
+            return true;
+        return this.registrationAtLine(func.getSourceFile(), request.line_number)?.handler === func;
+    }
+    /**
+     * The declared type of a symbol the model named, found as the bundle finds
+     * it (through a barrel's re-exports), in a file this program already
+     * holds. A name that declares a value and no type resolves to nothing.
+     */
+    modelSymbolType(named) {
+        const absolutePath = path.isAbsolute(named.source_file)
+            ? named.source_file
+            : path.resolve(this.repoRoot, named.source_file);
+        const sourceFile = this.project.getSourceFile(absolutePath);
+        if (!sourceFile)
+            return undefined;
+        const site = declarationSite(sourceFile, named.symbol_name, named.source_file, this.expandOrigin());
+        if ('reason' in site)
+            return undefined;
+        const declaration = site.sourceFile.getInterface(site.name) ??
+            site.sourceFile.getTypeAlias(site.name) ??
+            site.sourceFile.getClass(site.name) ??
+            site.sourceFile.getEnum(site.name);
+        return declaration?.getType();
+    }
     /**
      * carrick#1836: list on `result` the declarations behind the names its text
      * prints that the request's file cannot resolve (`PrintedTypes.namesIn`).
@@ -915,6 +992,16 @@ export class TypeInferrer {
         if (provenance && provenance.length > 0) {
             inferred.any_provenance = provenance;
         }
+        // The relation is asked only of the function the row's own line names.
+        // A locator that binds inside a callback of the handler (`user` in
+        // `this.users.find((user) => user.id === id)`) reaches this with that
+        // callback, whose return is not the route's, and a read of the wrong
+        // function must never displace the symbol the model named.
+        if (this.modelSymbols.has(inferred.alias) && this.isTheRowsOwnFunction(request, func)) {
+            this.relateModelSymbol(request, inferred, [
+                unwrapResult.wasUnwrapped ? unwrapResult.payloadType : awaitedType,
+            ]);
+        }
         return inferred;
     }
     /**
@@ -1201,7 +1288,11 @@ export class TypeInferrer {
             typeString = this.expandResolvedTypeStructural(resolved, typeText(resolved, payloadNode), this.wireFormatFor(request));
         }
         const anchor = this.unwrapArrayLevels(this.unwrapPromiseType(payloadType));
-        return this.createInferredType(request, typeString, false, this.getNodeLocation(payloadNode), unwrapResult.wasUnwrapped ? unwrapResult.typeString : undefined, this.primaryTypeSymbol(anchor.element), anchor.depth, this.primaryTypeSymbolSource(anchor.element));
+        const inferred = this.createInferredType(request, typeString, false, this.getNodeLocation(payloadNode), unwrapResult.wasUnwrapped ? unwrapResult.typeString : undefined, this.primaryTypeSymbol(anchor.element), anchor.depth, this.primaryTypeSymbolSource(anchor.element));
+        this.relateModelSymbol(request, inferred, [
+            unwrapResult.wasUnwrapped ? unwrapResult.payloadType : this.unwrapPromiseType(payloadType),
+        ]);
+        return inferred;
     }
     /**
      * The handler a module exports on `line`: a function that opens on exactly
@@ -1456,6 +1547,7 @@ export class TypeInferrer {
         const inferred = this.createInferredType(request, recovered.typeString, recovered.isExplicit, this.getNodeLocation(recovered.node), undefined, resolvedSymbol ?? writtenAnchor?.symbol, writtenAnchor ? writtenAnchor.depth : recoveredAnchor?.depth, writtenAnchor ? writtenAnchor.source : resolvedSource);
         if (recovered.responseModes)
             inferred.response_modes = recovered.responseModes;
+        this.relateModelSymbol(request, inferred, recovered.readTypes);
         return inferred;
     }
     /**
@@ -2215,9 +2307,25 @@ export class TypeInferrer {
             if (requestType) {
                 return this.declaredRequestInferredType(request, requestType, this.getNodeLocation(registrationHandler));
             }
-            // A genuinely payload-less handler (no typed request read): do NOT fall
-            // through to read the registration call's return type, which would emit a
-            // spurious framework type. Report unresolved, as before this capability.
+            // carrick#827: the handler reads nothing from its parameters, so the
+            // route takes no request body, and that is a decision. Left undecided,
+            // the capture re-reads this same span and publishes the registration
+            // call's own type (`void` wherever the server library resolves) as the
+            // route's request contract.
+            if (this.handlerReadsNothingFromItsParameters(registrationHandler)) {
+                this.log(`Route registration at ${request.file_path}:${request.line_number}: its handler reads ` +
+                    'nothing from its parameters; the route takes no request body');
+                return this.decidedAbstain(request, this.getNodeLocation(registrationHandler), {
+                    path: '',
+                    kind: 'unknown',
+                    reason: 'no_request_body',
+                    detail: "the route's handler reads nothing from its parameters (each use of one is a call " +
+                        'whose value it discards or returns), so the route takes no request body',
+                });
+            }
+            // A handler that reads from a parameter and states no type at the read:
+            // do NOT fall through to read the registration call's return type, which
+            // would emit a spurious framework type. Report unresolved, as before.
             this.log(`Route registration at ${request.file_path}:${request.line_number} has no typed request read; leaving unresolved`);
             return null;
         }
@@ -2475,7 +2583,20 @@ export class TypeInferrer {
         if (chainRead) {
             return { terminal: chainRead, projectionOnly: false, projections: [] };
         }
-        const returnStmt = callExpr.getFirstAncestorByKind(SyntaxKind.ReturnStatement);
+        // A return statement answers only for a call of the function it returns
+        // from (carrick#2282). The nearest `return` above a call in a callback is
+        // an OUTER function's, and its expression is what that function hands
+        // back with the callback inside it: a command table, a client object, a
+        // UI element. The one callback it does answer for is the executor of a
+        // promise it returns (`return new Promise<T>((resolve) => { request(…,
+        // (res) => resolve(…)) })`): what the caller receives is what that
+        // promise settles with, and the call made in the executor produces it.
+        const nearestReturn = callExpr.getFirstAncestorByKind(SyntaxKind.ReturnStatement);
+        const returnStmt = nearestReturn &&
+            (this.findContainingFunctionForNode(nearestReturn) === func ||
+                this.callIsInReturnedPromiseExecutor(nearestReturn, func))
+            ? nearestReturn
+            : undefined;
         if (returnStmt) {
             const returnExpr = returnStmt.getExpression();
             if (returnExpr) {
@@ -2505,6 +2626,15 @@ export class TypeInferrer {
             const projections = [];
             /** The value itself was read: returned, passed, aliased, or body-read. */
             let sawWholeRead = false;
+            // Where the call's own value states no type, a call that takes it whole
+            // is the first place the source states one, and the walk follows it
+            // (`parse(raw)` after `const raw = await readRaw()`, carrick#1375).
+            const callValue = this.unwrapPromiseType(callExpr.getType());
+            const callValueIsUntyped = callValue.isAny() || callValue.isUnknown();
+            // A transport response handed whole to a helper is a body read through
+            // that helper (`const data: T = await parseJson(response)`), as
+            // `response.json()` is one in place.
+            const callValueIsTransport = this.typeIsOrContainsResponseMachinery(callValue);
             const startPos = callExpr.getStart();
             const candidates = this.collectDefUseNodes(func);
             for (const expr of candidates) {
@@ -2582,25 +2712,113 @@ export class TypeInferrer {
                         }
                     }
                 }
-                // The last expression the value flows into is the call's payload — a
-                // cast, a parse, an alias. An expression that only reads MEMBERS out
-                // of it is a projection and states a part of the payload, never the
-                // payload: the hook that derives `query.data?.flags` off a query
-                // result published a boolean map as the expected response of a call
-                // whose envelope the client declares in full (carrick#1375).
+                // A later expression answers for the call only where it RESTATES the
+                // value: an alias, a cast, a typed binding. An expression that only
+                // reads MEMBERS out of it is a projection and states a part of the
+                // payload, never the payload: the hook that derives
+                // `query.data?.flags` off a query result published a boolean map as
+                // the expected response of a call whose envelope the client declares
+                // in full (carrick#1375). Any other use computes something else from
+                // the value (`describe(page)`, `Math.max(...items.map(…))`,
+                // `rows.map(…)`, `flag && render(row)`): it reads the value whole, and
+                // the answer stays the call's own (carrick#2112). An expression that
+                // takes the body out of a transport response in a form that is not
+                // JSON or text (`new Uint8Array(await res.arrayBuffer())`) holds the
+                // body, and answers as it did.
                 if (this.expressionUsesNames(expr, currentNames) &&
                     !this.usesNamesOnlyByProjection(expr, currentNames)) {
-                    lastNode = expr;
+                    if (callValueIsUntyped ||
+                        this.restatesTrackedValue(expr, currentNames) ||
+                        this.holdsBinaryBodyRead(expr, currentNames) ||
+                        (callValueIsTransport && this.handsTrackedValueToACall(expr, currentNames))) {
+                        lastNode = expr;
+                    }
+                    else {
+                        sawWholeRead = true;
+                    }
                 }
             }
             return {
-                terminal: lastNode,
+                terminal: this.destructuredValueTerminal(lastNode, binding.node, callExpr, callValueIsTransport),
                 projectionOnly: projections.length > 0 && !sawWholeRead,
                 projections,
             };
         }
         return { terminal: callExpr, projectionOnly: false, projections: [] };
     }
+    /**
+     * Where the walk ends on the call's own destructuring binding (`const {
+     * tasks } = await api.list()`), the declaration has no type of its own: the
+     * checker answers `any` for it. The value it takes apart is the call's, so
+     * the call answers (carrick#2112). Not for a transport value: a helper's
+     * `{ body, response }` read as text would bypass the capture's machinery
+     * guard, so that binding stays unread and the capture answers the row.
+     */
+    destructuredValueTerminal(lastNode, bindingNode, callExpr, callValueIsTransport) {
+        if (lastNode !== bindingNode ||
+            callValueIsTransport ||
+            !Node.isVariableDeclaration(lastNode) ||
+            Node.isIdentifier(lastNode.getNameNode())) {
+            return lastNode;
+        }
+        return callExpr;
+    }
+    /**
+     * `expr` declares a name for what a call returns when it is handed a
+     * tracked name whole (`const data: T = await parseJson(response, 'op')`).
+     */
+    handsTrackedValueToACall(expr, names) {
+        if (!Node.isVariableDeclaration(expr))
+            return false;
+        const init = this.unwrapExpressionNode(expr.getInitializer());
+        return (Node.isCallExpression(init) &&
+            init
+                .getArguments()
+                .some((argument) => this.isIdentifierUsage(this.unwrapExpressionNode(argument), names)));
+    }
+    /** `expr` holds a binary whole-body read taken on a tracked name. */
+    holdsBinaryBodyRead(expr, names) {
+        return expr
+            .getDescendantsOfKind(SyntaxKind.Identifier)
+            .some((id) => this.isIdentifierUsage(id, names) &&
+            this.bodyReadOnReceiver(id, BINARY_BODY_READS) !== undefined);
+    }
+    /**
+     * `func`, the function a call is made in, is the executor of the promise
+     * `returnStmt` returns: `return new Promise<T>((resolve, reject) => { … })`
+     * (carrick#2282). The promise is recognised by the language's await
+     * protocol on the constructed value, never by a name.
+     */
+    callIsInReturnedPromiseExecutor(returnStmt, func) {
+        if (!func || !Node.isReturnStatement(returnStmt))
+            return false;
+        const returned = this.unwrapExpressionNode(returnStmt.getExpression());
+        if (!Node.isNewExpression(returned))
+            return false;
+        const [executor] = returned.getArguments();
+        if (!executor || this.unwrapExpressionNode(executor) !== func)
+            return false;
+        const constructed = returned.getType();
+        return this.unwrapPromiseType(constructed) !== constructed;
+    }
+    /**
+     * `expr` declares a name for the tracked value as it is: its initializer,
+     * with the wrappers that leave a value what it was peeled (parentheses,
+     * `await`, `as`, `satisfies`, `!`), is a tracked name (carrick#2112). The
+     * declaration's type is then the value's, as the source restates it.
+     */
+    restatesTrackedValue(expr, names) {
+        if (!Node.isVariableDeclaration(expr))
+            return false;
+        let value = expr.getInitializer();
+        for (;;) {
+            const peeled = value && this.unwrapExpressionNode(value);
+            value = peeled && Node.isSatisfiesExpression(peeled) ? peeled.getExpression() : peeled;
+            if (value === peeled)
+                break;
+        }
+        return !!value && this.isIdentifierUsage(value, names);
+    }
     /**
      * True when a member read on the call's result resolves to one of that
      * result's own TYPE ARGUMENTS — the source is unwrapping a generic envelope
@@ -2668,6 +2886,10 @@ export class TypeInferrer {
      * as written.
      */
     resultCarrierPayload(type, at, projections, where, callArgs) {
+        const deferred = this.deferredConditionalPayload(type, at, projections, where, callArgs);
+        if (deferred !== undefined) {
+            return deferred;
+        }
         const shape = this.resultCarrierArguments(type, at, callArgs);
         if (!shape) {
             return undefined;
@@ -2736,6 +2958,90 @@ export class TypeInferrer {
             'only non-error one and the source reads none of them out. Not guessing which ' +
             'argument is the payload');
     }
+    /**
+     * carrick#1841: the branches of a conditional type the compiler left
+     * deferred on a type parameter, each with its promise-like peeled, or
+     * `undefined` for any other type.
+     *
+     * Inside a generic function whose result depends on a type parameter it has
+     * not fixed (`<Throw extends boolean>(o) => client.get<Table, Errors,
+     * Throw>(…)`), the call's result is such a conditional. The compiler states
+     * what its branches allow itself: the constraint of the conditional, which
+     * is its apparent type. No branch is read off the alias's declaration.
+     */
+    deferredConditionalBranches(type) {
+        const compilerType = type.compilerType;
+        if (!(compilerType.flags & ts.TypeFlags.Conditional))
+            return undefined;
+        const checked = compilerType.checkType;
+        if (!(checked.flags & ts.TypeFlags.TypeParameter))
+            return undefined;
+        let apparent;
+        try {
+            apparent = type.getApparentType();
+        }
+        catch {
+            return undefined;
+        }
+        if (apparent === type || apparent.isUnknown() || apparent.isAny())
+            return undefined;
+        const members = apparent.isUnion() ? apparent.getUnionTypes() : [apparent];
+        return members.map((member) => this.unwrapThenableType(this.unwrapPromiseType(member)));
+    }
+    /**
+     * carrick#1841: what a call result deferred on a type parameter carries,
+     * read through its branches. `undefined` where `type` is no such
+     * conditional, or none of its branches is a result carrier, and the type
+     * keeps the answer it had.
+     *
+     * Each branch that is a carrier is read by the carrier read, with the
+     * call's own type arguments. Every one of them must name the same payload,
+     * by the compiler's type identity, and every other branch must hold that
+     * payload as the type of one of its members (the branch a client answers
+     * with when it throws on failure holds the body and no error side). Then
+     * the payload is the body whichever branch the caller fixes. A carrier
+     * branch that states no contract decides for the whole. Branches that
+     * disagree state none: the conditional is the client's bookkeeping and is
+     * never published as written.
+     */
+    deferredConditionalPayload(type, at, projections, where, callArgs) {
+        const branches = this.deferredConditionalBranches(type);
+        if (!branches)
+            return undefined;
+        const reads = branches.map((branch) => ({
+            branch,
+            read: this.resultCarrierPayload(branch, at, projections, where, callArgs),
+        }));
+        const carriers = reads.flatMap((entry) => (entry.read ? [entry.read] : []));
+        if (carriers.length === 0)
+            return undefined;
+        const abstained = carriers.find((read) => 'abstain' in read);
+        if (abstained)
+            return abstained;
+        const [{ payload }] = carriers;
+        const isPayload = (candidate) => candidate.compilerType === payload.compilerType;
+        if (!carriers.every((read) => isPayload(read.payload))) {
+            return {
+                abstain: "the call's result depends on a type parameter and its branches carry different " +
+                    'bodies, so this site states no response contract',
+            };
+        }
+        const holdsPayload = (branch) => branch.getProperties().some((property) => {
+            try {
+                return isPayload(property.getTypeAtLocation(at));
+            }
+            catch {
+                return false;
+            }
+        });
+        if (!reads.every((entry) => entry.read !== undefined || holdsPayload(entry.branch))) {
+            return {
+                abstain: "the call's result depends on a type parameter and one of its branches does not " +
+                    'hold the body the others carry, so this site states no response contract',
+            };
+        }
+        return { payload };
+    }
     /**
      * The value of a response table's one success row, for a table a carrier
      * holds as itself rather than through its body. `undefined` where the table
@@ -2788,6 +3094,17 @@ export class TypeInferrer {
      * holds as a member. `undefined` when `type` is not a carrier.
      */
     resultCarrierArguments(type, at, callArgs = []) {
+        // carrick#1841: a conditional deferred on a type parameter is a carrier
+        // where one of its branches is.
+        const deferredBranches = this.deferredConditionalBranches(type);
+        if (deferredBranches) {
+            for (const branch of deferredBranches) {
+                const shape = this.resultCarrierArguments(branch, at, callArgs);
+                if (shape)
+                    return shape;
+            }
+            return undefined;
+        }
         const carrier = this.unwrapThenableType(this.unwrapPromiseType(type));
         if (!carrier.isUnion()) {
             return undefined;
@@ -3278,14 +3595,15 @@ export class TypeInferrer {
      * The zero-argument whole-body read that takes `receiver` as its receiver,
      * `res.json()` or `res.text()`, or `undefined`. A text read is a body read
      * like a json one (carrick#1842): without it, `return res.text()` left the
-     * walk on the response binding and published the transport object.
+     * walk on the response binding and published the transport object. `reads`
+     * names the reads asked for.
      */
-    bodyReadOnReceiver(receiver) {
+    bodyReadOnReceiver(receiver, reads = WHOLE_BODY_READS) {
         const access = receiver.getParent();
         if (!access ||
             !Node.isPropertyAccessExpression(access) ||
             access.getExpression() !== receiver ||
-            !WHOLE_BODY_READS.has(access.getName())) {
+            !reads.has(access.getName())) {
             return undefined;
         }
         const call = access.getParent();
@@ -4126,6 +4444,12 @@ export class TypeInferrer {
      */
     expandResolvedTypeStructural(type, fallback, wire = 'declared') {
         try {
+            // carrick#2116: a narrowed `unknown` or `object`, at the root or as a
+            // member of the root union, states no shape. It would print `{}` or
+            // `object` and be judged as a body that lacks every field.
+            if (statesNoShape(this.project.getTypeChecker().compilerObject, type.compilerType)) {
+                return 'unknown';
+            }
             const expanded = expandTypeStructural(type, this.expandOrigin(), { wire });
             // A wire print that differs from the declared one is the answer even
             // without an inlined object: a bare `Date` payload sends a string.
@@ -4276,6 +4600,7 @@ export class TypeInferrer {
             // A union joined several payloads, so there is no single anchor — the
             // same rule the wrapper-unwrap path applies.
             anchorType: distinct.length === 1 ? distinct[0].anchorType : undefined,
+            readTypes: distinct.map((c) => c.anchorType),
             statedTypeNode: distinct.length === 1 ? distinct[0].statedTypeNode : undefined,
         };
     }
@@ -5914,6 +6239,130 @@ export class TypeInferrer {
         }
         return undefined;
     }
+    /**
+     * True when `handler` reads nothing from the incoming message (carrick#827):
+     * every use of one of its parameters, named or destructured, is the receiver
+     * of a call chain whose value the handler discards or returns
+     * (`reply.json(result)`, `return c.status(201).json(result)`). That is a
+     * send. A returned chain must end in a call that takes an argument, so a
+     * read handed straight back (`return request.json()`) is not one.
+     *
+     * Anything else may be a read of the body and makes this false: a property
+     * read, a call whose value is used, a parameter handed whole to another
+     * function, or a call in the chain handed an argument that can receive what
+     * the parameter gives (`argumentCanReceive`: a callback, an object with a
+     * method), as in `request.pipe(dest)`, `request.on('data', cb)` and
+     * `request.json().then(cb)`. No method or property name is consulted. A
+     * handler with no parameter, or one that uses `this`, proves nothing: it may
+     * read the message from `this` or a closure.
+     */
+    handlerReadsNothingFromItsParameters(handler) {
+        // A declared `this` parameter, or any `this` in the body, is a way in the
+        // walk below does not follow.
+        const parameters = new Set(handler.getParameters().filter((parameter) => parameter.getName() !== 'this'));
+        if (parameters.size === 0)
+            return false;
+        const body = handler.getBody();
+        if (!body)
+            return false;
+        if (body.getFirstDescendantByKind(SyntaxKind.ThisKeyword))
+            return false;
+        const namesAParameter = (identifier) => (identifier.getSymbol()?.getDeclarations() ?? []).some((declaration) => {
+            const parameter = Node.isParameterDeclaration(declaration)
+                ? declaration
+                : Node.isBindingElement(declaration)
+                    ? declaration.getFirstAncestorByKind(SyntaxKind.Parameter)
+                    : undefined;
+            return parameter !== undefined && parameters.has(parameter);
+        });
+        for (const identifier of body.getDescendantsOfKind(SyntaxKind.Identifier)) {
+            if (!namesAParameter(identifier))
+                continue;
+            // Climb the call chain the parameter is the root receiver of.
+            let top = identifier;
+            let lastCall;
+            for (;;) {
+                const parent = top.getParent();
+                if (!parent)
+                    break;
+                if (Node.isPropertyAccessExpression(parent) && parent.getExpression() === top) {
+                    top = parent;
+                }
+                else if (Node.isCallExpression(parent) && parent.getExpression() === top) {
+                    // A send hands the parameter data; an argument able to receive may
+                    // be where the body goes.
+                    if (parent.getArguments().some((argument) => this.argumentCanReceive(argument))) {
+                        return false;
+                    }
+                    lastCall = parent;
+                    top = parent;
+                }
+                else if ((Node.isAwaitExpression(parent) ||
+                    Node.isParenthesizedExpression(parent) ||
+                    Node.isNonNullExpression(parent)) &&
+                    parent.getExpression() === top) {
+                    top = parent;
+                }
+                else {
+                    break;
+                }
+            }
+            // The chain has to end in a call: a property read yields a value.
+            if (!lastCall || this.unwrapExpressionNode(top) !== lastCall)
+                return false;
+            const holder = top.getParent();
+            const discarded = !!holder && Node.isExpressionStatement(holder);
+            const returned = !!holder &&
+                (Node.isReturnStatement(holder) || (holder === handler && handler.getBody() === top)) &&
+                lastCall.getArguments().length > 0;
+            if (!discarded && !returned)
+                return false;
+        }
+        return true;
+    }
+    /**
+     * True unless `argument` is proven to be data that cannot receive anything
+     * from the call it is handed to (carrick#827). Data is a primitive or literal,
+     * `null`/`undefined`, or an object with no call or construct signature and
+     * no callable member; an array of such, or a union all of whose members are.
+     * A callback, an object with a method (a stream, an emitter), or a type the
+     * compiler cannot state (`any`, `unknown`, a type parameter) can receive.
+     * Sibling of `callResultIsPlainData`, which reads a call's result and so
+     * rejects primitives and empty objects; an argument of either is data.
+     */
+    argumentCanReceive(argument) {
+        const canReceive = (type, depth) => {
+            if (depth > 3)
+                return true;
+            if (type.isAny() || type.isUnknown() || type.isTypeParameter())
+                return true;
+            if (type.isUnion()) {
+                return type.getUnionTypes().some((member) => canReceive(member, depth + 1));
+            }
+            if (type.isIntersection()) {
+                return type.getIntersectionTypes().some((member) => canReceive(member, depth + 1));
+            }
+            const element = type.getArrayElementType();
+            if (element)
+                return canReceive(element, depth + 1);
+            if (type.isTuple()) {
+                return type.getTupleElements().some((member) => canReceive(member, depth + 1));
+            }
+            if (!type.isObject())
+                return false;
+            if (this.isCallableType(type))
+                return true;
+            const indexed = type.getStringIndexType() ?? type.getNumberIndexType();
+            const callable = (held) => held.isAny() ||
+                (held.isUnion()
+                    ? held.getUnionTypes().some((member) => this.isCallableType(member))
+                    : this.isCallableType(held));
+            if (indexed && callable(indexed))
+                return true;
+            return type.getProperties().some((member) => callable(member.getTypeAtLocation(argument)));
+        };
+        return canReceive(argument.getType(), 0);
+    }
     /**
      * Scan a handler function body for the FIRST request-body read that carries a
      * type, and return that type's structural text — or null when the body holds
@@ -7489,6 +7938,20 @@ export class TypeInferrer {
         const MIN_REVERSE_MATCH_COVERAGE = 0.5;
         const containingMatches = candidates.filter((c) => c.text.includes(normalizedTarget));
         if (containingMatches.length > 0) {
+            // A text that is only a wrapped call's first line (`load({`) is held by
+            // every sibling that opens alike, and the smallest of them is not the
+            // one the locator names (carrick#2114). The nodes whose own text OPENS
+            // with the text are the ones a first line names: among those the stated
+            // line decides, then size. A fragment from the middle of a node opens
+            // nothing, and stays on the smallest node holding it.
+            const opening = lineNumber === undefined
+                ? []
+                : containingMatches.filter((c) => c.text.startsWith(normalizedTarget));
+            if (lineNumber !== undefined && opening.length > 0) {
+                const distance = (c) => Math.abs(startLineOf(c.node) - lineNumber);
+                const nearest = Math.min(...opening.map(distance));
+                return this.pickBestMatch(opening.filter((c) => distance(c) === nearest).map((c) => c.node), lineNumber);
+            }
             return this.pickBestMatch(containingMatches.map((c) => c.node), lineNumber);
         }
         const reverseMatches = candidates.filter((c) => c.text.length >= MIN_REVERSE_MATCH_LEN &&