carrick 0.3.104 → 0.3.106

package/sidecar/dist/src/printed-names.js

@@ -0,0 +1,186 @@
+/**
+ * carrick#1836: what each bare name in an inference's printed text meant.
+ *
+ * The structural printer (`type-structural-expander.ts`) hands some subtrees
+ * back to the compiler's own print with no enclosing declaration, and that
+ * print writes every named type by its bare name: a database client's row,
+ * which is a library's mapped type, prints `{ status: EntityStatus; ... }`.
+ * The file a request names often never imports `EntityStatus`, so the text
+ * names nothing where it is read (TS2304), and the member reads `any` in the
+ * capture's surface.
+ *
+ * The compiler knew the symbol when it printed the name, and only then. So
+ * every type print made while an inference runs is noted (`notePrintedType`),
+ * and when it ends (`PrintedTypes.namesIn`) the names its text prints that the
+ * request's file cannot resolve are looked up in those prints: the node
+ * builder gives each name it writes the symbol it wrote it for. Each such
+ * symbol is recorded as the module that declares it and its export path
+ * there. A name printed for two declarations is recorded twice, and the
+ * reader of the record decides what an ambiguous name means.
+ *
+ * Only the prints whose text writes such a name are read back, and only when
+ * the inference's text has one, so an inference whose names all resolve costs
+ * no more than keeping the list.
+ */
+import { ts } from 'ts-morph';
+/** The prints of the inference running now, when one is recording. */
+let recording;
+/**
+ * Note a type the compiler printed as `text`, so the inference running now can
+ * tell what the names in that print meant. Does nothing outside a recording.
+ */
+export function notePrintedType(type, enclosing, text) {
+    recording?.push({ type: type.compilerType, enclosing: enclosing?.compilerNode, text });
+}
+/**
+ * Same flags the printers pass `typeToString` (`NoTruncation`, `InTypeAlias`),
+ * so the node read back is the one that was printed.
+ */
+const NODE_FLAGS = ts.NodeBuilderFlags.NoTruncation | ts.NodeBuilderFlags.InTypeAlias | ts.NodeBuilderFlags.IgnoreErrors;
+const REFERENCE_MEANING = ts.SymbolFlags.Type | ts.SymbolFlags.Namespace | ts.SymbolFlags.Alias;
+/** The type prints one inference made. */
+export class PrintedTypes {
+    prints = [];
+    /** Run `read`, noting every type it prints. */
+    during(read) {
+        const outer = recording;
+        recording = this.prints;
+        try {
+            return read();
+        }
+        finally {
+            recording = outer;
+        }
+    }
+    /**
+     * The declarations behind each name `texts` print that `source` does not
+     * resolve, sorted, one entry per distinct declaration. `checker` must be
+     * the one the prints were made with: call this before the program changes.
+     */
+    namesIn(texts, source, checker) {
+        const wanted = new Set();
+        for (const text of texts) {
+            for (const name of referencedNames(text)) {
+                if (!checker.resolveName(name, source, REFERENCE_MEANING, false))
+                    wanted.add(name);
+            }
+        }
+        if (wanted.size === 0)
+            return [];
+        // Only a print whose text writes one of the names can say what it meant.
+        const alternatives = [...wanted].map((name) => name.replace(/\$/g, '\\$')).join('|');
+        const writes = new RegExp(`(?<![\\w$.])(?:${alternatives})(?![\\w$])`);
+        const found = new Map();
+        const identities = new Map();
+        const visited = new Map();
+        for (const { type, enclosing, text } of this.prints) {
+            if (!writes.test(text))
+                continue;
+            const at = visited.get(type) ?? new Set();
+            if (at.has(enclosing))
+                continue;
+            visited.set(type, at.add(enclosing));
+            let node;
+            try {
+                node = checker.typeToTypeNode(type, enclosing, NODE_FLAGS);
+            }
+            catch {
+                continue;
+            }
+            const visit = (current) => {
+                if (ts.isTypeReferenceNode(current)) {
+                    const id = leftmost(current.typeName);
+                    const name = ts.idText(id);
+                    const symbol = wanted.has(name) ? symbolOf(id, checker) : undefined;
+                    if (symbol) {
+                        if (!identities.has(symbol))
+                            identities.set(symbol, identityOf(symbol, checker));
+                        const identity = identities.get(symbol);
+                        if (identity) {
+                            found.set(`${name}\0${identity.file}\0${identity.export_path.join('.')}`, { name, ...identity });
+                        }
+                    }
+                }
+                ts.forEachChild(current, visit);
+            };
+            if (node)
+                visit(node);
+        }
+        return [...found.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([, entry]) => entry);
+    }
+}
+function leftmost(name) {
+    return ts.isIdentifier(name) ? name : leftmost(name.left);
+}
+/**
+ * The leftmost names of the type references `text` makes, less the type
+ * parameters the text declares itself (`[K in ...]`, `infer U`).
+ */
+function referencedNames(text) {
+    const parsed = ts.createSourceFile('printed.ts', `type __Printed = ${text};`, ts.ScriptTarget.Latest, true);
+    const names = new Set();
+    const declared = new Set();
+    const visit = (node) => {
+        if (ts.isTypeParameterDeclaration(node))
+            declared.add(node.name.text);
+        if (ts.isTypeReferenceNode(node))
+            names.add(ts.idText(leftmost(node.typeName)));
+        ts.forEachChild(node, visit);
+    };
+    visit(parsed);
+    for (const name of declared)
+        names.delete(name);
+    names.delete('__Printed');
+    return names;
+}
+/**
+ * The symbol a printed name was written for. The node builder sets it on
+ * every identifier it creates (`symbol` is not in the public typings); a name
+ * it copied from source carries none, and is read at its original node.
+ */
+function symbolOf(id, checker) {
+    const written = id.symbol;
+    if (written)
+        return written;
+    const original = ts.getOriginalNode(id);
+    return original !== id && original.parent ? checker.getSymbolAtLocation(original) : undefined;
+}
+/**
+ * The module that declares `symbol`'s type and the export path to it there,
+ * or undefined for a type no module export reaches: a global, a type
+ * parameter, a declaration a function body holds, a module itself.
+ */
+function identityOf(symbol, checker) {
+    const resolve = (s) => s.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(s) : s;
+    const target = resolve(symbol);
+    if (!(target.flags & (ts.SymbolFlags.Type | ts.SymbolFlags.Namespace)) ||
+        target.flags & ts.SymbolFlags.TypeParameter) {
+        return undefined;
+    }
+    const declaration = target.declarations?.[0];
+    if (!declaration || ts.isSourceFile(declaration))
+        return undefined;
+    const file = declaration.getSourceFile();
+    const moduleSymbol = checker.getSymbolAtLocation(file);
+    if (!moduleSymbol)
+        return undefined;
+    const direct = checker.getExportsOfModule(moduleSymbol).filter((e) => resolve(e) === target);
+    if (direct.length > 0) {
+        const chosen = direct.find((e) => e.getName() === target.getName()) ?? direct[0];
+        return { file: file.fileName, export_path: [chosen.getName()] };
+    }
+    // A namespace member: `"<module>".Billing.Kind`, checked step by step.
+    const qualified = checker.getFullyQualifiedName(target);
+    const close = qualified.startsWith('"') ? qualified.indexOf('"', 1) : -1;
+    if (close < 0)
+        return undefined;
+    const exportPath = qualified.slice(close + 2).split('.');
+    let current = moduleSymbol;
+    for (const part of exportPath) {
+        const next = current
+            ? checker.getExportsOfModule(current).find((e) => e.getName() === part)
+            : undefined;
+        current = next && resolve(next);
+    }
+    return current === target ? { file: file.fileName, export_path: exportPath } : undefined;
+}

package/sidecar/dist/src/retype.js

@@ -25,6 +25,7 @@
  * 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 { fileDiagnostics } from './unwidened.js';
 /** Names appended to a file that is not ours carry this prefix. */
 const PREFIX = '__carrick_';
@@ -688,111 +689,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;
 }
-function branchSide(condition, whenTrue, isResponse) {
-    const ok = okWhenTrue(condition, isResponse);
-    if (ok === undefined || ok === 'unclear')
-        return ok;
-    return ok === whenTrue ? 'success' : 'failure';
+/** `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]);
+}
+/** A success status whose response can carry the producer's body. */
+function carriesBody(status) {
+    return SUCCEEDED(status) && !NO_CONTENT_STATUSES.has(status);
 }
 /**
- * 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`.
+ * The success statuses whose response carries no content (RFC 9110: 204 No
+ * Content, 205 Reset Content).
  */
-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;
-            switch (op) {
-                case SyntaxKind.EqualsEqualsEqualsToken:
-                case SyntaxKind.EqualsEqualsToken:
-                    return success;
-                case SyntaxKind.ExclamationEqualsEqualsToken:
-                case SyntaxKind.ExclamationEqualsToken:
-                    return !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;
-}
+const NO_CONTENT_STATUSES = new Set([204, 205]);
 /** `node.json()` with no arguments, where `node` is the receiver. */
 function bodyReadOn(node) {
     const access = node.getParent();

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

@@ -97,6 +97,11 @@ export declare class TypeInferrer {
      * @returns InferResult with inferred types or errors
      */
     infer(requests: InferRequestItem[], extractionConfig?: ExtractionConfig): 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 +262,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
@@ -349,10 +373,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,9 +455,17 @@ export declare class TypeInferrer {
      * about the body and is skipped.
      */
     private castsOfUnreadParameter;
+    /**
+     * The zero-argument whole-body read that takes `identifier` 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;
+    /** `expr` is a use of a tracked name, or contains one. */
+    private usesTrackedNames;
     private isIdentifierUsage;
     private isInFunctionScope;
     /**