carrick 0.3.125 → 0.3.127

package/sidecar/dist/src/position-rows.d.ts

@@ -71,6 +71,17 @@ export declare const FLAG_TOO_MANY = 16;
 export declare const FLAG_PUBLISHED = 32;
 /** The declaration is what its module exports as `export =` or `default` (carrick#2508). */
 export declare const FLAG_MODULE_DEFAULT = 64;
+/**
+ * A `call` row only: the call's declared return is the result of the
+ * function it is handed (`ReturnType<F>`, a bare type parameter the handed
+ * function returns, or an awaitable of one), so the library runs it and
+ * hands its result back (carrick#2634). Set when the call passes at least
+ * one argument at a function-typed parameter and every such parameter
+ * meets that return. The last free bit of the `u8`: the next flag widens
+ * the field and bumps the format. Pinned to `FLAG_RUNS_HANDED` in
+ * `src/position_rows.rs` by `position-rows-runs-handed.test.ts`.
+ */
+export declare const FLAG_RUNS_HANDED = 128;
 /** The most `decl` rows one position lists. */
 export declare const DECL_CAP = 16;
 /** The kinds {@link kindOf} gives a node; `decl` and `jsx` rows are written beside them. */
@@ -109,14 +120,26 @@ export interface PositionRowsOptions {
 export declare function writePositionRows(options: PositionRowsOptions): PositionRowsCounts;
 /** What a declaration's file is written as in a row's `decl_file`: `lib:<name>` for the default library, else `PathNames`'. */
 export declare function declaringFileName(program: ts.Program, paths: PathNames, file: ts.SourceFile): string | null;
+/** The installed package directory a resolved file lies in, and its name, as the module graph places it. */
+export type PackageDirectoryOf = (fileName: string) => {
+    directory: string;
+    name: string;
+} | undefined;
 /**
  * Names for the files rows point at, never an absolute path: relative to the
  * scanned repo's root when inside it (its real path too, so a root reached
  * through a link still contains its files), `lib:<name>` for the compiler's
  * default library, `pkg:<name>/<path>` for an installed package outside the
  * root, and nothing otherwise.
+ *
+ * An installed package outside the root is found by its path's last
+ * `node_modules` segment, else by `packageDirectoryOf`: the module graph's
+ * answer where the resolver serves a package from a cache whose path has no
+ * `node_modules` segment (carrick#2599). Either way the directory must hold a
+ * package.json.
  */
 export declare class PathNames {
+    private readonly packageDirectoryOf;
     private readonly roots;
     private readonly packageNames;
     /**
@@ -126,7 +149,7 @@ export declare class PathNames {
      */
     private readonly declaringFiles;
     private readonly declaringPackages;
-    constructor(scanRoot: string);
+    constructor(scanRoot: string, packageDirectoryOf?: PackageDirectoryOf);
     /** The root `file` lies under, and its path from there; `undefined` outside every root. */
     private inside;
     /** A request file's name: relative to the root, which every file the scanner sends is inside. */
@@ -151,5 +174,100 @@ export declare class PathNames {
      */
     scrubType(text: string): string;
 }
+/**
+ * The rows of one program's files. The `implementations` action
+ * (`implementations.ts`, carrick#2432) reads a call's symbol and names its
+ * answers through the same walker, so they join as the rows do.
+ */
+export declare class PositionWalker {
+    private readonly program;
+    private readonly paths;
+    private readonly loader;
+    private readonly checker;
+    /** Each module's exports by name, and its `export =` and `default` targets, aliases followed. */
+    private readonly moduleExports;
+    constructor(program: ts.Program, paths: PathNames, loader: ProjectLoader);
+    rowsOf(sourceFile: ts.SourceFile): PositionRow[];
+    private row;
+    /**
+     * Whether a call's declared return is the result of the function it is
+     * handed (carrick#2634), read from the declared signature through public
+     * checker calls. See {@link FLAG_RUNS_HANDED}.
+     */
+    private runsHanded;
+    /** The call signatures of a parameter's type, a type parameter read through its constraint, `null` and `undefined` skipped. */
+    private callSignaturesOf;
+    /** The compiler's own awaited type differs from the type: `Promise<R>`, `PromiseLike<R>`. */
+    private isAwaitable;
+    /**
+     * An intrinsic element's type: the attributes `JSX.IntrinsicElements`
+     * gives its tag. The compiler types an intrinsic tag name itself as the
+     * error type, though the name resolves. A tag is intrinsic when it is an
+     * identifier that starts with a lowercase letter or holds a `-`, as the
+     * language reads it.
+     */
+    private intrinsicProps;
+    /** How rows name a position in a program file: its file, 1-based line and package. */
+    located(declaringFile: ts.SourceFile, position: number): {
+        declFile: string | null;
+        declLine: number;
+        declPackage: string | null;
+    };
+    /**
+     * The declaration a member with none is attributed to (carrick#2448): the
+     * mapped type node, or the alias naming it, of the receiver's type. A
+     * mapped type's members are made by the checker and have no declaration of
+     * their own. This is the owner `memberTypeWithoutDeclaration` reads such a
+     * member at (type-structural-expander.ts): the type's symbol, else its
+     * alias symbol. A union or intersection receiver contributes the one
+     * constituent that has the property; with several the row is left as it is.
+     */
+    private ownerDeclaration;
+    /** The declaration of a type's symbol, else of its alias symbol: a mapped type node, or the alias naming it. */
+    private typeDeclaration;
+    /**
+     * How `declaration`'s module publishes `symbol`: {@link FLAG_PUBLISHED}
+     * when under the symbol's own name (or as a global), and
+     * {@link FLAG_MODULE_DEFAULT} when as the module's `export =` or `default`.
+     * The module is the nearest ambient `declare module "…"` or the file.
+     */
+    private publication;
+    /** A namespace member, found among the exports of the module it sits in. */
+    private publishedByExports;
+    private publishedIn;
+    /** The type of the object a `member` or `call` row's name is read on, if the name is read on one. */
+    private receiverOf;
+    /**
+     * The `decl` rows of a `call` or `member` row (spans unset): one per
+     * declaration the receiver's union constituents give the member, when they
+     * give more than one (carrick#2448). A constituent's declaration is its
+     * member's ({@link attributedDeclaration}), or, for a member with none, the
+     * constituent type's own ({@link typeDeclaration}). Two instantiations of
+     * one generic class, or one class and `undefined`, give one, and no row.
+     * A throw writes one row flagged {@link FLAG_CHECKER_THREW}.
+     */
+    private declRows;
+    /** The row's symbol, following aliases to a target that has a declaration. */
+    symbolOf(kind: PositionKind, node: ts.Node): ts.Symbol | undefined;
+    /**
+     * In a TypeScript file `const { a } = require("m")` binds `a` as `any` with
+     * the binding as its only declaration (TypeScript resolves `require` itself
+     * only in JavaScript files), so a trace stops there. Name the export the
+     * call resolves to instead (carrick#2454): for the binding itself, and for
+     * `m.x` where `m` is a whole-module binding. `undefined` when the name is
+     * not such a binding, the specifier is not a literal or does not resolve,
+     * or the module has no such export.
+     */
+    private requiredExport;
+    /** The `require` binding a symbol is, when its only declaration is one. */
+    private requireBinding;
+    /** `"m"` of a call `require("m")` to the global `require`, else `undefined`. */
+    private requireSpecifier;
+    private exportOfRequired;
+    private host;
+    private resolutionHost;
+}
+/** Order two `decl_file` names, `null` last. */
+export declare function compareNames(a: string | null, b: string | null): number;
 /** The kind of row a node gives, if any (exported for the editor-parity test, carrick#2418). */
 export declare function kindOf(node: ts.Node): NodeKind | undefined;

package/sidecar/dist/src/position-rows.js

@@ -53,7 +53,7 @@ import * as path from 'node:path';
 import * as zlib from 'node:zlib';
 import { ts } from 'ts-morph';
 import { WriteGuard, installedPackageDirectory, isDeclarationFileName, moduleExport } from './capture/index.js';
-import { attributedDeclaration, installedPackageOf } from './declaration-attribution.js';
+import { attributedDeclaration, installedPackageOf, typeDeclaration } from './declaration-attribution.js';
 import { typeToStringAsDeclared } from './print-type.js';
 /** The format's version, written in the header. */
 export const POSITION_ROWS_VERSION = 4;
@@ -76,6 +76,17 @@ export const FLAG_TOO_MANY = 16;
 export const FLAG_PUBLISHED = 32;
 /** The declaration is what its module exports as `export =` or `default` (carrick#2508). */
 export const FLAG_MODULE_DEFAULT = 64;
+/**
+ * A `call` row only: the call's declared return is the result of the
+ * function it is handed (`ReturnType<F>`, a bare type parameter the handed
+ * function returns, or an awaitable of one), so the library runs it and
+ * hands its result back (carrick#2634). Set when the call passes at least
+ * one argument at a function-typed parameter and every such parameter
+ * meets that return. The last free bit of the `u8`: the next flag widens
+ * the field and bumps the format. Pinned to `FLAG_RUNS_HANDED` in
+ * `src/position_rows.rs` by `position-rows-runs-handed.test.ts`.
+ */
+export const FLAG_RUNS_HANDED = 128;
 /** The most `decl` rows one position lists. */
 export const DECL_CAP = 16;
 const COMPARE_OPERATORS = new Set([
@@ -102,7 +113,7 @@ export function writePositionRows(options) {
     const { loader, files, scanRoot, outPath, service } = options;
     const outDir = path.dirname(outPath);
     const guard = WriteGuard.of({ dirs: [outDir], protect: [loader.getRepoRoot(), scanRoot] });
-    const paths = new PathNames(scanRoot);
+    const paths = new PathNames(scanRoot, (file) => loader.packageDirectoryOf(file));
     const lines = new Array(files.length);
     const counts = {
         files: files.length,
@@ -256,8 +267,15 @@ function fileLine(line) {
  * through a link still contains its files), `lib:<name>` for the compiler's
  * default library, `pkg:<name>/<path>` for an installed package outside the
  * root, and nothing otherwise.
+ *
+ * An installed package outside the root is found by its path's last
+ * `node_modules` segment, else by `packageDirectoryOf`: the module graph's
+ * answer where the resolver serves a package from a cache whose path has no
+ * `node_modules` segment (carrick#2599). Either way the directory must hold a
+ * package.json.
  */
 export class PathNames {
+    packageDirectoryOf;
     roots;
     packageNames = new Map();
     /**
@@ -267,7 +285,8 @@ export class PathNames {
      */
     declaringFiles = new Map();
     declaringPackages = new Map();
-    constructor(scanRoot) {
+    constructor(scanRoot, packageDirectoryOf = () => undefined) {
+        this.packageDirectoryOf = packageDirectoryOf;
         const resolved = path.resolve(scanRoot);
         let real = resolved;
         try {
@@ -306,7 +325,7 @@ export class PathNames {
         const inside = this.inside(fileName);
         if (inside)
             return toSlashes(inside.rel);
-        const installed = installedPackageDirectory(this.roots[0], fileName);
+        const installed = installedPackageDirectory(this.roots[0], fileName) ?? this.packageDirectoryOf(fileName);
         if (installed && fs.existsSync(path.join(installed.directory, 'package.json'))) {
             return `pkg:${installed.name}/${toSlashes(path.relative(installed.directory, fileName))}`;
         }
@@ -381,8 +400,12 @@ export class PathNames {
 function toSlashes(p) {
     return p.split(path.sep).join('/');
 }
-/** The rows of one program's files. */
-class PositionWalker {
+/**
+ * The rows of one program's files. The `implementations` action
+ * (`implementations.ts`, carrick#2432) reads a call's symbol and names its
+ * answers through the same walker, so they join as the rows do.
+ */
+export class PositionWalker {
     program;
     paths;
     loader;
@@ -426,6 +449,8 @@ class PositionWalker {
             if (type.flags & ts.TypeFlags.Any) {
                 flags |= type.intrinsicName === 'error' ? FLAG_ERROR_TYPE : FLAG_ANY;
             }
+            if (kind === 'call' && this.runsHanded(node))
+                flags |= FLAG_RUNS_HANDED;
             const typeText = this.paths.scrubType(typeToStringAsDeclared(this.checker, type, undefined));
             if (!symbol)
                 return [kind, start, end, null, null, null, null, typeText, flags];
@@ -453,6 +478,114 @@ class PositionWalker {
             return [kind, start, end, null, null, null, null, null, FLAG_CHECKER_THREW];
         }
     }
+    /**
+     * Whether a call's declared return is the result of the function it is
+     * handed (carrick#2634), read from the declared signature through public
+     * checker calls. See {@link FLAG_RUNS_HANDED}.
+     */
+    runsHanded(node) {
+        if (!ts.isCallExpression(node) && !ts.isNewExpression(node))
+            return false;
+        const args = node.arguments ?? [];
+        if (args.length === 0)
+            return false;
+        try {
+            const declaration = this.checker.getResolvedSignature(node)?.declaration;
+            if (!declaration || ts.isJSDocSignature(declaration))
+                return false;
+            const declared = this.checker.getSignatureFromDeclaration(declaration);
+            if (!declared)
+                return false;
+            const own = new Set(declared.getTypeParameters() ?? []);
+            const results = new Map();
+            const resultOf = (f) => {
+                let atom = results.get(f);
+                if (!atom)
+                    results.set(f, (atom = {}));
+                return atom;
+            };
+            const atoms = (t, out, depth = 0) => {
+                if (depth > 8)
+                    return out;
+                if (t.flags & ts.TypeFlags.TypeParameter) {
+                    if (own.has(t))
+                        out.add(t);
+                }
+                else if (t.flags & ts.TypeFlags.UnionOrIntersection) {
+                    for (const member of t.types)
+                        atoms(member, out, depth + 1);
+                }
+                else if (t.flags & ts.TypeFlags.Conditional) {
+                    const f = resultOfConditional(t, own);
+                    if (f)
+                        out.add(resultOf(f));
+                }
+                else if (isReference(t) && this.isAwaitable(t)) {
+                    for (const arg of this.checker.getTypeArguments(t))
+                        atoms(arg, out, depth + 1);
+                }
+                return out;
+            };
+            const returned = atoms(this.checker.getReturnTypeOfSignature(declared), new Set());
+            if (returned.size === 0)
+                return false;
+            const parameters = declared.getParameters();
+            let handed = 0;
+            for (let i = 0; i < args.length; i++) {
+                const parameter = parameters[Math.min(i, parameters.length - 1)];
+                if (!parameter)
+                    continue;
+                const isRest = parameter.valueDeclaration !== undefined &&
+                    ts.isParameter(parameter.valueDeclaration) &&
+                    parameter.valueDeclaration.dotDotDotToken !== undefined;
+                if (!isRest && i >= parameters.length)
+                    continue;
+                let type = this.checker.getTypeOfSymbolAtLocation(parameter, declaration);
+                if (isRest) {
+                    if (!isReference(type))
+                        continue;
+                    const [element] = this.checker.getTypeArguments(type);
+                    if (!element)
+                        continue;
+                    type = element;
+                }
+                const signatures = this.callSignaturesOf(type);
+                if (signatures.length === 0)
+                    continue;
+                handed++;
+                const mine = new Set();
+                if (type.flags & ts.TypeFlags.TypeParameter)
+                    mine.add(resultOf(type));
+                else
+                    for (const signature of signatures)
+                        atoms(this.checker.getReturnTypeOfSignature(signature), mine);
+                if (![...mine].some((atom) => returned.has(atom)))
+                    return false;
+            }
+            return handed > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** The call signatures of a parameter's type, a type parameter read through its constraint, `null` and `undefined` skipped. */
+    callSignaturesOf(type) {
+        let t = type;
+        if (t.flags & ts.TypeFlags.TypeParameter)
+            t = this.checker.getBaseConstraintOfType(t) ?? t;
+        if (t.flags & ts.TypeFlags.Union) {
+            const kept = t.types.filter((m) => !(m.flags & (ts.TypeFlags.Null | ts.TypeFlags.Undefined)));
+            if (kept.length !== 1)
+                return [];
+            t = kept[0];
+        }
+        return this.checker.getSignaturesOfType(t, ts.SignatureKind.Call);
+    }
+    /** The compiler's own awaited type differs from the type: `Promise<R>`, `PromiseLike<R>`. */
+    isAwaitable(t) {
+        const awaited = this.checker.getAwaitedType(t);
+        return awaited !== undefined && awaited !== t;
+    }
     /**
      * An intrinsic element's type: the attributes `JSX.IntrinsicElements`
      * gives its tag. The compiler types an intrinsic tag name itself as the
@@ -495,8 +628,7 @@ class PositionWalker {
     }
     /** The declaration of a type's symbol, else of its alias symbol: a mapped type node, or the alias naming it. */
     typeDeclaration(type) {
-        const owner = type.getSymbol() ?? type.aliasSymbol;
-        return attributedDeclaration(() => this.program, owner?.declarations ?? []);
+        return typeDeclaration(() => this.program, type);
     }
     /**
      * How `declaration`'s module publishes `symbol`: {@link FLAG_PUBLISHED}
@@ -742,7 +874,7 @@ function tail(row) {
     return [row[3], row[4], row[5], row[6], row[7], row[8]];
 }
 /** Order two `decl_file` names, `null` last. */
-function compareNames(a, b) {
+export function compareNames(a, b) {
     if (a === b)
         return 0;
     if (a === null)
@@ -751,6 +883,28 @@ function compareNames(a, b) {
         return -1;
     return a < b ? -1 : 1;
 }
+function isReference(t) {
+    return !!(t.flags & ts.TypeFlags.Object) && !!(t.objectFlags & ts.ObjectFlags.Reference);
+}
+/**
+ * The type parameter `F` of a conditional written `F extends (...) => infer R ? R : _`
+ * (`ReturnType<F>`): the result of `F`. `Parameters<F>` and the like infer
+ * elsewhere and give nothing.
+ */
+function resultOfConditional(t, own) {
+    if (!(t.checkType.flags & ts.TypeFlags.TypeParameter) || !own.has(t.checkType))
+        return undefined;
+    const node = t.root.node;
+    if (!ts.isFunctionTypeNode(node.extendsType))
+        return undefined;
+    const returns = node.extendsType.type;
+    if (!ts.isInferTypeNode(returns))
+        return undefined;
+    const yielded = node.trueType;
+    if (!ts.isTypeReferenceNode(yielded) || !ts.isIdentifier(yielded.typeName))
+        return undefined;
+    return yielded.typeName.text === returns.typeParameter.name.text ? t.checkType : undefined;
+}
 /** The kind of row a node gives, if any (exported for the editor-parity test, carrick#2418). */
 export function kindOf(node) {
     if (ts.isCallExpression(node) || ts.isNewExpression(node) || ts.isTaggedTemplateExpression(node)) {

package/sidecar/dist/src/project-loader.d.ts

@@ -182,6 +182,21 @@ export declare class ProjectLoader {
      * through Deno, and for a file the workspace itself owns.
      */
     packageOf(filePath: string): string | undefined;
+    /**
+     * The installed package directory a resolved file lies in, and its name,
+     * when the module graph places it (carrick#2599). `undefined` for a project
+     * that did not resolve through Deno: there the path says it.
+     */
+    packageDirectoryOf(filePath: string): {
+        directory: string;
+        name: string;
+    } | undefined;
+    /**
+     * How the module graph resolves `name` from `from`, as the program did
+     * (carrick#2599). `undefined` for a project that did not resolve through
+     * Deno: there Node resolution is the program's.
+     */
+    resolveThroughGraph(name: string, from: string, options: import('typescript').CompilerOptions): import('typescript').ResolvedModuleFull | undefined;
     /**
      * Check if the project has been successfully initialized
      */

package/sidecar/dist/src/project-loader.js

@@ -502,6 +502,22 @@ export class ProjectLoader {
     packageOf(filePath) {
         return this.denoProject?.packageOf(filePath);
     }
+    /**
+     * The installed package directory a resolved file lies in, and its name,
+     * when the module graph places it (carrick#2599). `undefined` for a project
+     * that did not resolve through Deno: there the path says it.
+     */
+    packageDirectoryOf(filePath) {
+        return this.denoProject?.packageDirectoryOf(filePath);
+    }
+    /**
+     * How the module graph resolves `name` from `from`, as the program did
+     * (carrick#2599). `undefined` for a project that did not resolve through
+     * Deno: there Node resolution is the program's.
+     */
+    resolveThroughGraph(name, from, options) {
+        return this.denoProject?.resolve(name, from, options);
+    }
     /**
      * Check if the project has been successfully initialized
      */

package/sidecar/dist/src/retype.js

@@ -548,14 +548,8 @@ function bodyReadsOf(call) {
     const chained = bodyReadOn(top);
     if (chained)
         return checkedBodyReads([chained]);
-    const declaration = top.getParent();
-    if (!declaration ||
-        !Node.isVariableDeclaration(declaration) ||
-        declaration.getInitializer() !== top) {
-        return [];
-    }
-    const name = declaration.getNameNode();
-    if (!Node.isIdentifier(name))
+    const name = responseBinding(top);
+    if (!name)
         return [];
     const reads = [];
     let handedOn = false;
@@ -583,6 +577,92 @@ function bodyReadsOf(call) {
     }
     return checkedBodyReads(reads);
 }
+/**
+ * The name the located call's response is bound to, when the source binds it
+ * in one of three ways: `const res = await call`, the first parameter of a
+ * `.then` callback (`call.then((res) => res.json())`), or an element of an
+ * array destructured off `Promise.all` (`const [a, b] = await Promise.all([call, ...])`).
+ */
+function responseBinding(top) {
+    const declaration = top.getParent();
+    if (declaration && Node.isVariableDeclaration(declaration) && declaration.getInitializer() === top) {
+        const name = declaration.getNameNode();
+        return Node.isIdentifier(name) ? name : undefined;
+    }
+    return thenParameter(top) ?? promiseAllElement(top);
+}
+/** `top.then((res) => ...)`: the callback's first parameter. */
+function thenParameter(top) {
+    const access = top.getParent();
+    if (!access || !Node.isPropertyAccessExpression(access) || access.getExpression() !== top) {
+        return undefined;
+    }
+    if (access.getName() !== 'then')
+        return undefined;
+    const then = access.getParent();
+    if (!then || !Node.isCallExpression(then) || then.getExpression() !== access)
+        return undefined;
+    const callback = then.getArguments()[0];
+    if (!callback || !(Node.isArrowFunction(callback) || Node.isFunctionExpression(callback))) {
+        return undefined;
+    }
+    const name = callback.getParameters()[0]?.getNameNode();
+    return name && Node.isIdentifier(name) ? name : undefined;
+}
+/**
+ * The name `top` is destructured to, when `top` is one element of the array
+ * literal handed to the language library's `Promise.all` and the call's
+ * awaited result is destructured to names:
+ * `const [a, b] = await Promise.all([call, other])`. An element after a
+ * spread has no position the destructuring can be read against.
+ */
+function promiseAllElement(top) {
+    const array = top.getParent();
+    if (!array || !Node.isArrayLiteralExpression(array))
+        return undefined;
+    const elements = array.getElements();
+    const index = elements.indexOf(top);
+    if (index < 0 || elements.slice(0, index + 1).some((e) => Node.isSpreadElement(e))) {
+        return undefined;
+    }
+    const all = array.getParent();
+    if (!all ||
+        !Node.isCallExpression(all) ||
+        all.getArguments()[0] !== array ||
+        !isLibraryPromiseAll(all)) {
+        return undefined;
+    }
+    let result = all;
+    while (Node.isAwaitExpression(result.getParentOrThrow()) ||
+        Node.isParenthesizedExpression(result.getParentOrThrow())) {
+        result = result.getParentOrThrow();
+    }
+    const declaration = result.getParent();
+    if (!declaration || !Node.isVariableDeclaration(declaration) || declaration.getInitializer() !== result) {
+        return undefined;
+    }
+    const pattern = declaration.getNameNode();
+    if (!Node.isArrayBindingPattern(pattern))
+        return undefined;
+    const element = pattern.getElements()[index];
+    if (!element || !Node.isBindingElement(element) || element.getDotDotDotToken())
+        return undefined;
+    const name = element.getNameNode();
+    return Node.isIdentifier(name) ? name : undefined;
+}
+/** `Promise.all` as the language library declares it, not a lookalike. */
+function isLibraryPromiseAll(call) {
+    const callee = call.getExpression();
+    if (!Node.isPropertyAccessExpression(callee) || callee.getName() !== 'all')
+        return false;
+    const declaration = resolvedDeclaration(call);
+    if (!declaration)
+        return false;
+    return call
+        .getProject()
+        .getProgram()
+        .compilerObject.isSourceFileDefaultLibrary(declaration.getSourceFile());
+}
 /**
  * Why these body reads cannot be retyped, or the reads to retype.
  *