Add jsdoc member names: Class#method (#44150)

* Everything mostly works

A couple of mixed, nested references don't work yet.
The scanner+parser interaction is wrong, the parser consumes one too
many spaces, and the checker+services code needs a little cleanup.

* Cleanup

1. I decided that correctly parsing a#b.c, an entity name containing an
instance reference, is not worth the work.
2. I made the scanner, at least the jsdoc part, emit a # token, and
provided a reScanPrivateIdentifier in order to convert #a to # a.
3. I cleaned up the code in the checker.
2. Unrelated: I added a missing space in linkPart display.

* Cleanup lint + var naming

* investigate+clean up a couple of TODOs

* Fix lint in utilities.ts

* change name to JSDocMemberName

* address PR comments

Author: sandersn

src/compiler/checker.ts

@@ -39156,16 +39156,6 @@ namespace ts {
             return node.parent.kind === SyntaxKind.ExpressionWithTypeArguments;
         }
 
-        function getJSDocEntryNameReference(node: Identifier | PrivateIdentifier | PropertyAccessExpression | QualifiedName): JSDocNameReference | undefined {
-            while (node.parent.kind === SyntaxKind.QualifiedName) {
-                node = node.parent as QualifiedName;
-            }
-            while (node.parent.kind === SyntaxKind.PropertyAccessExpression) {
-                node = node.parent as PropertyAccessExpression;
-            }
-            return isJSDocNameReference(node.parent) ? node.parent : undefined;
-        }
-
         function forEachEnclosingClass<T>(node: Node, callback: (node: Node) => T | undefined): T | undefined {
             let result: T | undefined;
 
@@ -39240,7 +39230,7 @@ namespace ts {
             return undefined;
         }
 
-        function getSymbolOfNameOrPropertyAccessExpression(name: EntityName | PrivateIdentifier | PropertyAccessExpression): Symbol | undefined {
+        function getSymbolOfNameOrPropertyAccessExpression(name: EntityName | PrivateIdentifier | PropertyAccessExpression | JSDocMemberName): Symbol | undefined {
             if (isDeclarationName(name)) {
                 return getSymbolOfNode(name.parent);
             }
@@ -39249,7 +39239,7 @@ namespace ts {
                 name.parent.kind === SyntaxKind.PropertyAccessExpression &&
                 name.parent === (name.parent.parent as BinaryExpression).left) {
                 // Check if this is a special property assignment
-                if (!isPrivateIdentifier(name)) {
+                if (!isPrivateIdentifier(name) && !isJSDocMemberName(name)) {
                     const specialPropertyAssignmentSymbol = getSpecialPropertyAssignmentSymbolFromEntityName(name);
                     if (specialPropertyAssignmentSymbol) {
                         return specialPropertyAssignmentSymbol;
@@ -39265,14 +39255,14 @@ namespace ts {
                     return success;
                 }
             }
-            else if (!isPropertyAccessExpression(name) && !isPrivateIdentifier(name) && isInRightSideOfImportOrExportAssignment(name)) {
+            else if (isEntityName(name) && isInRightSideOfImportOrExportAssignment(name)) {
                 // Since we already checked for ExportAssignment, this really could only be an Import
                 const importEqualsDeclaration = getAncestor(name, SyntaxKind.ImportEqualsDeclaration);
                 Debug.assert(importEqualsDeclaration !== undefined);
                 return getSymbolOfPartOfRightHandSideOfImportEquals(name, /*dontResolveAlias*/ true);
             }
 
-            if (!isPropertyAccessExpression(name) && !isPrivateIdentifier(name)) {
+            if (isEntityName(name)) {
                 const possibleImportNode = isImportTypeQualifierPart(name);
                 if (possibleImportNode) {
                     getTypeFromTypeNode(possibleImportNode);
@@ -39281,8 +39271,8 @@ namespace ts {
                 }
             }
 
-            while (isRightSideOfQualifiedNameOrPropertyAccess(name)) {
-                name = name.parent as QualifiedName | PropertyAccessEntityNameExpression;
+            while (isRightSideOfQualifiedNameOrPropertyAccessOrJSDocMemberName(name)) {
+                name = name.parent as QualifiedName | PropertyAccessEntityNameExpression | JSDocMemberName;
             }
 
             if (isHeritageClauseElementIdentifier(name)) {
@@ -39323,12 +39313,14 @@ namespace ts {
                     return undefined;
                 }
 
+                const isJSDoc = findAncestor(name, or(isJSDocLink, isJSDocNameReference, isJSDocMemberName));
+                const meaning = isJSDoc ? SymbolFlags.Type | SymbolFlags.Namespace | SymbolFlags.Value : SymbolFlags.Value;
                 if (name.kind === SyntaxKind.Identifier) {
                     if (isJSXTagName(name) && isJsxIntrinsicIdentifier(name)) {
                         const symbol = getIntrinsicTagSymbol(name.parent as JsxOpeningLikeElement);
                         return symbol === unknownSymbol ? undefined : symbol;
                     }
-                    return resolveEntityName(name, SymbolFlags.Value, /*ignoreErrors*/ false, /*dontResolveAlias*/ true);
+                    return resolveEntityName(name, meaning, /*ignoreErrors*/ false, /*dontResolveAlias*/ !isJSDoc, getHostSignatureFromJSDoc(name));
                 }
                 else if (name.kind === SyntaxKind.PropertyAccessExpression || name.kind === SyntaxKind.QualifiedName) {
                     const links = getNodeLinks(name);
@@ -39342,47 +39334,53 @@ namespace ts {
                     else {
                         checkQualifiedName(name, CheckMode.Normal);
                     }
+                    if (!links.resolvedSymbol && isJSDoc && isQualifiedName(name)) {
+                        return resolveJSDocMemberName(name);
+                    }
                     return links.resolvedSymbol;
                 }
+                else if (isJSDocMemberName(name)) {
+                    return resolveJSDocMemberName(name);
+                }
             }
             else if (isTypeReferenceIdentifier(name as EntityName)) {
                 const meaning = name.parent.kind === SyntaxKind.TypeReference ? SymbolFlags.Type : SymbolFlags.Namespace;
                 return resolveEntityName(name as EntityName, meaning, /*ignoreErrors*/ false, /*dontResolveAlias*/ true);
             }
-
-            const jsdocReference = getJSDocEntryNameReference(name);
-            if (jsdocReference || isJSDocLink(name.parent)) {
-                const meaning = SymbolFlags.Type | SymbolFlags.Namespace | SymbolFlags.Value;
-                const symbol = resolveEntityName(name as EntityName, meaning, /*ignoreErrors*/ false, /*dontResolveAlias*/ false, getHostSignatureFromJSDoc(name));
-                if (symbol) {
-                    return symbol;
-                }
-                else if (isQualifiedName(name) && isIdentifier(name.left)) {
-                    // resolve C.m as a static member first
-                    const links = getNodeLinks(name);
-                    if (links.resolvedSymbol) {
-                        return links.resolvedSymbol;
-                    }
-                    checkQualifiedName(name, CheckMode.Normal);
-                    if (links.resolvedSymbol) {
-                        return links.resolvedSymbol;
-                    }
-
-                    // then resolve it as an instance member
-                    const s = resolveEntityName(name.left, meaning, /*ignoreErrors*/ false);
-                    if (s) {
-                        const t = getDeclaredTypeOfSymbol(s);
-                        return getPropertyOfType(t, name.right.escapedText);
-                    }
-                }
-            }
             if (name.parent.kind === SyntaxKind.TypePredicate) {
                 return resolveEntityName(name as Identifier, /*meaning*/ SymbolFlags.FunctionScopedVariable);
             }
 
             return undefined;
         }
 
+        /**
+         * Recursively resolve entity names and jsdoc instance references:
+         * 1. K#m as K.prototype.m for a class (or other value) K
+         * 2. K.m as K.prototype.m
+         * 3. I.m as I.m for a type I, or any other I.m that fails to resolve in (1) or (2)
+         */
+        function resolveJSDocMemberName(name: EntityName | JSDocMemberName): Symbol | undefined {
+            if (isEntityName(name)) {
+                const symbol = resolveEntityName(
+                    name,
+                    SymbolFlags.Type | SymbolFlags.Namespace | SymbolFlags.Value,
+                    /*ignoreErrors*/ false,
+                    /*dontResolveAlias*/ true,
+                    getHostSignatureFromJSDoc(name));
+                if (symbol || isIdentifier(name)) {
+                    // can't recur on identifier, so just return when it's undefined
+                    return symbol;
+                }
+            }
+            const left = resolveJSDocMemberName(name.left);
+            if (left) {
+                const proto = left.flags & SymbolFlags.Value && getPropertyOfType(getTypeOfSymbol(left), "prototype" as __String);
+                const t = proto ? getTypeOfSymbol(proto) : getDeclaredTypeOfSymbol(left);
+                return getPropertyOfType(t, name.right.escapedText);
+            }
+        }
+
         function getSymbolAtLocation(node: Node, ignoreErrors?: boolean): Symbol | undefined {
             if (node.kind === SyntaxKind.SourceFile) {
                 return isExternalModule(node as SourceFile) ? getMergedSymbol(node.symbol) : undefined;

src/compiler/factory/nodeFactory.ts

@@ -345,6 +345,8 @@ namespace ts {
             updateJSDocSeeTag,
             createJSDocNameReference,
             updateJSDocNameReference,
+            createJSDocMemberName,
+            updateJSDocMemberName,
             createJSDocLink,
             updateJSDocLink,
             // lazily load factory members for JSDoc tags with similar structure
@@ -4391,29 +4393,48 @@ namespace ts {
         }
 
         // @api
-        function createJSDocNameReference(name: EntityName): JSDocNameReference {
+        function createJSDocNameReference(name: EntityName | JSDocMemberName): JSDocNameReference {
             const node = createBaseNode<JSDocNameReference>(SyntaxKind.JSDocNameReference);
             node.name = name;
             return node;
         }
 
         // @api
-        function updateJSDocNameReference(node: JSDocNameReference, name: EntityName): JSDocNameReference {
+        function updateJSDocNameReference(node: JSDocNameReference, name: EntityName | JSDocMemberName): JSDocNameReference {
             return node.name !== name
                 ? update(createJSDocNameReference(name), node)
                 : node;
         }
 
         // @api
-        function createJSDocLink(name: EntityName | undefined, text: string): JSDocLink {
+        function createJSDocMemberName(left: EntityName | JSDocMemberName, right: Identifier) {
+            const node = createBaseNode<JSDocMemberName>(SyntaxKind.JSDocMemberName);
+            node.left = left;
+            node.right = right;
+            node.transformFlags |=
+                propagateChildFlags(node.left) |
+                propagateChildFlags(node.right);
+            return node;
+        }
+
+        // @api
+        function updateJSDocMemberName(node: JSDocMemberName, left: EntityName | JSDocMemberName, right: Identifier) {
+            return node.left !== left
+                || node.right !== right
+                ? update(createJSDocMemberName(left, right), node)
+                : node;
+        }
+
+        // @api
+        function createJSDocLink(name: EntityName | JSDocMemberName | undefined, text: string): JSDocLink {
             const node = createBaseNode<JSDocLink>(SyntaxKind.JSDocLink);
             node.name = name;
             node.text = text;
             return node;
         }
 
         // @api
-        function updateJSDocLink(node: JSDocLink, name: EntityName | undefined, text: string): JSDocLink {
+        function updateJSDocLink(node: JSDocLink, name: EntityName | JSDocMemberName | undefined, text: string): JSDocLink {
             return node.name !== name
                 ? update(createJSDocLink(name, text), node)
                 : node;

src/compiler/factory/nodeTests.ts

@@ -770,6 +770,10 @@ namespace ts {
         return node.kind === SyntaxKind.JSDocNameReference;
     }
 
+    export function isJSDocMemberName(node: Node): node is JSDocMemberName {
+        return node.kind === SyntaxKind.JSDocMemberName;
+    }
+
     export function isJSDocLink(node: Node): node is JSDocLink {
         return node.kind === SyntaxKind.JSDocLink;
     }

src/compiler/parser.ts

@@ -489,6 +489,9 @@ namespace ts {
                     (typeof (node as JSDoc).comment === "string" ? undefined : visitNodes(cbNode, cbNodes, (node as JSDoc).comment as NodeArray<JSDocText | JSDocLink> | undefined));
             case SyntaxKind.JSDocNameReference:
                 return visitNode(cbNode, (node as JSDocNameReference).name);
+            case SyntaxKind.JSDocMemberName:
+                return visitNode(cbNode, (node as JSDocMemberName).left) ||
+                    visitNode(cbNode, (node as JSDocMemberName).right);
             case SyntaxKind.JSDocParameterTag:
             case SyntaxKind.JSDocPropertyTag:
                 return visitNode(cbNode, (node as JSDocTag).tagName) ||
@@ -1424,6 +1427,10 @@ namespace ts {
             return currentToken = scanner.reScanLessThanToken();
         }
 
+        function reScanHashToken(): SyntaxKind {
+            return currentToken = scanner.reScanHashToken();
+        }
+
         function scanJsxIdentifier(): SyntaxKind {
             return currentToken = scanner.scanJsxIdentifier();
         }
@@ -7338,7 +7345,13 @@ namespace ts {
             export function parseJSDocNameReference(): JSDocNameReference {
                 const pos = getNodePos();
                 const hasBrace = parseOptional(SyntaxKind.OpenBraceToken);
-                const entityName = parseEntityName(/* allowReservedWords*/ false);
+                const p2 = getNodePos();
+                let entityName: EntityName | JSDocMemberName = parseEntityName(/* allowReservedWords*/ false);
+                while (token() === SyntaxKind.PrivateIdentifier) {
+                    reScanHashToken(); // rescan #id as # id
+                    nextTokenJSDoc(); // then skip the #
+                    entityName = finishNode(factory.createJSDocMemberName(entityName, parseIdentifier()), p2);
+                }
                 if (hasBrace) {
                     parseExpectedJSDoc(SyntaxKind.CloseBraceToken);
                 }
@@ -7793,9 +7806,17 @@ namespace ts {
                     nextTokenJSDoc(); // start at token after link, then skip any whitespace
                     skipWhitespace();
                     // parseEntityName logs an error for non-identifier, so create a MissingNode ourselves to avoid the error
-                    const name = tokenIsIdentifierOrKeyword(token())
+                    const p2 = getNodePos();
+                    let name: EntityName | JSDocMemberName | undefined = tokenIsIdentifierOrKeyword(token())
                         ? parseEntityName(/*allowReservedWords*/ true)
                         : undefined;
+                    if (name) {
+                        while (token() === SyntaxKind.PrivateIdentifier) {
+                            reScanHashToken(); // rescan #id as # id
+                            nextTokenJSDoc(); // then skip the #
+                            name = finishNode(factory.createJSDocMemberName(name, parseIdentifier()), p2);
+                        }
+                    }
                     const text = [];
                     while (token() !== SyntaxKind.CloseBraceToken && token() !== SyntaxKind.NewLineTrivia && token() !== SyntaxKind.EndOfFileToken) {
                         text.push(scanner.getTokenText());

src/compiler/scanner.ts

@@ -42,6 +42,7 @@ namespace ts {
         reScanJsxAttributeValue(): SyntaxKind;
         reScanJsxToken(allowMultilineJsxText?: boolean): JsxTokenSyntaxKind;
         reScanLessThanToken(): SyntaxKind;
+        reScanHashToken(): SyntaxKind;
         reScanQuestionToken(): SyntaxKind;
         reScanInvalidIdentifier(): SyntaxKind;
         scanJsxToken(): JsxTokenSyntaxKind;
@@ -220,7 +221,8 @@ namespace ts {
         "&&=": SyntaxKind.AmpersandAmpersandEqualsToken,
         "??=": SyntaxKind.QuestionQuestionEqualsToken,
         "@": SyntaxKind.AtToken,
-        "`": SyntaxKind.BacktickToken
+        "#": SyntaxKind.HashToken,
+        "`": SyntaxKind.BacktickToken,
     }));
 
     /*
@@ -981,6 +983,7 @@ namespace ts {
             reScanJsxAttributeValue,
             reScanJsxToken,
             reScanLessThanToken,
+            reScanHashToken,
             reScanQuestionToken,
             reScanInvalidIdentifier,
             scanJsxToken,
@@ -2240,6 +2243,14 @@ namespace ts {
             return token;
         }
 
+        function reScanHashToken(): SyntaxKind {
+            if (token === SyntaxKind.PrivateIdentifier) {
+                pos = tokenPos + 1;
+                return token = SyntaxKind.HashToken;
+            }
+            return token;
+        }
+
         function reScanQuestionToken(): SyntaxKind {
             Debug.assert(token === SyntaxKind.QuestionQuestionToken, "'reScanQuestionToken' should only be called on a '??'");
             pos = tokenPos + 1;
@@ -2426,6 +2437,8 @@ namespace ts {
                     return token = SyntaxKind.DotToken;
                 case CharacterCodes.backtick:
                     return token = SyntaxKind.BacktickToken;
+                case CharacterCodes.hash:
+                    return token = SyntaxKind.HashToken;
                 case CharacterCodes.backslash:
                     pos--;
                     const extendedCookedChar = peekExtendedUnicodeEscape();