carrick 0.3.126 → 0.3.128

package/sidecar/dist/src/retype.js

@@ -26,6 +26,7 @@
  */
 import { Node, SyntaxKind, ts } from 'ts-morph';
 import { readsResponseStatus, statusesIn, SUCCEEDED, testsOnPath, } from './failure-path.js';
+import { statesNoBody } from './capture/index.js';
 import { lineIndex } from './line-index.js';
 import { typeToStringAsDeclared } from './print-type.js';
 import { fileDiagnostics } from './unwidened.js';
@@ -469,6 +470,9 @@ function resultEscapes(call, throughCasts = false) {
         (throughCasts && Node.isAsExpression(top.getParentOrThrow()))) {
         top = top.getParentOrThrow();
     }
+    if (returnedFromNoBodyFunction(top)) {
+        return 'the response is returned from a function that declares it returns no body, so there is no body to judge';
+    }
     if (returnsUndeclared(top)) {
         return 'the response is returned from a function with no declared return type, so its readers are elsewhere';
     }
@@ -493,6 +497,38 @@ function resultEscapes(call, throughCasts = false) {
     }
     return undefined;
 }
+/**
+ * `top` is returned whole from a function whose declared return states no
+ * body (carrick#2743): `Promise<void>`, `Promise<undefined>`, or a reference
+ * every written type argument of which is one of those
+ * (`Promise<ClientResponse<void>>`). In source the compiler takes a client's
+ * free result parameter from that return position, so the file compiles;
+ * the retype's written type argument turns that inference off and the
+ * declared return then reports the default response object. That is a
+ * diagnostic about the written argument, not a body anyone reads.
+ */
+function returnedFromNoBodyFunction(top) {
+    const parent = top.getParent();
+    const fn = Node.isReturnStatement(parent)
+        ? parent.getFirstAncestor((n) => Node.isFunctionDeclaration(n) ||
+            Node.isFunctionExpression(n) ||
+            Node.isArrowFunction(n) ||
+            Node.isMethodDeclaration(n))
+        : Node.isArrowFunction(parent)
+            ? parent
+            : undefined;
+    let declared = Node.isReturnTyped(fn) ? fn.getReturnTypeNode() : undefined;
+    while (Node.isTypeReference(declared) &&
+        ['Promise', 'PromiseLike'].includes(declared.getTypeName().getText())) {
+        declared = declared.getTypeArguments()[0];
+    }
+    if (!declared)
+        return false;
+    if (statesNoBody(declared.getType().compilerType))
+        return true;
+    const args = Node.isTypeReference(declared) ? declared.getTypeArguments() : [];
+    return args.length > 0 && args.every((arg) => statesNoBody(arg.getType().compilerType));
+}
 /** `node` is (part of) what a function with an inferred return type returns. */
 function returnsUndeclared(node) {
     for (let at = node; at; at = at.getParent()) {
@@ -548,14 +584,8 @@ function bodyReadsOf(call) {
     const chained = bodyReadOn(top);
     if (chained)
         return checkedBodyReads([chained]);
-    const declaration = top.getParent();
-    if (!declaration ||
-        !Node.isVariableDeclaration(declaration) ||
-        declaration.getInitializer() !== top) {
-        return [];
-    }
-    const name = declaration.getNameNode();
-    if (!Node.isIdentifier(name))
+    const name = responseBinding(top);
+    if (!name)
         return [];
     const reads = [];
     let handedOn = false;
@@ -583,6 +613,92 @@ function bodyReadsOf(call) {
     }
     return checkedBodyReads(reads);
 }
+/**
+ * The name the located call's response is bound to, when the source binds it
+ * in one of three ways: `const res = await call`, the first parameter of a
+ * `.then` callback (`call.then((res) => res.json())`), or an element of an
+ * array destructured off `Promise.all` (`const [a, b] = await Promise.all([call, ...])`).
+ */
+function responseBinding(top) {
+    const declaration = top.getParent();
+    if (declaration && Node.isVariableDeclaration(declaration) && declaration.getInitializer() === top) {
+        const name = declaration.getNameNode();
+        return Node.isIdentifier(name) ? name : undefined;
+    }
+    return thenParameter(top) ?? promiseAllElement(top);
+}
+/** `top.then((res) => ...)`: the callback's first parameter. */
+function thenParameter(top) {
+    const access = top.getParent();
+    if (!access || !Node.isPropertyAccessExpression(access) || access.getExpression() !== top) {
+        return undefined;
+    }
+    if (access.getName() !== 'then')
+        return undefined;
+    const then = access.getParent();
+    if (!then || !Node.isCallExpression(then) || then.getExpression() !== access)
+        return undefined;
+    const callback = then.getArguments()[0];
+    if (!callback || !(Node.isArrowFunction(callback) || Node.isFunctionExpression(callback))) {
+        return undefined;
+    }
+    const name = callback.getParameters()[0]?.getNameNode();
+    return name && Node.isIdentifier(name) ? name : undefined;
+}
+/**
+ * The name `top` is destructured to, when `top` is one element of the array
+ * literal handed to the language library's `Promise.all` and the call's
+ * awaited result is destructured to names:
+ * `const [a, b] = await Promise.all([call, other])`. An element after a
+ * spread has no position the destructuring can be read against.
+ */
+function promiseAllElement(top) {
+    const array = top.getParent();
+    if (!array || !Node.isArrayLiteralExpression(array))
+        return undefined;
+    const elements = array.getElements();
+    const index = elements.indexOf(top);
+    if (index < 0 || elements.slice(0, index + 1).some((e) => Node.isSpreadElement(e))) {
+        return undefined;
+    }
+    const all = array.getParent();
+    if (!all ||
+        !Node.isCallExpression(all) ||
+        all.getArguments()[0] !== array ||
+        !isLibraryPromiseAll(all)) {
+        return undefined;
+    }
+    let result = all;
+    while (Node.isAwaitExpression(result.getParentOrThrow()) ||
+        Node.isParenthesizedExpression(result.getParentOrThrow())) {
+        result = result.getParentOrThrow();
+    }
+    const declaration = result.getParent();
+    if (!declaration || !Node.isVariableDeclaration(declaration) || declaration.getInitializer() !== result) {
+        return undefined;
+    }
+    const pattern = declaration.getNameNode();
+    if (!Node.isArrayBindingPattern(pattern))
+        return undefined;
+    const element = pattern.getElements()[index];
+    if (!element || !Node.isBindingElement(element) || element.getDotDotDotToken())
+        return undefined;
+    const name = element.getNameNode();
+    return Node.isIdentifier(name) ? name : undefined;
+}
+/** `Promise.all` as the language library declares it, not a lookalike. */
+function isLibraryPromiseAll(call) {
+    const callee = call.getExpression();
+    if (!Node.isPropertyAccessExpression(callee) || callee.getName() !== 'all')
+        return false;
+    const declaration = resolvedDeclaration(call);
+    if (!declaration)
+        return false;
+    return call
+        .getProject()
+        .getProgram()
+        .compilerObject.isSourceFileDefaultLibrary(declaration.getSourceFile());
+}
 /**
  * Why these body reads cannot be retyped, or the reads to retype.
  *

package/sidecar/dist/src/server-labels.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The members a service's server-framework labels name, for an `infer`
+ * request's route rows (carrick#2674).
+ *
+ * The labels are verified again with the library-claims verifier, which reads
+ * them through a probe file. That file is added to a program of its own (the
+ * key's `scripts` program, built by the same factory and resolution host),
+ * never to the program the inferrer reads: adding and removing it there
+ * rebuilt that program twice and threw away its warm checker. Members join
+ * across the two programs by `declarationKey`, the compiler's file name and
+ * the declaration's start.
+ */
+import type { Project } from 'ts-morph';
+import { type LabelledMembers, type ModuleGraph } from './library-claims.js';
+import type { ServerClaims } from './types.js';
+/** What the label read needs of the project loader. */
+export interface LabelSource extends ModuleGraph {
+    getRepoRoot(): string;
+    /** A program for `key` the caller owns and drops: never the inferrer's. */
+    scriptProjectFor(key: string): Project;
+}
+/** No label: the inferrer reads nothing new. */
+export declare const NO_LABELS: LabelledMembers;
+/**
+ * The members `claims` name in the program behind `key`. A claim the schema
+ * refuses is dropped; a read that throws answers no labels, so every item of
+ * the request is read as it would be without them.
+ */
+export declare function readServerLabels(source: LabelSource, key: string, claims: ServerClaims, budgetMs: number, log: (message: string) => void): LabelledMembers;

package/sidecar/dist/src/server-labels.js

@@ -0,0 +1,45 @@
+/**
+ * The members a service's server-framework labels name, for an `infer`
+ * request's route rows (carrick#2674).
+ *
+ * The labels are verified again with the library-claims verifier, which reads
+ * them through a probe file. That file is added to a program of its own (the
+ * key's `scripts` program, built by the same factory and resolution host),
+ * never to the program the inferrer reads: adding and removing it there
+ * rebuilt that program twice and threw away its warm checker. Members join
+ * across the two programs by `declarationKey`, the compiler's file name and
+ * the declaration's start.
+ */
+import path from 'node:path';
+import { LibraryClaimsVerifier } from './library-claims.js';
+import { settledServerChecks } from './validators.js';
+/** No label: the inferrer reads nothing new. */
+export const NO_LABELS = { sends: new Map(), bodies: new Set() };
+/**
+ * The members `claims` name in the program behind `key`. A claim the schema
+ * refuses is dropped; a read that throws answers no labels, so every item of
+ * the request is read as it would be without them.
+ */
+export function readServerLabels(source, key, claims, budgetMs, log) {
+    const { checks, refused } = settledServerChecks(claims.checks);
+    if (refused > 0) {
+        log(`Dropped ${refused} server claim(s) the library-check schema refuses (a make or scope among them leaves its ops unread)`);
+    }
+    if (checks.length === 0)
+        return NO_LABELS;
+    const fromDir = path.resolve(source.getRepoRoot(), claims.from_dir);
+    try {
+        const verifier = new LibraryClaimsVerifier(source.scriptProjectFor(key), {
+            packageDirectoryOf: (file) => source.packageDirectoryOf(file),
+            resolveModule: (name, from, options) => source.resolveModule(name, from, options),
+        });
+        const labels = verifier.labelledMembers(fromDir, checks, budgetMs, claims.scan_root, claims.type_packages);
+        log(`Read ${labels.sends.size} labelled send and ${labels.bodies.size} body member(s) for handler parameters ` +
+            `from ${checks.length} claim(s) in ${fromDir}: ${JSON.stringify(labels.outcomes ?? {})}`);
+        return labels;
+    }
+    catch (error) {
+        log(`Reading server labels in ${fromDir} failed, so no handler parameter is read through them: ${String(error)}`);
+        return NO_LABELS;
+    }
+}

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

@@ -0,0 +1,138 @@
+/**
+ * What a route handler's own parameters state about the route's bodies
+ * (carrick#2674), read through the members the service's verified
+ * server-framework labels name ({@link LabelledMembers}). A member is matched
+ * by its declaration, never by its name, so a type the repo declares itself
+ * with a member of the same name states nothing here.
+ *
+ * - The request: the member a receive op's `request.body` path ends on, read
+ *   at the handler's parameter. A type the source fills is the body. A body
+ *   the source leaves `never`, or leaves at the library's unfilled `unknown`
+ *   while it writes a type argument for the route, is "no request body",
+ *   provided nothing reads it (`bodyIsUnread`).
+ * - The reply: the payload a labelled `send` member's slot takes, read at the
+ *   handler's parameter, where the library declares that payload through a
+ *   type parameter of the reply type. A union of success and error bodies is
+ *   cut to the variants a success-status send through the parameter carries.
+ */
+import { Node, type ArrowFunction, type CallExpression, type FunctionDeclaration, type FunctionExpression, type MethodDeclaration, type ParameterDeclaration, type Type } from 'ts-morph';
+import { type LabelledMembers } from './library-claims.js';
+/** A function a handler can be: what the inferrer follows a registration to. */
+export type HandlerFunction = FunctionDeclaration | ArrowFunction | FunctionExpression | MethodDeclaration;
+/** What a handler's parameters state about the request body. */
+export type StatedRequest = {
+    kind: 'body';
+    type: Type;
+    at: ParameterDeclaration;
+} | {
+    kind: 'no_body';
+    at: ParameterDeclaration;
+    detail: string;
+};
+/** The reply a handler's parameters state: one or more success variants. */
+export interface StatedReply {
+    variants: Type[];
+    at: ParameterDeclaration;
+}
+/** The status a send's own chain states, as the inferrer reads it. */
+export type ChainStatus = (call: CallExpression) => 'success' | 'error' | 'redirect' | 'variable' | 'undecided' | undefined;
+export declare class StatedParams {
+    private readonly labels;
+    /** True for a file the repo declares itself (not a library's or the runtime's). */
+    private readonly isRepoFile;
+    private readonly chainStatus;
+    constructor(labels: LabelledMembers, 
+    /** True for a file the repo declares itself (not a library's or the runtime's). */
+    isRepoFile: (file: Node) => boolean, chainStatus: ChainStatus);
+    /** No label names a member: every reading answers nothing. */
+    get isEmpty(): boolean;
+    /** Whether some label names a reply's send member. */
+    get readsReplies(): boolean;
+    /**
+     * The request body the handler's parameters state, the first parameter
+     * whose type has a labelled body member deciding. Undefined when no
+     * parameter has one, or the one that does states nothing decidable. A
+     * route whose `registration` hands in another function beside the handler
+     * (a middleware, which can read the body first) decides no "no body".
+     */
+    request(handler: HandlerFunction, registration?: Node): StatedRequest | undefined;
+    /**
+     * The route hands in a function besides the handler: a callable argument
+     * (or list of them) beside the handler on any call it is passed through
+     * up to the registration, or, where the registration names the handler by
+     * reference, a second callable argument or property there. What such a
+     * function (a middleware) does with the request is not read here.
+     */
+    private handsInAnotherFunction;
+    /**
+     * 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),
+     * through any calls enclosing that one as an argument, or on the
+     * parameter's own annotation.
+     */
+    private writesTypeArgument;
+    /**
+     * Nothing reads the labelled body member off parameter `index` of
+     * `func`, nor off the request in the repo functions it is handed to, up to
+     * `REACH_DEPTH` calls deep. Every use of the request must be a member
+     * read that is not the body and is not itself called (a framework's own
+     * body reader), or a hand-off to a function the repo declares, whole and
+     * by position. Anything else (a destructured parameter, a library
+     * function, an alias, a spread) is a read this cannot rule out.
+     */
+    private bodyIsUnread;
+    /**
+     * A read of a request member (`req.headers`, `req.headers.host`) whose
+     * value goes nowhere a body could be read from. Along its member chain, a
+     * method called on anything but a plain value (`req.raw.pipe(...)`, or a
+     * framework's own body reader `req.file()`) is a read, and so is a
+     * non-plain value handed to a function (`getRawBody(req.raw)`). A plain
+     * value (a header string) holds no body, whatever is done with it.
+     */
+    private memberReadStaysPut;
+    /** The function a callee names, where the repo declares it; undefined otherwise. */
+    private repoFunction;
+    /**
+     * The reply the handler's parameters state, cut to its success variants.
+     * Undefined when no parameter has a labelled send member that states a
+     * payload, when two such members disagree, when the payload is `any`,
+     * `unknown` or `never`, or when a union of bodies has no variant a
+     * success send through the parameter carries.
+     */
+    reply(handler: HandlerFunction): StatedReply | undefined;
+    /**
+     * The payload the labelled send members the handler calls through the
+     * parameter state: `none` when it calls none, `abstain` when they state
+     * different payloads, else the one payload type. A member the handler never
+     * calls (a reply object's status-code send beside its body send) says
+     * nothing about this route.
+     */
+    private statedPayload;
+    /** The payload slot a labelled send member takes, by any of its declarations. */
+    private sendSlotOf;
+    /**
+     * The type parameters of the type that declares the member that its
+     * payload is declared through: a slot each route fills. None for a payload
+     * declared with a fixed type (a file path), which says nothing about any
+     * one route.
+     */
+    private payloadTypeParameters;
+    /** The type the call signature takes at the payload slot, read at `at`. */
+    private payloadAt;
+    /**
+     * The calls of a labelled send member the handler makes on `parameter`, or
+     * on a call chain rooted at it (`res.status(201).json(body)`), each with
+     * its payload slot and the keys of the member's declarations.
+     */
+    private sendsThrough;
+    /**
+     * The payloads the sends carry whose chain states a success status or
+     * none. A value typed `any` or `unknown` is assignable to every variant, so
+     * it tells no success body from an error body and is left out.
+     */
+    private successPayloads;
+    /** The symbol at the root of a member or call chain (`res.status(201)` is `res`). */
+    private rootSymbol;
+    /** The member of the parameter's type whose declaration a label names. */
+    private labelledMember;
+}