carrick 0.3.126 → 0.3.128

package/sidecar/dist/src/stated-params.js

@@ -0,0 +1,547 @@
+/**
+ * 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, SyntaxKind, ts, } from 'ts-morph';
+import { declarationKey } from './library-claims.js';
+/** Type flags of a value that cannot hold a request body: a string, number, boolean and the like. */
+const PLAIN_VALUE_FLAGS = ts.TypeFlags.StringLike |
+    ts.TypeFlags.NumberLike |
+    ts.TypeFlags.BigIntLike |
+    ts.TypeFlags.BooleanLike |
+    ts.TypeFlags.EnumLike |
+    ts.TypeFlags.Undefined |
+    ts.TypeFlags.Null |
+    ts.TypeFlags.Void;
+/** The expression's type is a plain value, or a union of plain values. */
+function holdsPlainValue(node) {
+    let type;
+    try {
+        type = node.getType();
+    }
+    catch {
+        return false;
+    }
+    const parts = type.isUnion() ? type.getUnionTypes() : [type];
+    return parts.every((part) => (part.getFlags() & PLAIN_VALUE_FLAGS) !== 0);
+}
+/** How many repo functions the request may be handed through before a read is unprovable. */
+const REACH_DEPTH = 2;
+export class StatedParams {
+    labels;
+    isRepoFile;
+    chainStatus;
+    constructor(labels, 
+    /** True for a file the repo declares itself (not a library's or the runtime's). */
+    isRepoFile, chainStatus) {
+        this.labels = labels;
+        this.isRepoFile = isRepoFile;
+        this.chainStatus = chainStatus;
+    }
+    /** No label names a member: every reading answers nothing. */
+    get isEmpty() {
+        return this.labels.sends.size === 0 && this.labels.bodies.size === 0;
+    }
+    /** Whether some label names a reply's send member. */
+    get readsReplies() {
+        return this.labels.sends.size > 0;
+    }
+    // ===========================================================================
+    // Request
+    // ===========================================================================
+    /**
+     * 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, registration) {
+        if (this.labels.bodies.size === 0)
+            return undefined;
+        const parameters = handler.getParameters();
+        for (const parameter of parameters) {
+            const member = this.labelledMember(parameter, (key) => this.labels.bodies.has(key));
+            if (!member)
+                continue;
+            let body;
+            try {
+                body = member.getTypeAtLocation(parameter);
+            }
+            catch {
+                return undefined;
+            }
+            if (body.isAny())
+                return undefined;
+            if (!body.isUnknown() && !body.isNever())
+                return { kind: 'body', type: body, at: parameter };
+            if (body.isUnknown() && !this.writesTypeArgument(handler, parameter))
+                return undefined;
+            if (registration && this.handsInAnotherFunction(registration, handler))
+                return undefined;
+            const declarations = new Set((member.getDeclarations() ?? []).map((d) => declarationKey(d.compilerNode)));
+            if (!this.bodyIsUnread(handler, parameters.indexOf(parameter), declarations, 0, new Map())) {
+                return undefined;
+            }
+            return {
+                kind: 'no_body',
+                at: parameter,
+                detail: body.isNever()
+                    ? "the route's request type states its body as never, and nothing the handler hands the request to reads it"
+                    : "the route's request type states its parts and no body, and nothing the handler hands the request to reads it",
+            };
+        }
+        return 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.
+     */
+    handsInAnotherFunction(registration, handler) {
+        const callable = (node) => {
+            let type;
+            try {
+                type = node.getType();
+            }
+            catch {
+                return true;
+            }
+            const element = type.getArrayElementType() ?? type.getTupleElements()[0];
+            return type.getCallSignatures().length > 0 || (element !== undefined && element.getCallSignatures().length > 0);
+        };
+        let node = handler;
+        let parent = node.getParent();
+        while (parent && Node.isCallExpression(parent) && parent.getArguments().includes(node)) {
+            const passed = node;
+            if (parent.getArguments().some((argument) => argument !== passed && callable(argument)))
+                return true;
+            node = parent;
+            parent = node.getParent();
+        }
+        const holdsHandler = registration === handler || handler.getAncestors().includes(registration);
+        if (holdsHandler) {
+            if (!Node.isObjectLiteralExpression(registration))
+                return false;
+            return registration
+                .getProperties()
+                .some((property) => !handler.getAncestors().includes(property) && callable(property));
+        }
+        const siblings = Node.isCallExpression(registration)
+            ? registration.getArguments()
+            : Node.isObjectLiteralExpression(registration)
+                ? registration.getProperties()
+                : [];
+        return siblings.filter(callable).length > 1;
+    }
+    /**
+     * 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.
+     */
+    writesTypeArgument(handler, parameter) {
+        const annotation = parameter.getTypeNode();
+        if (annotation && Node.isTypeReference(annotation) && annotation.getTypeArguments().length > 0) {
+            return true;
+        }
+        let node = handler;
+        let parent = node.getParent();
+        while (parent && Node.isCallExpression(parent) && parent.getArguments().includes(node)) {
+            if (parent.getTypeArguments().length > 0)
+                return true;
+            node = parent;
+            parent = node.getParent();
+        }
+        return false;
+    }
+    /**
+     * 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.
+     */
+    bodyIsUnread(func, index, bodyKeys, depth, seen) {
+        const visited = seen.get(func) ?? new Set();
+        if (visited.has(index))
+            return true;
+        visited.add(index);
+        seen.set(func, visited);
+        const parameter = func.getParameters()[index];
+        if (!parameter)
+            return true;
+        if (parameter.isRestParameter())
+            return false;
+        const name = parameter.getNameNode();
+        if (!Node.isIdentifier(name))
+            return false;
+        const symbol = name.getSymbol();
+        const body = func.getBody();
+        if (!symbol || !body)
+            return false;
+        for (const use of body.getDescendantsOfKind(SyntaxKind.Identifier)) {
+            if (use.getSymbol() !== symbol)
+                continue;
+            const parent = use.getParent();
+            if (!parent)
+                return false;
+            if (Node.isPropertyAccessExpression(parent) && parent.getExpression() === use) {
+                const declarations = parent.getNameNode().getSymbol()?.getDeclarations() ?? [];
+                if (declarations.some((d) => bodyKeys.has(declarationKey(d.compilerNode))))
+                    return false;
+                if (!this.memberReadStaysPut(parent))
+                    return false;
+                continue;
+            }
+            if (Node.isCallExpression(parent) && parent.getArguments().includes(use)) {
+                const position = parent.getArguments().indexOf(use);
+                if (parent.getArguments().slice(0, position).some(Node.isSpreadElement))
+                    return false;
+                if (depth >= REACH_DEPTH)
+                    return false;
+                const callee = this.repoFunction(parent.getExpression());
+                if (!callee)
+                    return false;
+                // A helper that takes the request under a type without the labelled
+                // body member could read the body under another declaration, which
+                // nothing here can match.
+                const taken = callee.getParameters()[position];
+                if (!taken || !this.labelledMember(taken, (key) => bodyKeys.has(key)))
+                    return false;
+                if (!this.bodyIsUnread(callee, position, bodyKeys, depth + 1, seen))
+                    return false;
+                continue;
+            }
+            return false;
+        }
+        return true;
+    }
+    /**
+     * 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.
+     */
+    memberReadStaysPut(read) {
+        let node = read;
+        for (;;) {
+            const outer = node.getParent();
+            if (!outer)
+                return true;
+            if ((Node.isCallExpression(outer) || Node.isNewExpression(outer)) && outer.getExpression() === node) {
+                const receiver = Node.isPropertyAccessExpression(node) || Node.isElementAccessExpression(node) ? node.getExpression() : undefined;
+                return receiver !== undefined && receiver !== read.getExpression() && holdsPlainValue(receiver);
+            }
+            if (Node.isCallExpression(outer) || Node.isNewExpression(outer)) {
+                return holdsPlainValue(node);
+            }
+            if ((Node.isPropertyAccessExpression(outer) || Node.isElementAccessExpression(outer)) &&
+                outer.getExpression() === node) {
+                node = outer;
+                continue;
+            }
+            if (Node.isNonNullExpression(outer) || Node.isParenthesizedExpression(outer)) {
+                node = outer;
+                continue;
+            }
+            return true;
+        }
+    }
+    /** The function a callee names, where the repo declares it; undefined otherwise. */
+    repoFunction(callee) {
+        let symbol = callee.getSymbol();
+        if (symbol?.isAlias())
+            symbol = symbol.getAliasedSymbol() ?? symbol;
+        for (const declaration of symbol?.getDeclarations() ?? []) {
+            if (!this.isRepoFile(declaration.getSourceFile()))
+                continue;
+            if (Node.isFunctionDeclaration(declaration) ||
+                Node.isMethodDeclaration(declaration) ||
+                Node.isArrowFunction(declaration) ||
+                Node.isFunctionExpression(declaration)) {
+                return declaration.getBody() ? declaration : undefined;
+            }
+            if (Node.isVariableDeclaration(declaration) || Node.isPropertyAssignment(declaration)) {
+                const initializer = declaration.getInitializer();
+                if (initializer && (Node.isArrowFunction(initializer) || Node.isFunctionExpression(initializer))) {
+                    return initializer;
+                }
+            }
+        }
+        return undefined;
+    }
+    // ===========================================================================
+    // Reply
+    // ===========================================================================
+    /**
+     * 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) {
+        if (this.labels.sends.size === 0)
+            return undefined;
+        for (const parameter of handler.getParameters()) {
+            const sends = this.sendsThrough(handler, parameter);
+            const stated = this.statedPayload(parameter, new Set(sends.flatMap((send) => send.keys)));
+            if (stated === 'none')
+                continue;
+            if (stated === 'abstain')
+                return undefined;
+            if (stated.isAny() || stated.isUnknown() || stated.isNever())
+                return undefined;
+            const variants = stated.isUnion() ? stated.getUnionTypes().filter((t) => !t.isNull() && !t.isUndefined()) : [stated];
+            const literalUnion = stated.isBoolean() || variants.every((t) => t.isLiteral() || t.isBooleanLiteral());
+            if (variants.length <= 1 || literalUnion) {
+                // An optional payload slot adds `undefined`: no body sent, not a body.
+                const defined = stated.isUnion() ? stated.getUnionTypes().filter((t) => !t.isUndefined()) : [stated];
+                return defined.length > 0 ? { variants: defined, at: parameter } : undefined;
+            }
+            const carried = this.successPayloads(sends);
+            const kept = variants.filter((variant) => carried.some((sent) => sent.isAssignableTo(variant)));
+            return kept.length > 0 ? { variants: kept, at: parameter } : undefined;
+        }
+        return 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.
+     */
+    statedPayload(parameter, called) {
+        let type;
+        try {
+            type = parameter.getType();
+        }
+        catch {
+            return 'none';
+        }
+        let found = false;
+        let payload;
+        for (const property of type.getProperties()) {
+            const keys = property.getDeclarations().map((d) => declarationKey(d.compilerNode));
+            if (!keys.some((key) => called.has(key)))
+                continue;
+            const slot = this.sendSlotOf(property.getDeclarations().map((d) => d.compilerNode));
+            if (!slot)
+                continue;
+            found = true;
+            const through = property
+                .getDeclarations()
+                .map((d) => this.payloadTypeParameters(d.compilerNode, slot))
+                .find((named) => named.length > 0);
+            if (!through)
+                continue;
+            const checker = parameter.getProject().getTypeChecker().compilerObject;
+            const defaults = new Set(through.flatMap((named) => (named.default ? [checker.getTypeFromTypeNode(named.default)] : [])));
+            let member;
+            try {
+                member = property.getTypeAtLocation(parameter);
+            }
+            catch {
+                continue;
+            }
+            for (const signature of member.getCallSignatures()) {
+                // A payload the member's own type parameter types is whatever each
+                // call passes: the parameter states nothing.
+                if (signature.getTypeParameters().length > 0)
+                    continue;
+                const at = this.payloadAt(signature.getParameters(), slot, parameter);
+                if (!at)
+                    continue;
+                // The type parameter at its declared default: the route filled
+                // nothing there (a status-code send left at `number`).
+                if (defaults.has(at.compilerType))
+                    continue;
+                if (payload === undefined)
+                    payload = at;
+                else if (payload.compilerType !== at.compilerType)
+                    return 'abstain';
+            }
+        }
+        if (!found)
+            return 'none';
+        return payload ?? 'none';
+    }
+    /** The payload slot a labelled send member takes, by any of its declarations. */
+    sendSlotOf(declarations) {
+        for (const declaration of declarations) {
+            const slot = this.labels.sends.get(declarationKey(declaration));
+            if (slot)
+                return slot;
+        }
+        return undefined;
+    }
+    /**
+     * 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.
+     */
+    payloadTypeParameters(declaration, slot) {
+        const owner = declaration.parent;
+        const ownParameters = new Set(owner && (ts.isInterfaceDeclaration(owner) || ts.isClassDeclaration(owner) || ts.isClassExpression(owner))
+            ? (owner.typeParameters ?? [])
+            : []);
+        if (ownParameters.size === 0)
+            return [];
+        let typeNode;
+        if (ts.isMethodSignature(declaration) || ts.isMethodDeclaration(declaration)) {
+            typeNode = declaration.parameters[slot.arg]?.type;
+        }
+        else if (ts.isPropertySignature(declaration) || ts.isPropertyDeclaration(declaration)) {
+            typeNode = declaration.type;
+        }
+        if (!typeNode)
+            return [];
+        const mentioned = new Set();
+        const visit = (node) => {
+            if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName)) {
+                const name = node.typeName.text;
+                for (const parameter of ownParameters) {
+                    if (ts.isTypeParameterDeclaration(parameter) && parameter.name.text === name)
+                        mentioned.add(parameter);
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(typeNode);
+        return [...mentioned];
+    }
+    /** The type the call signature takes at the payload slot, read at `at`. */
+    payloadAt(parameters, slot, at) {
+        const symbol = parameters[slot.arg];
+        if (!symbol)
+            return undefined;
+        const declaration = symbol.getDeclarations()[0];
+        let type = symbol.getTypeAtLocation(at);
+        if (declaration && Node.isParameterDeclaration(declaration) && declaration.isRestParameter()) {
+            if (!type.isTuple())
+                return undefined;
+            const first = type.getTupleElements()[0];
+            if (!first)
+                return undefined;
+            type = first;
+        }
+        if (slot.key !== undefined) {
+            const property = type.getProperty(slot.key);
+            if (!property)
+                return undefined;
+            type = property.getTypeAtLocation(at);
+        }
+        const optional = declaration !== undefined && Node.isParameterDeclaration(declaration) && declaration.isOptional();
+        if (optional && type.isUnion()) {
+            const defined = type.getUnionTypes().filter((t) => !t.isUndefined());
+            if (defined.length === 1)
+                return defined[0];
+        }
+        return type;
+    }
+    /**
+     * 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.
+     */
+    sendsThrough(handler, parameter) {
+        const name = parameter.getNameNode();
+        const symbol = Node.isIdentifier(name) ? name.getSymbol() : undefined;
+        const body = handler.getBody();
+        if (!symbol || !body)
+            return [];
+        const sends = [];
+        for (const call of body.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+            const callee = call.getExpression();
+            if (!Node.isPropertyAccessExpression(callee))
+                continue;
+            const declarations = (callee.getNameNode().getSymbol()?.getDeclarations() ?? []).map((d) => d.compilerNode);
+            const slot = this.sendSlotOf(declarations);
+            if (!slot)
+                continue;
+            if (this.rootSymbol(callee.getExpression()) !== symbol)
+                continue;
+            sends.push({ call, slot, keys: declarations.map(declarationKey) });
+        }
+        return sends;
+    }
+    /**
+     * 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.
+     */
+    successPayloads(sends) {
+        const sent = [];
+        for (const { call, slot } of sends) {
+            const status = this.chainStatus(call);
+            if (status !== undefined && status !== 'success')
+                continue;
+            let argument = call.getArguments()[slot.arg];
+            if (!argument || Node.isSpreadElement(argument))
+                continue;
+            if (slot.key !== undefined) {
+                if (!Node.isObjectLiteralExpression(argument))
+                    continue;
+                const property = argument.getProperty(slot.key);
+                if (!property || !Node.isPropertyAssignment(property))
+                    continue;
+                const initializer = property.getInitializer();
+                if (!initializer)
+                    continue;
+                argument = initializer;
+            }
+            const type = argument.getType();
+            if (type.isAny() || type.isUnknown())
+                continue;
+            sent.push(type);
+        }
+        return sent;
+    }
+    /** The symbol at the root of a member or call chain (`res.status(201)` is `res`). */
+    rootSymbol(expression) {
+        let node = expression;
+        for (;;) {
+            if (Node.isPropertyAccessExpression(node) || Node.isCallExpression(node) || Node.isParenthesizedExpression(node) || Node.isNonNullExpression(node)) {
+                node = node.getExpression();
+                continue;
+            }
+            break;
+        }
+        return Node.isIdentifier(node) ? node.getSymbol() : undefined;
+    }
+    /** The member of the parameter's type whose declaration a label names. */
+    labelledMember(parameter, labelled) {
+        let type;
+        try {
+            type = parameter.getType();
+        }
+        catch {
+            return undefined;
+        }
+        return type
+            .getProperties()
+            .find((property) => property.getDeclarations().some((d) => labelled(declarationKey(d.compilerNode))));
+    }
+}