carrick 0.3.118 → 0.3.120

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

@@ -14,6 +14,7 @@
  * | `compare` | `=== !== == != < > <= >= instanceof in`           | the left operand          | the left operand |
  * | `ident`   | an identifier in expression position              | itself                    | itself         |
  * | `impl`    | a `call` or `member` whose declaration has no body | an implementation of it  | nothing        |
+ * | `decl`    | a `call` or `member` on a union of declaring types | one of those declarations | nothing       |
  * | `jsx`     | a JSX opening or self-closing element's tag        | the tag's name           | the tag        |
  *
  * An `impl` row (version 2, carrick#2430) follows the `call` or `member` row
@@ -24,9 +25,18 @@
  * initializer. Its `decl_*` name the implementing declaration. Past
  * {@link IMPL_CAP} the row is one, with {@link FLAG_TOO_MANY} and nothing else.
  *
- * A row's key is `(start, end, kind)`, except that several `impl` rows share
- * one: TypeScript `getStart()`/`getEnd()` of the node, in UTF-16 code units
- * from the start of the file, which is what the scanner's `sidecar_position`
+ * A `decl` row (version 3, carrick#2448) follows the `call` or `member` row
+ * it belongs to, before its `impl` rows, and has its span: one per
+ * declaration of the member when the receiver is a union whose constituents
+ * declare it at more than one place (`(pick ? a : b).get()` with two
+ * classes). That row names only the first of them. Each constituent's
+ * declaration is its own member's, or, for a member with none (a mapped
+ * type's), the declaration of the constituent type itself. Sorted and capped
+ * as `impl` rows are; `type_text` is `null`.
+ *
+ * A row's key is `(start, end, kind)`, except that several `impl` rows, and
+ * several `decl` rows, share one: TypeScript `getStart()`/`getEnd()` of the
+ * node, in UTF-16 code units from the start of the file, which is what the scanner's `sidecar_position`
  * gives for an SWC span. Every path written is relative to the scanned repo's
  * root, with `/` separators.
  *
@@ -49,7 +59,7 @@ import { WriteGuard, installedPackageDirectory, isDeclarationFileName, moduleExp
 import { attributedDeclaration, installedPackageOf } from './declaration-attribution.js';
 import { typeToStringAsDeclared } from './print-type.js';
 /** The format's version, written in the header. */
-export const POSITION_ROWS_VERSION = 2;
+export const POSITION_ROWS_VERSION = 3;
 /** The type is `any`, declared or inferred. Never set with the error type. */
 export const FLAG_ANY = 1;
 /** The type is the compiler's error type: something did not resolve. */
@@ -58,9 +68,18 @@ export const FLAG_ERROR_TYPE = 2;
 export const FLAG_CHECKER_THREW = 4;
 /** The declaration is outside the checkout, not the default library and in no installed package. */
 export const FLAG_DECLARATION_UNNAMED = 8;
-/** An `impl` row standing for more implementations than {@link IMPL_CAP}; it names none. */
+/** An `impl` or `decl` row standing for more than {@link IMPL_CAP} rows of its kind; it names none. */
 export const FLAG_TOO_MANY = 16;
-/** The most implementations one declaration's `impl` rows list. */
+/**
+ * The declaration is published under the row's symbol name: its module
+ * exports it by that name, or it is a global (a script's top-level
+ * declaration, or one in `declare global`). A member of a class, interface,
+ * type literal or object literal never is (carrick#2508).
+ */
+export const FLAG_PUBLISHED = 32;
+/** The declaration is what its module exports as `export =` or `default` (carrick#2508). */
+export const FLAG_MODULE_DEFAULT = 64;
+/** The most `impl` rows one declaration lists, and the most `decl` rows one position lists. */
 export const IMPL_CAP = 16;
 const COMPARE_OPERATORS = new Set([
     ts.SyntaxKind.EqualsEqualsEqualsToken,
@@ -379,6 +398,8 @@ class PositionWalker {
     implementations = new Map();
     /** The same for a member whose symbol has no declaration, keyed by symbol. */
     undeclaredImplementations = new Map();
+    /** Each module's exports by name, and its `export =` and `default` targets, aliases followed. */
+    moduleExports = new Map();
     constructor(program, service, paths, loader) {
         this.program = program;
         this.service = service;
@@ -394,6 +415,8 @@ class PositionWalker {
                 const row = this.row(kind, node, sourceFile);
                 rows.push(row);
                 if ((kind === 'call' || kind === 'member') && !(row[8] & FLAG_CHECKER_THREW)) {
+                    for (const decl of this.declRows(kind, node))
+                        rows.push(['decl', row[1], row[2], ...tail(decl)]);
                     for (const impl of this.implRows(kind, node))
                         rows.push(['impl', row[1], row[2], ...tail(impl)]);
                 }
@@ -424,6 +447,9 @@ class PositionWalker {
                 this.ownerDeclaration(kind, node, symbol);
             if (!declaration)
                 return [kind, start, end, ts.symbolName(symbol), null, null, null, typeText, flags];
+            // A declaration named through its owner's type is a member.
+            if ((symbol.declarations ?? []).includes(declaration))
+                flags |= this.publication(symbol, declaration);
             // A file's own module symbol is named by the compiler as the quoted
             // absolute file name (`"/<checkout>/pkg/index"`). Name it as `decl_file`
             // names the file. A symbol that merely lives in a file (CommonJS
@@ -566,20 +592,135 @@ class PositionWalker {
      * constituent that has the property; with several the row is left as it is.
      */
     ownerDeclaration(kind, node, symbol) {
-        if (kind !== 'member' && kind !== 'call')
-            return undefined;
-        const named = nameNodeOf(kind, node);
-        const access = named?.parent;
-        if (!access || !(ts.isPropertyAccessExpression(access) || ts.isElementAccessExpression(access))) {
+        const receiver = this.receiverOf(kind, node);
+        if (!receiver)
             return undefined;
-        }
-        const receiver = this.checker.getTypeAtLocation(access.expression);
         const holders = (receiver.isUnionOrIntersection() ? receiver.types : [receiver]).filter((constituent) => constituent.getProperty(symbol.name) !== undefined);
         if (holders.length !== 1)
             return undefined;
-        const owner = holders[0].getSymbol() ?? holders[0].aliasSymbol;
+        return this.typeDeclaration(holders[0]);
+    }
+    /** 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 ?? []);
     }
+    /**
+     * 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.
+     */
+    publication(symbol, declaration) {
+        let container = declaration.parent;
+        while (container && !ts.isSourceFile(container) && !ts.isModuleBlock(container)) {
+            // Anything but a statement list between the declaration and its module
+            // (a class, interface, type or object literal, a function body) makes
+            // it a member or a local.
+            if (!ts.isVariableDeclarationList(container) && !ts.isVariableStatement(container))
+                return 0;
+            container = container.parent;
+        }
+        if (!container)
+            return 0;
+        const block = ts.isModuleBlock(container) ? container.parent : undefined;
+        if (block && block.flags & ts.NodeFlags.GlobalAugmentation)
+            return FLAG_PUBLISHED;
+        // A namespace's member is published when the module its file is publishes it.
+        if (block && !ts.isStringLiteral(block.name))
+            return this.publishedByExports(symbol, declaration);
+        const moduleSymbol = this.checker.getSymbolAtLocation(block ? block.name : container);
+        if (moduleSymbol)
+            return this.publishedIn(moduleSymbol, symbol);
+        // A script's top-level declaration is a global.
+        return ts.isSourceFile(container) && !ts.isExternalModule(container) ? FLAG_PUBLISHED : 0;
+    }
+    /** A namespace member, found among the exports of the module it sits in. */
+    publishedByExports(symbol, declaration) {
+        for (let node = declaration.parent; node; node = node.parent) {
+            if (ts.isModuleDeclaration(node) && ts.isStringLiteral(node.name)) {
+                const moduleSymbol = this.checker.getSymbolAtLocation(node.name);
+                return moduleSymbol ? this.publishedIn(moduleSymbol, symbol) : 0;
+            }
+            if (ts.isSourceFile(node)) {
+                const moduleSymbol = this.checker.getSymbolAtLocation(node);
+                return moduleSymbol ? this.publishedIn(moduleSymbol, symbol) & FLAG_PUBLISHED : 0;
+            }
+        }
+        return 0;
+    }
+    publishedIn(moduleSymbol, symbol) {
+        let exports = this.moduleExports.get(moduleSymbol);
+        if (!exports) {
+            const resolve = (s) => s.flags & ts.SymbolFlags.Alias ? this.checker.getAliasedSymbol(s) : s;
+            const byName = new Map();
+            for (const exported of this.checker.getExportsOfModule(moduleSymbol)) {
+                byName.set(exported.getName(), resolve(exported));
+            }
+            const wholes = [ts.InternalSymbolName.ExportEquals, ts.InternalSymbolName.Default]
+                .map((key) => moduleSymbol.exports?.get(key))
+                .filter((own) => own !== undefined)
+                .map(resolve);
+            exports = { byName, wholes };
+            this.moduleExports.set(moduleSymbol, exports);
+        }
+        return ((exports.byName.get(symbol.getName()) === symbol ? FLAG_PUBLISHED : 0) |
+            (exports.wholes.includes(symbol) ? FLAG_MODULE_DEFAULT : 0));
+    }
+    /** The type of the object a `member` or `call` row's name is read on, if the name is read on one. */
+    receiverOf(kind, node) {
+        if (kind !== 'member' && kind !== 'call')
+            return undefined;
+        const access = nameNodeOf(kind, node)?.parent;
+        if (!access || !(ts.isPropertyAccessExpression(access) || ts.isElementAccessExpression(access))) {
+            return undefined;
+        }
+        return this.checker.getTypeAtLocation(access.expression);
+    }
+    /**
+     * 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}.
+     */
+    declRows(kind, node) {
+        const found = new Set();
+        let name;
+        try {
+            const symbol = this.symbolOf(kind, node);
+            const receiver = this.receiverOf(kind, node);
+            if (!symbol || !receiver || !receiver.isUnion())
+                return [];
+            name = ts.symbolName(symbol);
+            for (const constituent of receiver.types) {
+                const member = constituent.getProperty(symbol.name);
+                if (!member)
+                    continue;
+                const declaration = attributedDeclaration(() => this.program, member.declarations ?? []) ?? this.typeDeclaration(constituent);
+                if (declaration)
+                    found.add(declaration);
+            }
+        }
+        catch {
+            return [['decl', 0, 0, null, null, null, null, null, FLAG_CHECKER_THREW]];
+        }
+        if (found.size < 2)
+            return [];
+        if (found.size > IMPL_CAP)
+            return [['decl', 0, 0, null, null, null, null, null, FLAG_TOO_MANY]];
+        const rows = [...found].map((declaration) => {
+            const file = declaration.getSourceFile();
+            const start = declaration.getStart(file);
+            const { declFile, declLine, declPackage } = this.located(file, start);
+            const flags = declFile === null ? FLAG_DECLARATION_UNNAMED : 0;
+            return { start, row: ['decl', 0, 0, name, declFile, declLine, declPackage, null, flags] };
+        });
+        rows.sort((a, b) => compareNames(a.row[4], b.row[4]) || a.start - b.start);
+        return rows.map(({ row }) => row);
+    }
     /** The row's symbol, following aliases to a target that has a declaration. */
     symbolOf(kind, node) {
         let symbol;
@@ -778,6 +919,7 @@ function nameNodeOf(kind, node) {
         case 'ident':
             return node;
         case 'impl':
+        case 'decl':
             return undefined;
         case 'jsx':
             // The tag: `<Badge>`, `<ui.Button>`, `<this.Panel>`; a namespaced