Replace eslint-plugin-jsdoc by extending local jsdoc-format rule, saving ~20% of our linting time (microsoft#51438)

jakebailey · web-flow · commit b4715d38911d · 2022-11-08T13:59:48.000-08:00
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -10,7 +10,7 @@
         "es6": true
     },
     "plugins": [
-        "@typescript-eslint", "jsdoc", "no-null", "import", "eslint-plugin-local"
+        "@typescript-eslint", "no-null", "import", "eslint-plugin-local"
     ],
     "rules": {
         "@typescript-eslint/adjacent-overload-signatures": "error",
@@ -95,9 +95,6 @@
         // eslint-plugin-no-null
         "no-null/no-null": "error",
 
-        // eslint-plugin-jsdoc
-        "jsdoc/check-alignment": "error",
-
         // eslint
         "constructor-super": "error",
         "curly": ["error", "multi-line"],
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -62,7 +62,6 @@
         "eslint": "^8.22.0",
         "eslint-formatter-autolinkable-stylish": "^1.2.0",
         "eslint-plugin-import": "^2.26.0",
-        "eslint-plugin-jsdoc": "^39.3.6",
         "eslint-plugin-local": "^1.0.0",
         "eslint-plugin-no-null": "^1.0.2",
         "fast-xml-parser": "^4.0.11",
diff --git a/scripts/eslint/rules/jsdoc-format.cjs b/scripts/eslint/rules/jsdoc-format.cjs
@@ -13,9 +13,11 @@ module.exports = createRule({
             internalCommentNotLastError: `@internal should only appear in final JSDoc comment for declaration.`,
             multipleJSDocError: `Declaration has multiple JSDoc comments.`,
             internalCommentOnParameterProperty: `@internal cannot appear on a JSDoc comment; use a declared property and an assignment in the constructor instead.`,
+            misalignedJSDocComment: `This JSDoc comment is misaligned.`,
         },
         schema: [],
         type: "problem",
+        fixable: "whitespace",
     },
     defaultOptions: [],
 
@@ -24,6 +26,11 @@ module.exports = createRule({
         const atInternal = "@internal";
         const jsdocStart = "/**";
 
+        /** @type {(text: string) => boolean} */
+        function isJSDocText(text) {
+            return text.startsWith(jsdocStart);
+        }
+
         /** @type {(c: TSESTree.Comment, indexInComment: number) => TSESTree.SourceLocation} */
         const getAtInternalLoc = (c, indexInComment) => {
             const line = c.loc.start.line;
@@ -51,7 +58,7 @@ module.exports = createRule({
         };
 
         /** @type {(node: TSESTree.Node) => void} */
-        const checkJSDocFormat = (node) => {
+        const checkDeclaration = (node) => {
             const blockComments = sourceCode.getCommentsBefore(node).filter(c => c.type === "Block");
             if (blockComments.length === 0) {
                 return;
@@ -63,7 +70,7 @@ module.exports = createRule({
                 const c = blockComments[i];
                 const rawComment = sourceCode.getText(c);
 
-                const isJSDoc = rawComment.startsWith(jsdocStart);
+                const isJSDoc = isJSDocText(rawComment);
                 if (isJSDoc && seenJSDoc) {
                     context.report({ messageId: "multipleJSDocError", node: c, loc: getJSDocStartLoc(c) });
                 }
@@ -86,25 +93,85 @@ module.exports = createRule({
             }
         };
 
+        /** @type {(node: TSESTree.Node) => void} */
+        const checkProgram = () => {
+            const comments = sourceCode.getAllComments();
+
+            for (const c of comments) {
+                if (c.type !== "Block") {
+                    continue;
+                }
+
+                const rawComment = sourceCode.getText(c);
+                if (!isJSDocText(rawComment)) {
+                    continue;
+                }
+
+                const expected = c.loc.start.column + 2;
+                const split = rawComment.split(/\r?\n/g);
+                for (let i = 1; i < split.length; i++) {
+                    const line = split[i];
+                    const match = /^ *\*/.exec(line);
+                    if (!match) {
+                        continue;
+                    }
+
+                    const actual = match[0].length;
+                    const diff = actual - expected;
+                    if (diff !== 0) {
+                        const line = c.loc.start.line + i;
+                        context.report({
+                            messageId: "misalignedJSDocComment",
+                            node: c,
+                            loc: {
+                                start: {
+                                    line,
+                                    column: 0,
+                                },
+                                end: {
+                                    line,
+                                    column: actual - 1,
+                                }
+                            },
+                            fix: (fixer) => {
+                                if (diff > 0) {
+                                    // Too many
+                                    const start = sourceCode.getIndexFromLoc({ line, column: expected - 1 });
+                                    return fixer.removeRange([start, start + diff]);
+                                }
+                                else {
+                                    // Too few
+                                    const start = sourceCode.getIndexFromLoc({ line, column: 0 });
+                                    return fixer.insertTextAfterRange([start, start], " ".repeat(-diff));
+                                }
+                            },
+                        });
+                        break;
+                    }
+                }
+            }
+        };
+
         return {
-            ClassDeclaration: checkJSDocFormat,
-            FunctionDeclaration: checkJSDocFormat,
-            TSEnumDeclaration: checkJSDocFormat,
-            TSModuleDeclaration: checkJSDocFormat,
-            VariableDeclaration: checkJSDocFormat,
-            TSInterfaceDeclaration: checkJSDocFormat,
-            TSTypeAliasDeclaration: checkJSDocFormat,
-            TSCallSignatureDeclaration: checkJSDocFormat,
-            ExportAllDeclaration: checkJSDocFormat,
-            ExportNamedDeclaration: checkJSDocFormat,
-            TSImportEqualsDeclaration: checkJSDocFormat,
-            TSNamespaceExportDeclaration: checkJSDocFormat,
-            TSConstructSignatureDeclaration: checkJSDocFormat,
-            ExportDefaultDeclaration: checkJSDocFormat,
-            TSPropertySignature: checkJSDocFormat,
-            TSIndexSignature: checkJSDocFormat,
-            TSMethodSignature: checkJSDocFormat,
-            TSParameterProperty: checkJSDocFormat,
+            Program: checkProgram,
+            ClassDeclaration: checkDeclaration,
+            FunctionDeclaration: checkDeclaration,
+            TSEnumDeclaration: checkDeclaration,
+            TSModuleDeclaration: checkDeclaration,
+            VariableDeclaration: checkDeclaration,
+            TSInterfaceDeclaration: checkDeclaration,
+            TSTypeAliasDeclaration: checkDeclaration,
+            TSCallSignatureDeclaration: checkDeclaration,
+            ExportAllDeclaration: checkDeclaration,
+            ExportNamedDeclaration: checkDeclaration,
+            TSImportEqualsDeclaration: checkDeclaration,
+            TSNamespaceExportDeclaration: checkDeclaration,
+            TSConstructSignatureDeclaration: checkDeclaration,
+            ExportDefaultDeclaration: checkDeclaration,
+            TSPropertySignature: checkDeclaration,
+            TSIndexSignature: checkDeclaration,
+            TSMethodSignature: checkDeclaration,
+            TSParameterProperty: checkDeclaration,
         };
     },
 });
