convert JSDoc typedef to type, issue#50644

Author: Brenda Huang

src/compiler/diagnosticMessages.json

@@ -6622,7 +6622,14 @@
         "category": "Suggestion",
         "code": 80008
     },
-
+    "JSDoc typedef may be converted to type": {
+        "category": "Suggestion",
+        "code": 80009
+    },
+    "JSDoc typedefs may be converted to types": {
+        "category": "Suggestion",
+        "code": 80010
+    },
     "Add missing 'super()' call": {
         "category": "Message",
         "code": 90001

src/services/_namespaces/ts.codefix.ts

@@ -17,6 +17,7 @@ export * from "../codefixes/convertToEsModule";
 export * from "../codefixes/correctQualifiedNameToIndexedAccessType";
 export * from "../codefixes/convertToTypeOnlyExport";
 export * from "../codefixes/convertToTypeOnlyImport";
+export * from "../codefixes/convertTypedefToType";
 export * from "../codefixes/convertLiteralTypeToMappedType";
 export * from "../codefixes/fixClassIncorrectlyImplementsInterface";
 export * from "../codefixes/importFixes";

src/services/codefixes/convertTypedefToType.ts

@@ -0,0 +1,249 @@
+import {
+    Diagnostics,
+    factory,
+    flatMap,
+    getTokenAtPosition,
+    HasJSDoc,
+    hasJSDocNodes,
+    InterfaceDeclaration,
+    isInJSDoc,
+    isJSDocTypedefTag,
+    JSDocPropertyTag,
+    JSDocTypedefTag,
+    JSDocTypeExpression,
+    JSDocTypeLiteral,
+    Node,
+    ParenthesizedTypeNode,
+    PropertySignature,
+    reduceLeft,
+    some,
+    SourceFile,
+    SyntaxKind,
+    textChanges,
+    TypeAliasDeclaration,
+    TypeNode,
+    TypeNodeSyntaxKind,
+    UnionTypeNode,
+} from "../_namespaces/ts";
+import { codeFixAll, createCodeFixAction, registerCodeFix } from "../_namespaces/ts.codefix";
+
+const fixId = "convertTypedefToType";
+const errorCodes = [Diagnostics.JSDoc_typedef_may_be_converted_to_type.code];
+registerCodeFix({
+    fixIds: [fixId],
+    errorCodes,
+    getCodeActions(context) {
+        const node = getTokenAtPosition(
+            context.sourceFile,
+            context.span.start
+        );
+        if (!node) return;
+        const changes = textChanges.ChangeTracker.with(context, t => doChange(t, node, context.sourceFile));
+
+        if (changes.length > 0) {
+            return [
+                createCodeFixAction(
+                    fixId,
+                    changes,
+                    Diagnostics.JSDoc_typedef_may_be_converted_to_type,
+                    fixId,
+                    Diagnostics.JSDoc_typedefs_may_be_converted_to_types
+                ),
+            ];
+        }
+    },
+    getAllCodeActions: context => codeFixAll(context, errorCodes, (changes, diag) => {
+        const node = getTokenAtPosition(diag.file, diag.start);
+        if (node) doChange(changes, node, diag.file);
+    })
+});
+
+function doChange(changes: textChanges.ChangeTracker, node: Node, sourceFile: SourceFile) {
+    if (containsTypeDefTag(node)) {
+        fixSingleTypeDef(changes, node, sourceFile);
+    }
+}
+
+function fixSingleTypeDef(
+    changes: textChanges.ChangeTracker,
+    typeDefNode: JSDocTypedefTag | undefined,
+    sourceFile: SourceFile,
+) {
+    if (!typeDefNode) return;
+
+    const declaration = createDeclaration(typeDefNode);
+    if (!declaration) return;
+
+    const comment = typeDefNode.parent;
+
+    changes.replaceNode(
+        sourceFile,
+        comment,
+        declaration
+    );
+}
+
+function createDeclaration(tag: JSDocTypedefTag): InterfaceDeclaration | TypeAliasDeclaration | undefined {
+    const { typeExpression } = tag;
+    if (!typeExpression) return;
+    const typeName = tag.name?.getFullText().trim();
+    if (!typeName) return;
+
+    // For use case @typedef {object}Foo @property{bar}number
+    // But object type can be nested, meaning the value in the k/v pair can be object itself
+    if (typeExpression.kind === SyntaxKind.JSDocTypeLiteral) {
+        return createInterfaceForTypeLiteral(typeName, typeExpression);
+    }
+    // for use case @typedef {(number|string|undefined)} Foo or @typedef {number|string|undefined} Foo
+    // In this case, we reach the leaf node of AST.
+    // Here typeExpression.type is a TypeNode, e.g. a UnionType or a primitive type, such as "number".
+    if (typeExpression.kind === SyntaxKind.JSDocTypeExpression) {
+        return createTypeAliasForTypeExpression(typeName, typeExpression);
+    }
+}
+
+function createInterfaceForTypeLiteral(
+    typeName: string,
+    typeLiteral: JSDocTypeLiteral
+): InterfaceDeclaration | undefined {
+    const propertySignatures = createSignatureFromTypeLiteral(typeLiteral);
+    if (!propertySignatures || propertySignatures.length === 0) return;
+    const interfaceDeclaration = factory.createInterfaceDeclaration(
+        [],
+        typeName,
+        [],
+        [],
+        propertySignatures,
+    );
+    return interfaceDeclaration;
+}
+
+function createTypeAliasForTypeExpression(
+    typeName: string,
+    typeExpression: JSDocTypeExpression
+): TypeAliasDeclaration | undefined {
+    const typeReference = createTypeReference(typeExpression.type);
+    if (!typeReference) return;
+    const declaration = factory.createTypeAliasDeclaration(
+        [],
+        factory.createIdentifier(typeName),
+        [],
+        typeReference
+    );
+    return declaration;
+}
+
+function createSignatureFromTypeLiteral(typeLiteral: JSDocTypeLiteral): PropertySignature[] | undefined {
+    const propertyTags = typeLiteral.jsDocPropertyTags;
+    if (!propertyTags || propertyTags.length === 0) return;
+
+    const getSignatures = (signatures: PropertySignature[], tag: JSDocPropertyTag) => {
+        const name = getPropertyName(tag);
+        const type = tag.typeExpression?.type;
+        let typeReference;
+
+        // Recursively handle nested object type
+        if (type && type.kind === SyntaxKind.JSDocTypeLiteral) {
+            const signatures = createSignatureFromTypeLiteral(type as JSDocTypeLiteral);
+            typeReference = factory.createTypeLiteralNode(signatures);
+        }
+        // Leaf node, where type.kind === SyntaxKind.JSDocTypeExpression
+        else if (type) {
+            typeReference = createTypeReference(type);
+        }
+        if (typeReference && name) {
+            const prop = factory.createPropertySignature(
+                [],
+                name,
+                // eslint-disable-next-line local/boolean-trivia
+                undefined,
+                typeReference
+            );
+            return [...signatures, prop];
+        }
+    };
+
+    const props = reduceLeft(propertyTags, getSignatures, []);
+    return props;
+}
+
+function getPropertyName(tag: JSDocPropertyTag): string | undefined {
+    const { name } = tag;
+    if (!name) return;
+
+    let propertyName;
+    // for "@property {string} parent.child" or "@property {string} parent.child.grandchild" in nested object type
+    // We'll get "child" in the first example or "grandchild" in the second example as the prop name
+    if (name.kind === SyntaxKind.QualifiedName) {
+        propertyName = name.right.getFullText().trim();
+    }
+    else {
+        propertyName = tag.name.getFullText().trim();
+    }
+    return propertyName;
+}
+
+// Create TypeReferenceNode when we reach the leaf node of AST
+function createTypeReference(type: TypeNode): TypeNode | undefined {
+    let typeReference;
+    if (type.kind === SyntaxKind.ParenthesizedType) {
+        type = (type as ParenthesizedTypeNode).type;
+    }
+    // Create TypeReferenceNode for UnionType
+    if (type.kind === SyntaxKind.UnionType) {
+        const elements = (type as UnionTypeNode).types;
+        const nodes = reduceLeft(
+            elements,
+            (nodeArray, element) => {
+                const node = transformUnionTypeKeyword(element.kind);
+                if (node) return [...nodeArray, node];
+            },
+            []
+        );
+
+        if (!nodes) return;
+        typeReference = factory.createUnionTypeNode(nodes);
+    }
+    //Create TypeReferenceNode for primitive types
+    else {
+        typeReference = transformUnionTypeKeyword(type.kind);
+    }
+    return typeReference;
+}
+
+function transformUnionTypeKeyword(keyword: TypeNodeSyntaxKind): TypeNode | undefined {
+    switch (keyword) {
+        case SyntaxKind.NumberKeyword:
+            return factory.createTypeReferenceNode("number");
+        case SyntaxKind.StringKeyword:
+            return factory.createTypeReferenceNode("string");
+        case SyntaxKind.UndefinedKeyword:
+            return factory.createTypeReferenceNode("undefined");
+        case SyntaxKind.ObjectKeyword:
+            return factory.createTypeReferenceNode("object");
+        case SyntaxKind.VoidKeyword:
+            return factory.createTypeReferenceNode("void");
+        default:
+            return;
+    }
+}
+
+/** @internal */
+export function containsJSDocTypedef(node: Node): node is HasJSDoc {
+    return hasJSDocNodes(node) && some(node.jsDoc, node => some(node.tags, tag => isJSDocTypedefTag(tag)));
+}
+
+/** @internal */
+export function getJSDocTypedefNode(node: HasJSDoc): JSDocTypedefTag {
+    const jsDocNodes = node.jsDoc || [];
+
+    return flatMap(jsDocNodes, (node) => {
+        const tags = node.tags || [];
+        return tags.filter((tag) => isJSDocTypedefTag(tag));
+    })[0] as unknown as JSDocTypedefTag;
+}
+
+/** @internal */
+export function containsTypeDefTag(node: Node): node is JSDocTypedefTag {
+    return isInJSDoc(node) && isJSDocTypedefTag(node);
+}

src/services/suggestionDiagnostics.ts

@@ -117,6 +117,11 @@ export function computeSuggestionDiagnostics(sourceFile: SourceFile, program: Pr
                 }
             }
 
+            if (codefix.containsJSDocTypedef(node)) {
+                const jsdocTypedefNode = codefix.getJSDocTypedefNode(node);
+                diags.push(createDiagnosticForNode(jsdocTypedefNode, Diagnostics.Convert_typedef_to_type));
+            }
+
             if (codefix.parameterShouldGetTypeFromJSDoc(node)) {
                 diags.push(createDiagnosticForNode(node.name || node, Diagnostics.JSDoc_types_may_be_moved_to_TypeScript_types));
             }

tests/cases/fourslash/codeFixConvertTypedefToType1.ts

@@ -0,0 +1,18 @@
+/// <reference path='fourslash.ts' />
+
+////
+//// /**
+////  * @typedef {Object}Foo
+////  * @property {number}bar
+////  */
+////
+
+verify.codeFix({
+  description: ts.Diagnostics.Convert_typedef_to_type.message,
+  index: 0,
+  newFileContent: `
+interface Foo {
+    bar: number;
+}
+`,
+});

tests/cases/fourslash/codeFixConvertTypedefToType2.ts

@@ -0,0 +1,15 @@
+/// <reference path='fourslash.ts' />
+
+////
+//// /**
+////  * @typedef {(number|string|undefined)} Foo
+////  */
+////
+
+verify.codeFix({
+  description: ts.Diagnostics.Convert_typedef_to_type.message,
+  index: 0,
+  newFileContent: `
+type Foo = number | string | undefined;
+`,
+});

tests/cases/fourslash/codeFixConvertTypedefToType3.ts

@@ -0,0 +1,23 @@
+/// <reference path='fourslash.ts' />
+
+////
+//// /**
+////  * @typedef Foo
+////  * type {object}
+////  * @property {string} id - person's ID
+////  * @property {string} name - person's name
+////  * @property {number} age - person's age
+////  */
+////
+
+verify.codeFix({
+  description: ts.Diagnostics.Convert_typedef_to_type.message,
+  index: 0,
+  newFileContent: `
+interface Foo {
+    id: string;
+    name: string;
+    age: number;
+}
+`,
+});

tests/cases/fourslash/codeFixConvertTypedefToType4.ts

@@ -0,0 +1,30 @@
+/// <reference path='fourslash.ts' />
+
+////
+//// /**
+////  * @typedef {object} Person
+////  * @property {object} data
+////  * @property {string} data.name
+////  * @property {number} data.age
+////  * @property {object} data.contact
+////  * @property {string} data.contact.address
+////  * @property {string} data.contact.phone
+////  */
+////
+
+verify.codeFix({
+  description: ts.Diagnostics.Convert_typedef_to_type.message,
+  index: 0,
+  newFileContent: `
+interface Person {
+    data: {
+        name: string;
+        age: number;
+        contact: {
+            address: string;
+            phone: string;
+        };
+    };
+}
+`,
+});

tests/cases/fourslash/codeFixConvertTypedefToType5.ts

@@ -0,0 +1,15 @@
+/// <reference path='fourslash.ts' />
+
+////
+//// /**
+////  * @typedef {number} Foo
+////  */
+////
+
+verify.codeFix({
+  description: ts.Diagnostics.Convert_typedef_to_type.message,
+  index: 0,
+  newFileContent: `
+type Foo = number;
+`,
+});