feat(42684): allow deprecated JSDoc tag to be used on aliased nodes (microsoft#47293)

a-tarasyuk · web-flow · commit 20b552383020 · 2022-01-25T15:49:33.000-08:00
diff --git a/src/compiler/checker.ts b/src/compiler/checker.ts
@@ -1198,6 +1198,10 @@ namespace ts {
             return diagnostic;
         }
 
+        function isDeprecatedSymbol(symbol: Symbol) {
+            return !!(getDeclarationNodeFlagsFromSymbol(symbol) & NodeFlags.Deprecated);
+        }
+
         function addDeprecatedSuggestion(location: Node, declarations: Node[], deprecatedEntity: string) {
             const diagnostic = createDiagnosticForNode(location, Diagnostics._0_is_deprecated, deprecatedEntity);
             return addDeprecatedSuggestionWorker(declarations, diagnostic);
@@ -15184,7 +15188,7 @@ namespace ts {
                 }
                 const prop = getPropertyOfType(objectType, propName);
                 if (prop) {
-                    if (accessFlags & AccessFlags.ReportDeprecated && accessNode && prop.declarations && getDeclarationNodeFlagsFromSymbol(prop) & NodeFlags.Deprecated && isUncalledFunctionReference(accessNode, prop)) {
+                    if (accessFlags & AccessFlags.ReportDeprecated && accessNode && prop.declarations && isDeprecatedSymbol(prop) && isUncalledFunctionReference(accessNode, prop)) {
                         const deprecatedNode = accessExpression?.argumentExpression ?? (isIndexedAccessTypeNode(accessNode) ? accessNode.indexType : accessNode);
                         addDeprecatedSuggestion(deprecatedNode, prop.declarations, propName as string);
                     }
@@ -25143,9 +25147,9 @@ namespace ts {
             }
 
             const localOrExportSymbol = getExportSymbolOfValueSymbolIfExported(symbol);
-            const sourceSymbol = localOrExportSymbol.flags & SymbolFlags.Alias ? resolveAlias(localOrExportSymbol) : localOrExportSymbol;
-            if (sourceSymbol.declarations && getDeclarationNodeFlagsFromSymbol(sourceSymbol) & NodeFlags.Deprecated && isUncalledFunctionReference(node, sourceSymbol)) {
-                addDeprecatedSuggestion(node, sourceSymbol.declarations, node.escapedText as string);
+            const targetSymbol = checkDeprecatedAliasedSymbol(localOrExportSymbol, node);
+            if (isDeprecatedSymbol(targetSymbol) && isUncalledFunctionReference(node, targetSymbol) && targetSymbol.declarations) {
+                addDeprecatedSuggestion(node, targetSymbol.declarations, node.escapedText as string);
             }
 
             let declaration = localOrExportSymbol.valueDeclaration;
@@ -28512,7 +28516,7 @@ namespace ts {
                 }
             }
             else {
-                if (prop.declarations && getDeclarationNodeFlagsFromSymbol(prop) & NodeFlags.Deprecated && isUncalledFunctionReference(node, prop)) {
+                if (isDeprecatedSymbol(prop) && isUncalledFunctionReference(node, prop) && prop.declarations) {
                     addDeprecatedSuggestion(right, prop.declarations, right.escapedText as string);
                 }
                 checkPropertyNotUsedBeforeDeclaration(prop, node, right);
@@ -39889,10 +39893,45 @@ namespace ts {
                     }
                 }
 
-                if (isImportSpecifier(node) && target.declarations?.every(d => !!(getCombinedNodeFlags(d) & NodeFlags.Deprecated))) {
-                    addDeprecatedSuggestion(node.name, target.declarations, symbol.escapedName as string);
+                if (isImportSpecifier(node)) {
+                    const targetSymbol = checkDeprecatedAliasedSymbol(symbol, node);
+                    if (isDeprecatedAliasedSymbol(targetSymbol) && targetSymbol.declarations) {
+                        addDeprecatedSuggestion(node, targetSymbol.declarations, targetSymbol.escapedName as string);
+                    }
+                }
+            }
+        }
+
+        function isDeprecatedAliasedSymbol(symbol: Symbol) {
+            return !!symbol.declarations && every(symbol.declarations, d => !!(getCombinedNodeFlags(d) & NodeFlags.Deprecated));
+        }
+
+        function checkDeprecatedAliasedSymbol(symbol: Symbol, location: Node) {
+            if (!(symbol.flags & SymbolFlags.Alias)) return symbol;
+
+            const targetSymbol = resolveAlias(symbol);
+            if (targetSymbol === unknownSymbol) return targetSymbol;
+
+            while (symbol.flags & SymbolFlags.Alias) {
+                const target = getImmediateAliasedSymbol(symbol);
+                if (target) {
+                    if (target === targetSymbol) break;
+                    if (target.declarations && length(target.declarations)) {
+                        if (isDeprecatedAliasedSymbol(target)) {
+                            addDeprecatedSuggestion(location, target.declarations, target.escapedName as string);
+                            break;
+                        }
+                        else {
+                            if (symbol === targetSymbol) break;
+                            symbol = target;
+                        }
+                    }
+                }
+                else {
+                    break;
                 }
             }
+            return targetSymbol;
         }
 
         function checkImportBinding(node: ImportEqualsDeclaration | ImportClause | NamespaceImport | ImportSpecifier) {
diff --git a/src/compiler/parser.ts b/src/compiler/parser.ts
@@ -7406,7 +7406,8 @@ namespace ts {
         }
 
         function parseExportSpecifier() {
-            return parseImportOrExportSpecifier(SyntaxKind.ExportSpecifier) as ExportSpecifier;
+            const hasJSDoc = hasPrecedingJSDocComment();
+            return withJSDoc(parseImportOrExportSpecifier(SyntaxKind.ExportSpecifier) as ExportSpecifier, hasJSDoc);
         }
 
         function parseImportSpecifier() {
diff --git a/src/compiler/types.ts b/src/compiler/types.ts
@@ -929,6 +929,7 @@ namespace ts {
         | JSDocFunctionType
         | ExportDeclaration
         | NamedTupleMember
+        | ExportSpecifier
         | EndOfFileToken
         ;
 
@@ -3117,7 +3118,7 @@ namespace ts {
         readonly isTypeOnly: boolean;
     }
 
-    export interface ExportSpecifier extends NamedDeclaration {
+    export interface ExportSpecifier extends NamedDeclaration, JSDocContainer {
         readonly kind: SyntaxKind.ExportSpecifier;
         readonly parent: NamedExports;
         readonly isTypeOnly: boolean;
diff --git a/src/compiler/utilities.ts b/src/compiler/utilities.ts
@@ -1247,7 +1247,8 @@ namespace ts {
             node.kind === SyntaxKind.FunctionExpression ||
             node.kind === SyntaxKind.ArrowFunction ||
             node.kind === SyntaxKind.ParenthesizedExpression ||
-            node.kind === SyntaxKind.VariableDeclaration) ?
+            node.kind === SyntaxKind.VariableDeclaration ||
+            node.kind === SyntaxKind.ExportSpecifier) ?
             concatenate(getTrailingCommentRanges(text, node.pos), getLeadingCommentRanges(text, node.pos)) :
             getLeadingCommentRanges(text, node.pos);
         // True if the comment starts with '/**' but not if it is '/**/'
diff --git a/tests/baselines/reference/api/tsserverlibrary.d.ts b/tests/baselines/reference/api/tsserverlibrary.d.ts
@@ -572,7 +572,7 @@ declare namespace ts {
     }
     export interface JSDocContainer {
     }
-    export type HasJSDoc = ParameterDeclaration | CallSignatureDeclaration | ClassStaticBlockDeclaration | ConstructSignatureDeclaration | MethodSignature | PropertySignature | ArrowFunction | ParenthesizedExpression | SpreadAssignment | ShorthandPropertyAssignment | PropertyAssignment | FunctionExpression | EmptyStatement | DebuggerStatement | Block | VariableStatement | ExpressionStatement | IfStatement | DoStatement | WhileStatement | ForStatement | ForInStatement | ForOfStatement | BreakStatement | ContinueStatement | ReturnStatement | WithStatement | SwitchStatement | LabeledStatement | ThrowStatement | TryStatement | FunctionDeclaration | ConstructorDeclaration | MethodDeclaration | VariableDeclaration | PropertyDeclaration | AccessorDeclaration | ClassLikeDeclaration | InterfaceDeclaration | TypeAliasDeclaration | EnumMember | EnumDeclaration | ModuleDeclaration | ImportEqualsDeclaration | ImportDeclaration | NamespaceExportDeclaration | ExportAssignment | IndexSignatureDeclaration | FunctionTypeNode | ConstructorTypeNode | JSDocFunctionType | ExportDeclaration | NamedTupleMember | EndOfFileToken;
+    export type HasJSDoc = ParameterDeclaration | CallSignatureDeclaration | ClassStaticBlockDeclaration | ConstructSignatureDeclaration | MethodSignature | PropertySignature | ArrowFunction | ParenthesizedExpression | SpreadAssignment | ShorthandPropertyAssignment | PropertyAssignment | FunctionExpression | EmptyStatement | DebuggerStatement | Block | VariableStatement | ExpressionStatement | IfStatement | DoStatement | WhileStatement | ForStatement | ForInStatement | ForOfStatement | BreakStatement | ContinueStatement | ReturnStatement | WithStatement | SwitchStatement | LabeledStatement | ThrowStatement | TryStatement | FunctionDeclaration | ConstructorDeclaration | MethodDeclaration | VariableDeclaration | PropertyDeclaration | AccessorDeclaration | ClassLikeDeclaration | InterfaceDeclaration | TypeAliasDeclaration | EnumMember | EnumDeclaration | ModuleDeclaration | ImportEqualsDeclaration | ImportDeclaration | NamespaceExportDeclaration | ExportAssignment | IndexSignatureDeclaration | FunctionTypeNode | ConstructorTypeNode | JSDocFunctionType | ExportDeclaration | NamedTupleMember | ExportSpecifier | EndOfFileToken;
     export type HasType = SignatureDeclaration | VariableDeclaration | ParameterDeclaration | PropertySignature | PropertyDeclaration | TypePredicateNode | ParenthesizedTypeNode | TypeOperatorNode | MappedTypeNode | AssertionExpression | TypeAliasDeclaration | JSDocTypeExpression | JSDocNonNullableType | JSDocNullableType | JSDocOptionalType | JSDocVariadicType;
     export type HasTypeArguments = CallExpression | NewExpression | TaggedTemplateExpression | JsxOpeningElement | JsxSelfClosingElement;
     export type HasInitializer = HasExpressionInitializer | ForStatement | ForInStatement | ForOfStatement | JsxAttribute;
@@ -1702,7 +1702,7 @@ declare namespace ts {
         readonly name: Identifier;
         readonly isTypeOnly: boolean;
     }
-    export interface ExportSpecifier extends NamedDeclaration {
+    export interface ExportSpecifier extends NamedDeclaration, JSDocContainer {
         readonly kind: SyntaxKind.ExportSpecifier;
         readonly parent: NamedExports;
         readonly isTypeOnly: boolean;
diff --git a/tests/baselines/reference/api/typescript.d.ts b/tests/baselines/reference/api/typescript.d.ts
@@ -572,7 +572,7 @@ declare namespace ts {
     }
     export interface JSDocContainer {
     }
-    export type HasJSDoc = ParameterDeclaration | CallSignatureDeclaration | ClassStaticBlockDeclaration | ConstructSignatureDeclaration | MethodSignature | PropertySignature | ArrowFunction | ParenthesizedExpression | SpreadAssignment | ShorthandPropertyAssignment | PropertyAssignment | FunctionExpression | EmptyStatement | DebuggerStatement | Block | VariableStatement | ExpressionStatement | IfStatement | DoStatement | WhileStatement | ForStatement | ForInStatement | ForOfStatement | BreakStatement | ContinueStatement | ReturnStatement | WithStatement | SwitchStatement | LabeledStatement | ThrowStatement | TryStatement | FunctionDeclaration | ConstructorDeclaration | MethodDeclaration | VariableDeclaration | PropertyDeclaration | AccessorDeclaration | ClassLikeDeclaration | InterfaceDeclaration | TypeAliasDeclaration | EnumMember | EnumDeclaration | ModuleDeclaration | ImportEqualsDeclaration | ImportDeclaration | NamespaceExportDeclaration | ExportAssignment | IndexSignatureDeclaration | FunctionTypeNode | ConstructorTypeNode | JSDocFunctionType | ExportDeclaration | NamedTupleMember | EndOfFileToken;
+    export type HasJSDoc = ParameterDeclaration | CallSignatureDeclaration | ClassStaticBlockDeclaration | ConstructSignatureDeclaration | MethodSignature | PropertySignature | ArrowFunction | ParenthesizedExpression | SpreadAssignment | ShorthandPropertyAssignment | PropertyAssignment | FunctionExpression | EmptyStatement | DebuggerStatement | Block | VariableStatement | ExpressionStatement | IfStatement | DoStatement | WhileStatement | ForStatement | ForInStatement | ForOfStatement | BreakStatement | ContinueStatement | ReturnStatement | WithStatement | SwitchStatement | LabeledStatement | ThrowStatement | TryStatement | FunctionDeclaration | ConstructorDeclaration | MethodDeclaration | VariableDeclaration | PropertyDeclaration | AccessorDeclaration | ClassLikeDeclaration | InterfaceDeclaration | TypeAliasDeclaration | EnumMember | EnumDeclaration | ModuleDeclaration | ImportEqualsDeclaration | ImportDeclaration | NamespaceExportDeclaration | ExportAssignment | IndexSignatureDeclaration | FunctionTypeNode | ConstructorTypeNode | JSDocFunctionType | ExportDeclaration | NamedTupleMember | ExportSpecifier | EndOfFileToken;
     export type HasType = SignatureDeclaration | VariableDeclaration | ParameterDeclaration | PropertySignature | PropertyDeclaration | TypePredicateNode | ParenthesizedTypeNode | TypeOperatorNode | MappedTypeNode | AssertionExpression | TypeAliasDeclaration | JSDocTypeExpression | JSDocNonNullableType | JSDocNullableType | JSDocOptionalType | JSDocVariadicType;
     export type HasTypeArguments = CallExpression | NewExpression | TaggedTemplateExpression | JsxOpeningElement | JsxSelfClosingElement;
     export type HasInitializer = HasExpressionInitializer | ForStatement | ForInStatement | ForOfStatement | JsxAttribute;
@@ -1702,7 +1702,7 @@ declare namespace ts {
         readonly name: Identifier;
         readonly isTypeOnly: boolean;
     }
-    export interface ExportSpecifier extends NamedDeclaration {
+    export interface ExportSpecifier extends NamedDeclaration, JSDocContainer {
         readonly kind: SyntaxKind.ExportSpecifier;
         readonly parent: NamedExports;
         readonly isTypeOnly: boolean;
diff --git a/tests/cases/fourslash/jsdocDeprecated_suggestion14.ts b/tests/cases/fourslash/jsdocDeprecated_suggestion14.ts
@@ -0,0 +1,33 @@
+/// <reference path="fourslash.ts" />
+
+// @module: esnext
+// @filename: /a.ts
+////export const a = 1;
+////export const b = 1;
+
+// @filename: /b.ts
+////export {
+////    /** @deprecated a is deprecated */
+////    a
+////} from "./a";
+
+// @filename: /c.ts
+////import { [|a|] } from "./b";
+////[|a|]
+
+goTo.file("/c.ts")
+
+verify.getSuggestionDiagnostics([
+    {
+        "code": 6385,
+        "message": "'a' is deprecated.",
+        "reportsDeprecated": true,
+        "range": test.ranges()[0]
+    },
+    {
+        "code": 6385,
+        "message": "'a' is deprecated.",
+        "reportsDeprecated": true,
+        "range": test.ranges()[1]
+    },
+]);
diff --git a/tests/cases/fourslash/jsdocDeprecated_suggestion15.ts b/tests/cases/fourslash/jsdocDeprecated_suggestion15.ts
@@ -0,0 +1,38 @@
+/// <reference path="fourslash.ts" />
+
+// @module: esnext
+// @filename: /a.ts
+////export const a = 1;
+////export const b = 1;
+
+// @filename: /b.ts
+////export {
+////    /** @deprecated a is deprecated */
+////    a
+////} from "./a";
+
+// @filename: /c.ts
+////export {
+////    a
+////} from "./b";
+
+// @filename: /d.ts
+////import { [|a|] } from "./c";
+////[|a|]
+
+goTo.file("/d.ts")
+
+verify.getSuggestionDiagnostics([
+    {
+        "code": 6385,
+        "message": "'a' is deprecated.",
+        "reportsDeprecated": true,
+        "range": test.ranges()[0]
+    },
+    {
+        "code": 6385,
+        "message": "'a' is deprecated.",
+        "reportsDeprecated": true,
+        "range": test.ranges()[1]
+    },
+]);
diff --git a/tests/cases/fourslash/jsdocDeprecated_suggestion16.ts b/tests/cases/fourslash/jsdocDeprecated_suggestion16.ts
@@ -0,0 +1,27 @@
+/// <reference path="fourslash.ts" />
+
+// @module: esnext
+// @filename: /a.ts
+////const a = 1;
+////const b = 1;
+////export { a, /** @deprecated b is deprecated */ b }
+
+// @filename: /b.ts
+////import { [|b|] } from "./a";
+////[|b|]
+
+goTo.file("/b.ts")
+verify.getSuggestionDiagnostics([
+    {
+        "code": 6385,
+        "message": "'b' is deprecated.",
+        "reportsDeprecated": true,
+        "range": test.ranges()[0]
+    },
+    {
+        "code": 6385,
+        "message": "'b' is deprecated.",
+        "reportsDeprecated": true,
+        "range": test.ranges()[1]
+    },
+]);

Original file line number	Diff line number	Diff line change
`@@ -7406,7 +7406,8 @@ namespace ts {`
`7406`	`7406`	`}`
`7407`	`7407`
`7408`	`7408`	`function parseExportSpecifier() {`
`7409`		`- return parseImportOrExportSpecifier(SyntaxKind.ExportSpecifier) as ExportSpecifier;`
	`7409`	`+ const hasJSDoc = hasPrecedingJSDocComment();`
	`7410`	`+ return withJSDoc(parseImportOrExportSpecifier(SyntaxKind.ExportSpecifier) as ExportSpecifier, hasJSDoc);`
`7410`	`7411`	`}`
`7411`	`7412`
`7412`	`7413`	`function parseImportSpecifier() {`
Original file line number	Diff line number	Diff line change
`@@ -929,6 +929,7 @@ namespace ts {`
`929`	`929`	`\| JSDocFunctionType`
`930`	`930`	`\| ExportDeclaration`
`931`	`931`	`\| NamedTupleMember`
	`932`	`+ \| ExportSpecifier`
`932`	`933`	`\| EndOfFileToken`
`933`	`934`	`;`
`934`	`935`
`@@ -3117,7 +3118,7 @@ namespace ts {`
`3117`	`3118`	`readonly isTypeOnly: boolean;`
`3118`	`3119`	`}`
`3119`	`3120`
`3120`		`- export interface ExportSpecifier extends NamedDeclaration {`
	`3121`	`+ export interface ExportSpecifier extends NamedDeclaration, JSDocContainer {`
`3121`	`3122`	`readonly kind: SyntaxKind.ExportSpecifier;`
`3122`	`3123`	`readonly parent: NamedExports;`
`3123`	`3124`	`readonly isTypeOnly: boolean;`
Original file line number	Diff line number	Diff line change
`@@ -572,7 +572,7 @@ declare namespace ts {`
`572`	`572`	`}`
`573`	`573`	`export interface JSDocContainer {`
`574`	`574`	`}`
`575`		- export type HasJSDoc = ParameterDeclaration \| CallSignatureDeclaration \| ClassStaticBlockDeclaration \| ConstructSignatureDeclaration \| MethodSignature \| PropertySignature \| ArrowFunction \| ParenthesizedExpression \| SpreadAssignment \| ShorthandPropertyAssignment \| PropertyAssignment \| FunctionExpression \| EmptyStatement \| DebuggerStatement \| Block \| VariableStatement \| ExpressionStatement \| IfStatement \| DoStatement \| WhileStatement \| ForStatement \| ForInStatement \| ForOfStatement \| BreakStatement \| ContinueStatement \| ReturnStatement \| WithStatement \| SwitchStatement \| LabeledStatement \| ThrowStatement \| TryStatement \| FunctionDeclaration \| ConstructorDeclaration \| MethodDeclaration \| VariableDeclaration \| PropertyDeclaration \| AccessorDeclaration \| ClassLikeDeclaration \| InterfaceDeclaration \| TypeAliasDeclaration \| EnumMember \| EnumDeclaration \| ModuleDeclaration \| ImportEqualsDeclaration \| ImportDeclaration \| NamespaceExportDeclaration \| ExportAssignment \| IndexSignatureDeclaration \| FunctionTypeNode \| ConstructorTypeNode \| JSDocFunctionType \| ExportDeclaration \| NamedTupleMember \| EndOfFileToken;
	`575`	+ export type HasJSDoc = ParameterDeclaration \| CallSignatureDeclaration \| ClassStaticBlockDeclaration \| ConstructSignatureDeclaration \| MethodSignature \| PropertySignature \| ArrowFunction \| ParenthesizedExpression \| SpreadAssignment \| ShorthandPropertyAssignment \| PropertyAssignment \| FunctionExpression \| EmptyStatement \| DebuggerStatement \| Block \| VariableStatement \| ExpressionStatement \| IfStatement \| DoStatement \| WhileStatement \| ForStatement \| ForInStatement \| ForOfStatement \| BreakStatement \| ContinueStatement \| ReturnStatement \| WithStatement \| SwitchStatement \| LabeledStatement \| ThrowStatement \| TryStatement \| FunctionDeclaration \| ConstructorDeclaration \| MethodDeclaration \| VariableDeclaration \| PropertyDeclaration \| AccessorDeclaration \| ClassLikeDeclaration \| InterfaceDeclaration \| TypeAliasDeclaration \| EnumMember \| EnumDeclaration \| ModuleDeclaration \| ImportEqualsDeclaration \| ImportDeclaration \| NamespaceExportDeclaration \| ExportAssignment \| IndexSignatureDeclaration \| FunctionTypeNode \| ConstructorTypeNode \| JSDocFunctionType \| ExportDeclaration \| NamedTupleMember \| ExportSpecifier \| EndOfFileToken;
`576`	`576`	`export type HasType = SignatureDeclaration \| VariableDeclaration \| ParameterDeclaration \| PropertySignature \| PropertyDeclaration \| TypePredicateNode \| ParenthesizedTypeNode \| TypeOperatorNode \| MappedTypeNode \| AssertionExpression \| TypeAliasDeclaration \| JSDocTypeExpression \| JSDocNonNullableType \| JSDocNullableType \| JSDocOptionalType \| JSDocVariadicType;`
`577`	`577`	`export type HasTypeArguments = CallExpression \| NewExpression \| TaggedTemplateExpression \| JsxOpeningElement \| JsxSelfClosingElement;`
`578`	`578`	`export type HasInitializer = HasExpressionInitializer \| ForStatement \| ForInStatement \| ForOfStatement \| JsxAttribute;`
`@@ -1702,7 +1702,7 @@ declare namespace ts {`
`1702`	`1702`	`readonly name: Identifier;`
`1703`	`1703`	`readonly isTypeOnly: boolean;`
`1704`	`1704`	`}`
`1705`		`- export interface ExportSpecifier extends NamedDeclaration {`
	`1705`	`+ export interface ExportSpecifier extends NamedDeclaration, JSDocContainer {`
`1706`	`1706`	`readonly kind: SyntaxKind.ExportSpecifier;`
`1707`	`1707`	`readonly parent: NamedExports;`
`1708`	`1708`	`readonly isTypeOnly: boolean;`