carrick 0.3.84 → 0.3.86

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

@@ -865,7 +865,7 @@ export class TypeInferrer {
         const serialisers = this.calleesProvenSerialiser(branches);
         const isSend = (candidate) => this.isResponseSend(candidate, extractionConfig, serialisers);
         const peeled = this.peelTransparentExpression(located);
-        const site = isSend(peeled) ? peeled : this.sendReceivingArgument(located, isSend);
+        const site = isSend(peeled) ? peeled : this.receivingCallOf(located, isSend);
         if (!site)
             return undefined;
         const contains = (outer, inner) => outer.getStart() <= inner.getStart() && inner.getEnd() <= outer.getEnd();
@@ -938,12 +938,16 @@ export class TypeInferrer {
             this.typeIsOrContainsResponseMachinery(result));
     }
     /**
-     * The send `node` is an argument of, looking through the wrappers that do
+     * The call `node` is an ARGUMENT of, looking through the wrappers that do
      * not change a payload (parentheses, `as`, `satisfies`, `!`, `await`) and a
-     * `JSON.stringify` around the body. `undefined` when the parent call is not
-     * a send or `node` is its callee.
+     * `JSON.stringify` around the body. `undefined` when `accept` rejects that
+     * call or `node` is its callee.
+     *
+     * Two readings use it: a value handed to a response send is the payload that
+     * send transmits, and a body read handed to a call that states what it
+     * returns is a better statement of that body than the read (carrick#1382).
      */
-    sendReceivingArgument(node, isSend) {
+    receivingCallOf(node, accept) {
         let current = node;
         let parent = current.getParent();
         while (parent &&
@@ -961,7 +965,7 @@ export class TypeInferrer {
         }
         if (!parent.getArguments().includes(current))
             return undefined;
-        return isSend(parent) ? parent : undefined;
+        return accept(parent) ? parent : undefined;
     }
     inferCallResult(sourceFile, request, extractionConfig) {
         const callExpr = this.resolveTargetCallExpression(sourceFile, request);
@@ -970,7 +974,8 @@ export class TypeInferrer {
         }
         // Walk up from the already-found call expression instead of re-searching
         const func = this.findContainingFunctionForNode(callExpr);
-        const terminalNode = this.resolveCallResultTerminalNode(callExpr, func);
+        const use = this.resolveCallResultTerminalNode(callExpr, func);
+        const terminalNode = use.terminal;
         const returnType = terminalNode.getType();
         let typeString = typeText(returnType, terminalNode);
         let isExplicit = false;
@@ -984,6 +989,76 @@ export class TypeInferrer {
             typeString = explicitType;
             isExplicit = true;
         }
+        // carrick#1376: the call answers a RESULT CARRIER — a generic union whose
+        // branches say whether the call worked and carry, on the success side, the
+        // value it produced. The carrier is the transport's own bookkeeping; the
+        // payload a caller receives is the success type argument, and publishing
+        // the carrier instead reports an envelope as a wire contract, which is the
+        // same class of answer the machinery guard refuses on the producer side.
+        //
+        // A wrapper rule that already unwrapped, and a type the source itself
+        // states, both outrank this: they are what the service's own config and
+        // its own author said.
+        const carrierCandidate = unwrapResult.wasUnwrapped || explicitType
+            ? undefined
+            : this.resultCarrierPayload(returnType, terminalNode, use.projections, `${request.file_path}:${request.line_number}`);
+        // 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;
+        if (carrierPayload && carrierText) {
+            typeString = carrierText;
+        }
+        else if (carrierCandidate) {
+            this.log(`Call result at ${request.file_path}:${request.line_number} carries a payload with no ` +
+                'printable member shape; publishing the carrier as written');
+        }
+        // carrick#1375: the source never read this call's result whole — every
+        // read took a member out of it, and one of those members is the generic
+        // this result was instantiated with. That is a source unwrapping an
+        // envelope by hand, so both answers available here are wrong: the
+        // projection is a fragment of the payload, and the envelope around it is
+        // machinery. A wrapper rule that DID unwrap the envelope, or a type the
+        // source itself states, is a contract and keeps its answer.
+        //
+        // A single explicit call generic (`client.get<Order[]>(url)`) is the
+        // caller's own payload claim and states the contract as plainly as an
+        // `as` does — it is what the anchor below falls back to on a checkout
+        // with no node_modules. Several generics claim nothing unambiguously.
+        //
+        // The decision has to ride the row: a plain `null` is re-read by the
+        // capture's own locator, which is kind-blind and would publish the
+        // projection this just declined to publish (`inference_decided_no_contract`,
+        // engine/type_compat_v2.rs). No anchor and no depth go with it, so the
+        // row also reads as blind rather than as a sighted answer.
+        if (use.projectionOnly &&
+            this.projectionReadsGenericPayload(callExpr, use.projections) &&
+            !unwrapResult.wasUnwrapped &&
+            !explicitType &&
+            !carrierPayload &&
+            callExpr.getTypeArguments().length !== 1) {
+            this.log(`Call result at ${request.file_path}:${request.line_number} is only ever read as ` +
+                `members of ${typeText(callExpr.getType(), callExpr)}; a part of a payload is not ` +
+                'a payload, so this site states no response contract');
+            const abstain = this.createInferredType(request, 'unknown', false, this.getNodeLocation(callExpr));
+            abstain.any_provenance = [
+                {
+                    path: '',
+                    kind: 'unknown',
+                    reason: 'projected_value_only',
+                    detail: "every read of this call's result takes a member out of it and none reads the " +
+                        'value itself, so what this site states is a part of a payload rather than the ' +
+                        'payload a caller receives',
+                },
+            ];
+            return abstain;
+        }
         typeString = this.unwrapPromise(typeString, returnType);
         // #336: consumer analogue of the #306 producer anchor. Anchor on the
         // CALL's own payload (the rule-extracted Type, else the awaited call
@@ -1001,9 +1076,17 @@ export class TypeInferrer {
         // anchor via that path.
         const callPayloadType = this.unwrapPromiseType(callExpr.getType());
         const callUnwrap = this.unwrapTypeWithConfig(callPayloadType, callExpr, extractionConfig);
-        const anchorSource = callUnwrap.wasUnwrapped
-            ? callUnwrap.payloadType
-            : callPayloadType;
+        // carrick#1376: the carrier's own symbol must never anchor either. The
+        // surface pre-claims the alias from the anchor, so anchoring on the
+        // carrier makes the capture emit the transport's bookkeeping as the
+        // operation's declaration — and where the carrier is a local interface the
+        // service does not export, nothing is emitted at all and the row reads
+        // null. The payload the carrier was found to hold is the anchor.
+        const anchorSource = carrierPayload
+            ? carrierPayload
+            : callUnwrap.wasUnwrapped
+                ? callUnwrap.payloadType
+                : callPayloadType;
         let anchor = anchorSource
             ? this.unwrapArrayLevels(this.unwrapPromiseType(anchorSource))
             : undefined;
@@ -1314,13 +1397,17 @@ export class TypeInferrer {
         if (returnStmt) {
             const returnExpr = returnStmt.getExpression();
             if (returnExpr) {
-                return returnExpr;
+                return { terminal: returnExpr, projectionOnly: false, projections: [] };
             }
         }
         const binding = this.extractBindingFromCall(callExpr);
         if (binding && func) {
             let currentNames = binding.names;
             let lastNode = binding.node;
+            /** The member reads taken OUT of the tracked value (carrick#1375). */
+            const projections = [];
+            /** The value itself was read: returned, passed, aliased, or body-read. */
+            let sawWholeRead = false;
             const startPos = callExpr.getStart();
             const candidates = this.collectDefUseNodes(func);
             for (const expr of candidates) {
@@ -1344,9 +1431,27 @@ export class TypeInferrer {
                 if (Node.isIdentifier(expr) && this.isIdentifierUsage(expr, currentNames)) {
                     const bodyRead = this.bodyReadOnReceiver(expr);
                     if (bodyRead) {
-                        lastNode = bodyRead;
+                        sawWholeRead = true;
+                        // carrick#1382: the read is a FLOOR, not a ceiling. Where the
+                        // source hands the body it read to a call that states what it
+                        // returns, that call says strictly more about the payload than
+                        // the untyped read does, and it must not lose to the read just
+                        // because the walk reaches the read second (candidates come in
+                        // pre-order, so the declaration of the parsed value is visited
+                        // before the identifier inside its own initializer).
+                        lastNode = this.statedPayloadAroundBodyRead(bodyRead) ?? bodyRead;
                         continue;
                     }
+                    // carrick#1375: how the source reads the value decides whether this
+                    // site states a payload at all. A member read takes a PART of it; a
+                    // return, an argument, an alias or a parse reads the value itself.
+                    const projection = this.projectionOnReceiver(expr);
+                    if (projection) {
+                        projections.push(projection);
+                    }
+                    else {
+                        sawWholeRead = true;
+                    }
                 }
                 if (Node.isVariableDeclaration(expr)) {
                     const initializer = expr.getInitializer();
@@ -1370,13 +1475,326 @@ export class TypeInferrer {
                         }
                     }
                 }
-                if (this.expressionUsesNames(expr, currentNames)) {
+                // The last expression the value flows into is the call's payload — a
+                // cast, a parse, an alias. An expression that only reads MEMBERS out
+                // of it is a projection and states a part of the payload, never the
+                // payload: the hook that derives `query.data?.flags` off a query
+                // result published a boolean map as the expected response of a call
+                // whose envelope the client declares in full (carrick#1375).
+                if (this.expressionUsesNames(expr, currentNames) &&
+                    !this.usesNamesOnlyByProjection(expr, currentNames)) {
                     lastNode = expr;
                 }
             }
-            return lastNode;
+            return {
+                terminal: lastNode,
+                projectionOnly: projections.length > 0 && !sawWholeRead,
+                projections,
+            };
         }
-        return callExpr;
+        return { terminal: callExpr, projectionOnly: false, projections: [] };
+    }
+    /**
+     * True when a member read on the call's result resolves to one of that
+     * result's own TYPE ARGUMENTS — the source is unwrapping a generic envelope
+     * by hand (`state.data` off a `ResourceState<Envelope>`), and the payload it
+     * carries is the instantiation, not the envelope (carrick#1375).
+     *
+     * The generic is what tells the two apart. A call that answers its payload
+     * directly is read member by member too, and its declared result IS the
+     * contract; abstaining there would throw away the type the request boundary
+     * states, which a replay over a real repo's consumer rows showed on a
+     * `{ ok: true } | { ok: false; reason: string }` result read as `sent.ok`.
+     */
+    projectionReadsGenericPayload(callExpr, projections) {
+        if (projections.length === 0)
+            return false;
+        const result = this.unwrapPromiseType(callExpr.getType());
+        const args = [...result.getTypeArguments(), ...result.getAliasTypeArguments()];
+        if (args.length === 0)
+            return false;
+        const argTexts = new Set(args.map((arg) => arg.getText()));
+        return projections.some((projection) => {
+            const read = this.unwrapPromiseType(projection.getType());
+            const parts = [read, read.getNonNullableType()];
+            for (const part of [...parts]) {
+                if (part.isUnion())
+                    parts.push(...part.getUnionTypes());
+            }
+            return parts.some((part) => argTexts.has(part.getText()));
+        });
+    }
+    /**
+     * The payload a RESULT CARRIER carries, or `undefined` when `type` is not
+     * one or its success side cannot be told from its failure side
+     * (carrick#1376).
+     *
+     * A carrier is recognised by its shape, never by a name: a union of object
+     * branches, instantiated with two or more type arguments, at least one of
+     * which a branch holds as a member. `Result<T, E>`, `Either<L, R>` and a
+     * hand-rolled `{ ok: true; value: T } | { ok: false; error: E }` are all the
+     * same shape, and a promise-like around one is peeled first through the
+     * language's own await protocol. A single generic object — a resource state,
+     * a query result — is NOT a union and is left to carrick#1375, which
+     * abstains on it so a sibling site can answer.
+     *
+     * Which argument is the payload is decided twice over, and never guessed:
+     *
+     *  1. the platform's error shape. Exactly one argument that is not
+     *     error-shaped, beside at least one that is, is the success side.
+     *  2. what the source reads. Where every argument looks alike — `Pair<A,
+     *     string>` — a member read of the carrier that resolves to exactly one
+     *     of the arguments names the side this call site takes.
+     *
+     * 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 carrier = this.unwrapThenableType(this.unwrapPromiseType(type));
+        if (!carrier.isUnion()) {
+            return undefined;
+        }
+        const branches = carrier.getUnionTypes();
+        if (branches.length < 2 || !branches.every((branch) => this.isObjectShape(branch))) {
+            return undefined;
+        }
+        const args = [
+            ...carrier.getAliasTypeArguments(),
+            ...carrier.getTypeArguments(),
+        ];
+        if (args.length < 2) {
+            return undefined;
+        }
+        // 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) => {
+            try {
+                return property.getTypeAtLocation(at).getText() === arg.getText();
+            }
+            catch {
+                return false;
+            }
+        })));
+        if (carried.length === 0) {
+            return undefined;
+        }
+        const argTexts = new Map(carried.map((arg) => [arg.getText(), arg]));
+        const read = new Set();
+        for (const projection of projections) {
+            const projected = this.unwrapPromiseType(projection.getType()).getNonNullableType();
+            if (argTexts.has(projected.getText())) {
+                read.add(projected.getText());
+            }
+        }
+        const byRead = read.size === 1 ? argTexts.get([...read][0]) : undefined;
+        const succeeded = carried.filter((arg) => !this.isErrorShaped(arg, at));
+        const byShape = succeeded.length === 1 && succeeded.length < carried.length ? succeeded[0] : undefined;
+        // The two tests must agree where both answer. An error shape is a shape,
+        // and a payload is free to have one — a contact form declares a `name` and
+        // a `message` too, and a service whose failure side is `{ code: number }`
+        // would then read as the success side. Where the source reads a DIFFERENT
+        // 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 undefined;
+        }
+        if (byShape ?? byRead) {
+            return byShape ?? byRead;
+        }
+        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;
+    }
+    /**
+     * `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.
+     */
+    unwrapThenableType(type) {
+        let current = type;
+        for (let depth = 0; depth < 8; depth++) {
+            const then = current.getProperty('then');
+            const declaration = then?.getDeclarations()[0];
+            if (!then || !declaration)
+                return current;
+            let onValue;
+            try {
+                onValue = then
+                    .getTypeAtLocation(declaration)
+                    .getCallSignatures()[0]
+                    ?.getParameters()[0]
+                    ?.getTypeAtLocation(declaration);
+            }
+            catch {
+                return current;
+            }
+            const value = onValue
+                ?.getCallSignatures()[0]
+                ?.getParameters()[0]
+                ?.getTypeAtLocation(declaration);
+            if (!value || value === current)
+                return current;
+            current = value;
+        }
+        return current;
+    }
+    /**
+     * The platform's error shape, in full: `name` and `message` strings AND a
+     * `stack`, which is what the `Error` interface declares and every subclass
+     * of it inherits.
+     *
+     * `stack` is what makes the test a test. A name and a message alone are a
+     * shape a PAYLOAD can have — a contact form declares both — and reading such
+     * a payload as the failure side would publish the other argument, which is
+     * the concrete-but-wrong answer this whole rule exists to avoid. A union is
+     * error-shaped when every member of it is.
+     */
+    isErrorShaped(type, at) {
+        if (type.isUnion()) {
+            return type.getUnionTypes().every((part) => this.isErrorShaped(part, at));
+        }
+        const typeOf = (property) => {
+            if (!property)
+                return undefined;
+            try {
+                return property.getTypeAtLocation(at);
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const stringy = (property) => typeOf(property)?.getNonNullableType().getText() === 'string';
+        return (stringy(type.getProperty('name')) &&
+            stringy(type.getProperty('message')) &&
+            stringy(type.getProperty('stack')));
+    }
+    /**
+     * The member read that takes `identifier` as its RECEIVER — `query` in
+     * `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 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.
+     */
+    projectionOnReceiver(identifier) {
+        const access = identifier.getParent();
+        if (!access ||
+            (!Node.isPropertyAccessExpression(access) &&
+                !Node.isElementAccessExpression(access)) ||
+            access.getExpression() !== identifier) {
+            return undefined;
+        }
+        const parent = access.getParent();
+        if (parent &&
+            Node.isCallExpression(parent) &&
+            parent.getExpression() === access) {
+            return undefined;
+        }
+        return access;
+    }
+    /**
+     * The call that CONSUMES this json body read and states what the body is —
+     * `parseEnvelope(await response.json())` — or `undefined` when nothing
+     * downstream of the read says more about it than the read itself does
+     * (carrick#1382).
+     *
+     * Three conditions, all shapes of the language rather than names:
+     *
+     *  - the read reaches the call as an ARGUMENT, through the wrappers that do
+     *    not change a value (`await`, parentheses, `as`, `satisfies`, `!`). A
+     *    cast with no call around it therefore keeps the read as the terminal,
+     *    so `(await res.json()) as Entry` is still read off the read itself;
+     *  - the call's own result is BOUND — declared into a variable, returned, or
+     *    assigned — so a call the source made for its side effect
+     *    (`store(await res.json())`) states nothing about the payload;
+     *  - that result is an OBJECT shape. A validator answering `boolean` or a
+     *    serialiser answering `string` describes what the caller did with the
+     *    body, not what the body is, and publishing it would be a
+     *    concrete-but-wrong contract where the honest `any` of the read is
+     *    merely unresolved.
+     */
+    statedPayloadAroundBodyRead(bodyRead) {
+        return this.receivingCallOf(bodyRead, (candidate) => Node.isCallExpression(candidate) &&
+            this.callResultIsBound(candidate) &&
+            this.isObjectShape(this.unwrapPromiseType(candidate.getType())));
+    }
+    /**
+     * The source keeps this call's result: it initializes a declaration, is
+     * returned, is assigned, or is an arrow's expression body. A result that is
+     * kept is one the source has a use for; a discarded one is a side effect.
+     */
+    callResultIsBound(call) {
+        let current = call;
+        let parent = current.getParent();
+        while (parent &&
+            (Node.isParenthesizedExpression(parent) ||
+                Node.isAwaitExpression(parent) ||
+                Node.isAsExpression(parent) ||
+                Node.isSatisfiesExpression(parent) ||
+                Node.isNonNullExpression(parent)) &&
+            parent.getExpression() === current) {
+            current = parent;
+            parent = current.getParent();
+        }
+        if (!parent)
+            return false;
+        if (Node.isVariableDeclaration(parent)) {
+            return parent.getInitializer() === current;
+        }
+        if (Node.isReturnStatement(parent)) {
+            return parent.getExpression() === current;
+        }
+        if (Node.isArrowFunction(parent)) {
+            return parent.getBody() === current;
+        }
+        if (Node.isBinaryExpression(parent)) {
+            return (parent.getOperatorToken().getKind() === SyntaxKind.EqualsToken &&
+                parent.getRight() === current);
+        }
+        return false;
+    }
+    /**
+     * A shape a JSON body can be: an object, an array, or a union of them.
+     * Top types, primitives, `void` and callables are not.
+     */
+    isObjectShape(type) {
+        if (type.isAny() || type.isUnknown())
+            return false;
+        if (type.isUnion()) {
+            const parts = type.getUnionTypes().filter((part) => !part.isUndefined() && !part.isNull());
+            return parts.length > 0 && parts.every((part) => this.isObjectShape(part));
+        }
+        if (type.isIntersection()) {
+            return type.getIntersectionTypes().every((part) => this.isObjectShape(part));
+        }
+        return type.isObject() && !this.isCallableType(type);
+    }
+    /**
+     * Every use of a tracked name inside `expr` reads a member out of the
+     * tracked value, so the expression's type describes a PART of the payload.
+     * False when the expression uses no tracked name at all, so a caller can
+     * read it as "this is a projection" rather than "this is not a use".
+     */
+    usesNamesOnlyByProjection(expr, names) {
+        const uses = expr
+            .getDescendantsOfKind(SyntaxKind.Identifier)
+            .filter((id) => this.isIdentifierUsage(id, names));
+        if (uses.length === 0) {
+            return false;
+        }
+        return uses.every((id) => this.projectionOnReceiver(id) !== undefined);
     }
     extractBindingFromCall(callExpr) {
         const varDecl = callExpr.getFirstAncestorByKind(SyntaxKind.VariableDeclaration);
@@ -2611,7 +3029,16 @@ export class TypeInferrer {
      * True when an object literal argument is response INIT rather than a body:
      * every property it declares is one the standard `ResponseInit` declares
      * (`status`, `statusText`, `headers`), and it states at least one of them as
-     * init really does — a numeric status in the HTTP range, or headers.
+     * init really does — a status in the HTTP range, or headers.
+     *
+     * The status does NOT have to be a literal code. A route that carries its
+     * outcome in a value writes `new Response(body, { status: result.status })`,
+     * where the source fixes no code and `statedStatusCodes` answers
+     * `'variable'` — status-shaped, just not pinned. Requiring a literal there
+     * left the whole init object reading as a body, so an endpoint whose payload
+     * this layer does not publish (a string body) published `{ status: number }`
+     * as its response contract instead: a wrong contract, served, where an
+     * abstention was the honest answer.
      *
      * A payload that merely has a `status` member of its own (`{ status: "ok",
      * service: "ledger" }`) declares members init does not, or states `status` as
@@ -2640,7 +3067,7 @@ export class TypeInferrer {
                 statesInit = true;
                 continue;
             }
-            if (name === 'status' && Array.isArray(this.statedStatusCodes(value))) {
+            if (name === 'status' && this.statedStatusCodes(value) !== undefined) {
                 statesInit = true;
             }
         }

package/templates/skills/carrick-census.md

@@ -54,7 +54,9 @@ Report these numbers before the list, per query where the field is per query:
   removed, and `best` where it names the closest of them. A count above zero is
   the case for one more search at a lower `similarity_threshold`;
 - `total_without_intent`, which is index-wide: functions carrying no intent
-  text, which no search looked at;
+  text, which the search ranked on their name, signature and body tokens
+  alone, so a query that names one finds it and a query that describes what
+  it does without naming it does not;
 - `total_intent_carried_forward` where the response states it, which are intents
   describing the code as of an earlier scan.