carrick 0.3.126 → 0.3.128

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

@@ -19,6 +19,7 @@
  */
 import { Project, SourceFile, type CallExpression } from 'ts-morph';
 import type { InferRequestItem, InferResult, ModelSymbol, ExtractionConfig } from './types.js';
+import type { LabelledMembers } from './library-claims.js';
 /**
  * Strongly-discriminating member names of HTTP transport machinery — the
  * fetch/DOM `Response` & `Request`, a Node `http.ServerResponse`, a framework
@@ -123,9 +124,15 @@ export declare class TypeInferrer {
      * @param onRequestDone - Called once per request, as the batch is done with it
      * @returns InferResult with inferred types or errors
      */
-    infer(requests: InferRequestItem[], extractionConfig?: ExtractionConfig, onRequestDone?: InferRequestDone, modelSymbols?: ModelSymbol[]): InferResult;
+    infer(requests: InferRequestItem[], extractionConfig?: ExtractionConfig, onRequestDone?: InferRequestDone, modelSymbols?: ModelSymbol[], labels?: LabelledMembers): InferResult;
     /** The types the model named, by the alias of the row each is for (carrick#2111). */
     private modelSymbols;
+    /**
+     * carrick#2674: what route handlers' parameters state, through the
+     * members the batch's verified server-framework labels name. Empty when
+     * the batch carries no labels, and then it reads nothing.
+     */
+    private statedParams;
     /**
      * 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
@@ -161,13 +168,20 @@ export declare class TypeInferrer {
      * really returns beside the published one (`unwidened_type_string`). See
      * `unwidened.ts` for what is marked and why the reading is sound.
      *
+     * carrick#2011: a request body (`read` is `'request_body'`) is read the same
+     * way, the call that sends it in place of the handler, except that a literal
+     * handed to any call other than the send is never marked.
+     *
      * One rewrite for the whole batch: every file on any request's path is
      * rewritten once, type-checked before and after, the requests re-inferred,
      * and every file restored before returning, so the project other requests
      * 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 +309,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).
@@ -629,6 +654,72 @@ export declare class TypeInferrer {
     private resultCarrierArguments;
     /** The member names every branch holds, each with one and the same type. */
     private membersCommonToEveryBranch;
+    /**
+     * What the source narrows a call's value to, where the type stated at the
+     * walk's terminal is a placeholder that leaves a position open
+     * (carrick#2714, `as { data: Item[] } | { error: unknown }`): the one type
+     * stated for the value later in the function, on its success path
+     * (`return json as { data: Item[] }`). A closed statement at the terminal
+     * keeps the answer it had.
+     */
+    private narrowedBodyStatement;
+    /**
+     * The rule that verifies a call's result as a request library's response
+     * object, or undefined (carrick#2714). The result is that object when its
+     * awaited type is one a rule recognises. It is that object too when the
+     * call states no type arguments and its declared result, with its free
+     * type parameters at their defaults (`freeResultAtDefaults`), is a type a
+     * rule recognises (`get<T, R = Response<T>>(): Promise<R>`).
+     * The compiler then takes the parameter from where the value goes
+     * (`return client.post(…)` in a function declared `Promise<void>` types the
+     * call `Promise<void>`), and that is the caller's claim about the object,
+     * not what the call returns.
+     */
+    private transportRuleOfCall;
+    /**
+     * The first rule that matches `type` as a wrapper whose body is a member
+     * (`payloadPropertyPath`) the type has, whether or not it reads a payload
+     * out of it. A
+     * wrapper with no such member (the platform's `Response`) is read by its
+     * body reads (`res.json()`), which the def-use walk follows.
+     */
+    private ruleRecognising;
+    /**
+     * What a call's declared result is when its free type parameters take
+     * their defaults, or undefined. A parameter is free when the declaration's
+     * result mentions it and none of its parameters do, so only a type
+     * argument, the default or the call's return position can fix it. The
+     * result is read through `Promise`, a free parameter (its default), and a
+     * conditional alias whose check type is a free parameter tested against
+     * exactly that parameter's default (`R extends Default ? Response<T> : R`:
+     * the true branch). Anything else is the type as written.
+     */
+    private freeResultAtDefaults;
+    /**
+     * The call states the body itself: the rules read a payload out of its
+     * result (`client.get<Widget>(url)`). An untyped payload is no payload to
+     * the rules (they verify the object and read nothing), and a result its
+     * return position chose is no response object to them.
+     */
+    private callStatesTypedPayload;
+    /**
+     * The body of a call that returns a response object (carrick#2714): the
+     * one type the source states, in the function the call is made in, for the
+     * reads of the object's payload member (`res.data as Widget`, `const w:
+     * Widget = res.data`, `return res.data` from a function that declares its
+     * return type), through a binding or in place. Where no read states one,
+     * or two state different types, or the object is handed on whole, the
+     * site states no response contract, and the abstain is decided so the
+     * capture does not re-read the call and publish the object.
+     */
+    private transportCallBody;
+    /**
+     * The reads of a response object's payload member (`path`, e.g. `data`)
+     * that take it off the call's value: in place (`(await call).data`),
+     * through the name the value is bound to (`res.data`), or as a name
+     * destructured out of it (`const { data } = await call`).
+     */
+    private payloadMemberReads;
     /**
      * The decided abstain of a call whose result carries transport the
      * service's wrapper rules verify and read no payload out of (carrick#1841,
@@ -1703,11 +1794,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;
     /**
@@ -1722,16 +1816,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
@@ -1952,6 +2062,12 @@ export declare class TypeInferrer {
      * 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,
@@ -1959,6 +2075,15 @@ export declare class TypeInferrer {
      * 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;
     /**
@@ -2042,6 +2167,17 @@ export declare class TypeInferrer {
      * own locator authoritative when a route declares nothing.
      */
     private declaredRequestContract;
+    /** The stated-parameter reader over `labels`, judging files and statuses as this inferrer does. */
+    private statedParamsFor;
+    /**
+     * carrick#2674: where today's reading of a route's response is empty
+     * (nothing, `void`, or an `unknown` the inferrer did not decide), the reply
+     * its handler's parameter states, cut to its success variants. A typed
+     * reading, or a decided abstain, stands as it is.
+     */
+    private withStatedReply;
+    /** Nothing read: `void`, or an `unknown` with no decided reason at its root. */
+    private isEmptyResponseReading;
     /**
      * Anchor (a): the request contract declared on the handler's own signature.
      *