Allow type predicates in JSDoc

src/compiler/checker.ts

@@ -7405,20 +7405,6 @@ namespace ts {
             return isBracketed || !!typeExpression && typeExpression.type.kind === SyntaxKind.JSDocOptionalType;
         }
 
-        function createTypePredicateFromTypePredicateNode(node: TypePredicateNode): IdentifierTypePredicate | ThisTypePredicate {
-            const { parameterName } = node;
-            const type = getTypeFromTypeNode(node.type);
-            if (parameterName.kind === SyntaxKind.Identifier) {
-                return createIdentifierTypePredicate(
-                    parameterName && parameterName.escapedText as string, // TODO: GH#18217
-                    parameterName && getTypePredicateParameterIndex(node.parent.parameters, parameterName),
-                    type);
-            }
-            else {
-                return createThisTypePredicate(type);
-            }
-        }
-
         function createIdentifierTypePredicate(parameterName: string, parameterIndex: number, type: Type): IdentifierTypePredicate {
             return { kind: TypePredicateKind.Identifier, parameterName, parameterIndex, type };
         }
@@ -7677,15 +7663,46 @@ namespace ts {
                 }
                 else {
                     const type = signature.declaration && getEffectiveReturnTypeNode(signature.declaration);
+                    let jsdocPredicate: TypePredicate | undefined;
+                    if (!type && isInJavaScriptFile(signature.declaration)) {
+                        const jsdocSignature = getSignatureOfTypeTag(signature.declaration!);
+                        if (jsdocSignature && signature !== jsdocSignature) {
+                            jsdocPredicate = getTypePredicateOfSignature(jsdocSignature);
+                        }
+                    }
                     signature.resolvedTypePredicate = type && isTypePredicateNode(type) ?
-                        createTypePredicateFromTypePredicateNode(type) :
-                        noTypePredicate;
+                        createTypePredicateFromTypePredicateNode(type, signature.declaration!) :
+                        jsdocPredicate || noTypePredicate;
                 }
                 Debug.assert(!!signature.resolvedTypePredicate);
             }
             return signature.resolvedTypePredicate === noTypePredicate ? undefined : signature.resolvedTypePredicate;
         }
 
+        function createTypePredicateFromTypePredicateNode(node: TypePredicateNode, func: SignatureDeclaration | JSDocSignature): IdentifierTypePredicate | ThisTypePredicate {
+            const { parameterName } = node;
+            const type = getTypeFromTypeNode(node.type);
+            if (parameterName.kind === SyntaxKind.Identifier) {
+                return createIdentifierTypePredicate(
+                    parameterName.escapedText as string,
+                    getTypePredicateParameterIndex(func.parameters, parameterName),
+                    type);
+            }
+            else {
+                return createThisTypePredicate(type);
+            }
+        }
+
+        function getTypePredicateParameterIndex(parameterList: ReadonlyArray<ParameterDeclaration | JSDocParameterTag>, parameter: Identifier): number {
+            for (let i = 0; i < parameterList.length; i++) {
+                const param = parameterList[i];
+                if (param.name.kind === SyntaxKind.Identifier && param.name.escapedText === parameter.escapedText) {
+                    return i;
+                }
+            }
+            return -1;
+        }
+
         function getReturnTypeOfSignature(signature: Signature): Type {
             if (!signature.resolvedReturnType) {
                 if (!pushTypeResolution(signature, TypeSystemPropertyName.ResolvedReturnType)) {
@@ -22049,18 +22066,6 @@ namespace ts {
             }
         }
 
-        function getTypePredicateParameterIndex(parameterList: NodeArray<ParameterDeclaration>, parameter: Identifier): number {
-            if (parameterList) {
-                for (let i = 0; i < parameterList.length; i++) {
-                    const param = parameterList[i];
-                    if (param.name.kind === SyntaxKind.Identifier && param.name.escapedText === parameter.escapedText) {
-                        return i;
-                    }
-                }
-            }
-            return -1;
-        }
-
         function checkTypePredicate(node: TypePredicateNode): void {
             const parent = getTypePredicateParent(node);
             if (!parent) {

src/compiler/parser.ts

@@ -2374,7 +2374,7 @@ namespace ts {
 
         function parseJSDocType(): TypeNode {
             const dotdotdot = parseOptionalToken(SyntaxKind.DotDotDotToken);
-            let type = parseType();
+            let type = parseTypeOrTypePredicate();
             if (dotdotdot) {
                 const variadic = createNode(SyntaxKind.JSDocVariadicType, dotdotdot.pos) as JSDocVariadicType;
                 variadic.type = type;

src/compiler/types.ts

@@ -1081,7 +1081,7 @@ namespace ts {
 
     export interface TypePredicateNode extends TypeNode {
         kind: SyntaxKind.TypePredicate;
-        parent: SignatureDeclaration;
+        parent: SignatureDeclaration | JSDocTypeExpression;
         parameterName: Identifier | ThisTypeNode;
         type: TypeNode;
     }

tests/baselines/reference/api/tsserverlibrary.d.ts

@@ -751,7 +751,7 @@ declare namespace ts {
     }
     interface TypePredicateNode extends TypeNode {
         kind: SyntaxKind.TypePredicate;
-        parent: SignatureDeclaration;
+        parent: SignatureDeclaration | JSDocTypeExpression;
         parameterName: Identifier | ThisTypeNode;
         type: TypeNode;
     }

tests/baselines/reference/api/typescript.d.ts

@@ -751,7 +751,7 @@ declare namespace ts {
     }
     interface TypePredicateNode extends TypeNode {
         kind: SyntaxKind.TypePredicate;
-        parent: SignatureDeclaration;
+        parent: SignatureDeclaration | JSDocTypeExpression;
         parameterName: Identifier | ThisTypeNode;
         type: TypeNode;
     }

tests/baselines/reference/jsdocTypeTagCast.errors.txt

@@ -11,9 +11,7 @@ tests/cases/conformance/jsdoc/b.js(58,1): error TS2322: Type 'SomeFakeClass' is
   Types of property 'p' are incompatible.
     Type 'string | number' is not assignable to type 'number'.
       Type 'string' is not assignable to type 'number'.
-tests/cases/conformance/jsdoc/b.js(66,8): error TS2352: Conversion of type 'boolean' to type 'string | number' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first.
-tests/cases/conformance/jsdoc/b.js(66,15): error TS2304: Cannot find name 'numOrStr'.
-tests/cases/conformance/jsdoc/b.js(66,24): error TS1005: '}' expected.
+tests/cases/conformance/jsdoc/b.js(66,15): error TS1228: A type predicate is only allowed in return type position for functions and methods.
 tests/cases/conformance/jsdoc/b.js(66,38): error TS2454: Variable 'numOrStr' is used before being assigned.
 tests/cases/conformance/jsdoc/b.js(67,2): error TS2322: Type 'string | number' is not assignable to type 'string'.
   Type 'number' is not assignable to type 'string'.
@@ -23,7 +21,7 @@ tests/cases/conformance/jsdoc/b.js(67,8): error TS2454: Variable 'numOrStr' is u
 ==== tests/cases/conformance/jsdoc/a.ts (0 errors) ====
     var W: string;
 
-==== tests/cases/conformance/jsdoc/b.js (12 errors) ====
+==== tests/cases/conformance/jsdoc/b.js (10 errors) ====
     // @ts-check
     var W = /** @type {string} */(/** @type {*} */ (4));
 
@@ -109,12 +107,8 @@ tests/cases/conformance/jsdoc/b.js(67,8): error TS2454: Variable 'numOrStr' is u
     /** @type {string} */
     var str;
     if(/** @type {numOrStr is string} */(numOrStr === undefined)) { // Error
-           ~~~~~~~~~~~~~~~
-!!! error TS2352: Conversion of type 'boolean' to type 'string | number' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first.
-                  ~~~~~~~~
-!!! error TS2304: Cannot find name 'numOrStr'.
-                           ~~
-!!! error TS1005: '}' expected.
+                  ~~~~~~~~~~~~~~~~~~
+!!! error TS1228: A type predicate is only allowed in return type position for functions and methods.
                                          ~~~~~~~~
 !!! error TS2454: Variable 'numOrStr' is used before being assigned.
     	str = numOrStr; // Error, no narrowing occurred

tests/baselines/reference/jsdocTypeTagCast.types

@@ -197,7 +197,7 @@ var str;
 >str : string
 
 if(/** @type {numOrStr is string} */(numOrStr === undefined)) { // Error
->(numOrStr === undefined) : string | number
+>(numOrStr === undefined) : boolean
 >numOrStr === undefined : boolean
 >numOrStr : string | number
 >undefined : undefined

tests/baselines/reference/returnTagTypeGuard.symbols

@@ -61,3 +61,55 @@ function f(chunk) {
 >x : Symbol(x, Decl(bug25127.js, 26, 7))
 }
 
+/**
+ * @param {any} value
+ * @return {value is boolean}
+ */
+function isBoolean(value) {
+>isBoolean : Symbol(isBoolean, Decl(bug25127.js, 28, 1))
+>value : Symbol(value, Decl(bug25127.js, 34, 19))
+
+    return typeof value === "boolean";
+>value : Symbol(value, Decl(bug25127.js, 34, 19))
+}
+
+/** @param {boolean | number} val */
+function foo(val) {
+>foo : Symbol(foo, Decl(bug25127.js, 36, 1))
+>val : Symbol(val, Decl(bug25127.js, 39, 13))
+
+    if (isBoolean(val)) {
+>isBoolean : Symbol(isBoolean, Decl(bug25127.js, 28, 1))
+>val : Symbol(val, Decl(bug25127.js, 39, 13))
+
+        val;
+>val : Symbol(val, Decl(bug25127.js, 39, 13))
+    }
+}
+
+/**
+ * @callback Cb
+ * @param {unknown} x
+ * @return {x is number}
+ */
+
+/** @type {Cb} */
+function isNumber(x) { return typeof x === "number" }
+>isNumber : Symbol(isNumber, Decl(bug25127.js, 43, 1))
+>x : Symbol(x, Decl(bug25127.js, 52, 18))
+>x : Symbol(x, Decl(bug25127.js, 52, 18))
+
+/** @param {unknown} x */
+function g(x) {
+>g : Symbol(g, Decl(bug25127.js, 52, 53))
+>x : Symbol(x, Decl(bug25127.js, 55, 11))
+
+    if (isNumber(x)) {
+>isNumber : Symbol(isNumber, Decl(bug25127.js, 43, 1))
+>x : Symbol(x, Decl(bug25127.js, 55, 11))
+
+        x * 2;
+>x : Symbol(x, Decl(bug25127.js, 55, 11))
+    }
+}
+

tests/baselines/reference/returnTagTypeGuard.types

@@ -69,3 +69,65 @@ function f(chunk) {
 >x : string | number
 }
 
+/**
+ * @param {any} value
+ * @return {value is boolean}
+ */
+function isBoolean(value) {
+>isBoolean : (value: any) => value is boolean
+>value : any
+
+    return typeof value === "boolean";
+>typeof value === "boolean" : boolean
+>typeof value : "string" | "number" | "boolean" | "symbol" | "undefined" | "object" | "function"
+>value : any
+>"boolean" : "boolean"
+}
+
+/** @param {boolean | number} val */
+function foo(val) {
+>foo : (val: number | boolean) => void
+>val : number | boolean
+
+    if (isBoolean(val)) {
+>isBoolean(val) : boolean
+>isBoolean : (value: any) => value is boolean
+>val : number | boolean
+
+        val;
+>val : boolean
+    }
+}
+
+/**
+ * @callback Cb
+ * @param {unknown} x
+ * @return {x is number}
+ */
+
+/** @type {Cb} */
+function isNumber(x) { return typeof x === "number" }
+>isNumber : (x: unknown) => x is number
+>x : unknown
+>typeof x === "number" : boolean
+>typeof x : "string" | "number" | "boolean" | "symbol" | "undefined" | "object" | "function"
+>x : unknown
+>"number" : "number"
+
+/** @param {unknown} x */
+function g(x) {
+>g : (x: unknown) => void
+>x : unknown
+
+    if (isNumber(x)) {
+>isNumber(x) : boolean
+>isNumber : (x: unknown) => x is number
+>x : unknown
+
+        x * 2;
+>x * 2 : number
+>x : number
+>2 : 2
+    }
+}
+

tests/cases/conformance/jsdoc/returnTagTypeGuard.ts

@@ -32,3 +32,34 @@ function f(chunk) {
     let x = chunk.isInit(chunk) ? chunk.c : chunk.d
     return x
 }
+
+/**
+ * @param {any} value
+ * @return {value is boolean}
+ */
+function isBoolean(value) {
+    return typeof value === "boolean";
+}
+
+/** @param {boolean | number} val */
+function foo(val) {
+    if (isBoolean(val)) {
+        val;
+    }
+}
+
+/**
+ * @callback Cb
+ * @param {unknown} x
+ * @return {x is number}
+ */
+
+/** @type {Cb} */
+function isNumber(x) { return typeof x === "number" }
+
+/** @param {unknown} x */
+function g(x) {
+    if (isNumber(x)) {
+        x * 2;
+    }
+}