carrick 0.3.70 → 0.3.73

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

@@ -135,6 +135,57 @@ export declare class TypeInferrer {
      */
     private resolveParamTarget;
     private inferResponseBody;
+    /**
+     * The wire representation a request's printed type takes. A route response
+     * is serialised as JSON by every sender this layer reads a payload out of,
+     * so it prints `toJSON()` results rather than the objects that declare them
+     * (carrick#1163). Everything else prints the declared type.
+     */
+    private wireFormatFor;
+    /** An inferred type for a payload read out of response sends. */
+    private inferredFromRecoveredPayload;
+    /**
+     * carrick#1161: type a route response from every send in the handler the
+     * locator anchors, rather than from the one send it names.
+     *
+     * The analyzer reports one response expression per row, and on a handler
+     * that guards before it succeeds that is the guard's body. So the located
+     * expression selects the HANDLER: the function that contains it, on a row
+     * whose line is a route registration. Its returned sends are enumerated
+     * (conditional branches split), each is classified by the status it states
+     * (`responseSiteStatus`), the error and redirect branches are dropped, and
+     * the success bodies are joined exactly as the payload walk joins return
+     * statements.
+     *
+     * Returns `undefined` when this does not apply, which leaves the caller's
+     * own reading of the located expression untouched:
+     *  - the row's line is not a route registration;
+     *  - the located expression is neither a send nor the argument of one;
+     *  - that send is not one the handler returns;
+     *  - it is a success send and the only one that survives, so the join would
+     *    be the located body anyway;
+     *  - no joined body is the located one (a text body beside JSON ones).
+     *
+     * When the located send is an error or redirect branch and no success body
+     * survives, the route sends no body a contract can describe: an explicit
+     * `unknown` with its reason, so no later locator re-run reads the error body
+     * or the redirect location back in.
+     */
+    private inferFromResponseSites;
+    /**
+     * True when `candidate` is a response send: a call or `new` whose result is
+     * transport machinery (by the extraction config's verified rule or the
+     * structural check), or whose callee this handler's own returns prove is a
+     * serialiser (`calleesProvenSerialiser`, which holds on a bare checkout).
+     */
+    private isResponseSend;
+    /**
+     * The send `node` is an argument of, looking through the wrappers that do
+     * not change a payload (parentheses, `as`, `satisfies`, `!`, `await`) and a
+     * `JSON.stringify` around the body. `undefined` when the parent call is not
+     * a send or `node` is its callee.
+     */
+    private sendReceivingArgument;
     private inferCallResult;
     private inferVariable;
     private inferExpression;
@@ -524,24 +575,45 @@ export declare class TypeInferrer {
      */
     private statesResponseInit;
     /**
-     * True when an argument states a >= 400 status: an options object carrying
-     * `status`/`statusCode`, or a bare status code (`send(body, 404)`).
+     * What a response send states about its HTTP status (carrick#1161).
      *
-     * Read from the AST first: `{ status: 400 }` in an argument position widens
-     * to `{ status: number }`, so the literal only survives syntactically. The
-     * type check behind it catches `as const` and hoisted option objects.
+     * Read in order, and the first that states anything decides:
+     *
+     *  1. an argument past the body that carries a status: a numeric literal
+     *     (`send(body, 404)`), an options object (`{ status: 401 }`), or any
+     *     expression whose TYPE is a status literal or a union of them
+     *     (`let code: 400 | 500`). A numeric argument whose type is a plain
+     *     `number` states a status the source does not fix, which is
+     *     `variable`: the branch fails open into the union and is logged.
+     *  2. the send call's own RESULT type, when a member of it is typed as a
+     *     status literal. A framework that types its sends records the status
+     *     there, and a redirect helper's default `302` is only visible there.
+     *     A result whose status member spans success and error codes (the
+     *     default of a typed `json(body, status?)`) says nothing either way.
+     *
+     * A status in the FIRST argument is a field of the body and is never read.
+     * No method or framework name is consulted anywhere.
      */
-    private statesErrorStatus;
+    private responseSiteStatus;
     /**
-     * The HTTP status an argument states, or `undefined`.
+     * The HTTP status codes an argument states, `'variable'` when it is a
+     * status-shaped value the source does not fix, or `undefined` when it says
+     * nothing about a status.
      *
      * Read from the AST first: `{ status: 400 }` in an argument position widens
      * to `{ status: number }`, so the literal only survives syntactically. The
-     * type check behind it catches `as const` and hoisted option objects. Only
-     * values in the HTTP range count — an arbitrary number named `status` on a
-     * domain object (`{ status: 2 }`) states nothing about transport.
+     * type read behind it catches `as const`, hoisted option objects and
+     * literal-typed variables. Only values in the HTTP range count: an
+     * arbitrary number named `status` on a domain object (`{ status: 2 }`)
+     * states nothing about transport.
+     */
+    private statedStatusCodes;
+    /**
+     * Status codes a send call's result type records: the members (of the
+     * result, or of each part of an intersection result) typed as a status
+     * literal or a union of them. `undefined` when none is.
      */
-    private statedStatusCode;
+    private sendResultStatusCodes;
     /**
      * Peel the wrappers that do not change an expression's payload: parentheses
      * and `await`. Unlike `unwrapExpressionNode` this KEEPS `as`/`satisfies`,
@@ -877,6 +949,11 @@ export declare class TypeInferrer {
      * the route declares its request nowhere we can read.
      */
     private requestContractFromRegistration;
+    /**
+     * An explicit request `InferredType` for a contract the route declares,
+     * carrying the provenance the reading recorded.
+     */
+    private declaredRequestInferredType;
     /**
      * The request contract a route DECLARES, in anchor order: the handler's
      * parameter annotation (a), the registration's schema object (b), then a
@@ -914,8 +991,9 @@ export declare class TypeInferrer {
      * The shape is a CALL among the registration's arguments whose own arguments
      * are a request part and a schema value. Neither the middleware's name nor
      * the schema library is checked: the part is read off the string literal, and
-     * the schema is whatever exposes a parsed output (`schemaOutputTypeText`) —
-     * the same test anchor (b) already applies to a `schema: { body: … }` object.
+     * the schema is whatever declares its types (`schemaContract`) — the same
+     * test anchor (b) already applies to a `schema: { body: … }` object. The
+     * contract is the schema's INPUT, what a caller sends (carrick#1101).
      *
      * `REQUEST_BODY_PARTS` is HTTP vocabulary for how a body is carried, not a
      * framework list. A middleware bound to any other part (`query`, `param`,
@@ -923,19 +1001,73 @@ export declare class TypeInferrer {
      * at all is not read: publishing a query schema as the request contract would
      * be the same confident-and-wrong answer this anchor exists to remove.
      */
-    private validatedBodyContractText;
+    private validatedBodyContract;
+    /**
+     * The values a registration's validator middleware binds to a body part, in
+     * argument order: every non-literal argument of a middleware call that names
+     * a `REQUEST_BODY_PARTS` part. Whether each one IS a schema is the reader's
+     * question (`schemaContract`), not this walk's.
+     */
+    private middlewareBodySchemaValues;
+    /**
+     * 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.
+     */
+    private schemaConsumingRead;
+    /**
+     * The part a validated read names when that part is not a body, or
+     * `undefined` (carrick#1166).
+     *
+     * The read is a call whose only argument is a string literal, and the
+     * registration carries a validator middleware binding that same literal.
+     * The part names match through the source's own literal, so no framework
+     * vocabulary is assumed beyond `REQUEST_BODY_PARTS`, which already decides
+     * what a body is for the middleware anchor.
+     */
+    private nonBodyValidatedPart;
+    /**
+     * The request contract behind a VALIDATED READ: a call inside a registered
+     * handler whose type is exactly the parsed output of a body schema the
+     * enclosing registration declares (carrick#1101).
+     *
+     * The read's own type is what validation hands the handler, the schema's
+     * output, so a locator that lands on it would publish the output as the
+     * request. The registration is found by walking the read's ancestors to each
+     * call or registry object whose handler contains the read and which declares
+     * a body schema (anchor (b) or (b2)). The match is on the printed type: only
+     * a read whose structural text equals that schema's output is substituted, so
+     * any other expression in the handler (a query read, a payload of a different
+     * shape) keeps its own type.
+     */
+    private validatedReadRequestContract;
     /**
      * Anchor (b): the contract declared in the route's validation schema.
      *
      * `part` is `'body'` for the request contract and `'response'` for the
      * response contract; a `response` entry keyed by status code resolves to its
-     * success entry. Returns null when the registration carries no schema, when
-     * the entry references something whose parsed output cannot be resolved, or
-     * when the schema is a plain JSON-schema literal (whose own object type is
-     * the JSON-Schema document, not the payload — emitting that would be worse
-     * than abstaining).
+     * success entry. The body reads the schema's input and the response its
+     * output (carrick#1101). Returns null when the registration carries no
+     * schema, when the entry references something whose declared types cannot be
+     * resolved, or when the schema is a plain JSON-schema literal (whose own
+     * object type is the JSON-Schema document, not the payload — emitting that
+     * would be worse than abstaining).
+     */
+    private routeSchemaContract;
+    /**
+     * The value a route `schema` object declares for `part`, as a zero- or
+     * one-element list: the `body` entry itself, or the success entry of a
+     * status-keyed `response` map.
      */
-    private routeSchemaContractText;
+    private routeSchemaEntryValues;
     /**
      * The `schema` object literal carried by a route registration: scan the
      * registration call's arguments (or the registry object literal itself) for a
@@ -950,17 +1082,63 @@ export declare class TypeInferrer {
      */
     private successStatusEntry;
     /**
-     * The payload type a schema entry declares.
+     * The payload type a schema entry declares, read in `direction`.
      *
      * The entry is either a REFERENCE call — `ref('CreateWidget')`, a
      * name-to-schema indirection whose registry is the argument the ref function
-     * was built from — or the schema value itself. Either way the payload is the
-     * schema's parsed output: the return type of its `parse` method (the shape
-     * every schema value exposes as its public validate-and-return API), falling
-     * back to a declared `_output` member. A value with neither is not a schema
-     * and yields null.
-     */
-    private schemaOutputTypeText;
+     * was built from — or the schema value itself. A value that declares no type
+     * in either direction is not a schema and yields null.
+     *
+     * `output` is the parsed value (`schemaOutputType`). `input` is what a caller
+     * sends (`schemaInputType`), and a schema that declares no input member reads
+     * its output instead, which is the whole of what is knowable about it.
+     *
+     * The input is decided member by member (carrick#1105). A member whose input
+     * is `any`/`unknown` where the output is concrete is what a coercion declares
+     * (it accepts any value and parses it into, say, a number). A top type in a
+     * published contract disqualifies the whole row downstream, so THAT member
+     * prints its output type, keeps the input key's optionality, and is recorded
+     * as `coerced_input` provenance. Every other member keeps its input, so a
+     * defaulted key beside a coerced one stays optional to send.
+     *
+     * Limits, each logged where it bites:
+     *  - the position walk is bounded (`walkTypePositions`), so a top type below
+     *    the bound is not compared and prints as the input declares it;
+     *  - a coerced position that cannot be substituted (its output is absent or
+     *    differs across union branches, or the printer cannot reach it inside a
+     *    tuple, behind a cycle or past the expansion depth) makes the row fall
+     *    back to the whole parsed output with every coerced member labelled. That
+     *    was the answer before the per-member reading, and it never publishes an
+     *    `unknown`.
+     */
+    private schemaContract;
+    /**
+     * Print a schema's input with each coerced position replaced by the output's
+     * type at that position (carrick#1105). Null when any position cannot be
+     * substituted: its output is missing or differs across union branches, or
+     * the printer never reached it. A partial substitution would publish an
+     * `unknown`, so it is not an answer.
+     */
+    private inputWithCoercedMembers;
+    /**
+     * Member positions inside `root` that are `any` or `unknown`, keyed by the
+     * member-path notation the provenance entries use (`''` for the root,
+     * `sub.field`, `items<0>` for an array element). Union and intersection
+     * members share their parent's position, so `unknown | undefined` on an
+     * optional key reads as `unknown` there.
+     */
+    private topTypePositions;
+    /**
+     * Visit every member position of `root`, in the notation `topTypePositions`
+     * documents. `visit` returns false to stop descending below a position;
+     * `unionPart` is true when the type is a union or intersection part visited
+     * at its parent's position. Callables are not descended into.
+     *
+     * Bounded and cycle-safe. It only has to tell a schema's input apart from its
+     * output, so a subtree past the bound is not compared, and that is logged:
+     * a coercion below the bound prints as its input declares it.
+     */
+    private walkTypePositions;
     /**
      * Follow a schema REFERENCE call (`ref('CreateWidget')`) to the schema value
      * it names.
@@ -975,12 +1153,31 @@ export declare class TypeInferrer {
     private registrySchemaType;
     /**
      * The parsed output type of a schema value: the return type of its `parse`
-     * method, else a declared `_output` member. Returns undefined when neither
-     * carries a usable type — including when the schema library's own types are
+     * method, else a declared `_output` member, else the Standard Schema member
+     * `~standard.types.output` (a library that exposes nothing else). Returns
+     * undefined when none carries a usable type — including when the schema library's own types are
      * unavailable (an uninstalled dependency resolves the schema to `any`), which
      * must abstain rather than publish `any` as a contract.
      */
     private schemaOutputType;
+    /**
+     * The input type of a schema value, what a caller may send (carrick#1101):
+     * the Standard Schema member `~standard.types.input`, else a declared
+     * `_input` member. Undefined when the schema declares neither.
+     *
+     * Unlike the output, an input of `unknown` is kept: it is a declared fact
+     * (a coercion accepts any value), and `schemaContract` decides what to
+     * publish for it. An `any` that is really an unresolved library still reads
+     * as no input, because an unresolved schema type has no members to read.
+     */
+    private schemaInputType;
+    /**
+     * `~standard.types.<side>` on a schema value: the Standard Schema
+     * specification's library-neutral statement of a schema's input and output
+     * types. `types` is declared optional, so its `undefined` is stripped before
+     * the side is read.
+     */
+    private standardSchemaType;
     /**
      * Find a node by matching expression text near a target line.
      *