carrick 0.3.124 → 0.3.126

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

@@ -190,6 +190,18 @@ const SERIALISED_BODY_UNREAD_DETAIL = {
 };
 /** `any` or `unknown` as a type in printed type text, not as a member name or a string. */
 const TOP_TYPE_TOKEN = /(?<![\w$'"`])(?:any|unknown)(?![\w$'"`?:])/;
+/**
+ * The type an assertion states, or undefined when it states none. A const
+ * assertion (`x as const`, `<const>x`) narrows its operand's own type and
+ * names no type: its type node prints as `const`, a name nothing declares
+ * (carrick#2590). The walk stops there rather than reaching for an assertion
+ * further out, which describes a larger value than the read.
+ */
+function statedAssertionType(typeNode) {
+    if (!typeNode || ts.isConstTypeReference(typeNode.compilerNode))
+        return undefined;
+    return typeNode;
+}
 /**
  * The items whose whitespace-collapsed texts differ, first of each kept, in
  * order: how a joined union drops a member it already has.
@@ -1996,6 +2008,27 @@ export class TypeInferrer {
             });
         }
         typeString = this.unwrapPromise(typeString, returnType);
+        // carrick#2594: the call's value is untyped (`Promise<any>`,
+        // `Promise<unknown>`), and the function it is made in states its type:
+        // it returns the value from a function with a declared return type, holds
+        // it in an annotated name, validates it with a schema, narrows it with a
+        // function that returns it unchanged, casts it whole, or hands it to a
+        // typed parameter. A function that converts the value into something new
+        // states nothing about it, and neither does a use on a failure path.
+        const untypedAnswer = typeString.trim() === 'any' || typeString.trim() === 'unknown';
+        if (untypedAnswer && func && !explicitType && !unwrapResult.wasUnwrapped && !carrierPayload) {
+            const stated = this.statedInFunction(callExpr, func, {
+                returned: true,
+                parameters: true,
+                skipFailurePaths: true,
+            });
+            if (stated) {
+                this.log(`Call result at ${where} is untyped, and its function states its type ` +
+                    `(${stated.how}); publishing that type`);
+                typeString = stated.text;
+                isExplicit = true;
+            }
+        }
         // #336: consumer analogue of the #306 producer anchor. Anchor on the
         // CALL's own payload (the rule-extracted Type, else the awaited call
         // type), peeling array levels to the element symbol + depth. Without the
@@ -2532,7 +2565,24 @@ export class TypeInferrer {
         // is its response, and a config's type is the config, so either one read
         // as the body publishes the wrong contract. Follow the call's signature to
         // the argument it sends as the body.
-        const inCall = this.requestBodyInCall(unwrapped);
+        let inCall = this.requestBodyInCall(unwrapped);
+        if (inCall.kind === 'none') {
+            // carrick#2628: the argument goes into a function that builds the body
+            // itself. An abstain here is a decision: capture's own re-read of the
+            // locator would publish the argument as the body.
+            const built = this.bodyBuiltByCallee(unwrapped);
+            if (built.kind === 'abstain') {
+                this.log(`Request locator at ${request.file_path}:${request.line_number}: ${built.why}; ` +
+                    'the argument is not the body');
+                return this.decidedAbstain(request, this.getNodeLocation(unwrapped), {
+                    path: '',
+                    kind: 'unknown',
+                    reason: 'body_built_by_callee',
+                    detail: `the located argument is not the request body: ${built.why}`,
+                });
+            }
+            inCall = built;
+        }
         if (inCall.kind === 'body') {
             this.log(`Request locator at ${request.file_path}:${request.line_number} names ${inCall.from}; ` +
                 'reading the body argument its signature declares');
@@ -2659,18 +2709,22 @@ export class TypeInferrer {
             isExplicit = true;
         }
         // carrick#1166: the read itself is untyped (`await c.req.json()` is `any`
-        // or `unknown`), and the handler validates it by handing it to a schema:
-        // `Schema.safeParse(body)`, `Schema.parse(await c.req.json())`. The schema
-        // declares what a caller may send, so its INPUT is the request contract,
-        // read the way every other request anchor reads a schema (carrick#1101).
+        // or `unknown`), and the handler states its type further on: it validates
+        // it with a schema (`Schema.safeParse(body ?? {})`, whose INPUT is the
+        // request contract, carrick#1101), assigns it to an annotated name
+        // (`let body: T; body = await c.req.json()`), narrows it with a function
+        // that returns it unchanged, or casts the whole value (carrick#2594).
         const readType = this.unwrapPromiseType(payloadType);
         if (!explicitType &&
             !unwrapResult.wasUnwrapped &&
             (readType.isAny() || readType.isUnknown())) {
-            const parsedWith = this.schemaConsumingRead(node);
+            const func = this.findContainingFunctionForNode(node);
+            const parsedWith = func
+                ? this.statedInFunction(node, func, { returned: false, parameters: false, skipFailurePaths: false })
+                : null;
             if (parsedWith) {
                 this.log(`Request locator at ${request.file_path}:${request.line_number} is an untyped read ` +
-                    "the handler validates with a schema; publishing the schema's input");
+                    `its handler states a type for (${parsedWith.how}); publishing that type`);
                 return this.declaredRequestInferredType(request, parsedWith, this.getNodeLocation(node));
             }
         }
@@ -2711,9 +2765,14 @@ export class TypeInferrer {
         // (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);
+        // A return whose value is an object or array literal built around the
+        // call (`return { ok: true, count: countOf(await client.add(…)) }`) hands
+        // back the caller's own value, which holds the result as one part: it
+        // answers for the call no more than a command table does (carrick#2628).
         const returnStmt = nearestReturn &&
             (this.findContainingFunctionForNode(nearestReturn) === func ||
-                this.callIsInReturnedPromiseExecutor(nearestReturn, func))
+                this.callIsInReturnedPromiseExecutor(nearestReturn, func)) &&
+            !this.callIsPartOfReturnedLiteral(callExpr, nearestReturn)
             ? nearestReturn
             : undefined;
         if (returnStmt) {
@@ -2727,8 +2786,9 @@ export class TypeInferrer {
         // the response, so the walk below has nothing to follow, and the call
         // itself would stand as the terminal and publish the transport object.
         // The read is the terminal, as it is when the walk finds it on a binding,
-        // and a call that takes the read and states what it returns says more
-        // than the read does (carrick#1382).
+        // and a call that takes the read and states it (a schema, or a function
+        // that returns it unchanged) says more than the read does (carrick#1382,
+        // carrick#2595).
         const inPlaceRead = this.bodyReadOnCallValue(callExpr);
         if (inPlaceRead) {
             return {
@@ -2746,8 +2806,11 @@ export class TypeInferrer {
             /** 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).
+            // and states it (a schema, or a function that returns it unchanged) is
+            // the first place the source states one, and the walk follows it
+            // (`parse(raw)` after `const raw = await readRaw()`, carrick#1375). A
+            // converter, or a declaration whose body cannot be read, states nothing
+            // about the value (carrick#2595).
             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
@@ -2846,7 +2909,7 @@ export class TypeInferrer {
                 // body, and answers as it did.
                 if (this.expressionUsesNames(expr, currentNames) &&
                     !this.usesNamesOnlyByProjection(expr, currentNames)) {
-                    if (callValueIsUntyped ||
+                    if ((callValueIsUntyped && this.statesTrackedValue(expr, currentNames)) ||
                         this.restatesTrackedValue(expr, currentNames) ||
                         this.holdsBinaryBodyRead(expr, currentNames) ||
                         (callValueIsTransport && this.handsTrackedValueToACall(expr, currentNames))) {
@@ -2882,18 +2945,51 @@ export class TypeInferrer {
         }
         return callExpr;
     }
+    /**
+     * Between `callExpr` and the return statement around it there is an object
+     * or array literal: the call's result is one part of a value the function
+     * builds and returns.
+     */
+    callIsPartOfReturnedLiteral(callExpr, returnStmt) {
+        const ancestors = callExpr.getAncestors();
+        return ancestors
+            .slice(0, ancestors.indexOf(returnStmt))
+            .some((a) => Node.isObjectLiteralExpression(a) || Node.isArrayLiteralExpression(a));
+    }
     /**
      * `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)));
+        return Node.isVariableDeclaration(expr) && this.callTakingTrackedValue(expr, names) !== undefined;
+    }
+    /**
+     * The call whose result `expr` declares or assigns a name for, and the
+     * index of its argument that is a tracked name whole, or undefined.
+     */
+    callTakingTrackedValue(expr, names) {
+        const value = Node.isVariableDeclaration(expr)
+            ? expr.getInitializer()
+            : Node.isBinaryExpression(expr) && expr.getOperatorToken().getKind() === SyntaxKind.EqualsToken
+                ? expr.getRight()
+                : undefined;
+        const init = this.unwrapExpressionNode(value);
+        if (!Node.isCallExpression(init))
+            return undefined;
+        const index = init
+            .getArguments()
+            .findIndex((argument) => this.isIdentifierUsage(this.unwrapExpressionNode(argument), names));
+        return index >= 0 ? { call: init, index } : undefined;
+    }
+    /**
+     * `expr` names the result of a call that states the tracked value it takes
+     * (`callStatesItsArgument`): a schema validates it, or the callee returns it
+     * unchanged. A converter's result describes what it built from the value,
+     * not the value (carrick#2595).
+     */
+    statesTrackedValue(expr, names) {
+        const taking = this.callTakingTrackedValue(expr, names);
+        return !!taking && this.callStatesItsArgument(taking.call, taking.index);
     }
     /** `expr` holds a binary whole-body read taken on a tracked name. */
     holdsBinaryBodyRead(expr, names) {
@@ -3480,12 +3576,18 @@ export class TypeInferrer {
      *    serialiser answering `string` describes what the caller did with the
      *    body, not what the body is, and publishing it would be a
      *    concrete-but-wrong contract where the honest `any` of the read is
-     *    merely unresolved.
+     *    merely unresolved;
+     *  - the call states its argument (`callStatesItsArgument`): a schema
+     *    validates it, or the callee returns it unchanged. A converter's
+     *    object result describes what it built, not the body (carrick#2595).
      */
     statedPayloadAroundBodyRead(bodyRead) {
         return this.receivingCallOf(bodyRead, (candidate) => Node.isCallExpression(candidate) &&
             this.callResultIsBound(candidate) &&
-            this.isObjectShape(this.unwrapPromiseType(candidate.getType())));
+            this.isObjectShape(this.unwrapPromiseType(candidate.getType())) &&
+            this.callStatesItsArgument(candidate, candidate
+                .getArguments()
+                .findIndex((argument) => argument.getStart() <= bodyRead.getStart() && bodyRead.getEnd() <= argument.getEnd())));
     }
     /**
      * The source keeps this call's result: it initializes a declaration, is
@@ -4490,22 +4592,14 @@ export class TypeInferrer {
         const asExpr = Node.isAsExpression(node)
             ? node
             : node.getFirstAncestorByKind(SyntaxKind.AsExpression);
-        if (asExpr) {
-            const typeNode = asExpr.getTypeNode();
-            if (typeNode) {
-                return typeNode;
-            }
+        const asType = statedAssertionType(asExpr?.getTypeNode());
+        if (asType) {
+            return asType;
         }
         const typeAssertion = Node.isTypeAssertion(node)
             ? node
             : node.getFirstAncestorByKind(SyntaxKind.TypeAssertionExpression);
-        if (typeAssertion) {
-            const typeNode = typeAssertion.getTypeNode();
-            if (typeNode) {
-                return typeNode;
-            }
-        }
-        return undefined;
+        return statedAssertionType(typeAssertion?.getTypeNode());
     }
     /**
      * Render an explicit annotation (`as T`, `<T>`, or a typed binding) as
@@ -6606,8 +6700,10 @@ export class TypeInferrer {
      *  - a cast on it: `(await request.json()) as NewWidget`;
      *  - the annotation of the binding it initialises:
      *    `const input: NewWidget = await request.json()`;
-     *  - a schema the read, or the binding that holds it, is handed to
-     *    (`schemaConsumingRead`): the schema's input is what a caller may send.
+     *  - a type the handler states for the read further on
+     *    (`statedInFunction`): a schema it is handed to, the annotation of a
+     *    name it is assigned to, a pass-through function, a cast of the whole
+     *    value.
      *
      * The first two are `typeNodeStatedAtRead`, the reading a consumer's
      * response read already gets. An annotation further out is not one of them:
@@ -6623,10 +6719,13 @@ export class TypeInferrer {
                 'reads off the platform request, as the source types that read');
             return this.createInferredType(request, statedText, true, this.getNodeLocation(read));
         }
-        const validated = this.schemaConsumingRead(read);
+        const func = this.findContainingFunctionForNode(read);
+        const validated = func
+            ? this.statedInFunction(read, func, { returned: false, parameters: false, skipFailurePaths: false })
+            : null;
         if (validated) {
             this.log(`Request at ${request.file_path}:${request.line_number} is the body its handler ` +
-                "reads off the platform request and validates with a schema; publishing the schema's input");
+                `reads off the platform request and states a type for (${validated.how}); publishing that type`);
             return this.declaredRequestInferredType(request, validated, this.getNodeLocation(read));
         }
         return null;
@@ -6921,6 +7020,231 @@ export class TypeInferrer {
         }
         return { kind: 'none' };
     }
+    /**
+     * carrick#2628: the located node is an argument of a call into a function
+     * whose body the program holds (an in-repo client method,
+     * `client.addTags(project, unique(tags))`), at a parameter that is not a
+     * body slot. What the call sends is decided inside that function, so the
+     * argument is the body only when the function sends it unchanged. One
+     * level, read off each use of the parameter in the function's body:
+     *
+     *  - the use IS the value of a body-named member (`body: tags`,
+     *    `body: JSON.stringify(tags)`) or of a body slot of a call: the
+     *    argument is the body, and its own type stands (`none`);
+     *  - the use sits inside such a value (`body: { tags }`,
+     *    `body: (event ?? {}) as never`): the body is that value, read at the
+     *    function without the casts around it;
+     *  - the use sits inside an object or array literal that is no body value
+     *    (`send(project, [labels])`): the body cannot be told, abstain.
+     *
+     * Uses that disagree abstain. A generic function's body may be typed by
+     * its type parameters, so it abstains too. A library's declaration
+     * (`fetch`, an installed client) has no body to read and is left alone,
+     * and so is an untyped argument (a handler's `request.body` handed to a
+     * helper): it states no contract to mistake, and the untyped-read path
+     * below reads it.
+     */
+    bodyBuiltByCallee(node) {
+        const own = node.getType();
+        if (own.isAny() || own.isUnknown())
+            return { kind: 'none' };
+        const call = this.receivingCallOf(node, (candidate) => Node.isCallExpression(candidate));
+        if (!call || !Node.isCallExpression(call))
+            return { kind: 'none' };
+        const index = call
+            .getArguments()
+            .findIndex((a) => a.getPos() <= node.getPos() && node.getEnd() <= a.getEnd());
+        if (index < 0)
+            return { kind: 'none' };
+        if (this.requestBodySlots(call)[index])
+            return { kind: 'none' };
+        const callee = this.project.getTypeChecker().getResolvedSignature(call)?.getDeclaration();
+        if (!callee ||
+            !(Node.isFunctionDeclaration(callee) ||
+                Node.isMethodDeclaration(callee) ||
+                Node.isArrowFunction(callee) ||
+                Node.isFunctionExpression(callee))) {
+            return { kind: 'none' };
+        }
+        const body = callee.getBody();
+        if (!body)
+            return { kind: 'none' };
+        const program = this.project.getProgram().compilerObject;
+        if (isExternalOrigin(program, callee.getSourceFile().compilerNode, this.repoRoot, externalImportsOf(this.project))) {
+            return { kind: 'none' };
+        }
+        const param = callee.getParameters()[index];
+        if (!param || param.isRestParameter())
+            return { kind: 'none' };
+        const paramName = param.getNameNode();
+        if (!Node.isIdentifier(paramName))
+            return { kind: 'none' };
+        const paramSymbol = paramName.getSymbol()?.compilerSymbol;
+        if (!paramSymbol)
+            return { kind: 'none' };
+        const checker = this.project.getTypeChecker().compilerObject;
+        const uses = body.getDescendantsOfKind(SyntaxKind.Identifier).filter((id) => {
+            const parent = id.getParent();
+            const symbol = parent && Node.isShorthandPropertyAssignment(parent)
+                ? checker.getShorthandAssignmentValueSymbol(parent.compilerNode)
+                : id.getSymbol()?.compilerSymbol;
+            return symbol === paramSymbol;
+        });
+        const from = 'a call into a function that builds the request body inside itself';
+        let passedThrough = false;
+        const built = [];
+        for (const use of uses) {
+            // carrick#2668: `data ? JSON.stringify(data) : undefined` tests the
+            // argument before it sends it; the test is no body.
+            if (this.inSendNothingTest(use, body))
+                continue;
+            const value = this.bodyValueAround(use, body);
+            if (value === use) {
+                passedThrough = true;
+                continue;
+            }
+            if (value) {
+                built.push(value);
+                continue;
+            }
+            const ancestors = use.getAncestors();
+            const insideLiteral = ancestors
+                .slice(0, ancestors.indexOf(body))
+                .some((a) => Node.isObjectLiteralExpression(a) || Node.isArrayLiteralExpression(a));
+            if (insideLiteral) {
+                return {
+                    kind: 'abstain',
+                    why: `the located argument goes into a value the called function builds and does not send as a body (${from})`,
+                };
+            }
+        }
+        if (built.length === 0)
+            return { kind: 'none' };
+        if (passedThrough) {
+            return { kind: 'abstain', why: `the called function both sends the argument and builds a body from it (${from})` };
+        }
+        if (callee.getTypeParameters().length > 0) {
+            return { kind: 'abstain', why: `the called function is generic, so the body it builds may be typed by its type parameters (${from})` };
+        }
+        const types = built.map((value) => this.sentValue(value));
+        const texts = new Set(types.map((value) => typeText(value.getType(), value)));
+        if (texts.size !== 1) {
+            return { kind: 'abstain', why: `the called function builds more than one body from the argument (${from})` };
+        }
+        const at = types[0];
+        const type = at.getType();
+        if (type.isTypeParameter() || printedTypeHoldsTopType([...texts][0])) {
+            return { kind: 'abstain', why: `the body the called function builds is not fully typed (${from})` };
+        }
+        return { kind: 'body_type', type, at, from };
+    }
+    /**
+     * The request body value `use` is part of, inside `scope`: the value of a
+     * body-named object member, or the argument at a body slot of a call,
+     * looking through parentheses, casts, `await` and a `JSON.stringify`
+     * around it. `use` itself when it is that value whole.
+     */
+    bodyValueAround(use, scope) {
+        let current = use;
+        while (current !== scope) {
+            const parent = current.getParent();
+            if (!parent)
+                return undefined;
+            if (Node.isShorthandPropertyAssignment(parent) &&
+                current === use &&
+                BODY_MEMBER_NAMES.has(parent.getName())) {
+                return use;
+            }
+            if (Node.isPropertyAssignment(parent) &&
+                parent.getInitializer() === current &&
+                BODY_MEMBER_NAMES.has(parent.getName())) {
+                return this.isSameValue(current, use) ? use : current;
+            }
+            if (Node.isCallExpression(parent)) {
+                const index = parent.getArguments().indexOf(current);
+                if (index >= 0 && this.requestBodySlots(parent)[index]?.kind === 'body') {
+                    return this.isSameValue(current, use) ? use : current;
+                }
+            }
+            current = parent;
+        }
+        return undefined;
+    }
+    /** `value` is `use` behind what `sentValue` sees through. */
+    isSameValue(value, use) {
+        return this.sentValue(value) === use;
+    }
+    /**
+     * The value a body slot sends when it sends anything, behind parentheses,
+     * casts, `await`, a `JSON.stringify`, and (carrick#2668) a choice whose
+     * other side sends nothing: `x ? JSON.stringify(x) : undefined`,
+     * `x || null`, `x ?? undefined`. A `?? {}` sends `{}`, so it is a body the
+     * function builds and is not seen through.
+     */
+    sentValue(value) {
+        let current = value;
+        for (;;) {
+            let inner = this.unwrapJsonStringifyArg(this.unwrapExpressionNode(current));
+            if (Node.isConditionalExpression(inner)) {
+                inner = this.sendingBranch(inner) ?? inner;
+            }
+            else if (Node.isBinaryExpression(inner)) {
+                const operator = inner.getOperatorToken().getKind();
+                if ((operator === SyntaxKind.BarBarToken || operator === SyntaxKind.QuestionQuestionToken) &&
+                    this.sendsNothing(inner.getRight(), false)) {
+                    inner = inner.getLeft();
+                }
+            }
+            if (inner === current)
+                return current;
+            current = inner;
+        }
+    }
+    /**
+     * The branch of `choice` that sends something, when its other branch sends
+     * nothing (`undefined`, `null`, `void 0`, or `{}` spread into a request).
+     */
+    sendingBranch(choice) {
+        const whenTrue = choice.getWhenTrue();
+        const whenFalse = choice.getWhenFalse();
+        if (this.sendsNothing(whenFalse, true) && !this.sendsNothing(whenTrue, true))
+            return whenTrue;
+        if (this.sendsNothing(whenTrue, true) && !this.sendsNothing(whenFalse, true))
+            return whenFalse;
+        return undefined;
+    }
+    /** `undefined`, `null`, `void 0`, or (where `emptyObject`) `{}`. */
+    sendsNothing(node, emptyObject) {
+        const value = this.unwrapExpressionNode(node);
+        if (Node.isNullLiteral(value) || Node.isVoidExpression(value))
+            return true;
+        if (Node.isIdentifier(value) && value.getText() === 'undefined')
+            return true;
+        return (emptyObject &&
+            Node.isObjectLiteralExpression(value) &&
+            value.getProperties().length === 0);
+    }
+    /**
+     * carrick#2668, #2664: `use` sits in the test of a choice whose other side
+     * sends nothing (`body ? JSON.stringify(body) : null`,
+     * `...(body === undefined ? {} : { body: JSON.stringify(body) })`). The
+     * test only decides whether the argument is sent.
+     */
+    inSendNothingTest(use, scope) {
+        let current = use;
+        while (current !== scope) {
+            const parent = current.getParent();
+            if (!parent)
+                return false;
+            if (Node.isConditionalExpression(parent) &&
+                parent.getCondition() === current &&
+                this.sendingBranch(parent)) {
+                return true;
+            }
+            current = parent;
+        }
+        return false;
+    }
     /** A string, a string literal, a template literal, or a union of strings. */
     isStringLikeType(type) {
         return (type.isString() ||
@@ -7285,71 +7609,304 @@ export class TypeInferrer {
         return values;
     }
     /**
-     * The contract of the schema a handler validates an untyped body read with
-     * (carrick#1166), or null.
-     *
-     * `read` is the located expression: the read call, or the binding that holds
-     * it. Every call in the enclosing function that takes that value as an
-     * argument is a candidate, and the schema is the call's receiver
-     * (`Schema.safeParse(body)`) or one of its other arguments
-     * (`parse(Schema, body)`). A candidate counts only when it declares schema
-     * types (`schemaOutputType` / `schemaInputType`), so a logger or a service
-     * call the body is also handed to is never read as a contract. No method or
-     * library name is matched.
-     */
-    schemaConsumingRead(read) {
-        const func = this.findContainingFunctionForNode(read);
-        if (!func)
-            return null;
-        const bindings = new Set();
-        const addBinding = (identifier) => {
-            const symbol = identifier?.getSymbol()?.compilerSymbol;
-            if (symbol)
-                bindings.add(symbol);
+     * The type the function a value is made in states for it, where the
+     * compiler types the value itself `any` or `unknown` (carrick#2594), or
+     * null.
+     *
+     * `value` is the located expression: a body read, or a call whose result is
+     * untyped. The value is followed through the names that hold it: a
+     * declaration it initialises, and a name it is assigned to later
+     * (`let body: unknown; body = await read()`). At each place the value or
+     * one of those names is used whole, the source can state a type:
+     *
+     *  0. the annotation of the name that holds it (`let body: Upload`), or the
+     *     declared return type of the function that returns it unchanged (only
+     *     with `reads.returned`);
+     *  1. a schema it is handed to (`Schema.safeParse(body ?? {})`,
+     *     `parse(Schema, body)`): the schema's input is what a sender may send
+     *     (carrick#1166). A candidate counts only when it declares schema types,
+     *     so no method or library name is matched;
+     *  2. a function of the project it is handed to that returns that argument
+     *     unchanged (through casts) or an empty default: its declared return
+     *     type. A function that builds a new value from its argument is a
+     *     converter, and its return type describes what it built, never the
+     *     value it was handed, so it states nothing here;
+     *  3. a cast of the whole value (`(body as { phone: string }).phone`);
+     *  4. the parameter of a call it is handed to (only with
+     *     `reads.parameters`), where that parameter's type is a body shape once
+     *     any callable member is dropped (a function never crosses the wire).
+     *
+     * The first rank with an answer decides. A placeholder (`unknown`,
+     * `Record<string, unknown>`, any type node with `any` or `unknown` written
+     * in it) states nothing, and two different statements in one rank decide
+     * nothing: the answer is null.
+     */
+    statedInFunction(value, func, reads) {
+        const holders = new Set();
+        const positions = [value];
+        const holderUse = (node) => {
+            if (!Node.isIdentifier(node))
+                return false;
+            const symbol = node.getSymbol()?.compilerSymbol;
+            return !!symbol && holders.has(symbol);
         };
-        if (Node.isIdentifier(read)) {
-            addBinding(read);
-        }
-        else {
-            const declaration = read.getFirstAncestorByKind(SyntaxKind.VariableDeclaration);
-            const initializer = declaration?.getInitializer();
-            if (declaration &&
-                initializer &&
-                this.unwrapExpressionNode(initializer) === read &&
-                Node.isIdentifier(declaration.getNameNode())) {
-                addBinding(declaration.getNameNode());
-            }
-        }
-        const carriesRead = (argument) => argument === read ||
-            (Node.isIdentifier(argument) &&
-                bindings.has(argument.getSymbol()?.compilerSymbol));
-        for (const call of func.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-            const args = call.getArguments().map((arg) => this.unwrapExpressionNode(arg));
-            const carrier = args.findIndex(carriesRead);
-            if (carrier < 0)
+        const hold = (name) => {
+            if (!Node.isIdentifier(name))
+                return;
+            const symbol = name.getSymbol()?.compilerSymbol;
+            if (!symbol || holders.has(symbol))
+                return;
+            holders.add(symbol);
+            for (const id of func.getDescendantsOfKind(SyntaxKind.Identifier)) {
+                if (id === name || id.getSymbol()?.compilerSymbol !== symbol)
+                    continue;
+                const parent = id.getParent();
+                if (Node.isVariableDeclaration(parent) && parent.getNameNode() === id)
+                    continue;
+                if (Node.isBinaryExpression(parent) &&
+                    parent.getLeft() === id &&
+                    parent.getOperatorToken().getKind() === SyntaxKind.EqualsToken) {
+                    continue;
+                }
+                positions.push(id);
+            }
+        };
+        hold(value);
+        const found = [];
+        const stateNode = (rank, typeNode, at, how) => {
+            if (!typeNode || this.leavesAPositionOpen(typeNode))
+                return;
+            const text = this.structuralTextFromTypeNode(typeNode);
+            if (text)
+                found.push({ rank, text, at, how });
+        };
+        for (let i = 0; i < positions.length; i++) {
+            const position = positions[i];
+            if (reads.skipFailurePaths &&
+                position !== value &&
+                reachedOnlyOnFailure(position, func, holderUse)) {
                 continue;
-            const candidates = [];
-            const callee = call.getExpression();
-            if (Node.isPropertyAccessExpression(callee)) {
-                candidates.push(callee.getExpression());
             }
-            args.forEach((arg, index) => {
-                if (index !== carrier)
-                    candidates.push(arg);
-            });
-            for (const candidate of candidates) {
-                const candidateType = candidate.getType();
-                if (!this.schemaOutputType(candidateType, candidate) &&
-                    !this.schemaInputType(candidateType, candidate)) {
+            // Climb the wrappers that leave the value what it was: parentheses,
+            // `await`, `!`, `satisfies`, a placeholder cast, and an empty default
+            // (`body ?? {}`).
+            let outer = position;
+            for (;;) {
+                const parent = outer.getParent();
+                if (!parent)
+                    break;
+                if ((Node.isParenthesizedExpression(parent) ||
+                    Node.isAwaitExpression(parent) ||
+                    Node.isNonNullExpression(parent) ||
+                    Node.isSatisfiesExpression(parent)) &&
+                    parent.getExpression() === outer) {
+                    outer = parent;
+                    continue;
+                }
+                if ((Node.isAsExpression(parent) || Node.isTypeAssertion(parent)) &&
+                    parent.getExpression() === outer) {
+                    const typeNode = parent.getTypeNode();
+                    if (typeNode && !this.leavesAPositionOpen(typeNode)) {
+                        stateNode(3, typeNode, parent, 'a cast of the whole value');
+                        break;
+                    }
+                    outer = parent;
+                    continue;
+                }
+                if (Node.isBinaryExpression(parent) &&
+                    parent.getLeft() === outer &&
+                    [SyntaxKind.QuestionQuestionToken, SyntaxKind.BarBarToken].includes(parent.getOperatorToken().getKind()) &&
+                    this.isEmptyDefault(parent.getRight())) {
+                    outer = parent;
+                    continue;
+                }
+                break;
+            }
+            const parent = outer.getParent();
+            if (!parent)
+                continue;
+            if (Node.isVariableDeclaration(parent) && parent.getInitializer() === outer) {
+                stateNode(0, parent.getTypeNode(), parent, 'the annotation of the name that holds it');
+                hold(parent.getNameNode());
+                continue;
+            }
+            if (Node.isBinaryExpression(parent) &&
+                parent.getRight() === outer &&
+                parent.getOperatorToken().getKind() === SyntaxKind.EqualsToken &&
+                Node.isIdentifier(parent.getLeft())) {
+                const declaration = parent.getLeft().getSymbol()?.getValueDeclaration();
+                if (declaration && Node.isVariableDeclaration(declaration)) {
+                    stateNode(0, declaration.getTypeNode(), declaration, 'the annotation of the name it is assigned to');
+                }
+                hold(parent.getLeft());
+                continue;
+            }
+            if (reads.returned) {
+                const returnedHere = (Node.isReturnStatement(parent) &&
+                    parent.getExpression() === outer &&
+                    this.findContainingFunctionForNode(parent) === func) ||
+                    (Node.isArrowFunction(parent) && parent === func && parent.getBody() === outer);
+                if (returnedHere) {
+                    stateNode(0, func.getReturnTypeNode(), func, 'the declared return type of the function that returns it');
                     continue;
                 }
-                const contract = this.schemaContract(candidate, 'input');
-                if (contract)
-                    return contract;
             }
+            if (Node.isCallExpression(parent) && parent.getArguments().includes(outer)) {
+                this.stateAtReceivingCall(parent, parent.getArguments().indexOf(outer), reads, found, stateNode);
+            }
+        }
+        if (found.length === 0)
+            return null;
+        const rank = Math.min(...found.map((entry) => entry.rank));
+        const decided = found.filter((entry) => entry.rank === rank);
+        if (new Set(decided.map((entry) => entry.text)).size !== 1) {
+            this.log(`A value at ${this.getNodeLocation(value).file_path}:${this.getNodeLocation(value).start_line} ` +
+                `is stated as ${decided.length} different types in its function; stating none`);
+            return null;
+        }
+        const [first] = decided;
+        return { text: first.text, provenance: first.provenance, at: first.at, how: first.how };
+    }
+    /**
+     * What a call that takes the value at argument `index` states for it:
+     * a schema among its receiver and other arguments (rank 1), a callee of the
+     * project that returns that argument unchanged (rank 2), or, with
+     * `reads.parameters`, the parameter's own type (rank 4).
+     */
+    stateAtReceivingCall(call, index, reads, found, stateNode) {
+        const contract = this.schemaHandedArgument(call, index);
+        if (contract) {
+            found.push({ rank: 1, text: contract.text, provenance: contract.provenance, at: call, how: 'a schema it is handed to' });
+            return;
+        }
+        const passThrough = this.passThroughFunction(call, index);
+        if (passThrough) {
+            stateNode(2, passThrough.getReturnTypeNode(), call, 'a function that returns it unchanged');
+            return;
+        }
+        if (!reads.parameters)
+            return;
+        const signature = this.project.getTypeChecker().getResolvedSignature(call);
+        const parameter = signature?.getParameters()[index];
+        const declaration = parameter?.getValueDeclaration();
+        if (!parameter || (declaration && Node.isParameterDeclaration(declaration) && declaration.isRestParameter())) {
+            return;
+        }
+        let parameterType = parameter.getTypeAtLocation(call);
+        if (parameterType.isUnion()) {
+            const bodies = parameterType.getUnionTypes().filter((part) => !this.isCallableType(part));
+            if (bodies.length !== 1)
+                return;
+            parameterType = bodies[0];
+        }
+        if (!this.isObjectShape(parameterType))
+            return;
+        const text = this.structuralTextFromType(parameterType, call);
+        if (!text || /\b(any|unknown)\b/.test(text))
+            return;
+        found.push({ rank: 4, text, at: call, how: 'the parameter of a call it is handed to' });
+    }
+    /**
+     * The input contract of a schema `call` validates its argument at `index`
+     * with: its receiver (`Schema.safeParse(body)`) or one of its other
+     * arguments (`parse(Schema, body)`), or null. A candidate counts only when
+     * it declares schema types, so no method or library name is matched
+     * (carrick#1166).
+     */
+    schemaHandedArgument(call, index) {
+        const candidates = [];
+        const callee = call.getExpression();
+        if (Node.isPropertyAccessExpression(callee))
+            candidates.push(callee.getExpression());
+        call.getArguments().forEach((argument, at) => {
+            if (at !== index)
+                candidates.push(this.unwrapExpressionNode(argument));
+        });
+        for (const candidate of candidates) {
+            const candidateType = candidate.getType();
+            if (!this.schemaOutputType(candidateType, candidate) &&
+                !this.schemaInputType(candidateType, candidate)) {
+                continue;
+            }
+            const contract = this.schemaContract(candidate, 'input');
+            if (contract)
+                return contract;
         }
         return null;
     }
+    /**
+     * `call`'s result describes the value it takes at argument `index`: it
+     * validates it with a schema, or its callee returns it unchanged
+     * (`passThroughFunction`). Any other call builds something new from the
+     * value, and its result describes what it built, never the value it was
+     * handed (carrick#2595).
+     */
+    callStatesItsArgument(call, index) {
+        return index >= 0 && (!!this.schemaHandedArgument(call, index) || !!this.passThroughFunction(call, index));
+    }
+    /**
+     * The project function `call` invokes, when every value it returns is its
+     * argument at `index` as it was handed in (through parentheses, casts,
+     * `satisfies` and `!`) or an empty default (`{}`, `[]`, `null`,
+     * `undefined`), and at least one return is that argument. Such a function
+     * narrows its argument, so its declared return type describes the value it
+     * was handed. Any other function builds something new from it, and is not
+     * this.
+     */
+    passThroughFunction(call, index) {
+        let symbol = call.getExpression().getSymbol();
+        if (symbol?.isAlias())
+            symbol = symbol.getAliasedSymbol() ?? symbol;
+        for (const declaration of symbol?.getDeclarations() ?? []) {
+            const fn = Node.isFunctionDeclaration(declaration) || Node.isMethodDeclaration(declaration)
+                ? declaration
+                : Node.isVariableDeclaration(declaration)
+                    ? this.unwrapExpressionNode(declaration.getInitializer())
+                    : undefined;
+            if (!fn ||
+                !(Node.isFunctionDeclaration(fn) ||
+                    Node.isMethodDeclaration(fn) ||
+                    Node.isArrowFunction(fn) ||
+                    Node.isFunctionExpression(fn)) ||
+                !fn.getBody() ||
+                fn.getSourceFile().isDeclarationFile() ||
+                fn.getSourceFile().isInNodeModules()) {
+                continue;
+            }
+            const parameter = fn.getParameters()[index];
+            const parameterSymbol = parameter?.getNameNode().getSymbol()?.compilerSymbol;
+            if (!parameter || parameter.isRestParameter() || !parameterSymbol)
+                continue;
+            const returned = this.returnedExpressions(fn);
+            let returnsArgument = false;
+            const everyReturnPasses = returned.every((expression) => {
+                let node = expression;
+                while (Node.isParenthesizedExpression(node) ||
+                    Node.isAsExpression(node) ||
+                    Node.isTypeAssertion(node) ||
+                    Node.isSatisfiesExpression(node) ||
+                    Node.isNonNullExpression(node)) {
+                    node = node.getExpression();
+                }
+                if (Node.isIdentifier(node) && node.getSymbol()?.compilerSymbol === parameterSymbol) {
+                    returnsArgument = true;
+                    return true;
+                }
+                return this.isEmptyDefault(node);
+            });
+            if (everyReturnPasses && returnsArgument)
+                return fn;
+        }
+        return undefined;
+    }
+    /** `{}`, `[]`, `null` or `undefined`: a default that states no member. */
+    isEmptyDefault(node) {
+        const bare = this.unwrapExpressionNode(node);
+        return ((Node.isObjectLiteralExpression(bare) && bare.getProperties().length === 0) ||
+            (Node.isArrayLiteralExpression(bare) && bare.getElements().length === 0) ||
+            Node.isNullLiteral(bare) ||
+            (Node.isIdentifier(bare) && bare.getText() === 'undefined'));
+    }
     /**
      * The part a validated read names when that part is not a body, or
      * `undefined` (carrick#1166).