Add support for "specialize" tag

Author: apendua

src/compiler/binder.ts

@@ -231,6 +231,7 @@ import {
     JSDocParameterTag,
     JSDocPropertyLikeTag,
     JSDocSignature,
+    JSDocSpecializeTag,
     JSDocTypedefTag,
     JSDocTypeLiteral,
     JsxAttribute,
@@ -3091,6 +3092,8 @@ function createBinder(): (file: SourceFile, options: CompilerOptions) => void {
                 return bind((node as JSDocOverloadTag).typeExpression);
             case SyntaxKind.JSDocImportTag:
                 return (jsDocImports || (jsDocImports = [])).push(node as JSDocImportTag);
+            case SyntaxKind.JSDocSpecializeTag:
+                return bindEach((node as JSDocSpecializeTag).typeArguments);
         }
     }
 

src/compiler/checker.ts

@@ -326,6 +326,7 @@ import {
     getJSDocParameterTags,
     getJSDocRoot,
     getJSDocSatisfiesExpressionType,
+    getJSDocSpecializeTag,
     getJSDocTags,
     getJSDocThisTag,
     getJSDocType,
@@ -35562,15 +35563,34 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker {
         return checkIndexedAccessIndexType(getFlowTypeOfAccessExpression(node, getNodeLinks(node).resolvedSymbol, indexedAccessType, indexExpression, checkMode), node);
     }
 
-    function callLikeExpressionMayHaveTypeArguments(node: CallLikeExpression): node is CallExpression | NewExpression | TaggedTemplateExpression | JsxOpeningElement {
+    function callLikeExpressionMayHaveTypeArguments(node: CallLikeExpression): node is CallExpression | NewExpression | TaggedTemplateExpression | JsxOpeningLikeElement {
         return isCallOrNewExpression(node) || isTaggedTemplateExpression(node) || isJsxOpeningLikeElement(node);
     }
 
+    function getTypeArgumentsForCallLikeExpression(node: CallExpression | NewExpression | TaggedTemplateExpression | JsxOpeningLikeElement) {
+        if (isSuperCall(node)) {
+            return undefined;
+        }
+        if (isInJSFile(node)) {
+            let { parent } = node;
+            if (isJsxElement(parent)) {
+                parent = parent.parent;
+            }
+            if (canHaveJSDoc(parent)) {
+                const specializeTag = getJSDocSpecializeTag(parent);
+                if (specializeTag) {
+                    return specializeTag.typeArguments;
+                }
+            }
+        }
+        return node.typeArguments;
+    }
+
     function resolveUntypedCall(node: CallLikeExpression): Signature {
         if (callLikeExpressionMayHaveTypeArguments(node)) {
             // Check type arguments even though we will give an error that untyped calls may not accept type arguments.
             // This gets us diagnostics for the type arguments and marks them as referenced.
-            forEach(node.typeArguments, checkSourceElement);
+            forEach(getTypeArgumentsForCallLikeExpression(node), checkSourceElement);
         }
 
         if (node.kind === SyntaxKind.TaggedTemplateExpression) {
@@ -36570,13 +36590,9 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker {
 
         let candidates: Signature[] = [];
         let typeArguments: NodeArray<TypeNode> | undefined;
-        if (!isDecorator && !isInstanceof && !isSuperCall(node) && !isJsxOpenFragment) {
-            typeArguments = (node as CallExpression).typeArguments;
-
-            // We already perform checking on the type arguments on the class declaration itself.
-            if (isTaggedTemplate || isJsxOpeningOrSelfClosingElement || (node as CallExpression).expression.kind !== SyntaxKind.SuperKeyword) {
-                forEach(typeArguments, checkSourceElement);
-            }
+        if (callLikeExpressionMayHaveTypeArguments(node)) {
+            typeArguments = getTypeArgumentsForCallLikeExpression(node);
+            forEach(typeArguments, checkSourceElement);
         }
 
         candidates = candidatesOutArray || [];
@@ -36748,7 +36764,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker {
                 diagnostics.add(getArgumentArityError(node, [candidateForArgumentArityError], args, headMessage));
             }
             else if (candidateForTypeArgumentError) {
-                checkTypeArguments(candidateForTypeArgumentError, (node as CallExpression | TaggedTemplateExpression | JsxOpeningLikeElement).typeArguments!, /*reportErrors*/ true, headMessage);
+                checkTypeArguments(candidateForTypeArgumentError, typeArguments!, /*reportErrors*/ true, headMessage);
             }
             else if (!isJsxOpenFragment) {
                 const signaturesWithCorrectTypeArgumentArity = filter(signatures, s => hasCorrectTypeArgumentArity(s, typeArguments));
@@ -36953,7 +36969,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker {
             return candidate;
         }
 
-        const typeArgumentNodes: readonly TypeNode[] | undefined = callLikeExpressionMayHaveTypeArguments(node) ? node.typeArguments : undefined;
+        const typeArgumentNodes: readonly TypeNode[] | undefined = callLikeExpressionMayHaveTypeArguments(node) ? getTypeArgumentsForCallLikeExpression(node) : undefined;
         const instantiated = typeArgumentNodes
             ? createSignatureInstantiation(candidate, getTypeArgumentsFromNodes(typeArgumentNodes, typeParameters, isInJSFile(node)))
             : inferSignatureInstantiationForOverloadFailure(node, typeParameters, candidate, args, checkMode);
@@ -37053,14 +37069,15 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker {
         // that the user will not add any.
         const callSignatures = getSignaturesOfType(apparentType, SignatureKind.Call);
         const numConstructSignatures = getSignaturesOfType(apparentType, SignatureKind.Construct).length;
+        const typeArguments = getTypeArgumentsForCallLikeExpression(node);
 
         // TS 1.0 Spec: 4.12
         // In an untyped function call no TypeArgs are permitted, Args can be any argument list, no contextual
         // types are provided for the argument expressions, and the result is always of type Any.
         if (isUntypedFunctionCall(funcType, apparentType, callSignatures.length, numConstructSignatures)) {
             // The unknownType indicates that an error already occurred (and was reported).  No
             // need to report another error in this case.
-            if (!isErrorType(funcType) && node.typeArguments) {
+            if (!isErrorType(funcType) && typeArguments) {
                 error(node, Diagnostics.Untyped_function_calls_may_not_accept_type_arguments);
             }
             return resolveUntypedCall(node);
@@ -37096,7 +37113,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker {
         // use the resolvingSignature singleton to indicate that we deferred processing. This result will be
         // propagated out and eventually turned into silentNeverType (a type that is assignable to anything and
         // from which we never make inferences).
-        if (checkMode & CheckMode.SkipGenericFunctions && !node.typeArguments && callSignatures.some(isGenericFunctionReturningFunction)) {
+        if (checkMode & CheckMode.SkipGenericFunctions && !typeArguments && callSignatures.some(isGenericFunctionReturningFunction)) {
             skippedGenericFunction(node, checkMode);
             return resolvingSignature;
         }
@@ -37141,11 +37158,12 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker {
             return resolveErrorCall(node);
         }
 
+        const typeArguments = getTypeArgumentsForCallLikeExpression(node);
         // TS 1.0 spec: 4.11
         // If expressionType is of type Any, Args can be any argument
         // list and the result of the operation is of type Any.
         if (isTypeAny(expressionType)) {
-            if (node.typeArguments) {
+            if (typeArguments) {
                 error(node, Diagnostics.Untyped_function_calls_may_not_accept_type_arguments);
             }
             return resolveUntypedCall(node);
@@ -37545,9 +37563,10 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker {
                 const result = getIntrinsicAttributesTypeFromJsxOpeningLikeElement(node);
                 const fakeSignature = createSignatureForJSXIntrinsic(node, result);
                 checkTypeAssignableToAndOptionallyElaborate(checkExpressionWithContextualType(node.attributes, getEffectiveFirstArgumentForJsxSignature(fakeSignature, node), /*inferenceContext*/ undefined, CheckMode.Normal), result, node.tagName, node.attributes);
-                if (length(node.typeArguments)) {
-                    forEach(node.typeArguments, checkSourceElement);
-                    diagnostics.add(createDiagnosticForNodeArray(getSourceFileOfNode(node), node.typeArguments!, Diagnostics.Expected_0_type_arguments_but_got_1, 0, length(node.typeArguments)));
+                const typeArguments = getTypeArgumentsForCallLikeExpression(node);
+                if (length(typeArguments)) {
+                    forEach(typeArguments, checkSourceElement);
+                    diagnostics.add(createDiagnosticForNodeArray(getSourceFileOfNode(node), typeArguments!, Diagnostics.Expected_0_type_arguments_but_got_1, 0, length(typeArguments)));
                 }
                 return fakeSignature;
             }
@@ -37804,7 +37823,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker {
      * @returns On success, the expression's signature's return type. On failure, anyType.
      */
     function checkCallExpression(node: CallExpression | NewExpression, checkMode?: CheckMode): Type {
-        checkGrammarTypeArguments(node, node.typeArguments);
+        checkGrammarTypeArguments(node, getTypeArgumentsForCallLikeExpression(node));
 
         const signature = getResolvedSignature(node, /*candidatesOutArray*/ undefined, checkMode);
         if (signature === resolvingSignature) {
@@ -38043,7 +38062,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker {
     }
 
     function checkTaggedTemplateExpression(node: TaggedTemplateExpression): Type {
-        if (!checkGrammarTaggedTemplateChain(node)) checkGrammarTypeArguments(node, node.typeArguments);
+        if (!checkGrammarTaggedTemplateChain(node)) checkGrammarTypeArguments(node, getTypeArgumentsForCallLikeExpression(node));
         if (languageVersion < LanguageFeatureMinimumTarget.TaggedTemplates) {
             checkExternalEmitHelpers(node, ExternalEmitHelpers.MakeTemplateObject);
         }
@@ -42661,7 +42680,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker {
     }
 
     function getEffectiveTypeArguments(node: TypeReferenceNode | ExpressionWithTypeArguments | NodeWithTypeArguments, typeParameters: readonly TypeParameter[]): Type[] {
-        return fillMissingTypeArguments(map(node.typeArguments!, getTypeFromTypeNode), typeParameters, getMinTypeArgumentCount(typeParameters), isInJSFile(node));
+        return fillMissingTypeArguments(map(node.typeArguments || [], getTypeFromTypeNode), typeParameters, getMinTypeArgumentCount(typeParameters), isInJSFile(node));
     }
 
     function checkTypeArgumentConstraints(node: TypeReferenceNode | ExpressionWithTypeArguments | NodeWithTypeArguments, typeParameters: readonly TypeParameter[]): boolean {
@@ -52696,7 +52715,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker {
 
     function checkGrammarJsxElement(node: JsxOpeningLikeElement) {
         checkGrammarJsxName(node.tagName);
-        checkGrammarTypeArguments(node, node.typeArguments);
+        checkGrammarTypeArguments(node, getTypeArgumentsForCallLikeExpression(node));
         const seen = new Map<__String, boolean>();
 
         for (const attr of node.attributes.properties) {

src/compiler/emitter.ts

@@ -257,6 +257,7 @@ import {
     JSDocSatisfiesTag,
     JSDocSeeTag,
     JSDocSignature,
+    JSDocSpecializeTag,
     JSDocTag,
     JSDocTemplateTag,
     JSDocThisTag,
@@ -1899,6 +1900,8 @@ export function createPrinter(printerOptions: PrinterOptions = {}, handlers: Pri
                     return emitJSDocSeeTag(node as JSDocSeeTag);
                 case SyntaxKind.JSDocImportTag:
                     return emitJSDocImportTag(node as JSDocImportTag);
+                case SyntaxKind.JSDocSpecializeTag:
+                    return emitJSDocSpecializeTag(node as JSDocSpecializeTag);
                 // SyntaxKind.JSDocPropertyTag (see JSDocParameterTag, above)
 
                 // Transformation nodes
@@ -4156,6 +4159,15 @@ export function createPrinter(printerOptions: PrinterOptions = {}, handlers: Pri
         emitJSDocComment(tag.comment);
     }
 
+    function emitJSDocSpecializeTag(tag: JSDocSpecializeTag) {
+        emitJSDocTagName(tag.tagName);
+        writeSpace();
+        writePunctuation("<");
+        emitList(tag, tag.typeArguments, ListFormat.CommaListElements);
+        writePunctuation(">");
+        emitJSDocComment(tag.comment);
+    }
+
     function emitJSDocNameReference(node: JSDocNameReference) {
         writeSpace();
         writePunctuation("{");

src/compiler/factory/nodeFactory.ts

@@ -251,6 +251,7 @@ import {
     JSDocSatisfiesTag,
     JSDocSeeTag,
     JSDocSignature,
+    JSDocSpecializeTag,
     JSDocTag,
     JSDocTemplateTag,
     JSDocText,
@@ -863,6 +864,8 @@ export function createNodeFactory(flags: NodeFactoryFlags, baseFactory: BaseNode
         updateJSDocSeeTag,
         createJSDocImportTag,
         updateJSDocImportTag,
+        createJSDocSpecializeTag,
+        updateJSDocSpecializeTag,
         createJSDocNameReference,
         updateJSDocNameReference,
         createJSDocMemberName,
@@ -5564,6 +5567,22 @@ export function createNodeFactory(flags: NodeFactoryFlags, baseFactory: BaseNode
             : node;
     }
 
+    // @api
+    function createJSDocSpecializeTag(tagName: Identifier | undefined, typeArguments: readonly TypeNode[], comment: string | NodeArray<JSDocComment> | undefined): JSDocSpecializeTag {
+        const node = createBaseJSDocTag<JSDocSpecializeTag>(SyntaxKind.JSDocSpecializeTag, tagName ?? createIdentifier("specialize"), /*comment*/ undefined);
+        node.typeArguments = asNodeArray(typeArguments);
+        node.comment = comment;
+        return node;
+    }
+
+    function updateJSDocSpecializeTag(node: JSDocSpecializeTag, tagName: Identifier | undefined, typeArguments: readonly TypeNode[], comment: string | NodeArray<JSDocComment> | undefined): JSDocSpecializeTag {
+        return node.tagName !== tagName
+                || node.typeArguments !== typeArguments
+                || node.comment !== comment
+            ? update(createJSDocSpecializeTag(tagName, typeArguments, comment), node)
+            : node;
+    }
+
     // @api
     function createJSDocText(text: string): JSDocText {
         const node = createBaseNode<JSDocText>(SyntaxKind.JSDocText);
@@ -7227,6 +7246,8 @@ function getDefaultTagNameForKind(kind: JSDocTag["kind"]): string {
             return "implements";
         case SyntaxKind.JSDocImportTag:
             return "import";
+        case SyntaxKind.JSDocSpecializeTag:
+            return "specialize";
         default:
             return Debug.fail(`Unsupported kind: ${Debug.formatSyntaxKind(kind)}`);
     }

src/compiler/factory/nodeTests.ts

@@ -113,6 +113,7 @@ import {
     JSDocSatisfiesTag,
     JSDocSeeTag,
     JSDocSignature,
+    JSDocSpecializeTag,
     JSDocTemplateTag,
     JSDocThisTag,
     JSDocThrowsTag,
@@ -1193,6 +1194,10 @@ export function isJSDocImportTag(node: Node): node is JSDocImportTag {
     return node.kind === SyntaxKind.JSDocImportTag;
 }
 
+export function isJSDocSpecializeTag(node: Node): node is JSDocSpecializeTag {
+    return node.kind === SyntaxKind.JSDocSpecializeTag;
+}
+
 // Synthesized list
 
 /** @internal */

src/compiler/parser.ts

@@ -149,6 +149,7 @@ import {
     isJSDocFunctionType,
     isJSDocNullableType,
     isJSDocReturnTag,
+    isJSDocSpecializeTag,
     isJSDocTypeTag,
     isJsxNamespacedName,
     isJsxOpeningElement,
@@ -202,6 +203,7 @@ import {
     JSDocSatisfiesTag,
     JSDocSeeTag,
     JSDocSignature,
+    JSDocSpecializeTag,
     JSDocSyntaxKind,
     JSDocTag,
     JSDocTemplateTag,
@@ -1132,6 +1134,9 @@ const forEachChildTable: ForEachChildTable = {
     [SyntaxKind.JSDocDeprecatedTag]: forEachChildInJSDocTag,
     [SyntaxKind.JSDocOverrideTag]: forEachChildInJSDocTag,
     [SyntaxKind.JSDocImportTag]: forEachChildInJSDocImportTag,
+    [SyntaxKind.JSDocSpecializeTag]: function forEachChildInJSDocSpecializeTag<T>(node: JSDocSpecializeTag, cbNode: (node: Node) => T | undefined, _cbNodes?: (nodes: NodeArray<Node>) => T | undefined): T | undefined {
+        return forEach(node.typeArguments, cbNode);
+    },
     [SyntaxKind.PartiallyEmittedExpression]: forEachChildInPartiallyEmittedExpression,
 };
 
@@ -9177,6 +9182,9 @@ namespace Parser {
                     case "import":
                         tag = parseImportTag(start, tagName, margin, indentText);
                         break;
+                    case "specialize":
+                        tag = parseSpecializeTag(start, tagName, margin, indentText);
+                        break;
                     default:
                         tag = parseUnknownTag(start, tagName, margin, indentText);
                         break;
@@ -9565,6 +9573,24 @@ namespace Parser {
                 return finishNode(factory.createJSDocImportTag(tagName, importClause, moduleSpecifier, attributes, comments), start);
             }
 
+            function parseSpecializeTag(start: number, tagName: Identifier, margin: number, indentText: string): JSDocSpecializeTag {
+                if (some(tags, isJSDocSpecializeTag)) {
+                    parseErrorAt(tagName.pos, scanner.getTokenStart(), Diagnostics._0_tag_already_specified, unescapeLeadingUnderscores(tagName.escapedText));
+                }
+                const pos = getNodePos();
+                scanner.setSkipJsDocLeadingAsterisks(true);
+                let typeArguments: NodeArray<TypeNode>;
+                if (token() === SyntaxKind.LessThanToken) {
+                    typeArguments = parseBracketedList(ParsingContext.TypeArguments, parseJSDocType, SyntaxKind.LessThanToken, SyntaxKind.GreaterThanToken);
+                }
+                else {
+                    typeArguments = parseBracketedList(ParsingContext.TypeArguments, parseJSDocType, SyntaxKind.OpenBraceToken, SyntaxKind.CloseBraceToken);
+                }
+                scanner.setSkipJsDocLeadingAsterisks(false);
+                const comments = margin !== undefined && indentText !== undefined ? parseTrailingTagComments(start, getNodePos(), margin, indentText) : undefined;
+                return finishNode(factory.createJSDocSpecializeTag(tagName, typeArguments, comments), pos);
+            }
+
             function parseExpressionWithTypeArgumentsForAugments(): ExpressionWithTypeArguments & { expression: Identifier | PropertyAccessEntityNameExpression; } {
                 const usedBrace = parseOptional(SyntaxKind.OpenBraceToken);
                 const pos = getNodePos();