carrick 0.3.110 → 0.3.112

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

@@ -257,6 +257,83 @@ function typeText(type, enclosingNode) {
  * `text` is `string`, alone or beside `null` and `undefined` in either order:
  * the only payload a raw-text read publishes (carrick#1842).
  */
+/**
+ * Source text with every plain string literal written in double quotes:
+ * `'/a'`, `"/a"` and an interpolation-free `` `/a` `` are one value, so text
+ * that differs only in its quotes compares equal (carrick#2056).
+ *
+ * The text is read left to right, pairing quotes the way the scanner does,
+ * so a template's closing backtick never pairs with the next template's
+ * opening one. A literal holding a quote, a backslash or an interpolation is
+ * copied as it is, and so is an unterminated one with everything after it.
+ */
+export function canonicalStringQuotes(text) {
+    const isQuote = (ch) => ch === "'" || ch === '"' || ch === '`';
+    // The index just past the literal opening at `start`, or -1.
+    const literalEnd = (start) => {
+        const quote = text[start];
+        let j = start + 1;
+        while (j < text.length) {
+            const ch = text[j];
+            if (ch === '\\') {
+                j += 2;
+            }
+            else if (ch === quote) {
+                return j + 1;
+            }
+            else if (quote === '`' && ch === '$' && text[j + 1] === '{') {
+                const close = codeEnd(j + 2);
+                if (close < 0)
+                    return -1;
+                j = close + 1;
+            }
+            else {
+                j++;
+            }
+        }
+        return -1;
+    };
+    // The index of the `}` that closes an interpolation whose code starts at `start`, or -1.
+    const codeEnd = (start) => {
+        let depth = 0;
+        let j = start;
+        while (j < text.length) {
+            const ch = text[j];
+            if (isQuote(ch)) {
+                const end = literalEnd(j);
+                if (end < 0)
+                    return -1;
+                j = end;
+                continue;
+            }
+            if (ch === '{')
+                depth++;
+            if (ch === '}') {
+                if (depth === 0)
+                    return j;
+                depth--;
+            }
+            j++;
+        }
+        return -1;
+    };
+    let out = '';
+    let i = 0;
+    while (i < text.length) {
+        if (!isQuote(text[i])) {
+            out += text[i];
+            i++;
+            continue;
+        }
+        const end = literalEnd(i);
+        if (end < 0)
+            return out + text.slice(i);
+        const body = text.slice(i + 1, end - 1);
+        out += /['"`\\]|\$\{/.test(body) ? text.slice(i, end) : `"${body}"`;
+        i = end;
+    }
+    return out;
+}
 function isBareStringText(text) {
     const members = text.split('|').map((member) => member.trim());
     return (members.includes('string') &&
@@ -1048,7 +1125,11 @@ export class TypeInferrer {
             // argument is the route path, not a payload. The span locator falls
             // back to exactly this shape when no payload expression was reported,
             // so drilling here would put the path literal's type in the manifest.
-            const registersCallback = args.some((arg) => Node.isArrowFunction(arg) || Node.isFunctionExpression(arg));
+            // A call handed a function whose result is plain data is not a
+            // registration but the payload: `rows.map((r) => ({ ... }))` sends the
+            // list, not the callback's return (carrick#2055).
+            const registersCallback = args.some((arg) => Node.isArrowFunction(arg) || Node.isFunctionExpression(arg)) &&
+                !this.callResultIsPlainData(node);
             if (registersCallback) {
                 // A registration that DECLARES its response contract in a schema needs
                 // no indirection: the declaration is the contract the framework
@@ -1099,7 +1180,9 @@ export class TypeInferrer {
             // `typeText` keeps the bare name `Payment`, which dangles in the
             // source-less cross-repo bundle → `any` → unverifiable. Expand the
             // resolved object structurally so the real members land in the bundle.
-            typeString = this.expandResolvedTypeStructural(resolved, typeString, this.wireFormatFor(request));
+            // The name it falls back to is the awaited one: a located call under
+            // `await` sends what it resolves to, never the promise (carrick#2055).
+            typeString = this.expandResolvedTypeStructural(resolved, typeText(resolved, payloadNode), this.wireFormatFor(request));
         }
         const anchor = this.unwrapArrayLevels(this.unwrapPromiseType(payloadType));
         return this.createInferredType(request, typeString, false, this.getNodeLocation(payloadNode), unwrapResult.wasUnwrapped ? unwrapResult.typeString : undefined, this.primaryTypeSymbol(anchor.element), anchor.depth, this.primaryTypeSymbolSource(anchor.element));
@@ -1257,6 +1340,8 @@ export class TypeInferrer {
      * returns the repo's own type (`toInstance(View, plain)`) is the payload.
      */
     callResultIsPayload(call) {
+        if (this.callResultIsPlainData(call))
+            return true;
         const { element } = this.unwrapArrayLevels(this.unwrapPromiseType(call.getType()));
         if (this.symbolIsLibOrExternalOrigin(element.getSymbol() ?? element.getAliasSymbol())) {
             return false;
@@ -1266,6 +1351,58 @@ export class TypeInferrer {
         // the call that built it would publish what it was built from.
         return this.nodeCarriesPayloadContract(call, false, false);
     }
+    /**
+     * True when a located call evaluates to plain data, so it is the payload
+     * whatever its arguments and wherever its type is declared (carrick#2055).
+     *
+     * `rows.map(toDto)`, `rows.filter(cb)` and `listItems(ownerId)` produce the
+     * list a route sends. Read as a send, the first produced the mapper's
+     * function type, the second a callback's return, and the third `string`.
+     * What a send or a registration hands back is never plain data: a reply
+     * builder or a router carries methods, a bare send returns `void`, and a
+     * serialiser returns a primitive. So the result alone tells them apart.
+     *
+     * Plain data, once promise levels are taken off: an object with at least
+     * one member, no call or construct signature, and no member that is itself
+     * callable; an array of one; or a union whose members other than `null` and
+     * `undefined` all are. Tuples and empty objects are left to the callers'
+     * own reading.
+     */
+    callResultIsPlainData(call) {
+        const isPlainData = (type, depth) => {
+            if (depth > 3)
+                return false;
+            if (type.isAny() || type.isUnknown() || type.isNever())
+                return false;
+            if (type.isUnion()) {
+                const members = type
+                    .getUnionTypes()
+                    .filter((member) => !member.isNull() && !member.isUndefined());
+                return members.length > 0 && members.every((member) => isPlainData(member, depth + 1));
+            }
+            if (type.isIntersection()) {
+                return type.getIntersectionTypes().every((member) => isPlainData(member, depth + 1));
+            }
+            const element = type.getArrayElementType();
+            if (element)
+                return isPlainData(element, depth + 1);
+            if (!type.isObject() || type.isTuple() || this.isCallableType(type))
+                return false;
+            if (this.typeIsOrContainsResponseMachinery(type))
+                return false;
+            const members = type.getProperties();
+            const indexed = type.getStringIndexType() ?? type.getNumberIndexType();
+            if (members.length === 0 && !indexed)
+                return false;
+            const callable = (held) => held.isUnion()
+                ? held.getUnionTypes().some((member) => this.isCallableType(member))
+                : this.isCallableType(held);
+            if (indexed && callable(indexed))
+                return false;
+            return members.every((member) => !callable(member.getTypeAtLocation(call)));
+        };
+        return isPlainData(this.unwrapPromiseType(call.getType()), 0);
+    }
     /**
      * The wire representation a request's printed type takes. A route response
      * is serialised as JSON by every sender this layer reads a payload out of,
@@ -1320,7 +1457,8 @@ export class TypeInferrer {
      *
      * Returns `undefined` when this does not apply, which leaves the caller's
      * own reading of the located expression untouched:
-     *  - the row's line is not a route registration;
+     *  - the row's line is neither a route registration nor a line inside the
+     *    handler the located send sits in;
      *  - the located expression is neither a send nor the argument of one;
      *  - that send is not one the handler returns;
      *  - it is a success send and the only one that survives, so the join would
@@ -1333,11 +1471,18 @@ export class TypeInferrer {
      * or the redirect location back in.
      */
     inferFromResponseSites(sourceFile, request, located, extractionConfig) {
-        if (!this.registrationAtLine(sourceFile, request.line_number))
-            return undefined;
         const func = this.findContainingFunctionForNode(located);
         if (!func)
             return undefined;
+        // The row's line is a registration, or a line inside the handler the
+        // located send sits in (carrick#2005: a file-based route's row names the
+        // send's own line, and a send's line is no registration). A row whose
+        // line is outside that function says nothing about it.
+        if (!this.registrationAtLine(sourceFile, request.line_number) &&
+            !(func.getStartLineNumber() <= request.line_number &&
+                request.line_number <= func.getEndLineNumber())) {
+            return undefined;
+        }
         const branches = this.responseReturnedExpressions(func).flatMap((expression) => this.expandResponseBranches(expression, 0));
         if (branches.length === 0)
             return undefined;
@@ -1352,10 +1497,10 @@ export class TypeInferrer {
         if (!locatedBranch)
             return undefined;
         const dropped = (status) => status === 'error' || status === 'redirect';
-        const siteStatus = this.responseSiteStatus(site);
+        const siteStatus = this.responseSiteStatus(site, true);
         const survivors = [];
         for (const branch of branches) {
-            const status = branch === locatedBranch ? siteStatus : this.responseSiteStatus(branch);
+            const status = branch === locatedBranch ? siteStatus : this.responseSiteStatus(branch, true);
             if (status === 'variable') {
                 this.log(`Response status at ${request.file_path}:${this.getNodeLocation(branch).start_line} ` +
                     'is not a literal; keeping that send in the route contract');
@@ -1448,8 +1593,12 @@ export class TypeInferrer {
     }
     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
+        // nothing this can read, and whatever other node its text overlaps is not
+        // the call's result (carrick#2056); the retype abstains on the same miss.
         if (!callExpr) {
-            return this.inferExpression(sourceFile, request, extractionConfig);
+            this.log(`Call-result locator at ${request.file_path}:${request.line_number} finds no call; leaving unresolved`);
+            return null;
         }
         // Walk up from the already-found call expression instead of re-searching
         const func = this.findContainingFunctionForNode(callExpr);
@@ -1860,18 +2009,25 @@ export class TypeInferrer {
                 parent.getInitializer() === current) {
                 break;
             }
-            if (!Node.isParenthesizedExpression(parent) &&
-                !Node.isAwaitExpression(parent) &&
-                !Node.isNonNullExpression(parent) &&
-                !Node.isAsExpression(parent) &&
-                !Node.isTypeAssertion(parent) &&
-                !Node.isSatisfiesExpression(parent)) {
+            if (!this.wrapsReadTransparently(parent)) {
                 return undefined;
             }
             current = parent;
         }
         return typeNode;
     }
+    /**
+     * A wrapper between a body read and the binding it initialises that leaves
+     * the read's value as it is: `await`, parentheses, `!`, a cast, `satisfies`.
+     */
+    wrapsReadTransparently(node) {
+        return (Node.isParenthesizedExpression(node) ||
+            Node.isAwaitExpression(node) ||
+            Node.isNonNullExpression(node) ||
+            Node.isAsExpression(node) ||
+            Node.isTypeAssertion(node) ||
+            Node.isSatisfiesExpression(node));
+    }
     /**
      * A stated type with `any` or `unknown` written anywhere in it (`unknown`,
      * `Record<string, unknown>`, `{ items: any[] }`) leaves a position open: it
@@ -2115,6 +2271,24 @@ export class TypeInferrer {
                 'to one body field by a keyed decorator; publishing the body those fields make up');
             return this.declaredRequestInferredType(request, keyedBody, this.getNodeLocation(located));
         }
+        // carrick#2057: the locator named a member of the body the handler parsed
+        // (`body.items` after `const body = (await request.json()) as ImportBody`,
+        // or a binding destructured from that read). A member is one field of the
+        // body, so publishing its type states the whole body is that field. The
+        // body is what the source states at the read; where it states nothing,
+        // nothing is published.
+        const bodyRead = this.parsedBodyReadHolding(located);
+        if (bodyRead) {
+            const stated = this.requestStatedAtBodyRead(request, bodyRead);
+            if (stated) {
+                this.log(`Request locator at ${request.file_path}:${request.line_number} names a member of the ` +
+                    'body its handler parses; publishing the body the source states at that read');
+                return stated;
+            }
+            this.log(`Request locator at ${request.file_path}:${request.line_number} names a member of the ` +
+                'body its handler parses, and the source states no type at that read; leaving unresolved');
+            return null;
+        }
         // Mirror inferCallResult: strip `await`/`as`/parens/`!` so the inner
         // expression's type (not the surrounding `Promise<any>`) is read.
         let unwrapped = this.unwrapExpressionNode(located);
@@ -2147,8 +2321,8 @@ export class TypeInferrer {
                     path: '',
                     kind: 'unknown',
                     reason: 'no_request_body',
-                    detail: `the located argument is the call's request config, and it sets no '${inCall.member}' ` +
-                        'member, which is where the call takes its body, so the call sends no request body',
+                    detail: `the call's request config sets no '${inCall.member}' member, which is where the call ` +
+                        'takes its body, so the call sends no request body',
                 },
             ];
             return abstain;
@@ -4436,7 +4610,7 @@ export class TypeInferrer {
      * A status in the FIRST argument is a field of the body and is never read.
      * No method or framework name is consulted anywhere.
      */
-    responseSiteStatus(expression) {
+    responseSiteStatus(expression, readChain = false) {
         const call = this.peelTransparentExpression(expression);
         if (!Node.isCallExpression(call) && !Node.isNewExpression(call)) {
             return 'undecided';
@@ -4459,6 +4633,14 @@ export class TypeInferrer {
         }
         if (variable)
             return 'variable';
+        // carrick#2005: a status an earlier call of the same chain states
+        // (`reply.status(401).json(body)`). Read only where the caller asks for
+        // it; the return walk does not read it yet (carrick#1962).
+        if (readChain) {
+            const chained = this.chainStatus(call);
+            if (chained)
+                return chained;
+        }
         const typed = this.sendResultStatusCodes(call);
         if (typed) {
             const kind = classifyStatusCodes(typed);
@@ -4467,6 +4649,37 @@ export class TypeInferrer {
         }
         return 'undecided';
     }
+    /**
+     * The status an earlier call of a send's own chain states: the receiver
+     * calls `call` is invoked on (`a.status(401).json(body)` has `a.status(401)`),
+     * innermost last. Each receiver call's first argument is read by the rule
+     * an argument past a body is, so a numeric literal or a literal-typed value
+     * counts and a plain `number` is `variable`. `undefined` when no receiver
+     * call states a status. No method name is consulted: a receiver call that
+     * is handed no status-shaped value says nothing.
+     */
+    chainStatus(call) {
+        if (!Node.isCallExpression(call))
+            return undefined;
+        let callee = call.getExpression();
+        while (Node.isPropertyAccessExpression(callee)) {
+            const receiver = this.peelTransparentExpression(callee.getExpression());
+            if (!Node.isCallExpression(receiver))
+                return undefined;
+            const first = receiver.getArguments()[0];
+            if (first) {
+                const read = this.statedStatusCodes(this.peelTransparentExpression(first));
+                if (read === 'variable')
+                    return 'variable';
+                if (read) {
+                    const kind = classifyStatusCodes(read);
+                    return kind === 'mixed' ? 'variable' : kind;
+                }
+            }
+            callee = receiver.getExpression();
+        }
+        return undefined;
+    }
     /**
      * The HTTP status codes an argument states, `'variable'` when it is a
      * status-shaped value the source does not fix, or `undefined` when it says
@@ -4574,6 +4787,25 @@ export class TypeInferrer {
         }
         return [expression];
     }
+    /**
+     * The symbol an anchor is named from: the type's own symbol, unless that
+     * symbol's name is synthetic (`__type`, `__object`, ...), in which case the
+     * alias symbol (carrick#2148).
+     *
+     * `type Widget = { id: string }` and an instantiated `Page<Order>` carry
+     * the anonymous `__type` as their own symbol and the alias as their alias
+     * symbol. Reading the own symbol first and stopping because it is truthy
+     * left every object-literal alias without an anchor, while the same shape
+     * declared as an interface had one. The own symbol still wins whenever it
+     * has a real name, so every type anchored before keeps its anchor.
+     */
+    anchorSymbolOf(type) {
+        const own = type.getSymbol();
+        if (own && !own.getName().startsWith('__')) {
+            return own;
+        }
+        return type.getAliasSymbol() ?? own;
+    }
     /**
      * The deterministic source symbol of a resolved type (`Payment` for a payload
      * typed `Payment`), or `undefined` when there is no single user-defined
@@ -4584,7 +4816,7 @@ export class TypeInferrer {
      * `primary_type_symbol` so the manifest anchor no longer depends on the LLM.
      */
     primaryTypeSymbol(type) {
-        const name = (type.getSymbol() || type.getAliasSymbol())?.getName();
+        const name = this.anchorSymbolOf(type)?.getName();
         // Reject the compiler's synthetic names for anonymous shapes (`__type`,
         // `__object`, `__function`, …). They are not user-facing type names, so
         // they would be a meaningless — and non-resolvable — anchor.
@@ -4604,7 +4836,8 @@ export class TypeInferrer {
      * declarations IN its `source_file`, so the request must point at the file
      * that actually declares the tsc-witnessed payload type.
      *
-     * The declarations read are those of the type's own symbol, so a name
+     * The declarations read are those of the symbol the anchor is named from
+     * (`anchorSymbolOf`: the type's own symbol, or its alias's), so a name
      * imported through a barrel reports the file that declares it, and a name
      * two files declare reports the one this type resolves to. A declaration in
      * an installed package or a TypeScript lib is reported as it is found, as
@@ -4623,7 +4856,7 @@ export class TypeInferrer {
         if (this.primaryTypeSymbol(type) === undefined) {
             return undefined;
         }
-        const decls = (type.getSymbol() || type.getAliasSymbol())?.getDeclarations() ?? [];
+        const decls = this.anchorSymbolOf(type)?.getDeclarations() ?? [];
         const declaring = decls.find((d) => Node.isInterfaceDeclaration(d) ||
             Node.isTypeAliasDeclaration(d) ||
             Node.isClassDeclaration(d) ||
@@ -5281,6 +5514,56 @@ export class TypeInferrer {
         }
         return undefined;
     }
+    /**
+     * The platform body read whose result `located` is a MEMBER of, or
+     * `undefined` (carrick#2057).
+     *
+     * A member is a property or element access off a binding, or a name
+     * destructured out of one. The binding must be initialised by the body read
+     * `platformBodyReadIn` finds in the function that declares it, with only
+     * transparent wrappers between the two (`await`, parentheses, `!`, a cast,
+     * `satisfies`). The binding itself is not a member, and neither is a member
+     * of anything else (a query object, a parameter, an outbound response).
+     */
+    parsedBodyReadHolding(located) {
+        let node = this.unwrapExpressionNode(located);
+        let member = false;
+        while (Node.isPropertyAccessExpression(node) ||
+            Node.isElementAccessExpression(node) ||
+            Node.isNonNullExpression(node) ||
+            Node.isParenthesizedExpression(node)) {
+            if (Node.isPropertyAccessExpression(node) || Node.isElementAccessExpression(node)) {
+                member = true;
+            }
+            node = node.getExpression();
+        }
+        if (!Node.isIdentifier(node))
+            return undefined;
+        let declaration = node.getSymbol()?.getDeclarations()?.[0];
+        while (declaration && Node.isBindingElement(declaration)) {
+            member = true;
+            declaration = declaration.getParent()?.getParent();
+        }
+        if (!member || !declaration || !Node.isVariableDeclaration(declaration))
+            return undefined;
+        const handler = this.findContainingFunctionForNode(declaration);
+        const read = handler ? this.platformBodyReadIn(handler) : undefined;
+        if (!read)
+            return undefined;
+        let current = read;
+        for (;;) {
+            const parent = current.getParent();
+            if (!parent)
+                return undefined;
+            if (parent === declaration) {
+                return declaration.getInitializer() === current ? read : undefined;
+            }
+            if (!this.wrapsReadTransparently(parent)) {
+                return undefined;
+            }
+            current = parent;
+        }
+    }
     /**
      * The request contract the source states AT a body read, or null when it
      * states none there (carrick#807).
@@ -5565,14 +5848,11 @@ export class TypeInferrer {
     requestBodyInCall(node) {
         if (Node.isCallExpression(node)) {
             const args = node.getArguments();
+            if (args.length === 1)
+                return this.requestObjectBody(args[0]);
             if (args.length < 2)
                 return { kind: 'none' };
-            const first = args[0].getType();
-            const stringLike = first.isString() ||
-                first.isStringLiteral() ||
-                first.isTemplateLiteral() ||
-                (first.isUnion() && first.getUnionTypes().every((t) => t.isString() || t.isStringLiteral()));
-            if (!stringLike)
+            if (!this.isStringLikeType(args[0].getType()))
                 return { kind: 'none' };
             const slots = this.requestBodySlots(node);
             for (let i = 1; i < args.length; i++) {
@@ -5608,6 +5888,80 @@ export class TypeInferrer {
         }
         return { kind: 'none' };
     }
+    /** A string, a string literal, a template literal, or a union of strings. */
+    isStringLikeType(type) {
+        return (type.isString() ||
+            type.isStringLiteral() ||
+            type.isTemplateLiteral() ||
+            (type.isUnion() && type.getUnionTypes().every((t) => t.isString() || t.isStringLiteral())));
+    }
+    /**
+     * carrick#1841, request half: a request call that states its URL on its one
+     * object argument (`client.post({ url: '/items', ...options })`, the way a
+     * generated client issues every operation). The method's own parameter
+     * types the body `unknown`, so the object is the only statement of it: its
+     * `body` member, the member `RequestInit` defines, written on the object or
+     * carried in by a spread whose type says what it is.
+     *
+     * - A `body` written after the object's last spread is the body.
+     * - Otherwise the object's own type has the answer. No `body` member, or
+     *   one typed `undefined` or `never`, means the call sends no body.
+     * - A member typed `any`, `unknown` or a type parameter, or one only the
+     *   compiler's default library declares (a spread `RequestInit` carries the
+     *   serialised `BodyInit`, not a payload), states no payload: abstain. So
+     *   does an object that carries another body-named member and no `body`.
+     *
+     * An object with no string-typed `url` member is not a request object.
+     */
+    requestObjectBody(arg) {
+        const literal = this.unwrapExpressionNode(arg);
+        if (!Node.isObjectLiteralExpression(literal))
+            return { kind: 'none' };
+        const objectType = literal.getType();
+        const url = objectType.getProperty('url');
+        if (!url || !this.isStringLikeType(url.getTypeAtLocation(literal).getNonNullableType())) {
+            return { kind: 'none' };
+        }
+        const from = "the request call's request object";
+        const member = 'body';
+        const properties = literal.getProperties();
+        const written = properties.findIndex((p) => (Node.isPropertyAssignment(p) || Node.isShorthandPropertyAssignment(p)) &&
+            p.getName() === member);
+        const spreadAfter = properties.some((p, i) => i > written && Node.isSpreadAssignment(p));
+        if (written >= 0 && !spreadAfter) {
+            const value = this.objectLiteralMemberValue(literal, member);
+            if (value)
+                return { kind: 'body', node: value, from };
+        }
+        const property = objectType.getProperty(member);
+        if (!property) {
+            const otherBodyMember = [...BODY_MEMBER_NAMES].some((name) => name !== member && objectType.getProperty(name));
+            return otherBodyMember
+                ? { kind: 'abstain', why: `the request object carries no '${member}' member but another body-named one` }
+                : { kind: 'no_body', member };
+        }
+        const type = property.getTypeAtLocation(literal);
+        if (type.isAny() || type.isUnknown() || type.isTypeParameter()) {
+            return { kind: 'abstain', why: `the request object's '${member}' member is not typed` };
+        }
+        const bare = type.getNonNullableType();
+        if (bare.isNever() || bare.isUndefined() || bare.isVoid()) {
+            return { kind: 'no_body', member };
+        }
+        if (bare.isAny() || bare.isUnknown() || bare.isTypeParameter()) {
+            return { kind: 'abstain', why: `the request object's '${member}' member is not typed` };
+        }
+        const program = this.project.getProgram().compilerObject;
+        const declarations = property.getDeclarations();
+        if (declarations.length > 0 &&
+            declarations.every((d) => program.isSourceFileDefaultLibrary(d.getSourceFile().compilerNode))) {
+            return {
+                kind: 'abstain',
+                why: `the request object's '${member}' member is the platform's serialised body, not a payload`,
+            };
+        }
+        return { kind: 'body_type', type: bare, at: literal, from };
+    }
     /**
      * The body a config-slot argument supplies through `member`: an object
      * literal's own member, or a variable's member read off its type.
@@ -6607,21 +6961,119 @@ export class TypeInferrer {
         // locator whose exact match failed would bind to the smallest embedded
         // sub-expression (pickBestMatch prefers small nodes), e.g. the 8-char
         // literal "active" inside a res.json object payload (#335).
+        //
+        // A node the text itself places strictly inside what it names is a
+        // fragment, however much of the text it covers (carrick#2056): the
+        // `new URLSearchParams(…)` inside a call's URL argument, or the object a
+        // callback nested in the named object returns. Only the node the text
+        // names, or a wrapper the text adds around it, may be bound this way. A
+        // fragment still points at what the text names where the source agrees
+        // with the text up to it: the enclosing node of the named kind whose text
+        // opens with the text's own opening up to the fragment (`new Response(`
+        // before a payload, when the text dropped the call's second argument).
         const MIN_REVERSE_MATCH_LEN = 8;
         const MIN_REVERSE_MATCH_COVERAGE = 0.5;
-        const substringMatches = candidates.filter((c) => c.text.includes(normalizedTarget) ||
-            (c.text.length >= MIN_REVERSE_MATCH_LEN &&
-                c.text.length >= normalizedTarget.length * MIN_REVERSE_MATCH_COVERAGE &&
-                normalizedTarget.includes(c.text)));
-        if (substringMatches.length > 0) {
-            // Prefer nodes where the LLM text is contained in the node text
-            const containingMatches = substringMatches.filter((c) => c.text.includes(normalizedTarget));
-            if (containingMatches.length > 0) {
-                return this.pickBestMatch(containingMatches.map((c) => c.node), lineNumber);
-            }
-            return this.pickBestMatch(substringMatches.map((c) => c.node), lineNumber);
+        const containingMatches = candidates.filter((c) => c.text.includes(normalizedTarget));
+        if (containingMatches.length > 0) {
+            return this.pickBestMatch(containingMatches.map((c) => c.node), lineNumber);
+        }
+        const reverseMatches = candidates.filter((c) => c.text.length >= MIN_REVERSE_MATCH_LEN &&
+            c.text.length >= normalizedTarget.length * MIN_REVERSE_MATCH_COVERAGE &&
+            normalizedTarget.includes(c.text));
+        if (reverseMatches.length === 0)
+            return undefined;
+        const named = this.locatorNames(normalizedTarget);
+        if (!named) {
+            return this.pickBestMatch(reverseMatches.map((c) => c.node), lineNumber);
+        }
+        const textOf = new Map(candidates.map((c) => [c.node, c.text]));
+        const bound = new Set();
+        for (const c of reverseMatches) {
+            if (named.texts.has(c.text)) {
+                bound.add(c.node);
+                continue;
+            }
+            const at = normalizedTarget.indexOf(c.text, named.rootStart + 1);
+            if (at < 0)
+                continue;
+            const opening = normalizedTarget.slice(named.rootStart, at);
+            const enclosing = c.node.getFirstAncestor((ancestor) => ancestor.getKind() === named.rootKind &&
+                textOf.get(ancestor)?.startsWith(opening) === true);
+            if (enclosing)
+                bound.add(enclosing);
         }
-        return undefined;
+        return bound.size > 0 ? this.pickBestMatch([...bound], lineNumber) : undefined;
+    }
+    /**
+     * What a locator's text names, read off its own parse (carrick#2056):
+     *
+     *  - `texts`: the normalized text of the expression it names and of each
+     *    wrapper it carries around it (`return`, a `const x =` binding, a label,
+     *    `await`, parentheses, a cast, `satisfies`, `!`). A node strictly inside
+     *    that expression is not among them;
+     *  - `rootKind` and `rootStart`: the innermost of those, its kind, and where
+     *    its text starts in the locator.
+     *
+     * `null` when the text does not parse as one expression or one statement:
+     * there is no structure to read, and the caller keeps its text rule.
+     */
+    locatorNames(normalizedTarget) {
+        const parsed = (source) => {
+            const file = ts.createSourceFile('locator.ts', source, ts.ScriptTarget.Latest, true);
+            const diagnostics = file
+                .parseDiagnostics;
+            return diagnostics && diagnostics.length === 0 && file.statements.length === 1 ? file : null;
+        };
+        // An object literal is a block as a statement, so try the text as an
+        // expression first.
+        const EXPRESSION_OPENING = '(\n';
+        const asExpression = parsed(`${EXPRESSION_OPENING}${normalizedTarget}\n);`);
+        let node;
+        let file = asExpression;
+        let offset = 0;
+        if (asExpression) {
+            const statement = asExpression.statements[0];
+            if (ts.isExpressionStatement(statement) && ts.isParenthesizedExpression(statement.expression)) {
+                node = statement.expression.expression;
+                offset = EXPRESSION_OPENING.length;
+            }
+        }
+        else {
+            file = parsed(normalizedTarget);
+            node = file?.statements[0];
+        }
+        if (!file || !node)
+            return null;
+        const texts = new Set();
+        let root;
+        while (node) {
+            if (ts.isLabeledStatement(node)) {
+                node = node.statement;
+            }
+            else if (ts.isExpressionStatement(node) || ts.isReturnStatement(node)) {
+                node = node.expression;
+            }
+            else if (ts.isVariableStatement(node)) {
+                const declarations = node.declarationList.declarations;
+                node = declarations.length === 1 ? declarations[0].initializer : undefined;
+            }
+            else {
+                texts.add(this.normalizeWhitespace(node.getText(file)));
+                root = node;
+                node =
+                    ts.isParenthesizedExpression(node) ||
+                        ts.isAwaitExpression(node) ||
+                        ts.isAsExpression(node) ||
+                        ts.isSatisfiesExpression(node) ||
+                        ts.isNonNullExpression(node) ||
+                        ts.isTypeAssertionExpression(node)
+                        ? node.expression
+                        : undefined;
+            }
+        }
+        if (!root)
+            return null;
+        return { texts, rootKind: root.kind, rootStart: root.getStart(file) - offset };
     }
     /**
      * Pick the best match from a set of candidate nodes:
@@ -6662,7 +7114,7 @@ export class TypeInferrer {
      * for the same reason.
      */
     normalizeWhitespace(text) {
-        return text
+        const collapsed = text
             .replace(/\s+/g, ' ')
             // A member chain broken before its dot (`client\n  .list(…)`) reads the
             // same as `client.list(…)`; a space around `.` / `?.` means nothing
@@ -6671,6 +7123,8 @@ export class TypeInferrer {
             .replace(/\s*,?\s*([}\)\]])/g, '$1')
             .replace(/([\(\[{])\s+/g, '$1')
             .trim();
+        // A string literal reads the same in any quotes (carrick#2056).
+        return canonicalStringQuotes(collapsed);
     }
     /**
      * Format a human-readable location string for error messages.
@@ -6877,11 +7331,11 @@ export class TypeInferrer {
             infer_kind: request.infer_kind,
             payload_type_string: payloadTypeString,
             primary_type_symbol: primaryTypeSymbol,
-            // Only meaningful relative to the anchor symbol: without an element
-            // symbol there is nothing for the explicit-bundle correction to match.
-            array_depth: primaryTypeSymbol !== undefined && arrayDepth !== undefined && arrayDepth > 0
-                ? arrayDepth
-                : undefined,
+            // Reported whether or not the element has a symbol (carrick#1967): an
+            // array whose element prints structurally is still a list. The Rust
+            // depth join copies it onto the model's symbol when the symbols agree,
+            // or, at a handler's send, when the element has no symbol to disagree.
+            array_depth: arrayDepth !== undefined && arrayDepth > 0 ? arrayDepth : undefined,
             // Same gate: a declaration source without an anchor symbol is useless.
             primary_type_symbol_source: primaryTypeSymbol !== undefined ? primaryTypeSymbolSource : undefined,
         };