Fix name resolution in typedef and allow defaults for template tags

src/compiler/binder.ts

@@ -3388,7 +3388,7 @@ namespace ts {
 
         function bindTypeParameter(node: TypeParameterDeclaration) {
             if (isJSDocTemplateTag(node.parent)) {
-                const container = find((node.parent.parent as JSDoc).tags!, isJSDocTypeAlias) || getHostSignatureFromJSDoc(node.parent); // TODO: GH#18217
+                const container = getEffectiveContainerForJSDocTemplateTag(node.parent);
                 if (container) {
                     if (!container.locals) {
                         container.locals = createSymbolTable();

src/compiler/checker.ts

@@ -2050,7 +2050,9 @@ namespace ts {
                     lastSelfReferenceLocation = location;
                 }
                 lastLocation = location;
-                location = location.parent;
+                location = isJSDocTemplateTag(location) ?
+                    getEffectiveContainerForJSDocTemplateTag(location) || location.parent :
+                    location.parent;
             }
 
             // We just climbed up parents looking for the name, meaning that we started in a descendant node of `lastLocation`.
@@ -12855,7 +12857,7 @@ namespace ts {
 
         function getParentSymbolOfTypeParameter(typeParameter: TypeParameter): Symbol | undefined {
             const tp = getDeclarationOfKind<TypeParameterDeclaration>(typeParameter.symbol, SyntaxKind.TypeParameter)!;
-            const host = isJSDocTemplateTag(tp.parent) ? getHostSignatureFromJSDoc(tp.parent) : tp.parent;
+            const host = isJSDocTemplateTag(tp.parent) ? getEffectiveContainerForJSDocTemplateTag(tp.parent) : tp.parent;
             return host && getSymbolOfNode(host);
         }
 
@@ -33547,7 +33549,7 @@ namespace ts {
                 }
             }
 
-            checkTypeParameters(node.typeParameters);
+            checkTypeParameters(getEffectiveTypeParameterDeclarations(node));
 
             forEach(node.parameters, checkParameter);
 
@@ -35180,6 +35182,7 @@ namespace ts {
                 checkTypeNameIsReserved(node.name, Diagnostics.Type_alias_name_cannot_be_0);
             }
             checkSourceElement(node.typeExpression);
+            checkTypeParameters(getEffectiveTypeParameterDeclarations(node));
         }
 
         function checkJSDocTemplateTag(node: JSDocTemplateTag): void {

src/compiler/parser.ts

@@ -8441,11 +8441,24 @@ namespace ts {
 
                 function parseTemplateTagTypeParameter() {
                     const typeParameterPos = getNodePos();
+                    const isBracketed = parseOptionalJsdoc(SyntaxKind.OpenBracketToken);
+                    if (isBracketed) {
+                        skipWhitespace();
+                    }
                     const name = parseJSDocIdentifierName(Diagnostics.Unexpected_token_A_type_parameter_name_was_expected_without_curly_braces);
+
+                    let defaultType: TypeNode | undefined;
+                    if (isBracketed) {
+                        skipWhitespace();
+                        parseExpected(SyntaxKind.EqualsToken);
+                        defaultType = doInsideOfContext(NodeFlags.JSDoc, parseJSDocType);
+                        parseExpected(SyntaxKind.CloseBracketToken);
+                    }
+
                     if (nodeIsMissing(name)) {
                         return undefined;
                     }
-                    return finishNode(factory.createTypeParameterDeclaration(name, /*constraint*/ undefined, /*defaultType*/ undefined), typeParameterPos);
+                    return finishNode(factory.createTypeParameterDeclaration(name, /*constraint*/ undefined, defaultType), typeParameterPos);
                 }
 
                 function parseTemplateTagTypeParameters() {

src/compiler/utilities.ts

@@ -2703,6 +2703,18 @@ namespace ts {
         return parameter && parameter.symbol;
     }
 
+    export function getEffectiveContainerForJSDocTemplateTag(node: JSDocTemplateTag) {
+        if (isJSDoc(node.parent) && node.parent.tags) {
+            // A @template tag belongs to any @typedef, @callback, or @enum tags in the same comment block, if they exist.
+            const typeAlias = find(node.parent.tags, isJSDocTypeAlias);
+            if (typeAlias) {
+                return typeAlias;
+            }
+        }
+        // otherwise it belongs to the host it annotates
+        return getHostSignatureFromJSDoc(node);
+    }
+
     export function getHostSignatureFromJSDoc(node: Node): SignatureDeclaration | undefined {
         const host = getEffectiveJSDocHost(node);
         return host && isFunctionLike(host) ? host : undefined;

tests/baselines/reference/completionEntryForUnionMethod.baseline

@@ -1722,7 +1722,7 @@
                   "kind": "space"
                 },
                 {
-                  "text": "Function used to determine the order of the elements. It is expected to return\r\na negative value if first argument is less than second argument, zero if they're equal and a positive\r\nvalue otherwise. If omitted, the elements are sorted in ascending, ASCII character order.\r\n```ts\r\n[11,2,22,1].sort((a, b) => a - b)\r\n```",
+                  "text": "Function used to determine the order of the elements. It is expected to return\r\na negative value if the first argument is less than the second argument, zero if they're equal, and a positive\r\nvalue otherwise. If omitted, the elements are sorted in ascending, ASCII character order.\r\n```ts\r\n[11,2,22,1].sort((a, b) => a - b)\r\n```",
                   "kind": "text"
                 }
               ]

tests/baselines/reference/jsdocTemplateTagDefault.errors.txt

@@ -0,0 +1,99 @@
+tests/cases/conformance/jsdoc/file.js(9,20): error TS2322: Type 'number' is not assignable to type 'string'.
+tests/cases/conformance/jsdoc/file.js(22,34): error TS1005: '=' expected.
+tests/cases/conformance/jsdoc/file.js(27,35): error TS1110: Type expected.
+tests/cases/conformance/jsdoc/file.js(33,14): error TS2706: Required type parameters may not follow optional type parameters.
+tests/cases/conformance/jsdoc/file.js(39,14): error TS2706: Required type parameters may not follow optional type parameters.
+tests/cases/conformance/jsdoc/file.js(44,17): error TS2744: Type parameter defaults can only reference previously declared type parameters.
+tests/cases/conformance/jsdoc/file.js(59,14): error TS2706: Required type parameters may not follow optional type parameters.
+tests/cases/conformance/jsdoc/file.js(66,17): error TS2744: Type parameter defaults can only reference previously declared type parameters.
+
+
+==== tests/cases/conformance/jsdoc/file.js (8 errors) ====
+    /**
+     * @template {string | number} [T=string] - ok: defaults are permitted
+     * @typedef {[T]} A
+     */
+
+    /** @type {A} */ // ok, default for `T` in `A` is `string`
+    const aDefault1 = [""];
+    /** @type {A} */ // error: `number` is not assignable to string`
+    const aDefault2 = [0];
+                       ~
+!!! error TS2322: Type 'number' is not assignable to type 'string'.
+    /** @type {A<string>} */ // ok, `T` is provided for `A`
+    const aString = [""];
+    /** @type {A<number>} */ // ok, `T` is provided for `A`
+    const aNumber = [0];
+
+    /**
+     * @template T
+     * @template [U=T] - ok: default can reference earlier type parameter
+     * @typedef {[T, U]} B
+     */
+
+    /**
+     * @template {string | number} [T] - error: default requires an `=type`
+                                     ~
+!!! error TS1005: '=' expected.
+     * @typedef {[T]} C
+     */
+
+    /**
+     * @template {string | number} [T=] - error: default requires a `type`
+                                      ~
+!!! error TS1110: Type expected.
+     * @typedef {[T]} D
+     */
+
+    /**
+     * @template {string | number} [T=string]
+     * @template U - error: Required type parameters cannot follow optional type parameters
+                 ~
+!!! error TS2706: Required type parameters may not follow optional type parameters.
+     * @typedef {[T, U]} E
+     */
+
+    /**
+     * @template {string | number} [T=string]
+     * @template U - error: Required type parameters cannot follow optional type parameters
+                 ~
+!!! error TS2706: Required type parameters may not follow optional type parameters.
+     * @typedef {[T, U]} F
+     */
+
+    /**
+     * @template [T=U] - error: Type parameter defaults can only reference previously declared type parameters.
+                    ~
+!!! error TS2744: Type parameter defaults can only reference previously declared type parameters.
+     * @template [U=T]
+     * @typedef {[T, U]} G
+     */
+
+    /**
+     * @template T
+     * @template [U=T] - ok: default can reference earlier type parameter
+     * @param {T} a
+     * @param {U} b
+     */
+    function f1(a, b) {}
+
+     /**
+     * @template {string | number} [T=string]
+     * @template U - error: Required type parameters cannot follow optional type parameters
+                 ~
+!!! error TS2706: Required type parameters may not follow optional type parameters.
+     * @param {T} a
+     * @param {U} b
+     */
+    function f2(a, b) {}
+
+    /**
+     * @template [T=U] - error: Type parameter defaults can only reference previously declared type parameters.
+                    ~
+!!! error TS2744: Type parameter defaults can only reference previously declared type parameters.
+     * @template [U=T]
+     * @param {T} a
+     * @param {U} b
+     */
+    function f3(a, b) {}
+

tests/baselines/reference/jsdocTemplateTagDefault.symbols

@@ -0,0 +1,89 @@
+=== tests/cases/conformance/jsdoc/file.js ===
+/**
+ * @template {string | number} [T=string] - ok: defaults are permitted
+ * @typedef {[T]} A
+ */
+
+/** @type {A} */ // ok, default for `T` in `A` is `string`
+const aDefault1 = [""];
+>aDefault1 : Symbol(aDefault1, Decl(file.js, 6, 5))
+
+/** @type {A} */ // error: `number` is not assignable to string`
+const aDefault2 = [0];
+>aDefault2 : Symbol(aDefault2, Decl(file.js, 8, 5))
+
+/** @type {A<string>} */ // ok, `T` is provided for `A`
+const aString = [""];
+>aString : Symbol(aString, Decl(file.js, 10, 5))
+
+/** @type {A<number>} */ // ok, `T` is provided for `A`
+const aNumber = [0];
+>aNumber : Symbol(aNumber, Decl(file.js, 12, 5))
+
+/**
+ * @template T
+ * @template [U=T] - ok: default can reference earlier type parameter
+ * @typedef {[T, U]} B
+ */
+
+/**
+ * @template {string | number} [T] - error: default requires an `=type`
+ * @typedef {[T]} C
+ */
+
+/**
+ * @template {string | number} [T=] - error: default requires a `type`
+ * @typedef {[T]} D
+ */
+
+/**
+ * @template {string | number} [T=string]
+ * @template U - error: Required type parameters cannot follow optional type parameters
+ * @typedef {[T, U]} E
+ */
+
+/**
+ * @template {string | number} [T=string]
+ * @template U - error: Required type parameters cannot follow optional type parameters
+ * @typedef {[T, U]} F
+ */
+
+/**
+ * @template [T=U] - error: Type parameter defaults can only reference previously declared type parameters.
+ * @template [U=T]
+ * @typedef {[T, U]} G
+ */
+
+/**
+ * @template T
+ * @template [U=T] - ok: default can reference earlier type parameter
+ * @param {T} a
+ * @param {U} b
+ */
+function f1(a, b) {}
+>f1 : Symbol(f1, Decl(file.js, 12, 20))
+>a : Symbol(a, Decl(file.js, 54, 12))
+>b : Symbol(b, Decl(file.js, 54, 14))
+
+ /**
+ * @template {string | number} [T=string]
+ * @template U - error: Required type parameters cannot follow optional type parameters
+ * @param {T} a
+ * @param {U} b
+ */
+function f2(a, b) {}
+>f2 : Symbol(f2, Decl(file.js, 54, 20))
+>a : Symbol(a, Decl(file.js, 62, 12))
+>b : Symbol(b, Decl(file.js, 62, 14))
+
+/**
+ * @template [T=U] - error: Type parameter defaults can only reference previously declared type parameters.
+ * @template [U=T]
+ * @param {T} a
+ * @param {U} b
+ */
+function f3(a, b) {}
+>f3 : Symbol(f3, Decl(file.js, 62, 20))
+>a : Symbol(a, Decl(file.js, 70, 12))
+>b : Symbol(b, Decl(file.js, 70, 14))
+

tests/baselines/reference/jsdocTemplateTagDefault.types

@@ -0,0 +1,97 @@
+=== tests/cases/conformance/jsdoc/file.js ===
+/**
+ * @template {string | number} [T=string] - ok: defaults are permitted
+ * @typedef {[T]} A
+ */
+
+/** @type {A} */ // ok, default for `T` in `A` is `string`
+const aDefault1 = [""];
+>aDefault1 : A<string>
+>[""] : [string]
+>"" : ""
+
+/** @type {A} */ // error: `number` is not assignable to string`
+const aDefault2 = [0];
+>aDefault2 : A<string>
+>[0] : [number]
+>0 : 0
+
+/** @type {A<string>} */ // ok, `T` is provided for `A`
+const aString = [""];
+>aString : A<string>
+>[""] : [string]
+>"" : ""
+
+/** @type {A<number>} */ // ok, `T` is provided for `A`
+const aNumber = [0];
+>aNumber : A<number>
+>[0] : [number]
+>0 : 0
+
+/**
+ * @template T
+ * @template [U=T] - ok: default can reference earlier type parameter
+ * @typedef {[T, U]} B
+ */
+
+/**
+ * @template {string | number} [T] - error: default requires an `=type`
+ * @typedef {[T]} C
+ */
+
+/**
+ * @template {string | number} [T=] - error: default requires a `type`
+ * @typedef {[T]} D
+ */
+
+/**
+ * @template {string | number} [T=string]
+ * @template U - error: Required type parameters cannot follow optional type parameters
+ * @typedef {[T, U]} E
+ */
+
+/**
+ * @template {string | number} [T=string]
+ * @template U - error: Required type parameters cannot follow optional type parameters
+ * @typedef {[T, U]} F
+ */
+
+/**
+ * @template [T=U] - error: Type parameter defaults can only reference previously declared type parameters.
+ * @template [U=T]
+ * @typedef {[T, U]} G
+ */
+
+/**
+ * @template T
+ * @template [U=T] - ok: default can reference earlier type parameter
+ * @param {T} a
+ * @param {U} b
+ */
+function f1(a, b) {}
+>f1 : <T, U = T>(a: T, b: U) => void
+>a : T
+>b : U
+
+ /**
+ * @template {string | number} [T=string]
+ * @template U - error: Required type parameters cannot follow optional type parameters
+ * @param {T} a
+ * @param {U} b
+ */
+function f2(a, b) {}
+>f2 : <T extends string | number = string, U>(a: T, b: U) => void
+>a : T
+>b : U
+
+/**
+ * @template [T=U] - error: Type parameter defaults can only reference previously declared type parameters.
+ * @template [U=T]
+ * @param {T} a
+ * @param {U} b
+ */
+function f3(a, b) {}
+>f3 : <T = U, U = T>(a: T, b: U) => void
+>a : T
+>b : U
+