carrick 0.3.130 → 0.3.132

package/sidecar/dist/src/retype.js

@@ -195,6 +195,12 @@ export class Retyper {
             };
         }
         if (declaresTypeParameters(call)) {
+            const inferred = inferredTypeParameterOf(call);
+            if (inferred) {
+                return (`the callee declares several type parameters and '${inferred}' is ` +
+                    `inferred from the arguments, so writing one type argument would turn ` +
+                    `its inference off`);
+            }
             const open = call.getFirstChildByKind(SyntaxKind.OpenParenToken);
             if (!open)
                 return 'the consumer call has no argument list to retype';
@@ -948,6 +954,42 @@ function bodyReadEdit(read) {
         { start: end, end, text: ` as Promise<${stated}>)`, statedAt: ' as Promise<'.length },
     ];
 }
+/**
+ * The name of a type parameter after the first that the call's arguments
+ * infer and whose default would change the call if inference were off, or
+ * `undefined`.
+ *
+ * Writing one type argument makes every other parameter take its default
+ * instead of its inferred type. A parameter the argument list mentions
+ * (`TVariables` in `options: Options<TData, TError, TVariables>`) and whose
+ * default is not `any` or `unknown` then types the argument against the
+ * default (`void`), and the call reports a diagnostic about the written
+ * argument, not about anything the consumer reads. A parameter nothing in the
+ * argument list mentions, or one defaulting to `any`, is unaffected.
+ */
+function inferredTypeParameterOf(call) {
+    const declaration = resolvedDeclaration(call);
+    const typeParameters = declaration?.typeParameters;
+    if (!declaration || !typeParameters || typeParameters.length < 2)
+        return undefined;
+    for (const parameter of typeParameters.slice(1)) {
+        const fallback = parameter.default;
+        if (fallback &&
+            (fallback.kind === ts.SyntaxKind.AnyKeyword || fallback.kind === ts.SyntaxKind.UnknownKeyword)) {
+            continue;
+        }
+        const name = parameter.name.text;
+        if (declaration.parameters.some((p) => p.type && mentionsTypeName(p.type, name)))
+            return name;
+    }
+    return undefined;
+}
+function mentionsTypeName(node, name) {
+    if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName) && node.typeName.text === name) {
+        return true;
+    }
+    return ts.forEachChild(node, (child) => (mentionsTypeName(child, name) ? true : undefined)) ?? false;
+}
 function declaresTypeParameters(call) {
     return (resolvedDeclaration(call)?.typeParameters?.length ?? 0) > 0;
 }

package/sidecar/dist/src/stated-params.d.ts

@@ -63,7 +63,7 @@ export declare class StatedParams {
      * reference, a second callable argument or property there. What such a
      * function (a middleware) does with the request is not read here.
      */
-    private handsInAnotherFunction;
+    handsInAnotherFunction(registration: Node, handler: HandlerFunction): boolean;
     /**
      * A type argument the source writes for this route: on a call the handler
      * is passed to (the registration, or a wrapper that makes the handler),

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

@@ -234,6 +234,18 @@ export declare class TypeInferrer {
      * truncation.
      */
     private inferFunctionParam;
+    /**
+     * carrick#2814: mark a route's request body as one its handler tolerates
+     * going unsent, when the handler is in reach and every read of the body
+     * survives `undefined` (`absent-body.ts`). The check then lets a caller that
+     * may send nothing call a route whose body type has no required member.
+     *
+     * No mark where the handler cannot be found, where a validator the
+     * registration declares reads the body first (a schema, or another function
+     * handed in beside the handler), or where the handler reads no body it can
+     * see: the check keeps the reading it had.
+     */
+    private withAbsentBodyMark;
     /**
      * Resolve a `function_param` locator against a function's parameter list.
      * Three shapes, tried in order:
@@ -2530,6 +2542,13 @@ export declare class TypeInferrer {
      * then substring match (preferring containing matches).
      */
     private matchByText;
+    /**
+     * The text a locator opens with before an elision, or `undefined` when the
+     * locator has none. An elision is `...` followed only by closing brackets
+     * (`{ a: x, ... }`); `...rest` is a spread and source text. An opening too
+     * short to tell nodes apart is judged by the caller.
+     */
+    private elidedLocatorOpening;
     /**
      * What a locator's text names, read off its own parse (carrick#2056):
      *

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

@@ -32,6 +32,7 @@ import { attributedDeclaration, installedPackageOf } from './declaration-attribu
 import { endLineOf, startLineOf } from './line-index.js';
 import { elapsedMs, inferTiming, phaseClock, timedPhase } from './infer-timing.js';
 import { StatedParams } from './stated-params.js';
+import { bindingToleratesAbsence, handlerToleratesAbsentBody } from './absent-body.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';
@@ -883,7 +884,7 @@ export class TypeInferrer {
             case 'expression':
                 return this.inferExpression(sourceFile, request, extractionConfig);
             case 'request_body':
-                return this.inferRequestBody(sourceFile, request, extractionConfig);
+                return this.withAbsentBodyMark(sourceFile, request, this.inferRequestBody(sourceFile, request, extractionConfig));
             case 'signature_return':
                 return this.inferSignatureReturn(sourceFile, request);
             case 'function_param':
@@ -1168,7 +1169,51 @@ export class TypeInferrer {
         // scanner re-aims the explicit bundle at the root symbol instead of
         // pasting this string, so the alias's definition stays self-contained.
         const anchor = this.unwrapArrayLevels(this.unwrapPromiseType(paramType));
-        return this.createInferredType(request, typeString, isExplicit, this.getNodeLocation(target.node), undefined, this.primaryTypeSymbol(anchor.element), anchor.depth, this.primaryTypeSymbolSource(anchor.element));
+        const inferred = this.createInferredType(request, typeString, isExplicit, this.getNodeLocation(target.node), undefined, this.primaryTypeSymbol(anchor.element), anchor.depth, this.primaryTypeSymbolSource(anchor.element));
+        // carrick#2814: a subscriber that defaults its payload, or reads it only
+        // in ways `undefined` survives, still works when none is sent.
+        const binding = Node.isBindingElement(target.node) ? target.node : target.param;
+        if (bindingToleratesAbsence(binding)) {
+            inferred.absent_body_tolerated = true;
+        }
+        return inferred;
+    }
+    /**
+     * carrick#2814: mark a route's request body as one its handler tolerates
+     * going unsent, when the handler is in reach and every read of the body
+     * survives `undefined` (`absent-body.ts`). The check then lets a caller that
+     * may send nothing call a route whose body type has no required member.
+     *
+     * No mark where the handler cannot be found, where a validator the
+     * registration declares reads the body first (a schema, or another function
+     * handed in beside the handler), or where the handler reads no body it can
+     * see: the check keeps the reading it had.
+     */
+    withAbsentBodyMark(sourceFile, request, inferred) {
+        if (!inferred)
+            return inferred;
+        const atLine = this.registrationAtLine(sourceFile, request.line_number);
+        let registration = atLine?.registration;
+        let handler = atLine?.handler;
+        if (!handler) {
+            const located = this.resolveTargetNode(sourceFile, request);
+            handler = located ? this.registrationHandlerAt(located) : undefined;
+            registration = handler && located ? this.unwrapExpressionNode(located) : undefined;
+        }
+        handler ??= this.exportedFunctionOpeningOn(sourceFile, request.line_number);
+        if (!handler)
+            return inferred;
+        if (registration) {
+            if (this.routeSchemaContract(registration, 'body') ?? this.validatedBodyContract(registration)) {
+                return inferred;
+            }
+            if (this.statedParams.handsInAnotherFunction(registration, handler))
+                return inferred;
+        }
+        if (handlerToleratesAbsentBody(handler)) {
+            inferred.absent_body_tolerated = true;
+        }
+        return inferred;
     }
     /**
      * Resolve a `function_param` locator against a function's parameter list.
@@ -9309,6 +9354,26 @@ export class TypeInferrer {
         if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(normalizedTarget)) {
             return undefined;
         }
+        // A locator that elides members (`body: { a: x, ... }`) stands for the
+        // whole node it opens: the text before the elision is where the source
+        // opens. Never a node the text merely contains, which is one member of the
+        // payload it names.
+        // An opening shorter than this (`{`) names no node in particular.
+        const MIN_ELIDED_OPENING_LEN = 8;
+        const elidedOpening = this.elidedLocatorOpening(normalizedTarget);
+        if (elidedOpening !== undefined) {
+            if (elidedOpening.length < MIN_ELIDED_OPENING_LEN)
+                return undefined;
+            const opened = candidates.filter((c) => c.text.startsWith(elidedOpening));
+            if (opened.length === 0)
+                return undefined;
+            if (lineNumber !== undefined) {
+                const distance = (c) => Math.abs(startLineOf(c.node) - lineNumber);
+                const nearest = Math.min(...opened.map(distance));
+                return this.pickBestMatch(opened.filter((c) => distance(c) === nearest).map((c) => c.node), lineNumber);
+            }
+            return this.pickBestMatch(opened.map((c) => c.node), lineNumber);
+        }
         // Fall back to substring match
         // For the reverse direction (target contains node text), require a minimum node text
         // length to avoid matching tiny identifiers like "res" or "body" too broadly.
@@ -9375,6 +9440,18 @@ export class TypeInferrer {
         }
         return bound.size > 0 ? this.pickBestMatch([...bound], lineNumber) : undefined;
     }
+    /**
+     * The text a locator opens with before an elision, or `undefined` when the
+     * locator has none. An elision is `...` followed only by closing brackets
+     * (`{ a: x, ... }`); `...rest` is a spread and source text. An opening too
+     * short to tell nodes apart is judged by the caller.
+     */
+    elidedLocatorOpening(normalizedTarget) {
+        const match = /^(.*?)[\s,]*\.\.\.[\s,)}\]]*$/s.exec(normalizedTarget);
+        if (!match)
+            return undefined;
+        return match[1];
+    }
     /**
      * What a locator's text names, read off its own parse (carrick#2056):
      *

package/sidecar/dist/src/types.d.ts

@@ -1228,6 +1228,14 @@ export interface InferredType {
      * Absent when the body is not a raw-text read.
      */
     raw_text_read?: true;
+    /**
+     * carrick#2814, a route's request body or a subscriber's payload: the
+     * handler is in reach and works when nothing is sent, because it defaults
+     * the body or reads it only in ways `undefined` survives (`?.`, `?? {}`).
+     * Absent when the handler dereferences it, reads it through something not
+     * seen, or was not found.
+     */
+    absent_body_tolerated?: true;
     /**
      * carrick#2054, a response joined from two or more success bodies: the
      * request fields whose values pick among them (`reads`), and, for one