carrick 0.3.109 → 0.3.110

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

@@ -24,8 +24,11 @@ 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 { readResponseModes } from './response-modes.js';
 import { functionAtLine } from './function-line-index.js';
+import { endLineOf, startLineOf } from './line-index.js';
 import { elapsedMs, inferTiming, phaseClock, timedPhase } from './infer-timing.js';
+import { classifyStatusCodes, constituents, httpStatus, statesNoBody, statusKeyCode, statusTableOf, successEntries, } from './capture/index.js';
 import { addedDiagnostics, applyInsertions, fileDiagnostics, literalInsertions, mapBack, mapForward, normalise, pathOf, } from './unwidened.js';
 import { expandTypeStructural, jsonWireType, } from './type-structural-expander.js';
 /**
@@ -169,11 +172,19 @@ const RESPONSE_HELPER_MAX_DEPTH = 4;
  * the branch an error path, whose shape is not the endpoint's contract.
  */
 const STATUS_MEMBER_NAMES = ['status', 'statusCode'];
-/** `value` when it is an integer in the HTTP status range, else `undefined`. */
-function httpStatus(value) {
-    return typeof value === 'number' && Number.isInteger(value) && value >= 100 && value <= 599
-        ? value
-        : undefined;
+/**
+ * The items whose whitespace-collapsed texts differ, first of each kept, in
+ * order: how a joined union drops a member it already has.
+ */
+function distinctByText(items, text) {
+    const seen = new Set();
+    return items.filter((item) => {
+        const key = text(item).replace(/\s+/g, ' ').trim();
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
 }
 /**
  * The status codes a TYPE fixes: a numeric literal, or a union made only of
@@ -193,16 +204,6 @@ function statusCodesOfType(type) {
     }
     return codes.length > 0 ? codes : undefined;
 }
-/** One verdict for a set of status codes, or `mixed` when they disagree. */
-function classifyStatusCodes(codes) {
-    if (codes.every((code) => code >= 400))
-        return 'error';
-    if (codes.every((code) => code >= 300 && code < 400))
-        return 'redirect';
-    if (codes.every((code) => code < 300))
-        return 'success';
-    return 'mixed';
-}
 /**
  * The parts of a request that ARE the body, as validator middleware names them
  * (`validate('json', Schema)`). HTTP vocabulary for how a body is carried — the
@@ -973,7 +974,7 @@ export class TypeInferrer {
             Node.isArrowFunction(ancestor) ||
             Node.isFunctionExpression(ancestor) ||
             Node.isMethodDeclaration(ancestor)) &&
-            ancestor.getStartLineNumber() === request.line_number);
+            startLineOf(ancestor) === request.line_number);
         const declaredHandler = insideFunctionOnLine
             ? this.handlerDeclaredAtLine(sourceFile, request.line_number)
             : undefined;
@@ -1130,7 +1131,7 @@ export class TypeInferrer {
      */
     exportedFunctionOpeningOn(sourceFile, line) {
         const declared = this.findFunctionByLine(sourceFile, line);
-        if (!declared || declared.getStartLineNumber() !== line)
+        if (!declared || startLineOf(declared) !== line)
             return undefined;
         if (Node.isFunctionDeclaration(declared)) {
             return Node.isSourceFile(declared.getParent()) && declared.isExported()
@@ -1299,7 +1300,10 @@ export class TypeInferrer {
         const resolvedSource = resolvedSymbol !== undefined && recoveredAnchor
             ? this.primaryTypeSymbolSource(recoveredAnchor.element)
             : undefined;
-        return this.createInferredType(request, recovered.typeString, recovered.isExplicit, this.getNodeLocation(recovered.node), undefined, resolvedSymbol ?? writtenAnchor?.symbol, writtenAnchor ? writtenAnchor.depth : recoveredAnchor?.depth, writtenAnchor ? writtenAnchor.source : resolvedSource);
+        const inferred = this.createInferredType(request, recovered.typeString, recovered.isExplicit, this.getNodeLocation(recovered.node), undefined, resolvedSymbol ?? writtenAnchor?.symbol, writtenAnchor ? writtenAnchor.depth : recoveredAnchor?.depth, writtenAnchor ? writtenAnchor.source : resolvedSource);
+        if (recovered.responseModes)
+            inferred.response_modes = recovered.responseModes;
+        return inferred;
     }
     /**
      * carrick#1161: type a route response from every send in the handler the
@@ -1472,7 +1476,9 @@ export class TypeInferrer {
         // carrier read gives its own. A result that is no carrier keeps the
         // answer it had.
         const where = `${request.file_path}:${request.line_number}`;
-        const resultIsCarrier = !explicitType && this.resultCarrierArguments(returnType, terminalNode) !== undefined;
+        const callArgs = this.callResultArguments(callExpr);
+        const resultIsCarrier = !explicitType &&
+            this.resultCarrierArguments(returnType, terminalNode, callArgs) !== undefined;
         // carrick#1877: the terminal holds a thenable the names do not peel, a
         // subclass of `Promise` or a class with a `then` of its own. What a
         // caller receives is what `await` yields for it, as it is for the
@@ -1521,12 +1527,22 @@ export class TypeInferrer {
         const readThroughCarrier = unwrapResult.wasUnwrapped &&
             resultIsCarrier &&
             !!afterRules &&
-            this.resultCarrierArguments(afterRules, terminalNode) === undefined;
-        const carrierCandidate = explicitType || !afterRules
+            this.resultCarrierArguments(afterRules, terminalNode, callArgs) === undefined;
+        const carrierRead = explicitType || !afterRules
             ? undefined
             : readThroughCarrier
-                ? afterRules
-                : this.resultCarrierPayload(afterRules, terminalNode, use.projections, where);
+                ? { payload: afterRules }
+                : this.resultCarrierPayload(afterRules, terminalNode, use.projections, where, callArgs);
+        // carrick#1841: a carrier built from a response table whose success side
+        // states no body (a `204` row), or whose side cannot be told, states no
+        // response contract. The abstain is decided for the same reason as the
+        // transport abstain above: left undecided, the capture's own locator
+        // re-reads the raw call and publishes the carrier.
+        if (carrierRead && 'abstain' in carrierRead) {
+            this.log(`Call result at ${where}: ${carrierRead.abstain}`);
+            return this.transportAbstain(request, callExpr, carrierRead.abstain);
+        }
+        const carrierCandidate = carrierRead?.payload;
         // 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
@@ -1658,7 +1674,7 @@ export class TypeInferrer {
         const callAfterRules = callUnwrap.wasUnwrapped ? callUnwrap.payloadType : callPayloadType;
         const leftCarrier = (callUnwrap.wasUnwrapped || readByProtocol) &&
             !!callAfterRules &&
-            this.resultCarrierArguments(callAfterRules, callExpr) !== undefined;
+            this.resultCarrierArguments(callAfterRules, callExpr, callArgs) !== undefined;
         const anchorSource = carrierPayload ?? (leftCarrier ? undefined : callAfterRules);
         let anchor = anchorSource
             ? this.unwrapArrayLevels(this.unwrapPromiseType(anchorSource))
@@ -2466,13 +2482,57 @@ export class TypeInferrer {
      * Where neither decides, the carrier keeps its own answer and the limit is
      * logged: a coin flip published as a contract is worse than an envelope a
      * reader can see is an envelope.
-     */
-    resultCarrierPayload(type, at, projections, where) {
-        const shape = this.resultCarrierArguments(type, at);
+     *
+     * carrick#1841: an argument that is a RESPONSE TABLE (`{ 200: Item }`, every
+     * key a status code) says which side it is by its keys, and that decides
+     * first: the one table whose keys are all 2xx is the success side, and what
+     * a caller receives is the table's body, the member the branch holds, never
+     * the table. A success table whose rows state no body (`{ 204: void }`)
+     * states no response contract. A carrier built from tables, or found
+     * through the call's arguments, that nothing decides states none either:
+     * the union is the client's bookkeeping, not a body, so it is not published
+     * as written.
+     */
+    resultCarrierPayload(type, at, projections, where, callArgs) {
+        const shape = this.resultCarrierArguments(type, at, callArgs);
         if (!shape) {
             return undefined;
         }
-        const { carrier, carried } = shape;
+        const { carrier, carried, bodies, readOffCall } = shape;
+        const checker = this.project.getTypeChecker().compilerObject;
+        const tables = carried.map((arg) => {
+            const entries = statusTableOf(checker, arg.compilerType);
+            return {
+                arg,
+                entries,
+                side: entries ? classifyStatusCodes(entries.map((entry) => entry.code)) : undefined,
+            };
+        });
+        const successTables = tables.filter((table) => table.side === 'success');
+        if (successTables.length === 1) {
+            const { arg, entries } = successTables[0];
+            const body = bodies.get(arg) ?? this.singleSuccessValue(arg, entries ?? [], at);
+            if (body && statesNoBody(body.compilerType)) {
+                return {
+                    abstain: `the call answers a carrier whose success side is the response table ` +
+                        `'${typeText(arg, at)}', and its success rows state no body, so this site ` +
+                        'states no response contract',
+                };
+            }
+            if (body) {
+                return { payload: body };
+            }
+        }
+        const builtFromTables = tables.some((table) => table.side !== undefined);
+        const undecided = (detail) => {
+            this.log(`Call result at ${where} answers a carrier (${typeText(carrier, at)}): ${detail}`);
+            return builtFromTables || readOffCall
+                ? {
+                    abstain: `the call answers a carrier (${typeText(carrier, at)}) whose success side ` +
+                        'cannot be told from its failure side, so this site states no response contract',
+                }
+                : undefined;
+        };
         const argTexts = new Map(carried.map((arg) => [arg.getText(), arg]));
         const read = new Set();
         for (const projection of projections) {
@@ -2491,27 +2551,69 @@ export class TypeInferrer {
         // argument out than the shape test picked, the two disagree about which
         // side is which and nothing here knows better than the source does.
         if (byShape && byRead && byShape !== byRead) {
-            this.log(`Call result at ${where} answers a carrier (${typeText(carrier, at)}) whose error ` +
-                `shape names '${typeText(byShape, at)}' as the payload while the source reads ` +
-                `'${typeText(byRead, at)}' out of it. Publishing the carrier as written rather ` +
-                'than picking one');
+            return undecided(`its error shape names '${typeText(byShape, at)}' as the payload while the source ` +
+                `reads '${typeText(byRead, at)}' out of it. Not picking one`);
+        }
+        const decided = byShape ?? byRead;
+        if (decided) {
+            return { payload: bodies.get(decided) ?? decided };
+        }
+        return undecided('its success side cannot be told from its failure side: no single argument is the ' +
+            'only non-error one and the source reads none of them out. Not guessing which ' +
+            'argument is the payload');
+    }
+    /**
+     * 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
+     * has more than one success row: their union has no single type here.
+     */
+    singleSuccessValue(table, entries, at) {
+        const success = successEntries(entries);
+        if (success.length !== 1)
             return undefined;
+        return table.getProperty(success[0].key)?.getTypeAtLocation(at);
+    }
+    /**
+     * carrick#1841: the type arguments a call's result was built from, for a
+     * result that no longer carries them. A client whose result type is a
+     * conditional alias (`Result<TData, TError, ThrowOnError>`) resolves to its
+     * branch at the call, and the branch is an anonymous union with no
+     * arguments of its own. The arguments are still stated in two places the
+     * compiler keeps:
+     *
+     *  - the call's own explicit type arguments (`client.get<Table, Errors>(…)`);
+     *  - the alias the callee's declared return type was written with, where
+     *    the callee is a function wrapping such a call
+     *    (`getItem<ThrowOnError>(…)` returning `Result<Table, Errors, ThrowOnError>`).
+     *
+     * An argument read here names a payload only where a branch of the result
+     * holds it (`resultCarrierArguments`), so a type parameter of the callee or
+     * a style flag carries nothing.
+     */
+    callResultArguments(callExpr) {
+        const explicit = callExpr.getTypeArguments().map((node) => node.getType());
+        if (explicit.length > 0)
+            return explicit;
+        try {
+            const declaration = this.project
+                .getTypeChecker()
+                .getResolvedSignature(callExpr)
+                ?.getDeclaration();
+            if (declaration && Node.isReturnTyped(declaration)) {
+                return declaration.getReturnType().getAliasTypeArguments();
+            }
         }
-        if (byShape ?? byRead) {
-            return byShape ?? byRead;
+        catch {
+            // A signature the checker cannot resolve states no arguments.
         }
-        this.log(`Call result at ${where} answers a carrier (${typeText(carrier, at)}) whose success ` +
-            'side cannot be told from its failure side: no single argument is the only ' +
-            'non-error one and the source reads none of them out. Publishing the carrier as ' +
-            'written rather than guessing which argument is the payload');
-        return undefined;
+        return [];
     }
     /**
      * 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.
      */
-    resultCarrierArguments(type, at) {
+    resultCarrierArguments(type, at, callArgs = []) {
         const carrier = this.unwrapThenableType(this.unwrapPromiseType(type));
         if (!carrier.isUnion()) {
             return undefined;
@@ -2520,26 +2622,80 @@ export class TypeInferrer {
         if (branches.length < 2 || !branches.every((branch) => this.isObjectShape(branch))) {
             return undefined;
         }
-        const args = [
-            ...carrier.getAliasTypeArguments(),
-            ...carrier.getTypeArguments(),
-        ];
+        const own = [...carrier.getAliasTypeArguments(), ...carrier.getTypeArguments()];
+        // carrick#1841: a carrier with no arguments of its own is read through the
+        // arguments its call was built from (`callResultArguments`).
+        const readOffCall = own.length === 0;
+        const args = readOffCall ? callArgs : own;
         if (args.length < 2) {
             return undefined;
         }
+        // carrick#1841: on a carrier read off the call, a member every branch
+        // holds with one type (the request and response objects a client hands
+        // back beside the result) is the transport's, not a side of the result.
+        const transport = readOffCall ? this.membersCommonToEveryBranch(branches, at) : new Set();
+        const checker = this.project.getTypeChecker().compilerObject;
+        // What a branch member holding a response table's body looks like: the
+        // table indexed by its own keys (`Table[keyof Table]`), which the compiler
+        // resolves to the union of the table's values.
+        const tableValues = new Map();
+        for (const arg of args) {
+            const entries = statusTableOf(checker, arg.compilerType);
+            if (entries) {
+                tableValues.set(arg, new Set(entries.flatMap((entry) => constituents(checker.getTypeOfSymbolAtLocation(entry.symbol, at.compilerNode)))));
+            }
+        }
+        const bodies = new Map();
         // A type argument only names a payload when a branch actually holds it:
         // a generic that parameterises a status code or a key carries nothing.
-        const carried = args.filter((arg) => branches.some((branch) => branch
-            .getProperties()
-            .some((property) => {
+        const carried = args.filter((arg) => branches.some((branch) => branch.getProperties().some((property) => {
+            if (transport.has(property.getName()))
+                return false;
             try {
-                return property.getTypeAtLocation(at).getText() === arg.getText();
+                const held = property.getTypeAtLocation(at);
+                if (held.getText() === arg.getText())
+                    return true;
+                const values = tableValues.get(arg);
+                const heldTypes = constituents(held.compilerType);
+                if (values &&
+                    heldTypes.length === values.size &&
+                    heldTypes.every((member) => values.has(member))) {
+                    bodies.set(arg, held);
+                    return true;
+                }
+                return false;
             }
             catch {
                 return false;
             }
         })));
-        return carried.length === 0 ? undefined : { carrier, carried };
+        return carried.length === 0 ? undefined : { carrier, carried, bodies, readOffCall };
+    }
+    /** The member names every branch holds, each with one and the same type. */
+    membersCommonToEveryBranch(branches, at) {
+        const [first, ...rest] = branches;
+        const common = new Set();
+        for (const property of first.getProperties()) {
+            const name = property.getName();
+            let held;
+            try {
+                held = property.getTypeAtLocation(at);
+            }
+            catch {
+                continue;
+            }
+            const same = rest.every((branch) => {
+                try {
+                    return branch.getProperty(name)?.getTypeAtLocation(at).compilerType === held.compilerType;
+                }
+                catch {
+                    return false;
+                }
+            });
+            if (same)
+                common.add(name);
+        }
+        return common;
     }
     /**
      * The decided abstain of a call whose result carries transport the
@@ -2549,16 +2705,16 @@ export class TypeInferrer {
      * re-reading the raw call (`inference_decided_no_contract`,
      * engine/type_compat_v2.rs).
      */
-    transportAbstain(request, callExpr) {
+    transportAbstain(request, callExpr, 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') {
         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',
+                detail,
             },
         ];
         return abstain;
@@ -3918,17 +4074,13 @@ export class TypeInferrer {
         const isEmptyObject = (text) => text.replace(/\s+/g, '') === '{}';
         const withMembers = candidates.filter((c) => !isEmptyObject(c.typeString));
         const kept = withMembers.length > 0 ? withMembers : candidates;
-        // Dedupe on the whitespace-collapsed text, preserving source order.
-        const seen = new Set();
-        const distinct = kept.filter((c) => {
-            const key = c.typeString.replace(/\s+/g, ' ').trim();
-            if (seen.has(key))
-                return false;
-            seen.add(key);
-            return true;
-        });
+        const distinct = distinctByText(kept, (c) => c.typeString);
         const typeString = distinct.map((c) => c.typeString).join(' | ');
         return {
+            // carrick#2054: which request field picks each member of the union.
+            responseModes: distinct.length >= 2
+                ? this.responseModesOf(kept.map((c) => ({ node: c.node, type_string: c.typeString })))
+                : undefined,
             typeString,
             // Every payload node that fed the union, deduped ones included: a
             // caller asks whether the expression it located is one of them.
@@ -3942,6 +4094,20 @@ export class TypeInferrer {
             statedTypeNode: distinct.length === 1 ? distinct[0].statedTypeNode : undefined,
         };
     }
+    /**
+     * The request field each member of a joined union answers
+     * (`response-modes.ts`). Case texts are joined by the published union's
+     * rule. A reading that fails is no reading: it must never cost the union.
+     */
+    responseModesOf(bodies) {
+        try {
+            return readResponseModes(bodies, (texts) => distinctByText(texts, (text) => text).join(' | '), (symbol) => this.symbolIsLibOrExternalOrigin(symbol));
+        }
+        catch (error) {
+            this.log(`Response modes not read: ${error instanceof Error ? error.message : String(error)}`);
+            return undefined;
+        }
+    }
     /**
      * The expressions a function returns, excluding returns belonging to nested
      * functions (a `.map(x => …)` callback returns a row, not the response).
@@ -4822,7 +4988,7 @@ export class TypeInferrer {
         for (const node of sourceFile.getDescendants()) {
             if ((Node.isCallExpression(node) ||
                 Node.isObjectLiteralExpression(node)) &&
-                node.getStartLineNumber() === line) {
+                startLineOf(node) === line) {
                 const handler = this.resolveRegisteredHandler(node);
                 if (handler) {
                     return { registration: node, handler };
@@ -5963,14 +6129,9 @@ export class TypeInferrer {
             if (!Node.isPropertyAssignment(prop)) {
                 continue;
             }
-            const name = prop.getName().replace(/['"`]/g, '').toLowerCase();
-            // `2xx` is a status RANGE key; treat it as the bottom of its range.
-            const code = /^\d{3}$/.test(name)
-                ? Number(name)
-                : /^\dxx$/.test(name)
-                    ? Number(name[0]) * 100
-                    : NaN;
-            if (!Number.isFinite(code) || code < 200 || code > 299) {
+            // `2xx` is a status RANGE key; it reads as the bottom of its range.
+            const code = statusKeyCode(prop.getName());
+            if (code === undefined || code < 200 || code > 299) {
                 continue;
             }
             const initializer = prop.getInitializer();
@@ -6418,7 +6579,7 @@ export class TypeInferrer {
         // Filter to nodes within the search window and pre-compute normalized text
         const candidates = (lineNumber
             ? nodes.filter((node) => {
-                const nodeLine = node.getStartLineNumber();
+                const nodeLine = startLineOf(node);
                 return nodeLine >= lineNumber - searchRadius && nodeLine <= lineNumber + searchRadius;
             })
             : nodes).map((node) => ({ node, text: this.normalizeWhitespace(node.getText()) }));
@@ -6476,8 +6637,8 @@ export class TypeInferrer {
             }
             // Tie-break by proximity to target line
             if (targetLine !== undefined) {
-                const bestDist = Math.abs(best.getStartLineNumber() - targetLine);
-                const currentDist = Math.abs(current.getStartLineNumber() - targetLine);
+                const bestDist = Math.abs(startLineOf(best) - targetLine);
+                const currentDist = Math.abs(startLineOf(current) - targetLine);
                 return currentDist < bestDist ? current : best;
             }
             return best;
@@ -6693,8 +6854,8 @@ export class TypeInferrer {
     // Result Building
     // ===========================================================================
     getNodeLocation(node) {
-        const startLinePos = node.getStartLineNumber();
-        const endLinePos = node.getEndLineNumber();
+        const startLinePos = startLineOf(node);
+        const endLinePos = endLineOf(node);
         const location = {
             file_path: node.getSourceFile().getFilePath(),
             start_line: startLinePos,

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

@@ -2,6 +2,7 @@
  * Type definitions for the sidecar message protocol
  * These types define the JSON messages exchanged between Rust and the Node.js sidecar
  */
+import type { ResponseModes } from './response-modes.js';
 /**
  * The kind of type inference to perform
  */
@@ -496,6 +497,12 @@ export interface SymbolRequest {
      * symbol as-is (the HTTP/socket/consumer default).
      */
     array_depth?: number;
+    /**
+     * carrick#1841: the symbol names what a consumer receives. A symbol that is
+     * a response table keyed by status code (`{ 200: Item }`) then bundles as
+     * its 2xx body, never as the table.
+     */
+    consumer_response?: boolean;
 }
 /**
  * Request for type inference at a specific location
@@ -947,6 +954,15 @@ export interface InferredType {
      * Absent when the body is not a raw-text read.
      */
     raw_text_read?: true;
+    /**
+     * carrick#2054, a response joined from two or more success bodies: the
+     * request fields whose values pick among them (`reads`), and, for one
+     * query parameter or body field whose every test the reading follows, the
+     * union each stated value receives (`cases`). `type_string` is unchanged.
+     * Absent when no request read separates the bodies, or when every value
+     * receives the same union.
+     */
+    response_modes?: ResponseModes;
 }
 /**
  * What the source states a body read to be (carrick#1749). The scanner