feat(no-bad-blocks): add rule to check for multi-line-style comments which fail to meet criteria of a jsdoc block

Expects jsdoc block to be a multiline-style comment beginning with two asterisks.
If beginning with only one, while having whitespace followed by whitespace or asterisks, and
an at-sign (`@`) and some non-whitespace (as with a jsdoc block tag), then report.

Author: brettz9

.README/rules/no-bad-blocks.md

@@ -0,0 +1,14 @@
+### `no-bad-blocks`
+
+This rule checks for multi-line-style comments which fail to meet the
+criteria of a jsdoc block, namely that it should begin with two asterisks,
+but which appear to be intended as jsdoc blocks due to the presence
+of whitespace followed by whitespace or asterisks, and
+an at-sign (`@`) and some non-whitespace (as with a jsdoc block tag).
+
+|||
+|---|---|
+|Context|Everywhere|
+|Tags|N/A|
+
+<!-- assertions noBadBlocks -->

src/index.js

@@ -13,6 +13,7 @@ import emptyTags from './rules/emptyTags';
 import implementsOnClasses from './rules/implementsOnClasses';
 import matchDescription from './rules/matchDescription';
 import newlineAfterDescription from './rules/newlineAfterDescription';
+import noBadBlocks from './rules/noBadBlocks';
 import noDefaults from './rules/noDefaults';
 import noTypes from './rules/noTypes';
 import noUndefinedTypes from './rules/noUndefinedTypes';
@@ -55,6 +56,7 @@ export default {
         'jsdoc/implements-on-classes': 'warn',
         'jsdoc/match-description': 'off',
         'jsdoc/newline-after-description': 'warn',
+        'jsdoc/no-bad-blocks': 'off',
         'jsdoc/no-defaults': 'off',
         'jsdoc/no-types': 'off',
         'jsdoc/no-undefined-types': 'warn',
@@ -95,6 +97,7 @@ export default {
     'implements-on-classes': implementsOnClasses,
     'match-description': matchDescription,
     'newline-after-description': newlineAfterDescription,
+    'no-bad-blocks': noBadBlocks,
     'no-defaults': noDefaults,
     'no-types': noTypes,
     'no-undefined-types': noUndefinedTypes,

src/iterateJsdoc.js

@@ -568,8 +568,8 @@ const iterateAllJsdocs = (iterator, ruleConfig) => {
           callIterator(context, node, [comment], state);
         },
         'Program:exit' () {
-          const allJsdocs = sourceCode.getAllComments();
-          const untrackedJSdoc = allJsdocs.filter((node) => {
+          const allComments = sourceCode.getAllComments();
+          const untrackedJSdoc = allComments.filter((node) => {
             return !trackedJsdocs.includes(node);
           });
 
@@ -581,6 +581,41 @@ const iterateAllJsdocs = (iterator, ruleConfig) => {
   };
 };
 
+/**
+ * Create an eslint rule that iterates over all JSDocs, regardless of whether
+ * they are attached to a function-like node.
+ *
+ * @param {JsdocVisitor} iterator
+ * @param {{meta: any}} ruleConfig
+ */
+const checkFile = (iterator, ruleConfig) => {
+  return {
+    create (context) {
+      const sourceCode = context.getSourceCode();
+      const settings = getSettings(context);
+
+      return {
+        'Program:exit' () {
+          const allComments = sourceCode.getAllComments();
+          const {lines} = sourceCode;
+          const utils = getBasicUtils(context, settings);
+
+          iterator({
+            allComments,
+            context,
+            lines,
+            makeReport,
+            settings,
+            sourceCode,
+            utils,
+          });
+        },
+      };
+    },
+    meta: ruleConfig.meta,
+  };
+};
+
 export {
   getSettings,
   parseComment,
@@ -603,6 +638,10 @@ export default function iterateJsdoc (iterator, ruleConfig) {
     throw new TypeError('The iterator argument must be a function.');
   }
 
+  if (ruleConfig.checkFile) {
+    return checkFile(iterator, ruleConfig);
+  }
+
   if (ruleConfig.iterateAllJsdocs) {
     return iterateAllJsdocs(iterator, ruleConfig);
   }

src/rules/noBadBlocks.js

@@ -0,0 +1,32 @@
+import iterateJsdoc from '../iterateJsdoc';
+
+export default iterateJsdoc(({
+  context,
+  sourceCode,
+  allComments,
+  makeReport,
+}) => {
+  const nonJsdocNodes = allComments.filter((comment) => {
+    return (/^\/\*(?!\*)[\s*]*@\w/).test(sourceCode.getText(comment));
+  });
+  if (!nonJsdocNodes.length) {
+    return;
+  }
+
+  nonJsdocNodes.forEach((node) => {
+    const report = makeReport(context, node);
+
+    const fix = (fixer) => {
+      const text = sourceCode.getText(node);
+
+      return fixer.replaceText(node, text.replace('/*', '/**'));
+    };
+    report('Expected JSDoc-like comment to begin with two asterisks.', fix);
+  });
+}, {
+  checkFile: true,
+  meta: {
+    fixable: 'code',
+    type: 'layout',
+  },
+});

test/rules/assertions/noBadBlocks.js

@@ -0,0 +1,72 @@
+export default {
+  invalid: [
+    {
+      code: `
+          /*
+           * @param foo
+           */
+          function quux (foo) {
+
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Expected JSDoc-like comment to begin with two asterisks.',
+        },
+      ],
+      output: `
+          /**
+           * @param foo
+           */
+          function quux (foo) {
+
+          }
+      `,
+    },
+    {
+      code: `
+          /*
+           * @property foo
+           */
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Expected JSDoc-like comment to begin with two asterisks.',
+        },
+      ],
+      output: `
+          /**
+           * @property foo
+           */
+      `,
+    },
+  ],
+  valid: [
+    {
+      code: `
+          /**
+           * @property foo
+           */
+      `,
+    },
+    {
+      code: `
+          /**
+           * @param foo
+           */
+           function quux () {
+
+           }
+      `,
+    },
+    {
+      code: `
+      function quux () {
+
+      }
+      `,
+    },
+  ],
+};

test/rules/index.js

@@ -22,6 +22,7 @@ const ruleTester = new RuleTester();
   'implements-on-classes',
   'match-description',
   'newline-after-description',
+  'no-bad-blocks',
   'no-defaults',
   'no-types',
   'no-undefined-types',