carrick 0.3.105 → 0.3.107

package/sidecar/dist/src/retype.js

@@ -25,6 +25,8 @@
  * project other requests read is the project the scan loaded.
  */
 import { Node, SyntaxKind, ts } from 'ts-morph';
+import { readsResponseStatus, statusesIn, SUCCEEDED, testsOnPath, } from './failure-path.js';
+import { lineIndex } from './line-index.js';
 import { fileDiagnostics } from './unwidened.js';
 /** Names appended to a file that is not ours carry this prefix. */
 const PREFIX = '__carrick_';
@@ -688,124 +690,71 @@ function responseTest(read) {
     return (node) => Node.isIdentifier(node) && node.getSymbol() === symbol;
 }
 /**
- * Which side of a test of the response's status `node` runs on: inside a
- * branch of one, or after an `if (test) return/throw` that leaves the rest of
- * the block to the other side. `undefined` when no test decides it.
+ * Whether `node` sits on the response's error path (`'failure'`), on a path
+ * whose status tests do not say (`'unclear'`), or where the producer's body
+ * is read (`undefined`, also when no test of the response is on its path).
+ *
+ * The tests on the path are read as failure-path.ts reads them, each as the
+ * statuses that take the side `node` is on, and taken together. On top of
+ * that reading, in this order:
+ *
+ *  - no success status reaches `node`: the error path;
+ *  - a test lets through every status but one success status that carries a
+ *    body (the side of `res.status === 200` the read after an early return on
+ *    it is on): the error path. This is the consumer's own reading of that
+ *    test, kept even when only success statuses get that far, because the
+ *    read there is not the body the source singled out;
+ *  - no status from 400 up reaches `node`: the producer's body;
+ *  - a `switch` on the status, or a test the reading cannot follow exactly
+ *    (`res.status === OK`, `res.ok || retry`), is on the path: unclear;
+ *  - the tests take away a success status that carries a body
+ *    (`res.status === 200 || res.status === 404`, `res.status > 200`):
+ *    unclear;
+ *  - otherwise they took away only error statuses, or statuses that carry no
+ *    content (carrick#1813: the retype only runs against a producer that
+ *    publishes a body, and that body never arrives with a 204 or 205), and
+ *    `node` is where the body is read, as it is with no test at all.
  */
 function sideOf(node, isResponse) {
-    let found;
-    const note = (side) => {
-        if (side === 'failure' || found === 'failure')
-            found = 'failure';
-        else if (side === 'unclear' || found === 'unclear')
-            found = 'unclear';
-        else
-            found = side ?? found;
-    };
-    for (let child = node, parent = node.getParent(); parent; child = parent, parent = parent.getParent()) {
-        if (Node.isIfStatement(parent) && child !== parent.getExpression()) {
-            note(branchSide(parent.getExpression(), child === parent.getThenStatement(), isResponse));
-        }
-        else if (Node.isConditionalExpression(parent) && child !== parent.getCondition()) {
-            note(branchSide(parent.getCondition(), child === parent.getWhenTrue(), isResponse));
-        }
-        else if (Node.isCaseClause(parent) || Node.isDefaultClause(parent)) {
-            const swtch = parent.getParent()?.getParent();
-            if (swtch && Node.isSwitchStatement(swtch) && testsResponse(swtch.getExpression(), isResponse)) {
-                note('unclear');
-            }
-        }
-        if (Node.isBlock(parent) || Node.isSourceFile(parent) || Node.isCaseClause(parent)) {
-            for (const statement of parent.getStatements()) {
-                if (statement === child)
-                    break;
-                if (Node.isIfStatement(statement) &&
-                    !statement.getElseStatement() &&
-                    exits(statement.getThenStatement())) {
-                    note(branchSide(statement.getExpression(), false, isResponse));
-                }
-            }
-        }
-    }
-    return found;
+    const sides = testsOnPath(node, undefined, isResponse);
+    const switched = node.getAncestors().some((ancestor) => {
+        if (!Node.isCaseClause(ancestor) && !Node.isDefaultClause(ancestor))
+            return false;
+        const statement = ancestor.getParent()?.getParent();
+        return (!!statement &&
+            Node.isSwitchStatement(statement) &&
+            readsResponseStatus(statement.getExpression(), isResponse));
+    });
+    if (sides.length === 0 && !switched)
+        return undefined;
+    const admitted = (status) => sides.every((side) => side.admits(status));
+    const reaching = statusesIn(admitted);
+    if (!reaching.some(SUCCEEDED))
+        return 'failure';
+    if (sides.some((side) => singlesOutABody(side.admits)))
+        return 'failure';
+    if (!reaching.some((status) => status >= 400))
+        return undefined;
+    if (switched || sides.some((side) => side.inexact))
+        return 'unclear';
+    if (statusesIn((status) => !admitted(status)).some(carriesBody))
+        return 'unclear';
+    return undefined;
+}
+/** `statuses` is every status but one success status that carries a body. */
+function singlesOutABody(statuses) {
+    const excluded = statusesIn((status) => !statuses(status));
+    return excluded.length === 1 && carriesBody(excluded[0]);
 }
-function branchSide(condition, whenTrue, isResponse) {
-    const ok = okWhenTrue(condition, isResponse);
-    if (ok === undefined || ok === 'unclear')
-        return ok;
-    return ok === whenTrue ? 'success' : 'failure';
+/** A success status whose response can carry the producer's body. */
+function carriesBody(status) {
+    return SUCCEEDED(status) && !NO_CONTENT_STATUSES.has(status);
 }
 /**
  * The success statuses whose response carries no content (RFC 9110: 204 No
  * Content, 205 Reset Content).
  */
 const NO_CONTENT_STATUSES = new Set([204, 205]);
-/**
- * Whether `condition` being true means the response succeeded: `res.ok`,
- * `res.status === 200`, `res.status !== 200`, `res.status >= 400` and their
- * negations. Any other test of the response is `'unclear'`; a condition that does not
- * test the response is `undefined`.
- *
- * An equality or inequality with a no-content status is `undefined` too
- * (carrick#1813). The retype only runs against a producer that publishes a
- * response body, and that body never arrives with a 204 or 205, so
- * `if (res.status === 204) return null` only takes away a status the body
- * cannot come with. The read after it sits where a read no test decides
- * sits, not on the error path.
- */
-function okWhenTrue(condition, isResponse) {
-    let e = condition;
-    while (Node.isParenthesizedExpression(e))
-        e = e.getExpression();
-    if (Node.isPrefixUnaryExpression(e) && e.getOperatorToken() === SyntaxKind.ExclamationToken) {
-        const inner = okWhenTrue(e.getOperand(), isResponse);
-        return typeof inner === 'boolean' ? !inner : inner;
-    }
-    if (isMember(e, 'ok', isResponse))
-        return true;
-    if (Node.isBinaryExpression(e)) {
-        const op = e.getOperatorToken().getKind();
-        const [left, right] = [e.getLeft(), e.getRight()];
-        const value = isMember(left, 'status', isResponse) && Node.isNumericLiteral(right)
-            ? right.getLiteralValue()
-            : undefined;
-        if (value !== undefined) {
-            const success = value >= 200 && value < 300;
-            const noContent = NO_CONTENT_STATUSES.has(value);
-            switch (op) {
-                case SyntaxKind.EqualsEqualsEqualsToken:
-                case SyntaxKind.EqualsEqualsToken:
-                    return noContent ? undefined : success;
-                case SyntaxKind.ExclamationEqualsEqualsToken:
-                case SyntaxKind.ExclamationEqualsToken:
-                    return noContent ? undefined : !success;
-                case SyntaxKind.GreaterThanEqualsToken:
-                    if (value >= 300)
-                        return false;
-                    break;
-            }
-            return 'unclear';
-        }
-    }
-    return testsResponse(e, isResponse) ? 'unclear' : undefined;
-}
-function isMember(node, name, isResponse) {
-    return (Node.isPropertyAccessExpression(node) && node.getName() === name && isResponse(node.getExpression()));
-}
-/** The expression reads the response's `ok` or `status`. */
-function testsResponse(node, isResponse) {
-    return [node, ...node.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)].some((n) => isMember(n, 'ok', isResponse) || isMember(n, 'status', isResponse));
-}
-/** A statement that always leaves the function. */
-function exits(statement) {
-    if (Node.isReturnStatement(statement) || Node.isThrowStatement(statement))
-        return true;
-    if (Node.isBlock(statement)) {
-        const last = statement.getStatements().at(-1);
-        return !!last && exits(last);
-    }
-    return false;
-}
 /** `node.json()` with no arguments, where `node` is the receiver. */
 function bodyReadOn(node) {
     const access = node.getParent();
@@ -894,22 +843,3 @@ function mapBack(pos, edits) {
     }
     return { kind: 'original', pos: pos - shift };
 }
-/** 1-based line of an original-file position. */
-function lineIndex(text) {
-    const starts = [0];
-    for (let i = 0; i < text.length; i++)
-        if (text[i] === '\n')
-            starts.push(i + 1);
-    return (pos) => {
-        let lo = 0;
-        let hi = starts.length - 1;
-        while (lo < hi) {
-            const mid = (lo + hi + 1) >> 1;
-            if (starts[mid] <= pos)
-                lo = mid;
-            else
-                hi = mid - 1;
-        }
-        return lo + 1;
-    };
-}

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

@@ -63,6 +63,11 @@ export interface TypeInferrerOptions {
      */
     unwidenedBudgetMs?: number;
 }
+/**
+ * Called each time an `infer` batch is done with one of its requests,
+ * whatever that request answered: skipped, refused, failed or inferred.
+ */
+export type InferRequestDone = () => void;
 /**
  * TypeInferrer - Extracts types from source code, both explicit and inferred
  *
@@ -94,9 +99,15 @@ export declare class TypeInferrer {
      *
      * @param requests - Array of inference requests
      * @param extractionConfig - Agent-generated extraction config for payload unwrapping
+     * @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): InferResult;
+    infer(requests: InferRequestItem[], extractionConfig?: ExtractionConfig, onRequestDone?: InferRequestDone): InferResult;
+    /**
+     * carrick#1836: list on `result` the declarations behind the names its text
+     * prints that the request's file cannot resolve (`PrintedTypes.namesIn`).
+     */
+    private recordPrintedNames;
     /**
      * carrick#1516: read each response inference again with the literals on its
      * handler's path marked `as const`, and record the narrower type the handler
@@ -257,6 +268,25 @@ export declare class TypeInferrer {
      */
     private receivingCallOf;
     private inferCallResult;
+    /**
+     * The terminal of a call's def-use walk is a zero-argument `.text()` read of
+     * the call's own result (carrick#1842): on its binding (`res.text()`,
+     * through a declaration, `await` or a cast), or in the callback a `then` on
+     * the call hands the response to (`fetch(u).then((res) => res.text())`).
+     */
+    private textReadAtTerminal;
+    /** `call` is `<receiver>.text()` with no arguments, and `accept` takes its receiver. */
+    private isTextReadOf;
+    /**
+     * The call's resolved signature, at this site, types a member of an object
+     * argument as exactly the literal `'text'`, and the source passes that
+     * literal there (carrick#1842). That is how a request library lets a caller
+     * choose a text body from the formats it offers (`{ type: 'text' }`): a
+     * generic config instantiated by the literal, or an overload taken by it.
+     * A member typed as a wider union (`kind: 'text' | 'image'`) chooses no
+     * format, and no member name is read.
+     */
+    private callChoosesTextBody;
     /**
      * What the source states the body read at `terminal` to be, when the type
      * `extractExplicitTypeFromAncestor` printed for it is stated AT the read
@@ -326,12 +356,54 @@ export declare class TypeInferrer {
      */
     private resultCarrierPayload;
     /**
-     * `Future<T>` -> `T` for a promise-like of the source's own making, read off
-     * the await protocol rather than a name: a `then` whose first parameter is a
-     * callback, whose own first parameter is the value awaiting it yields.
-     * `Promise` and `PromiseLike` are peeled by `unwrapPromiseType` before this.
+     * The shape test of `resultCarrierPayload`: the carrier `type` is, once a
+     * promise-like around it is peeled, and the type arguments a branch of it
+     * holds as a member. `undefined` when `type` is not a carrier.
+     */
+    private resultCarrierArguments;
+    /**
+     * The decided abstain of a call whose result carries transport the
+     * service's wrapper rules verify and read no payload out of (carrick#1841,
+     * carrick#1843): `unknown` with `machinery_envelope` at the root and no
+     * anchor. The root reason is what keeps the capture's own locator from
+     * re-reading the raw call (`inference_decided_no_contract`,
+     * engine/type_compat_v2.rs).
+     */
+    private transportAbstain;
+    /**
+     * `Future<T>` -> `T` for a thenable, read off the await protocol rather
+     * than a name: a `then` whose first parameter is a callback, whose own
+     * first parameter is the value awaiting it yields. `Promise` and
+     * `PromiseLike` are peeled by `unwrapPromiseType` before this.
+     *
+     * The callback is read through `null` and `undefined` (carrick#1877). A
+     * `then` of the source's own making declares `(value: T) => void`; the
+     * platform's declares `onfulfilled?: ((value: T) => ...) | null`, and that
+     * is the `then` a subclass of `Promise` inherits. Read as written, an
+     * optional, nullable callback has no call signature, and the subclass was
+     * not seen as a thenable at all.
+     *
+     * A `then` that cannot be called, or whose first parameter is no callback,
+     * is no protocol, and the type is returned as it is.
+     *
+     * The compiler's own awaited type arbitrates. This walk reads the first
+     * signature of `then`; the language reads all of them. Where awaiting the
+     * type and awaiting what this walk found are not the same thing to the
+     * compiler (an overloaded `then` whose first signature is not the one
+     * `await` takes), the walk did not read the protocol, and the type is
+     * returned as it is rather than published as a guess.
      */
     private unwrapThenableType;
+    /** The value `then`'s first signature hands its callback, read until it stops changing. */
+    private firstThenValue;
+    /**
+     * What `await` yields for `type` where the names do not say: `type` is,
+     * once `Promise` and `PromiseLike` are peeled, a thenable by the protocol
+     * (a subclass of `Promise`, a class with a `then` of its own). `undefined`
+     * where the names say it all or `type` is no thenable, so a caller keeps
+     * the reading it had (carrick#1877).
+     */
+    private awaitedBeyondPromise;
     /**
      * The platform's error shape, in full: `name` and `message` strings AND a
      * `stack`, which is what the `Error` interface declares and every subclass
@@ -349,10 +421,10 @@ export declare class TypeInferrer {
      * `query.data`, `envelope` in `envelope.list[0]` — or `undefined` when the
      * identifier names the value itself.
      *
-     * A member CALL is not a projection: `res.text()` yields a body rather than
+     * A member CALL is not a projection: `res.blob()` yields a body rather than
      * a part of one, and what it returns stays the walk's business. The
-     * zero-argument json body read has its own branch and is taken before this
-     * is asked.
+     * zero-argument json and text body reads have their own branch and are
+     * taken before this is asked.
      */
     private projectionOnReceiver;
     /**
@@ -431,6 +503,22 @@ export declare class TypeInferrer {
      * about the body and is skipped.
      */
     private castsOfUnreadParameter;
+    /**
+     * The zero-argument whole-body read taken in place on the value `callExpr`
+     * yields, or `undefined` (carrick#1851): `(await fetch(url)).text()`. The
+     * receiver is the call itself, through the wrappers that leave a value as
+     * it is (parentheses, `await`, `!`), so it is the same read
+     * `bodyReadOnReceiver` finds on a binding of that value. A call that is not
+     * awaited first is read the same way: a request that is a promise and reads
+     * its own body (`send(url).json()`) yields the body from that read too.
+     */
+    private bodyReadOnCallValue;
+    /**
+     * 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.
+     */
     private bodyReadOnReceiver;
     private collectDefUseNodes;
     private expressionUsesNames;
@@ -488,12 +576,27 @@ export declare class TypeInferrer {
      * Try to unwrap a type using a single ExtractionRule.
      */
     private tryUnwrapWithRule;
+    /**
+     * The names `type` goes by, own symbol first (carrick#1843).
+     *
+     * `type Task<A> = __Task<A>` has the class's symbol and arguments, and the
+     * alias's beside them. `type Reply<T> = { ... }` has the anonymous `__type`
+     * with no arguments of its own. `type Outcome<A, E> = Done<A, E> |
+     * Failed<A, E>` has no symbol of its own at all. In each, the alias and its
+     * arguments are what a rule naming `Task`, `Reply` or `Outcome` describes.
+     */
+    private wrapperReadings;
     /**
      * Extract the payload type from a matched wrapper. Returns null when the
      * rule matched the wrapper but no payload is recoverable from generics or
      * property paths — the caller decides what a payload-less match means
      * (verified machinery collapses to `unknown` after every rule has run;
      * a name-only match leaves the type untouched).
+     *
+     * `payloadGenericIndex` counts the arguments of `reading`, the name the
+     * rule matched (carrick#1843): an alias is free to order its parameters
+     * differently from the type it stands for, so the same index into the
+     * other list is a different argument.
      */
     private extractPayloadFromWrapper;
     /**
@@ -890,11 +993,19 @@ export declare class TypeInferrer {
     /**
      * Declaration file (absolute path) of the anchor symbol
      * `primaryTypeSymbol` reports for this type, or `undefined` when the type
-     * has no user-facing anchor or no source declaration. The scanner's
-     * pub/sub two-anchor arbitration (carrick#413) uses this to re-aim a
-     * demoted explicit bundle request: the bundler resolves a `SymbolRequest`
-     * only against declarations IN its `source_file`, so the request must
-     * point at the file that actually declares the tsc-witnessed payload type.
+     * has no user-facing anchor or no source declaration. Every path that
+     * reports the symbol reports this beside it (carrick#1819): it is where a
+     * reader finds the type an anchor names. The scanner's pub/sub two-anchor
+     * arbitration (carrick#413) also uses it to re-aim a demoted explicit
+     * bundle request: the bundler resolves a `SymbolRequest` only against
+     * declarations IN its `source_file`, so the request must point at the file
+     * that actually declares the tsc-witnessed payload type.
+     *
+     * The declarations read are those of the type's own symbol, so a name
+     * imported through a barrel reports the file that declares it, and a name
+     * two files declare reports the one this type resolves to. A declaration in
+     * an installed package or a TypeScript lib is reported as it is found, as
+     * an absolute path; what a reader is shown for it is the scanner's call.
      *
      * Only declaration kinds the bundler's `validateSymbols` can resolve
      * (interface, type alias, class, enum, function, variable) count. A