carrick 0.3.133 → 0.3.134

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

@@ -30,6 +30,7 @@ import { readResponseModes } from './response-modes.js';
 import { functionAtLine } from './function-line-index.js';
 import { attributedDeclaration, installedPackageOf } from './declaration-attribution.js';
 import { endLineOf, startLineOf } from './line-index.js';
+import { callsOf, descendantsOf, descendantsOnLine, descendantsOnLines, wrap, } from './node-index.js';
 import { elapsedMs, inferTiming, phaseClock, timedPhase } from './infer-timing.js';
 import { StatedParams } from './stated-params.js';
 import { bindingToleratesAbsence, handlerToleratesAbsentBody } from './absent-body.js';
@@ -933,7 +934,49 @@ export class TypeInferrer {
     // ===========================================================================
     // Inference Methods by Kind
     // ===========================================================================
+    /**
+     * carrick#2824: a located response expression that sits in ANOTHER route's
+     * handler is not this row's. A model can locate `response` at a line that
+     * belongs to the next registration in the same module; reading that node
+     * publishes the other route's reply. Returns the request with its locator
+     * dropped, so it is answered by the registration on its own line, when:
+     *  1. a registration R sits on the request's line;
+     *  2. the located node is outside R and outside R's handler;
+     *  3. some ancestor of the node is a registration whose handler contains it.
+     * Anything else is returned unchanged. Matches on node shape, no names.
+     */
+    withoutForeignLocator(sourceFile, request) {
+        const node = this.resolveTargetNode(sourceFile, request);
+        if (!node)
+            return request;
+        const atLine = this.registrationAtLine(sourceFile, request.line_number);
+        if (!atLine)
+            return request;
+        const within = (inner, outer) => inner.getPos() >= outer.getPos() && inner.getEnd() <= outer.getEnd();
+        if (within(node, atLine.registration) || within(node, atLine.handler)) {
+            return request;
+        }
+        const inOtherHandler = node.getAncestors().some((ancestor) => {
+            if (!Node.isCallExpression(ancestor) && !Node.isObjectLiteralExpression(ancestor)) {
+                return false;
+            }
+            const handler = this.resolveRegisteredHandler(ancestor);
+            return handler !== undefined && within(node, handler);
+        });
+        if (!inOtherHandler)
+            return request;
+        this.log(`Located expression at ${request.file_path}:${request.expression_line ?? request.line_number} ` +
+            `sits in another registration's handler; answering by the registration on line ${request.line_number}`);
+        return {
+            ...request,
+            span_start: undefined,
+            span_end: undefined,
+            expression_text: undefined,
+            expression_line: undefined,
+        };
+    }
     inferFunctionReturn(sourceFile, request, extractionConfig) {
+        request = this.withoutForeignLocator(sourceFile, request);
         // A `function_return` request can point at a route REGISTRATION: that is
         // the shape the scanner sends for a route whose handler RETURNS its
         // payload. The containing-function walk below then resolves the function
@@ -948,6 +991,16 @@ export class TypeInferrer {
         }
         const func = this.resolveContainingFunction(sourceFile, request);
         if (!func) {
+            // carrick#807: a file route exported as a call to a route builder
+            // (`export const x = builder(options, async () => ...)`) starts no
+            // function at its line; the handler follows the options object. Where a
+            // registration sits on the line, read the handler it hands in, as the
+            // line-only `response_body` path does.
+            const atLine = this.registrationAtLine(sourceFile, request.line_number);
+            if (atLine) {
+                this.log(`Line ${request.line_number} is a route registration; following handler return`);
+                return this.buildFunctionReturnInferredType(request, atLine.handler, extractionConfig, true);
+            }
             this.log(`No function found for request at ${request.file_path}:${request.line_number}`);
             return null;
         }
@@ -1263,6 +1316,7 @@ export class TypeInferrer {
         return undefined;
     }
     inferResponseBody(sourceFile, request, extractionConfig) {
+        request = this.withoutForeignLocator(sourceFile, request);
         const node = this.resolveTargetNode(sourceFile, request);
         if (!node) {
             // Line-only anchor (no span, no expression text) — the shape the scanner
@@ -1998,6 +2052,78 @@ export class TypeInferrer {
             return undefined;
         return accept(parent) ? parent : undefined;
     }
+    /**
+     * A call's result read through the library store's label (carrick#2818):
+     * `whole` is the awaited type, `member` is that member of every non-nullish
+     * constituent of it, and `parse` is the awaited return of that method as the
+     * call returns it (a thenable's own `json()` is not on what it resolves to).
+     * A part the type lacks is a decided abstain, so the capture's own re-read
+     * of the raw call does not publish the envelope in its place.
+     */
+    labelledCallResult(request, callExpr, label) {
+        const location = this.getNodeLocation(callExpr);
+        const raw = callExpr.getType();
+        const awaited = this.awaitedBeyondPromise(raw) ?? this.unwrapPromiseType(raw);
+        const missing = (what) => this.decidedAbstain(request, location, {
+            path: '',
+            kind: 'unknown',
+            reason: 'result_member_missing',
+            detail: `the library's label names ${what}, which this call's type does not have`,
+        });
+        let read;
+        if ('whole' in label) {
+            read = [awaited];
+        }
+        else if ('member' in label) {
+            const name = label.member[0];
+            read = [];
+            const constituents = awaited.isUnion() ? awaited.getUnionTypes() : [awaited];
+            for (const constituent of constituents) {
+                if (isNullishType(constituent))
+                    continue;
+                const held = this.readMemberType(constituent, name, callExpr);
+                if (!held)
+                    return missing(`the member '${name}'`);
+                for (const part of held.isUnion() ? held.getUnionTypes() : [held]) {
+                    if (!isNullishType(part))
+                        read.push(part);
+                }
+            }
+            if (read.length === 0)
+                return missing(`the member '${name}'`);
+        }
+        else {
+            const method = (this.readMemberType(raw, label.parse, callExpr) ??
+                this.readMemberType(awaited, label.parse, callExpr));
+            const signature = method
+                ?.getCallSignatures()
+                .find((candidate) => candidate.getParameters().every((parameter) => {
+                const declaration = parameter.getDeclarations()[0];
+                return (!!declaration &&
+                    Node.isParameterDeclaration(declaration) &&
+                    (declaration.hasQuestionToken() ||
+                        declaration.hasInitializer() ||
+                        declaration.isRestParameter()));
+            }));
+            if (!signature)
+                return missing(`the method '${label.parse}'`);
+            const returned = signature.getReturnType();
+            const parsed = this.awaitedBeyondPromise(returned) ?? this.unwrapPromiseType(returned);
+            // A type parameter of the method that nothing at the call instantiates
+            // (`json<J>()`) states no type: the caller supplies it.
+            if (parsed.isTypeParameter())
+                return missing(`a concrete type from '${label.parse}'`);
+            read = [parsed];
+        }
+        const texts = [];
+        for (const part of read) {
+            const text = this.structuralTextFromType(part, callExpr) ?? typeText(part, callExpr);
+            if (!texts.includes(text))
+                texts.push(text);
+        }
+        const anchor = read.length === 1 ? this.unwrapArrayLevels(this.unwrapPromiseType(read[0])) : undefined;
+        return this.createInferredType(request, texts.join(' | '), false, location, undefined, anchor ? this.primaryTypeSymbol(anchor.element) : undefined, anchor?.depth, anchor ? this.primaryTypeSymbolSource(anchor.element) : undefined);
+    }
     inferCallResult(sourceFile, request, extractionConfig) {
         const callExpr = this.resolveTargetCallExpression(sourceFile, request);
         // A call's result is read off the call. A locator that finds no call names
@@ -2007,6 +2133,12 @@ export class TypeInferrer {
             this.log(`Call-result locator at ${request.file_path}:${request.line_number} finds no call; leaving unresolved`);
             return null;
         }
+        // carrick#2818: the library store labels which part of this call's result
+        // holds the response body. The label is the library's own statement, so it
+        // is read before any wrapper rule of the service's extraction config.
+        if (request.result) {
+            return this.labelledCallResult(request, callExpr, request.result);
+        }
         // Walk up from the already-found call expression instead of re-searching
         const func = this.findContainingFunctionForNode(callExpr);
         const use = this.resolveCallResultTerminalNode(callExpr, func);
@@ -4624,6 +4756,14 @@ export class TypeInferrer {
         }
         return readings;
     }
+    /**
+     * The type of `type`'s member `name` at `node`, or `undefined` when the type
+     * has no such member. The one property read the payload-property rules and
+     * the library store's result label (carrick#2818) share.
+     */
+    readMemberType(type, name, node) {
+        return type.getProperty(name)?.getTypeAtLocation(node);
+    }
     /**
      * Extract the payload type from a matched wrapper. Returns null when the
      * rule matched the wrapper but no payload is recoverable from generics or
@@ -4696,11 +4836,10 @@ export class TypeInferrer {
         if (rule.payloadPropertyPath && rule.payloadPropertyPath.length > 0) {
             let currentType = type;
             for (const propName of rule.payloadPropertyPath) {
-                const prop = currentType.getProperty(propName);
-                if (!prop) {
+                const propType = this.readMemberType(currentType, propName, node);
+                if (!propType) {
                     break;
                 }
-                const propType = prop.getTypeAtLocation(node);
                 currentType = propType;
             }
             if (currentType !== type) {
@@ -6730,10 +6869,10 @@ export class TypeInferrer {
      * registration node itself, so the schema anchors need both halves.
      */
     registrationAtLine(sourceFile, line) {
-        for (const node of sourceFile.getDescendants()) {
-            if ((Node.isCallExpression(node) ||
-                Node.isObjectLiteralExpression(node)) &&
-                startLineOf(node) === line) {
+        for (const entry of descendantsOnLine(sourceFile, line)) {
+            if (entry.kind === SyntaxKind.CallExpression ||
+                entry.kind === SyntaxKind.ObjectLiteralExpression) {
+                const node = wrap(sourceFile, entry);
                 const handler = this.resolveRegisteredHandler(node);
                 if (handler) {
                     return { registration: node, handler };
@@ -9307,20 +9446,23 @@ export class TypeInferrer {
      * 5. Return smallest matching node closest to target line
      */
     findNodeByText(sourceFile, expressionText, lineNumber, searchRadius = 5) {
-        const allNodes = sourceFile.getDescendants().filter((node) => {
-            if (Node.isSourceFile(node))
-                return false;
-            if (node.getKind() === SyntaxKind.SyntaxList)
-                return false;
-            return true;
-        });
-        return this.matchByText(allNodes, expressionText, lineNumber, searchRadius);
+        // Only the window's nodes are wrapped: `matchByText` keeps no other.
+        const inWindow = lineNumber
+            ? descendantsOnLines(sourceFile, lineNumber - searchRadius, lineNumber + searchRadius)
+            : descendantsOf(sourceFile);
+        const nodes = inWindow
+            .filter((entry) => entry.kind !== SyntaxKind.SyntaxList)
+            .map((entry) => wrap(sourceFile, entry));
+        return this.matchByText(nodes, expressionText, lineNumber, searchRadius);
     }
     /**
      * Find a CallExpression by matching expression text near a target line.
      */
     findCallExpressionByText(sourceFile, expressionText, lineNumber, searchRadius = 5) {
-        const callExpressions = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
+        const inWindow = lineNumber
+            ? callsOf(sourceFile).filter((entry) => entry.line >= lineNumber - searchRadius && entry.line <= lineNumber + searchRadius)
+            : callsOf(sourceFile);
+        const callExpressions = inWindow.map((entry) => wrap(sourceFile, entry));
         return this.matchByText(callExpressions, expressionText, lineNumber, searchRadius);
     }
     /**
@@ -9606,23 +9748,15 @@ export class TypeInferrer {
         });
     }
     findNodeAtSpan(sourceFile, spanStart, spanEnd) {
-        const allNodes = sourceFile.getDescendants();
-        const containing = allNodes.filter((node) => {
-            if (Node.isSourceFile(node))
-                return false;
-            // Skip SyntaxList nodes as they have unreliable types
-            if (node.getKind() === SyntaxKind.SyntaxList)
-                return false;
-            const start = node.getStart();
-            const end = node.getEnd();
-            return start <= spanStart && spanEnd <= end;
-        });
+        const containing = descendantsOf(sourceFile).filter(
+        // Skip SyntaxList nodes as they have unreliable types
+        (entry) => entry.kind !== SyntaxKind.SyntaxList && entry.start <= spanStart && spanEnd <= entry.end);
         if (containing.length === 0) {
             return undefined;
         }
-        return containing.reduce((best, current) => {
-            const bestRange = best.getEnd() - best.getStart();
-            const currentRange = current.getEnd() - current.getStart();
+        const best = containing.reduce((best, current) => {
+            const bestRange = best.end - best.start;
+            const currentRange = current.end - current.start;
             // Prefer exact matches, then smallest containing
             const bestDelta = Math.abs(bestRange - (spanEnd - spanStart));
             const currentDelta = Math.abs(currentRange - (spanEnd - spanStart));
@@ -9635,10 +9769,9 @@ export class TypeInferrer {
             // span published `any` as its request body. Descendants follow their
             // ancestors in `getDescendants()` order, so a tied later node inside the
             // current best is the deeper one.
-            return current.getStart() >= best.getStart() && current.getEnd() <= best.getEnd()
-                ? current
-                : best;
+            return current.start >= best.start && current.end <= best.end ? current : best;
         });
+        return wrap(sourceFile, best);
     }
     findCallExpressionAtSpan(sourceFile, spanStart, spanEnd) {
         // Tolerate the SWC span convention (#336): the scanner sends raw SWC
@@ -9658,23 +9791,18 @@ export class TypeInferrer {
         // more and the slack only widens the candidate set. Removing it is
         // carrick#823, which wants its own before/after.
         const SPAN_SLACK = 2;
-        const callExpressions = sourceFile
-            .getDescendantsOfKind(SyntaxKind.CallExpression);
-        const candidates = callExpressions.filter((expr) => {
-            const start = expr.getStart();
-            const end = expr.getEnd();
-            return start - SPAN_SLACK <= spanStart && spanEnd <= end + SPAN_SLACK;
-        });
+        const candidates = callsOf(sourceFile).filter((entry) => entry.start - SPAN_SLACK <= spanStart && spanEnd <= entry.end + SPAN_SLACK);
         if (candidates.length === 0) {
             return undefined;
         }
-        return candidates.reduce((best, current) => {
-            const bestRange = best.getEnd() - best.getStart();
-            const currentRange = current.getEnd() - current.getStart();
+        const best = candidates.reduce((best, current) => {
+            const bestRange = best.end - best.start;
+            const currentRange = current.end - current.start;
             const bestDelta = Math.abs(bestRange - (spanEnd - spanStart));
             const currentDelta = Math.abs(currentRange - (spanEnd - spanStart));
             return currentDelta < bestDelta ? current : best;
         });
+        return wrap(sourceFile, best);
     }
     // ===========================================================================
     // Type Utilities
@@ -9845,3 +9973,7 @@ function nodeAtSpan(span) {
     }
     return node;
 }
+/** `undefined`, `null` and `void`: what a labelled read removes (carrick#2818). */
+function isNullishType(type) {
+    return type.isUndefined() || type.isNull() || type.getText() === 'void';
+}

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

@@ -3,6 +3,7 @@
  * These types define the JSON messages exchanged between Rust and the Node.js sidecar
  */
 import type { ResponseModes } from './response-modes.js';
+import type { ResultLabel } from './capture/api.js';
 /**
  * The kind of type inference to perform
  */
@@ -543,6 +544,8 @@ export type LibraryClaim = {
     key_labels?: Record<string, KeyLabel>;
     name_scope?: NameScope;
     picker?: string;
+    /** Which part of what the maker returns holds the value its function resolves to; read by a `result` claim, never by this one. */
+    result?: ResultShape;
 } | {
     /** A member that returns a receiver bound to a name (a channel, room or queue). */
     kind: 'scope';
@@ -603,6 +606,23 @@ export type LibraryClaim = {
     yields?: Yields;
     /** Route fields (#2474 R0), `receive` only: where the handler's request holds its path and method. */
     request?: RequestAt;
+    /** Which part of what the call returns holds the response; read by a `result` claim, never by this one. */
+    result?: ResultShape;
+} | {
+    /**
+     * Which part of what a call returns holds the response body, judged over
+     * every overload of `member` (after `path`) on the receiver; `member`
+     * null is the receiver itself called (carrick#2817). `form` says whether
+     * the call is a maker's or an op's.
+     */
+    kind: 'result';
+    form: 'make' | 'op';
+    member: string | null;
+    path?: string[];
+    on?: ClaimOn;
+    of?: string;
+    picker?: string;
+    result: ResultShape;
 } | {
     /** A name the library emits itself, spelled in one of `member`'s parameters. */
     kind: 'reserved';
@@ -713,6 +733,11 @@ export interface InferRequestItem {
     param_name?: string;
     /** The member of a request options literal that carries the body (`request_config`). */
     member?: string;
+    /**
+     * carrick#2818: the library store's label for the call's result, naming the
+     * part that holds the response body. Read for `call_result`.
+     */
+    result?: ResultLabel;
 }
 /**
  * Response status
@@ -1005,7 +1030,34 @@ export interface SurfaceKey {
 export interface SurfaceSignature {
     params: SurfaceParam[];
     returns: string;
+    /**
+     * Which parts of the awaited return could hold the response body
+     * (carrick#2817). Left out of the surface hash. Absent when the signature
+     * returns nothing.
+     */
+    result_candidates?: SurfaceResultCandidates;
 }
+/** What a signature's return offers as its result, by rule R (`result-candidates.ts`). */
+export interface SurfaceResultCandidates {
+    /** The caller supplies the whole return as a type argument: `whole` is the only candidate. */
+    whole_decided: boolean;
+    /** Properties that carry a type parameter of the signature, sorted. */
+    members: string[];
+    /** Methods with no required argument that return a bare type parameter of their own, sorted. */
+    parse: string[];
+}
+/**
+ * Which part of what a call returns holds the response the server sent:
+ * exactly one of the whole awaited return, one member of it, or the awaited
+ * return of one of its parse methods (carrick#2817).
+ */
+export type ResultShape = {
+    whole: true;
+} | {
+    member: [string];
+} | {
+    parse: string;
+};
 export interface SurfaceMember {
     name: string;
     /** Declared by the receiver's home packages (not only inherited from another package). */

package/sidecar/dist/src/unwidened.js

@@ -303,12 +303,21 @@ export function mapBack(pos, insertions) {
     }
     return pos - shift;
 }
+/**
+ * Diagnostics about how the program was assembled (a file outside `rootDir`,
+ * a file missing from a composite project's list, an output that would
+ * overwrite its input), not about the text of the file they are reported on.
+ * The compiler attaches them to an import or a root file, and whether one is
+ * present depends on which program build ran last, so a before/after
+ * comparison would read it as added by a rewrite (carrick#2898).
+ */
+const PROGRAM_ASSEMBLY_CODES = new Set([6059, 6305, 6307]);
 /** Syntactic and semantic diagnostics reported in this file. */
 export function fileDiagnostics(sourceFile) {
     const program = sourceFile.getProject().getProgram().compilerObject;
     const node = sourceFile.compilerNode;
     return [...program.getSyntacticDiagnostics(node), ...program.getSemanticDiagnostics(node)]
-        .filter((d) => d.file === node && d.start !== undefined)
+        .filter((d) => d.file === node && d.start !== undefined && !PROGRAM_ASSEMBLY_CODES.has(d.code))
         .map((d) => ({
         start: d.start,
         code: d.code,