carrick 0.3.125 → 0.3.127

package/sidecar/dist/src/type-inferrer.d.ts

@@ -167,7 +167,10 @@ export declare class TypeInferrer {
      * read is the project the scan loaded.
      *
      * Nothing is read past `deadline`: a batch that runs out keeps the readings
-     * it made and publishes none for the rest.
+     * it made and publishes none for the rest, and marks each of the rest
+     * `unwidened_out_of_budget` (carrick#2100). A request that never needed a
+     * reading (a declared return, nothing to mark) or lost it for a reason of
+     * its own (a marking that added a diagnostic) is never marked.
      */
     private addUnwidenedReadings;
     /**
@@ -295,6 +298,17 @@ export declare class TypeInferrer {
      * when the located expression is not part of what the handler returns.
      */
     private returnedSendHolding;
+    /**
+     * True when `node` is a bare reference to a parameter of the handler the
+     * route registration on the request's line hands in (found as
+     * `registrationAtLine` finds it, wrappers included): the request, the reply
+     * or the context the framework passes, never a body the route sends
+     * (carrick-cloud#2576). Where the parameter's type is declared is not read:
+     * a parameter of any other function is data, whether the repo or an
+     * installed package types it (`.then((account) => reply.send(account))`, a
+     * helper's `account: Account`).
+     */
+    private isRouteHandlerParameter;
     /**
      * True when a located call's own result is the route's payload, so the
      * transitional drill into its first argument must not run (carrick#1732).
@@ -479,11 +493,29 @@ export declare class TypeInferrer {
      * guard, so that binding stays unread and the capture answers the row.
      */
     private destructuredValueTerminal;
+    /**
+     * 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.
+     */
+    private callIsPartOfReturnedLiteral;
     /**
      * `expr` declares a name for what a call returns when it is handed a
      * tracked name whole (`const data: T = await parseJson(response, 'op')`).
      */
     private handsTrackedValueToACall;
+    /**
+     * 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.
+     */
+    private callTakingTrackedValue;
+    /**
+     * `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).
+     */
+    private statesTrackedValue;
     /** `expr` holds a binary whole-body read taken on a tracked name. */
     private holdsBinaryBodyRead;
     /**
@@ -696,7 +728,10 @@ export declare 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).
      */
     private statedPayloadAroundBodyRead;
     /**
@@ -1682,11 +1717,14 @@ export declare class TypeInferrer {
      */
     private registrationHandlerAt;
     /**
-     * The handler function referenced by a route-registration call: the first
+     * The handler function referenced by a route-registration call: the LAST
      * argument that is an inline function, or an identifier bound to a function
-     * (typically the 2nd+ arg — the path literal is not function-valued, so it is
-     * skipped naturally). No callee-name check: a call whose argument resolves to
-     * a function is structurally a registration regardless of the framework.
+     * (carrick#2472 P3-2b). The functions before it are middleware
+     * (`route(path).post(auth, audit, handler)`), which runs first and hands on;
+     * reading the first function read a middleware as the route. The path
+     * literal is not function-valued, so it is skipped naturally. No callee-name
+     * check: a call whose argument resolves to a function is structurally a
+     * registration regardless of the framework.
      */
     private handlerFromRegistrationCall;
     /**
@@ -1701,16 +1739,32 @@ export declare class TypeInferrer {
      * declaration (via the compiler's definition nodes) and returned when that
      * declaration is — or initializes to — a function. Anything else (a path
      * literal, an object, a non-function binding) yields undefined.
+     * `followWrapperCalls` false reads a binding to a wrapper call as no
+     * function, so a name the wrapper walk meets is never walked again.
      */
     private asHandlerFunction;
     /**
      * Extract a `FunctionLike` from a declaration node the compiler resolved an
      * identifier to: a function declaration is itself the function; a variable
      * declaration / binding whose initializer is an inline function yields that
-     * function (`const h = async () => { … }`). Import/re-export shims are walked
-     * by ts-morph's `getDefinitionNodes`, so no manual import chasing is needed.
+     * function (`const h = async () => { … }`), and one whose initializer is a
+     * wrapper call yields the function the call wraps
+     * (`const h = wrap<Contract>(async (req, res) => { … })`, carrick#2472
+     * P3-2b; `functionWrappedBy`). Import/re-export shims are walked by
+     * ts-morph's `getDefinitionNodes`, so no manual import chasing is needed.
      */
     private functionFromDeclaration;
+    /**
+     * The function a call wraps, for a name bound to that call and used as a
+     * handler (carrick#2472 P3-2b): the call's one argument that is a function
+     * literal, a name bound to one, or another such call, a few calls deep.
+     *
+     * Two conditions keep this to wrappers. The call's own value has to be
+     * callable, because the name is used as a function: `rows.map((row) => …)`
+     * is handed a function and yields a list. And exactly one argument may be a
+     * function: with two there is no saying which of them is wrapped.
+     */
+    private functionWrappedBy;
     /**
      * True when `handler` reads nothing from the incoming message (carrick#827):
      * every use of one of its parameters, named or destructured, is the receiver
@@ -1906,6 +1960,77 @@ export declare class TypeInferrer {
      * whose type does not resolve the member, or an opaque config, abstains.
      */
     private requestBodyInCall;
+    /**
+     * 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.
+     */
+    private bodyBuiltByCallee;
+    /**
+     * `bodyBuiltByCallee`, telling apart a callee that sends the argument
+     * unchanged (`passes`) from one that states nothing about it (`none`).
+     * `depth` counts the forwarded locals followed (carrick#2671).
+     */
+    private calleeBodyRead;
+    /**
+     * 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.
+     */
+    private bodyValueAround;
+    /**
+     * carrick#2671: the `const` local whose initializer holds `use`, inside
+     * `scope`, when `scope` sends that local unchanged as the body: whole in a
+     * body slot, or as an argument into a function that passes it on as its
+     * body. The local's name, so its declared type is read. Undefined when the
+     * local is never sent, when a further body is built from it, or when a
+     * function lies between `use` and the declaration.
+     */
+    private forwardedLocalHolding;
+    /** `value` is `use` behind what `sentValue` sees through. */
+    private isSameValue;
+    /**
+     * 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.
+     */
+    private sentValue;
+    /**
+     * The branch of `choice` that sends something, when its other branch sends
+     * nothing (`undefined`, `null`, `void 0`, or `{}` spread into a request).
+     */
+    private sendingBranch;
+    /** `undefined`, `null`, `void 0`, or (where `emptyObject`) `{}`. */
+    private sendsNothing;
+    /**
+     * 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.
+     */
+    private inSendNothingTest;
     /** A string, a string literal, a template literal, or a union of strings. */
     private isStringLikeType;
     /**
@@ -2072,6 +2197,22 @@ export declare class TypeInferrer {
      * `reads.parameters`, the parameter's own type (rank 4).
      */
     private stateAtReceivingCall;
+    /**
+     * 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).
+     */
+    private schemaHandedArgument;
+    /**
+     * `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).
+     */
+    private callStatesItsArgument;
     /**
      * The project function `call` invokes, when every value it returns is its
      * argument at `index` as it was handed in (through parentheses, casts,