feat: add require-asterisk-prefix rule

This rule checks that each line of the jsdoc comment starts with an asterisk. For composability with
other rules, this does not check the alignment or indentation of the comment content.

fix gajus#199

Author: Eli Skeggs

.README/README.md

@@ -63,6 +63,7 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/no-defaults": 1,
         "jsdoc/no-types": 1,
         "jsdoc/no-undefined-types": 1, // Recommended
+        "jsdoc/require-asterisk-prefix": 1,
         "jsdoc/require-description": 1,
         "jsdoc/require-description-complete-sentence": 1,
         "jsdoc/require-example": 1,
@@ -512,6 +513,7 @@ selector).
 {"gitdown": "include", "file": "./rules/no-defaults.md"}
 {"gitdown": "include", "file": "./rules/no-types.md"}
 {"gitdown": "include", "file": "./rules/no-undefined-types.md"}
+{"gitdown": "include", "file": "./rules/require-asterisk-prefix.md"}
 {"gitdown": "include", "file": "./rules/require-description-complete-sentence.md"}
 {"gitdown": "include", "file": "./rules/require-description.md"}
 {"gitdown": "include", "file": "./rules/require-example.md"}

.README/rules/require-asterisk-prefix.md

@@ -0,0 +1,12 @@
+### `require-asterisk-prefix`
+
+Requires that each JSDoc line starts with an `*`.
+
+#### Options
+
+This rule allows one optional string argument. If it is `"always"` then a problem is raised when there is no asterisk prefix on a given jsdoc line. If it is `"never"` then a problem is raised when there is an asterisk present. The default value is `"always"`.
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|N/a|

README.md

@@ -17,6 +17,7 @@ import noBadBlocks from './rules/noBadBlocks';
 import noDefaults from './rules/noDefaults';
 import noTypes from './rules/noTypes';
 import noUndefinedTypes from './rules/noUndefinedTypes';
+import requireAsteriskPrefix from './rules/requireAsteriskPrefix';
 import requireDescription from './rules/requireDescription';
 import requireDescriptionCompleteSentence from './rules/requireDescriptionCompleteSentence';
 import requireExample from './rules/requireExample';
@@ -64,6 +65,7 @@ export default {
         'jsdoc/no-defaults': 'off',
         'jsdoc/no-types': 'off',
         'jsdoc/no-undefined-types': 'warn',
+        'jsdoc/require-asterisk-prefix': 'off',
         'jsdoc/require-description': 'off',
         'jsdoc/require-description-complete-sentence': 'off',
         'jsdoc/require-example': 'off',
@@ -108,6 +110,7 @@ export default {
     'no-defaults': noDefaults,
     'no-types': noTypes,
     'no-undefined-types': noUndefinedTypes,
+    'require-asterisk-prefix': requireAsteriskPrefix,
     'require-description': requireDescription,
     'require-description-complete-sentence': requireDescriptionCompleteSentence,
     'require-example': requireExample,

src/index.js

@@ -0,0 +1,41 @@
+import iterateJsdoc from '../iterateJsdoc';
+
+const prefixMatch = /^(\s+)(?:\*( ?))?/u;
+const validPrefix = /^\s+\*(?:\/?$| )/u;
+
+export default iterateJsdoc(({
+  sourceCode,
+  jsdocNode,
+  report,
+}) => {
+  const fix = (fixer) => {
+    const replacement = sourceCode.getText(jsdocNode).split('\n')
+      .map((line, index) => {
+        return index && !validPrefix.test(line) ? line.replace(prefixMatch, (_, $1, $2) => {
+          return `${$1}*${$2 || ' '}`;
+        }) : line;
+      })
+      .join('\n');
+
+    return fixer.replaceText(jsdocNode, replacement);
+  };
+
+  sourceCode.getText(jsdocNode).split('\n').some((line, index) => {
+    const lineNum = parseInt(index, 10);
+    if (lineNum && !validPrefix.test(line)) {
+      report('Expected JSDoc block to have the prefix.', fix, {
+        line: lineNum,
+      });
+
+      return true;
+    }
+
+    return false;
+  });
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    fixable: 'code',
+    type: 'layout',
+  },
+});

src/rules/requireAsteriskPrefix.js

@@ -0,0 +1,91 @@
+export default {
+  invalid: [
+    {
+      code: `
+
+        /**
+         @param {Number} foo
+         */
+        function quux (foo) {
+          // with spaces
+        }
+      `,
+      errors: [
+        {
+          line: 4,
+          message: 'Expected JSDoc block to have the prefix.',
+        },
+      ],
+      output: `
+
+        /**
+         * @param {Number} foo
+         */
+        function quux (foo) {
+          // with spaces
+        }
+      `,
+    },
+    {
+      code: `
+        /**
+          @param {Number} foo
+         */function quux (foo) {
+          // with spaces
+        }
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Expected JSDoc block to have the prefix.',
+        },
+      ],
+      output: `
+        /**
+          * @param {Number} foo
+         */function quux (foo) {
+          // with spaces
+        }
+      `,
+    },
+  ],
+  valid: [
+    {
+      code: `
+        /**
+         * Desc
+         *
+         * @param {Number} foo
+         *   This is more comment.
+         */
+        function quux (foo) {
+
+        }
+      `,
+    },
+    {
+      code: `
+        /**
+         * Desc
+         *
+         * @param {{
+         * foo: Bar,
+         * bar: Baz
+         * }} foo
+         *
+         */
+        function quux (foo) {
+
+        }
+      `,
+    },
+    {
+      code: `
+        /*  <- JSDoc must start with 2 stars.
+         So this is unchecked.
+         */
+        function quux (foo) {}
+      `,
+    },
+  ],
+};

test/rules/assertions/requireAsteriskPrefix.js

@@ -26,6 +26,7 @@ const ruleTester = new RuleTester();
   'no-defaults',
   'no-types',
   'no-undefined-types',
+  'require-asterisk-prefix',
   'require-description',
   'require-description-complete-sentence',
   'require-example',