carrick 0.3.111 → 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') &&
@@ -1516,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);
@@ -1928,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
@@ -2183,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);
@@ -4681,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
@@ -4691,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.
@@ -4711,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
@@ -4730,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) ||
@@ -5388,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).
@@ -6785,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:
@@ -6840,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
@@ -6849,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.