carrick 0.3.114 → 0.3.116

package/sidecar/dist/src/index.js

@@ -322,7 +322,7 @@ function handleInfer(request) {
         const results = [...byProject(request.requests, (item) => item.file_path)].map(([key, items]) => projectComponents(key).typeInferrer.infer(items, request.extraction_config, () => {
             done += 1;
             report();
-        }));
+        }, request.model_symbols));
         const result = results.length === 1
             ? results[0]
             : (() => {

package/sidecar/dist/src/symbol-relation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * How a type the model named for a producer's response relates to the
+ * compiler's type of what the handler sends (carrick#2111).
+ *
+ * The model names one symbol per row, and by schema it is a bare name. The
+ * compiler reads the response expression itself. Where the two are the same
+ * type the name is the better thing to publish; where they are not, the name
+ * is wrong about the body: an element named for a list, a helper's input type
+ * named for its result, a type named for the wrapper sent around it.
+ *
+ * The compiler decides, by assignability asked both ways. Neither names nor
+ * printed text are compared.
+ */
+import { ts } from 'ts-morph';
+import type { ModelSymbolRelation } from './types.js';
+/**
+ * The relation of `symbol` (the type the model named) to `read` (the types
+ * of the expressions the handler sends, one per surviving branch), or
+ * `undefined` where there is nothing to compare: either side is `any` or
+ * `unknown` at its root, or is only `null`.
+ *
+ *  - `same`: the two are one type. A list's own `readonly` does not count.
+ *  - `list`: the read is a list of the symbol, `depth` levels deep.
+ *  - `member`: the symbol is one member of the read's union, and the rest
+ *    is more than `null` or `undefined`. Which member is the success body is
+ *    decided by status, elsewhere.
+ *  - `nullable`: the read is the symbol or `null`/`undefined`.
+ *  - `different`: anything else.
+ */
+export declare function relateSymbolToRead(checker: ts.TypeChecker, symbol: ts.Type, read: readonly ts.Type[]): ModelSymbolRelation | undefined;
+/**
+ * Whether a printed type holds `any` or `unknown` anywhere. Such a read has
+ * a part the compiler could not see, and assignability against it says
+ * nothing about the part it could.
+ */
+export declare function printedTypeHoldsTopType(text: string): boolean;

package/sidecar/dist/src/symbol-relation.js

@@ -0,0 +1,109 @@
+/**
+ * How a type the model named for a producer's response relates to the
+ * compiler's type of what the handler sends (carrick#2111).
+ *
+ * The model names one symbol per row, and by schema it is a bare name. The
+ * compiler reads the response expression itself. Where the two are the same
+ * type the name is the better thing to publish; where they are not, the name
+ * is wrong about the body: an element named for a list, a helper's input type
+ * named for its result, a type named for the wrapper sent around it.
+ *
+ * The compiler decides, by assignability asked both ways. Neither names nor
+ * printed text are compared.
+ */
+import { ts } from 'ts-morph';
+/** A list level deeper than this is not a payload shape worth following. */
+const MAX_LIST_DEPTH = 10;
+const NULLISH = ts.TypeFlags.Null | ts.TypeFlags.Undefined | ts.TypeFlags.Void;
+const TOP = ts.TypeFlags.Any | ts.TypeFlags.Unknown;
+function partsOf(types) {
+    const members = [];
+    let nullish = false;
+    for (const type of types) {
+        for (const part of type.isUnion() ? type.types : [type]) {
+            if (part.flags & NULLISH)
+                nullish = true;
+            else if (!members.includes(part))
+                members.push(part);
+        }
+    }
+    return { members, nullish };
+}
+/**
+ * `type` with its list levels peeled, whichever of `T[]`, `readonly T[]` and
+ * a tuple each level is. JSON has no `readonly`, so a list's own modifier is set
+ * aside; one deeper inside the element is the wire transform's to drop.
+ */
+function peelLists(checker, type) {
+    let element = type;
+    let depth = 0;
+    while (depth < MAX_LIST_DEPTH && (checker.isArrayType(element) || checker.isTupleType(element))) {
+        // A tuple is a list on the wire: its element is every member's type.
+        const inner = checker.getIndexTypeOfType(element, ts.IndexKind.Number);
+        if (!inner)
+            break;
+        element = inner;
+        depth += 1;
+    }
+    return { element, depth };
+}
+/**
+ * The relation of `symbol` (the type the model named) to `read` (the types
+ * of the expressions the handler sends, one per surviving branch), or
+ * `undefined` where there is nothing to compare: either side is `any` or
+ * `unknown` at its root, or is only `null`.
+ *
+ *  - `same`: the two are one type. A list's own `readonly` does not count.
+ *  - `list`: the read is a list of the symbol, `depth` levels deep.
+ *  - `member`: the symbol is one member of the read's union, and the rest
+ *    is more than `null` or `undefined`. Which member is the success body is
+ *    decided by status, elsewhere.
+ *  - `nullable`: the read is the symbol or `null`/`undefined`.
+ *  - `different`: anything else.
+ */
+export function relateSymbolToRead(checker, symbol, read) {
+    if (read.length === 0)
+        return undefined;
+    if ([symbol, ...read].some((type) => type.flags & TOP))
+        return undefined;
+    const sent = partsOf(read);
+    const named = partsOf([symbol]);
+    if (sent.members.length === 0 || named.members.length === 0)
+        return undefined;
+    const same = (a, b) => checker.isTypeAssignableTo(a, b) && checker.isTypeAssignableTo(b, a);
+    /** One type, up to `readonly` on its list levels. */
+    const sameBody = (a, b) => {
+        if (same(a, b))
+            return true;
+        const left = peelLists(checker, a);
+        const right = peelLists(checker, b);
+        return left.depth > 0 && left.depth === right.depth && same(left.element, right.element);
+    };
+    const namedAreSent = named.members.every((n) => sent.members.some((s) => sameBody(s, n)));
+    const sentAreNamed = sent.members.every((s) => named.members.some((n) => sameBody(s, n)));
+    if (namedAreSent && sentAreNamed) {
+        if (sent.nullish === named.nullish)
+            return { relation: 'same' };
+        return { relation: sent.nullish ? 'nullable' : 'different' };
+    }
+    if (namedAreSent && (sent.nullish || !named.nullish)) {
+        return { relation: 'member' };
+    }
+    if (sent.members.length === 1 && !sent.nullish && !named.nullish) {
+        const list = peelLists(checker, sent.members[0]);
+        const element = named.members.length === 1 ? peelLists(checker, symbol) : { element: symbol, depth: 0 };
+        if (list.depth > element.depth && same(list.element, element.element)) {
+            return { relation: 'list', depth: list.depth - element.depth };
+        }
+    }
+    return { relation: 'different' };
+}
+/**
+ * Whether a printed type holds `any` or `unknown` anywhere. Such a read has
+ * a part the compiler could not see, and assignability against it says
+ * nothing about the part it could.
+ */
+export function printedTypeHoldsTopType(text) {
+    const withoutLiterals = text.replace(/'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"|`(?:[^`\\]|\\.)*`/g, "''");
+    return /\b(?:any|unknown)\b/.test(withoutLiterals);
+}

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

@@ -18,7 +18,7 @@
  * function's return type.
  */
 import { Project, SourceFile, type CallExpression } from 'ts-morph';
-import type { InferRequestItem, InferResult, ExtractionConfig } from './types.js';
+import type { InferRequestItem, InferResult, ModelSymbol, ExtractionConfig } from './types.js';
 /**
  * Strongly-discriminating member names of HTTP transport machinery — the
  * fetch/DOM `Response` & `Request`, a Node `http.ServerResponse`, a framework
@@ -123,7 +123,33 @@ 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): InferResult;
+    infer(requests: InferRequestItem[], extractionConfig?: ExtractionConfig, onRequestDone?: InferRequestDone, modelSymbols?: ModelSymbol[]): InferResult;
+    /** The types the model named, by the alias of the row each is for (carrick#2111). */
+    private modelSymbols;
+    /**
+     * 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
+     * of what the handler sends (`read`, one type per surviving branch). The
+     * driver keeps, re-depths or drops the model's symbol on the answer.
+     *
+     * Nothing is recorded, and the symbol stands, where there is nothing to
+     * compare: the symbol does not resolve in this program, or the published
+     * read holds `any` or `unknown` somewhere.
+     */
+    private relateModelSymbol;
+    /**
+     * `func` is the function the row's line names: it opens on that line (a
+     * method under its decorators, an exported handler), or it is the handler
+     * of the registration that opens there (`app.post<…>(\n '/path',\n async
+     * (request) => { … })`, or a named handler declared elsewhere).
+     */
+    private isTheRowsOwnFunction;
+    /**
+     * The declared type of a symbol the model named, found as the bundle finds
+     * it (through a barrel's re-exports), in a file this program already
+     * holds. A name that declares a value and no type resolves to nothing.
+     */
+    private modelSymbolType;
     /**
      * carrick#1836: list on `result` the declarations behind the names its text
      * prints that the request's file cannot resolve (`PrintedTypes.namesIn`).
@@ -423,6 +449,36 @@ export declare class TypeInferrer {
     private inferExpression;
     private inferRequestBody;
     private resolveCallResultTerminalNode;
+    /**
+     * Where the walk ends on the call's own destructuring binding (`const {
+     * tasks } = await api.list()`), the declaration has no type of its own: the
+     * checker answers `any` for it. The value it takes apart is the call's, so
+     * the call answers (carrick#2112). Not for a transport value: a helper's
+     * `{ body, response }` read as text would bypass the capture's machinery
+     * guard, so that binding stays unread and the capture answers the row.
+     */
+    private destructuredValueTerminal;
+    /**
+     * `expr` declares a name for what a call returns when it is handed a
+     * tracked name whole (`const data: T = await parseJson(response, 'op')`).
+     */
+    private handsTrackedValueToACall;
+    /** `expr` holds a binary whole-body read taken on a tracked name. */
+    private holdsBinaryBodyRead;
+    /**
+     * `func`, the function a call is made in, is the executor of the promise
+     * `returnStmt` returns: `return new Promise<T>((resolve, reject) => { … })`
+     * (carrick#2282). The promise is recognised by the language's await
+     * protocol on the constructed value, never by a name.
+     */
+    private callIsInReturnedPromiseExecutor;
+    /**
+     * `expr` declares a name for the tracked value as it is: its initializer,
+     * with the wrappers that leave a value what it was peeled (parentheses,
+     * `await`, `as`, `satisfies`, `!`), is a tracked name (carrick#2112). The
+     * declaration's type is then the value's, as the source restates it.
+     */
+    private restatesTrackedValue;
     /**
      * True when a member read on the call's result resolves to one of that
      * result's own TYPE ARGUMENTS — the source is unwrapping a generic envelope
@@ -473,6 +529,35 @@ export declare class TypeInferrer {
      * as written.
      */
     private resultCarrierPayload;
+    /**
+     * carrick#1841: the branches of a conditional type the compiler left
+     * deferred on a type parameter, each with its promise-like peeled, or
+     * `undefined` for any other type.
+     *
+     * Inside a generic function whose result depends on a type parameter it has
+     * not fixed (`<Throw extends boolean>(o) => client.get<Table, Errors,
+     * Throw>(…)`), the call's result is such a conditional. The compiler states
+     * what its branches allow itself: the constraint of the conditional, which
+     * is its apparent type. No branch is read off the alias's declaration.
+     */
+    private deferredConditionalBranches;
+    /**
+     * carrick#1841: what a call result deferred on a type parameter carries,
+     * read through its branches. `undefined` where `type` is no such
+     * conditional, or none of its branches is a result carrier, and the type
+     * keeps the answer it had.
+     *
+     * Each branch that is a carrier is read by the carrier read, with the
+     * call's own type arguments. Every one of them must name the same payload,
+     * by the compiler's type identity, and every other branch must hold that
+     * payload as the type of one of its members (the branch a client answers
+     * with when it throws on failure holds the body and no error side). Then
+     * the payload is the body whichever branch the caller fixes. A carrier
+     * branch that states no contract decides for the whole. Branches that
+     * disagree state none: the conditional is the client's bookkeeping and is
+     * never published as written.
+     */
+    private deferredConditionalPayload;
     /**
      * The value of a response table's one success row, for a table a carrier
      * holds as itself rather than through its body. `undefined` where the table
@@ -661,7 +746,8 @@ export declare class TypeInferrer {
      * The zero-argument whole-body read that takes `receiver` as its receiver,
      * `res.json()` or `res.text()`, or `undefined`. A text read is a body read
      * like a json one (carrick#1842): without it, `return res.text()` left the
-     * walk on the response binding and published the transport object.
+     * walk on the response binding and published the transport object. `reads`
+     * names the reads asked for.
      */
     private bodyReadOnReceiver;
     private collectDefUseNodes;
@@ -1629,6 +1715,35 @@ export declare class TypeInferrer {
      * by ts-morph's `getDefinitionNodes`, so no manual import chasing is needed.
      */
     private functionFromDeclaration;
+    /**
+     * True when `handler` reads nothing from the incoming message (carrick#827):
+     * every use of one of its parameters, named or destructured, is the receiver
+     * of a call chain whose value the handler discards or returns
+     * (`reply.json(result)`, `return c.status(201).json(result)`). That is a
+     * send. A returned chain must end in a call that takes an argument, so a
+     * read handed straight back (`return request.json()`) is not one.
+     *
+     * Anything else may be a read of the body and makes this false: a property
+     * read, a call whose value is used, a parameter handed whole to another
+     * function, or a call in the chain handed an argument that can receive what
+     * the parameter gives (`argumentCanReceive`: a callback, an object with a
+     * method), as in `request.pipe(dest)`, `request.on('data', cb)` and
+     * `request.json().then(cb)`. No method or property name is consulted. A
+     * handler with no parameter, or one that uses `this`, proves nothing: it may
+     * read the message from `this` or a closure.
+     */
+    private handlerReadsNothingFromItsParameters;
+    /**
+     * True unless `argument` is proven to be data that cannot receive anything
+     * from the call it is handed to (carrick#827). Data is a primitive or literal,
+     * `null`/`undefined`, or an object with no call or construct signature and
+     * no callable member; an array of such, or a union all of whose members are.
+     * A callback, an object with a method (a stream, an emitter), or a type the
+     * compiler cannot state (`any`, `unknown`, a type parameter) can receive.
+     * Sibling of `callResultIsPlainData`, which reads a call's result and so
+     * rejects primitives and empty objects; an argument of either is data.
+     */
+    private argumentCanReceive;
     /**
      * Scan a handler function body for the FIRST request-body read that carries a
      * type, and return that type's structural text — or null when the body holds