carrick 0.3.105 → 0.3.106

package/sidecar/dist/src/type-inferrer.js

@@ -20,6 +20,7 @@
 import * as path from 'node:path';
 import { Node, SyntaxKind, ts, } from 'ts-morph';
 import { validateInferRequestItem } from './validators.js';
+import { notePrintedType, PrintedTypes } from './printed-names.js';
 import { externalImportsOf, isExternalOrigin } from './origin.js';
 import { reachedOnlyOnFailure } from './failure-path.js';
 import { addedDiagnostics, applyInsertions, fileDiagnostics, literalInsertions, mapBack, mapForward, normalise, pathOf, } from './unwidened.js';
@@ -220,6 +221,14 @@ const REQUEST_BODY_PARTS = new Set(['json', 'form', 'body']);
  * these names; a type parameter alone also types response modes and fallbacks.
  */
 const BODY_MEMBER_NAMES = new Set(['data', 'body', 'json']);
+/**
+ * The zero-argument reads that take the WHOLE body out of a transport response
+ * (the platform `Response` and the clients that copy its shape): parsed as
+ * JSON, or as raw text (carrick#1842).
+ */
+const WHOLE_BODY_READS = new Set(['json', 'text']);
+/** The body format a caller names to read a response as raw text (carrick#1842). */
+const RAW_TEXT_FORMAT = 'text';
 /**
  * Print a `Type` to its string form WITHOUT the compiler's default truncation.
  *
@@ -230,7 +239,18 @@ const BODY_MEMBER_NAMES = new Set(['data', 'body', 'json']);
  */
 const TYPE_TEXT_FLAGS = ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.InTypeAlias;
 function typeText(type, enclosingNode) {
-    return type.getText(enclosingNode, TYPE_TEXT_FLAGS);
+    const text = type.getText(enclosingNode, TYPE_TEXT_FLAGS);
+    notePrintedType(type, enclosingNode, text);
+    return text;
+}
+/**
+ * `text` is `string`, alone or beside `null` and `undefined` in either order:
+ * the only payload a raw-text read publishes (carrick#1842).
+ */
+function isBareStringText(text) {
+    const members = text.split('|').map((member) => member.trim());
+    return (members.includes('string') &&
+        members.every((member) => member === 'string' || member === 'null' || member === 'undefined'));
 }
 /**
  * How long the unwidened reading of one batch may take by default. The
@@ -310,8 +330,14 @@ export class TypeInferrer {
                     errors.push(`Invalid infer item at ${request.file_path}:${loc} (${request.infer_kind}): ${itemError}`);
                     continue;
                 }
-                const result = this.inferSingle(request, extractionConfig);
+                // carrick#1836: what the names the published text prints meant, read
+                // while the program the prints were made in is still the project's.
+                // The unwidened re-read below records nothing: it prints the same
+                // node, and its reading has a budget.
+                const prints = new PrintedTypes();
+                const result = prints.during(() => this.inferSingle(request, extractionConfig));
                 if (result) {
+                    this.recordPrintedNames(result, request, prints);
                     inferredTypes.push(result);
                     if (request.infer_kind === 'response_body' || request.infer_kind === 'function_return') {
                         responses.push({ request, result });
@@ -341,6 +367,18 @@ export class TypeInferrer {
             errors: errors.length > 0 ? errors : undefined,
         };
     }
+    /**
+     * carrick#1836: list on `result` the declarations behind the names its text
+     * prints that the request's file cannot resolve (`PrintedTypes.namesIn`).
+     */
+    recordPrintedNames(result, request, prints) {
+        const sourceFile = this.getSourceFile(request.file_path);
+        if (!sourceFile)
+            return;
+        const printedNames = prints.namesIn([result.type_string], sourceFile.compilerNode, this.project.getTypeChecker().compilerObject);
+        if (printedNames.length > 0)
+            result.printed_names = printedNames;
+    }
     /**
      * 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
@@ -1209,16 +1247,55 @@ export class TypeInferrer {
         const carrierCandidate = unwrapResult.wasUnwrapped || explicitType
             ? undefined
             : this.resultCarrierPayload(returnType, terminalNode, use.projections, `${request.file_path}:${request.line_number}`);
+        // carrick#1841: what the carrier holds goes through the service's wrapper
+        // rules before it is published, as the call's own result did. The carrier
+        // is found by its shape, so what it holds can still be a library's
+        // envelope: a request library answers `Task<Outcome<Reply<T>, E>>`, and
+        // `Reply<T>` is that library's response object, a status, a url and
+        // headers around the body. Where a rule reads a payload out of it, that
+        // payload is the body. Where a rule verifies it as the library's transport
+        // and reads nothing out of it, this site states no contract, and the
+        // transport object must not stand in for one: judged against a
+        // producer's body, every member it adds reads as a field the producer
+        // does not send.
+        //
+        // The abstain is decided, so it rides the row (`machinery_envelope` at the
+        // root, no anchor). A plain `null` is re-read by the capture's own
+        // locator, which would resolve the raw call and publish the carrier.
+        const carrierUnwrap = carrierCandidate
+            ? this.unwrapTypeWithConfig(carrierCandidate, terminalNode, extractionConfig)
+            : undefined;
+        if (carrierCandidate &&
+            carrierUnwrap?.wasUnwrapped &&
+            carrierUnwrap.typeString.trim() === 'unknown') {
+            const carried = typeText(carrierCandidate, terminalNode);
+            this.log(`Call result at ${request.file_path}:${request.line_number} carries ${carried}, which ` +
+                "the service's wrapper rules verify as transport and read no payload out of; this " +
+                'site states no response contract');
+            const abstain = this.createInferredType(request, 'unknown', false, this.getNodeLocation(callExpr));
+            abstain.any_provenance = [
+                {
+                    path: '',
+                    kind: 'unknown',
+                    reason: 'machinery_envelope',
+                    detail: "what this call's result carries is transport that the service's wrapper rules " +
+                        'verify and read no payload out of (a library response object around the body), ' +
+                        'so this site states no response contract',
+                },
+            ];
+            return abstain;
+        }
+        const carried = carrierUnwrap?.wasUnwrapped && carrierUnwrap.payloadType
+            ? carrierUnwrap.payloadType
+            : carrierCandidate;
         // The payload rides the row as its own MEMBERS, never as its bare name
         // (#257): `derive_capture_anchors` turns a usable inference into a literal
         // capture anchor, and a bare name is out of scope where the surface
         // declares the alias, so it would decay to a top type and publish nothing
         // — trading a wrong answer for no answer. Where the payload carries no
         // member shape to print, the carrier keeps its own answer.
-        const carrierText = carrierCandidate
-            ? this.structuralTextFromType(carrierCandidate, terminalNode)
-            : null;
-        const carrierPayload = carrierText ? carrierCandidate : undefined;
+        const carrierText = carried ? this.structuralTextFromType(carried, terminalNode) : null;
+        const carrierPayload = carrierText ? carried : undefined;
         if (carrierPayload && carrierText) {
             typeString = carrierText;
         }
@@ -1346,8 +1423,101 @@ export class TypeInferrer {
         if (statedBody) {
             inferred.stated_body = statedBody;
         }
+        // carrick#1842: `string` cannot tell a body read as raw text from a JSON
+        // body that is a string, and raw text states no structural contract. The
+        // row says which it is, so the check phase can read the pair unverifiable
+        // instead of comparing `string` with the other side's body.
+        if (isBareStringText(typeString) &&
+            (this.textReadAtTerminal(callExpr, terminalNode) || this.callChoosesTextBody(callExpr))) {
+            inferred.raw_text_read = true;
+        }
         return inferred;
     }
+    /**
+     * 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())`).
+     */
+    textReadAtTerminal(callExpr, terminal) {
+        const value = Node.isVariableDeclaration(terminal) ? terminal.getInitializer() : terminal;
+        const read = value ? this.unwrapExpressionNode(value) : undefined;
+        if (!read || !Node.isCallExpression(read))
+            return false;
+        const callResult = this.unwrapPromiseType(callExpr.getType()).compilerType;
+        if (this.isTextReadOf(read, (receiver) => receiver === callExpr ||
+            this.unwrapPromiseType(receiver.getType()).compilerType === callResult)) {
+            return true;
+        }
+        const then = read.getExpression();
+        if (!Node.isPropertyAccessExpression(then) ||
+            then.getName() !== 'then' ||
+            this.unwrapExpressionNode(then.getExpression()) !== callExpr) {
+            return false;
+        }
+        const callback = read.getArguments()[0];
+        if (!callback || (!Node.isArrowFunction(callback) && !Node.isFunctionExpression(callback))) {
+            return false;
+        }
+        const param = callback.getParameters()[0]?.getNameNode();
+        if (!param || !Node.isIdentifier(param))
+            return false;
+        const returned = this.returnedExpressions(callback);
+        const inner = returned.length === 1 ? this.unwrapExpressionNode(returned[0]) : undefined;
+        return (!!inner &&
+            Node.isCallExpression(inner) &&
+            this.isTextReadOf(inner, (receiver) => Node.isIdentifier(receiver) && receiver.getSymbol() === param.getSymbol()));
+    }
+    /** `call` is `<receiver>.text()` with no arguments, and `accept` takes its receiver. */
+    isTextReadOf(call, accept) {
+        const access = call.getExpression();
+        return (Node.isPropertyAccessExpression(access) &&
+            access.getName() === RAW_TEXT_FORMAT &&
+            call.getArguments().length === 0 &&
+            accept(this.unwrapExpressionNode(access.getExpression())));
+    }
+    /**
+     * 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.
+     */
+    callChoosesTextBody(callExpr) {
+        const checker = this.project.getTypeChecker().compilerObject;
+        let signature;
+        try {
+            signature = checker.getResolvedSignature(callExpr.compilerNode);
+        }
+        catch {
+            return false;
+        }
+        if (!signature || signature.parameters.length === 0)
+            return false;
+        return callExpr.getArguments().some((argument, index) => {
+            if (!Node.isObjectLiteralExpression(argument))
+                return false;
+            const parameter = signature.parameters[Math.min(index, signature.parameters.length - 1)];
+            const parameterType = checker.getTypeOfSymbolAtLocation(parameter, callExpr.compilerNode);
+            return argument.getProperties().some((property) => {
+                if (!Node.isPropertyAssignment(property))
+                    return false;
+                const value = property.getInitializer();
+                if (!value ||
+                    !(Node.isStringLiteral(value) || Node.isNoSubstitutionTemplateLiteral(value)) ||
+                    value.getLiteralValue() !== RAW_TEXT_FORMAT) {
+                    return false;
+                }
+                const member = checker.getPropertyOfType(parameterType, property.getName());
+                if (!member)
+                    return false;
+                const declared = checker.getNonNullableType(checker.getTypeOfSymbolAtLocation(member, callExpr.compilerNode));
+                return declared.isStringLiteral() && declared.value === RAW_TEXT_FORMAT;
+            });
+        });
+    }
     /**
      * What the source states the body read at `terminal` to be, when the type
      * `extractExplicitTypeFromAncestor` printed for it is stated AT the read
@@ -1459,10 +1629,12 @@ export class TypeInferrer {
             symbol = symbol.getAliasedSymbol() ?? symbol;
         }
         const source = symbol?.getDeclarations()[0]?.getSourceFile().getFilePath();
+        const typeArguments = node.getTypeArguments().length;
         return {
             root: nameNode.getText(),
             ...(source ? { root_source: source } : {}),
             ...depthField,
+            ...(typeArguments > 0 ? { root_type_arguments: typeArguments } : {}),
         };
     }
     inferVariable(sourceFile, request, extractionConfig) {
@@ -1834,9 +2006,9 @@ export class TypeInferrer {
                     continue;
                 }
                 // The body a caller reads OUT of a transport response IS the payload
-                // of the call that produced it: `res.json()` on the tracked binding,
-                // with whatever `as T` the source states around it read by
-                // `extractExplicitTypeFromAncestor` below. A bare identifier never
+                // of the call that produced it: `res.json()` or `res.text()` on the
+                // tracked binding, with whatever `as T` the source states around it
+                // read by `extractExplicitTypeFromAncestor` below. A bare identifier never
                 // matches `expressionUsesNames` (it tests DESCENDANTS), so without
                 // this the body read is invisible to the def-use walk.
                 if (Node.isIdentifier(expr) && this.isIdentifierUsage(expr, currentNames)) {
@@ -2094,10 +2266,10 @@ export 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.
      */
     projectionOnReceiver(identifier) {
         const access = identifier.getParent();
@@ -2340,12 +2512,18 @@ export class TypeInferrer {
                 !this.leavesAPositionOpen(statedNode));
         });
     }
+    /**
+     * 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.
+     */
     bodyReadOnReceiver(identifier) {
         const access = identifier.getParent();
         if (!access ||
             !Node.isPropertyAccessExpression(access) ||
             access.getExpression() !== identifier ||
-            access.getName() !== 'json') {
+            !WHOLE_BODY_READS.has(access.getName())) {
             return undefined;
         }
         const call = access.getParent();

package/sidecar/dist/src/type-structural-expander.js

@@ -31,6 +31,7 @@
 import { ts } from 'ts-morph';
 import { canonicalizeUnionsInText, foldBooleanLiterals, } from './type-text-canonicalizer.js';
 import { isExternalOrigin } from './origin.js';
+import { notePrintedType } from './printed-names.js';
 /**
  * Bound on the structural-expansion recursion. Deep enough for every realistic
  * request/response shape; a backstop against pathological/recursive types the
@@ -385,8 +386,16 @@ function isLibraryType(type, origin) {
 export function namedText(type) {
     return canonicalizeUnionsInText(compilerText(type));
 }
-/** The compiler's print, with the two fallbacks. */
+/**
+ * The compiler's print, with the two fallbacks. The print writes names bare,
+ * whatever scope reads it, so it is noted for the inference (carrick#1836).
+ */
 function compilerText(type) {
+    const text = compilerPrint(type);
+    notePrintedType(type, undefined, text);
+    return text;
+}
+function compilerPrint(type) {
     try {
         return type.getText(undefined, ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.InTypeAlias);
     }

package/sidecar/dist/src/types.d.ts

@@ -823,6 +823,23 @@ export interface InferredType {
      * stated, or when the only annotation is further away than the read.
      */
     stated_body?: StatedBody;
+    /**
+     * carrick#1836: the declarations behind the names `type_string` prints that
+     * the request's file does not resolve. The printer writes names bare where
+     * no scope reads them, so this is the only record of what they meant. A
+     * name printed for two declarations is listed twice. Absent when there is
+     * nothing to list.
+     */
+    printed_names?: PrintedName[];
+    /**
+     * carrick#1842, `call_result` only: the published `string` is the body read
+     * as raw text, by a `.text()` read of the call's response or by a call whose
+     * signature takes the literal `'text'` the source passes as its body format.
+     * Raw text states no structural contract, so the check phase reads the pair
+     * unverifiable rather than comparing `string` with the other side's body.
+     * Absent when the body is not a raw-text read.
+     */
+    raw_text_read?: true;
 }
 /**
  * What the source states a body read to be (carrick#1749). The scanner
@@ -843,6 +860,11 @@ export interface StatedBody {
     root_source?: string;
     /** Array levels peeled on the way to `root`. Omitted when 0. */
     array_depth?: number;
+    /**
+     * Type arguments written at `root` (`Page<Order>` → 1). Omitted when 0.
+     * `root` alone does not name the body such a statement states.
+     */
+    root_type_arguments?: number;
 }
 /**
  * Why a type carries `any`/`unknown` at a position, and where.
@@ -853,6 +875,8 @@ export interface StatedBody {
  * across the bundle seam.
  */
 export type TypeProvenance = import('./capture/api.js').TypeProvenance;
+/** carrick#1836: declared in the capture bundle, which reads it on a literal anchor. */
+export type PrintedName = import('./capture/api.js').PrintedName;
 export type TypeProvenanceReason = import('./capture/api.js').TypeProvenanceReason;
 /**
  * Source location information for a type

package/sidecar/dist/src/validators.d.ts

@@ -332,18 +332,44 @@ export declare const CaptureV2RequestSchema: z.ZodObject<{
         type_text: z.ZodString;
         anchor_origin: z.ZodEnum<["llm-symbol", "deterministic-infer", "anchor-backfill", "manifest-placeholder"]>;
         source_file: z.ZodOptional<z.ZodString>;
+        printed_names: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            file: z.ZodString;
+            export_path: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            file: string;
+            export_path: string[];
+        }, {
+            name: string;
+            file: string;
+            export_path: string[];
+        }>, "many">>;
+        raw_text_read: z.ZodOptional<z.ZodLiteral<true>>;
     }, "strip", z.ZodTypeAny, {
         kind: "literal";
         alias: string;
         anchor_origin: "llm-symbol" | "deterministic-infer" | "anchor-backfill" | "manifest-placeholder";
         type_text: string;
         source_file?: string | undefined;
+        printed_names?: {
+            name: string;
+            file: string;
+            export_path: string[];
+        }[] | undefined;
+        raw_text_read?: true | undefined;
     }, {
         kind: "literal";
         alias: string;
         anchor_origin: "llm-symbol" | "deterministic-infer" | "anchor-backfill" | "manifest-placeholder";
         type_text: string;
         source_file?: string | undefined;
+        printed_names?: {
+            name: string;
+            file: string;
+            export_path: string[];
+        }[] | undefined;
+        raw_text_read?: true | undefined;
     }>]>, "many">;
     out_dir: z.ZodString;
     tsconfig_path: z.ZodOptional<z.ZodString>;
@@ -382,6 +408,12 @@ export declare const CaptureV2RequestSchema: z.ZodObject<{
         anchor_origin: "llm-symbol" | "deterministic-infer" | "anchor-backfill" | "manifest-placeholder";
         type_text: string;
         source_file?: string | undefined;
+        printed_names?: {
+            name: string;
+            file: string;
+            export_path: string[];
+        }[] | undefined;
+        raw_text_read?: true | undefined;
     })[];
     out_dir: string;
     tsconfig_path?: string | undefined;
@@ -420,6 +452,12 @@ export declare const CaptureV2RequestSchema: z.ZodObject<{
         anchor_origin: "llm-symbol" | "deterministic-infer" | "anchor-backfill" | "manifest-placeholder";
         type_text: string;
         source_file?: string | undefined;
+        printed_names?: {
+            name: string;
+            file: string;
+            export_path: string[];
+        }[] | undefined;
+        raw_text_read?: true | undefined;
     })[];
     out_dir: string;
     tsconfig_path?: string | undefined;
@@ -2077,18 +2115,44 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
         type_text: z.ZodString;
         anchor_origin: z.ZodEnum<["llm-symbol", "deterministic-infer", "anchor-backfill", "manifest-placeholder"]>;
         source_file: z.ZodOptional<z.ZodString>;
+        printed_names: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            file: z.ZodString;
+            export_path: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            file: string;
+            export_path: string[];
+        }, {
+            name: string;
+            file: string;
+            export_path: string[];
+        }>, "many">>;
+        raw_text_read: z.ZodOptional<z.ZodLiteral<true>>;
     }, "strip", z.ZodTypeAny, {
         kind: "literal";
         alias: string;
         anchor_origin: "llm-symbol" | "deterministic-infer" | "anchor-backfill" | "manifest-placeholder";
         type_text: string;
         source_file?: string | undefined;
+        printed_names?: {
+            name: string;
+            file: string;
+            export_path: string[];
+        }[] | undefined;
+        raw_text_read?: true | undefined;
     }, {
         kind: "literal";
         alias: string;
         anchor_origin: "llm-symbol" | "deterministic-infer" | "anchor-backfill" | "manifest-placeholder";
         type_text: string;
         source_file?: string | undefined;
+        printed_names?: {
+            name: string;
+            file: string;
+            export_path: string[];
+        }[] | undefined;
+        raw_text_read?: true | undefined;
     }>]>, "many">;
     out_dir: z.ZodString;
     tsconfig_path: z.ZodOptional<z.ZodString>;
@@ -2127,6 +2191,12 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
         anchor_origin: "llm-symbol" | "deterministic-infer" | "anchor-backfill" | "manifest-placeholder";
         type_text: string;
         source_file?: string | undefined;
+        printed_names?: {
+            name: string;
+            file: string;
+            export_path: string[];
+        }[] | undefined;
+        raw_text_read?: true | undefined;
     })[];
     out_dir: string;
     tsconfig_path?: string | undefined;
@@ -2165,6 +2235,12 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
         anchor_origin: "llm-symbol" | "deterministic-infer" | "anchor-backfill" | "manifest-placeholder";
         type_text: string;
         source_file?: string | undefined;
+        printed_names?: {
+            name: string;
+            file: string;
+            export_path: string[];
+        }[] | undefined;
+        raw_text_read?: true | undefined;
     })[];
     out_dir: string;
     tsconfig_path?: string | undefined;

package/sidecar/dist/src/validators.js

@@ -184,6 +184,14 @@ const CaptureAnchorRequestSchema = z.discriminatedUnion('kind', [
         type_text: z.string().min(1),
         anchor_origin: AnchorOriginSchema,
         source_file: z.string().min(1).optional(),
+        printed_names: z
+            .array(z.object({
+            name: z.string().min(1),
+            file: z.string().min(1),
+            export_path: z.array(z.string().min(1)).min(1),
+        }))
+            .optional(),
+        raw_text_read: z.literal(true).optional(),
     }),
 ]);
 export const CaptureV2RequestSchema = BaseRequestSchema.extend({