feat(check-access): add rule to check access levels

BREAKING CHANGE:  New rule updates `recommended`

Checks `@access` for allowed values and prohibits multiple access
modifier tags on the same block

.README/README.md

@@ -314,6 +314,7 @@ only (e.g., to match `Array` if the type is `Array` vs. `Array.<string>`).
 
 ## Rules
 
+{"gitdown": "include", "file": "./rules/check-access.md"}
 {"gitdown": "include", "file": "./rules/check-alignment.md"}
 {"gitdown": "include", "file": "./rules/check-examples.md"}
 {"gitdown": "include", "file": "./rules/check-indentation.md"}

.README/rules/check-access.md

@@ -0,0 +1,21 @@
+### `check-access`
+
+Checks that `@access` tags use one of the following values:
+
+- "package", "private", "protected", "public"
+
+Also reports:
+
+- Mixing of `@access` with `@public`, `@private`, `@protected`, or `@package`
+  on the same doc block.
+- Use of multiple instances of `@access` (or the `@public`, etc. style tags)
+  on the same doc block.
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|`@access`|
+|Settings||
+|Options||
+
+<!-- assertions checkAccess -->

README.md

@@ -19,6 +19,7 @@ JSDoc linting rules for ESLint.
         * [`@override`/`@augments`/`@extends`/`@implements` Without Accompanying `@param`/`@description`/`@example`/`@returns`](#eslint-plugin-jsdoc-settings-override-augments-extends-implements-without-accompanying-param-description-example-returns)
         * [Settings to Configure `check-types` and `no-undefined-types`](#eslint-plugin-jsdoc-settings-settings-to-configure-check-types-and-no-undefined-types)
     * [Rules](#eslint-plugin-jsdoc-rules)
+        * [`check-access`](#eslint-plugin-jsdoc-rules-check-access)
         * [`check-alignment`](#eslint-plugin-jsdoc-rules-check-alignment)
         * [`check-examples`](#eslint-plugin-jsdoc-rules-check-examples)
         * [`check-indentation`](#eslint-plugin-jsdoc-rules-check-indentation)
@@ -363,6 +364,142 @@ only (e.g., to match `Array` if the type is `Array` vs. `Array.<string>`).
 <a name="eslint-plugin-jsdoc-rules"></a>
 ## Rules
 
+<a name="eslint-plugin-jsdoc-rules-check-access"></a>
+### <code>check-access</code>
+
+Checks that `@access` tags use one of the following values:
+
+- "package", "private", "protected", "public"
+
+Also reports:
+
+- Mixing of `@access` with `@public`, `@private`, `@protected`, or `@package`
+  on the same doc block.
+- Use of multiple instances of `@access` (or the `@public`, etc. style tags)
+  on the same doc block.
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|`@access`|
+|Settings||
+|Options||
+
+The following patterns are considered problems:
+
+````js
+/**
+ * @access foo
+ */
+function quux (foo) {
+
+}
+// Message: Missing valid JSDoc @access level.
+
+/**
+ * @accessLevel foo
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"access":"accessLevel"}}}
+// Message: Missing valid JSDoc @accessLevel level.
+
+/**
+ * @access
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"access":false}}}
+// Message: Unexpected tag `@access`
+
+class MyClass {
+  /**
+   * @access
+   */
+  myClassField = 1
+}
+// Message: Missing valid JSDoc @access level.
+
+/**
+ * @access public
+ * @public
+ */
+function quux (foo) {
+
+}
+// Message: The @access tag may not be used with specific access-control tags (@package, @private, @protected, or @public).
+
+/**
+ * @access public
+ * @access private
+ */
+function quux (foo) {
+
+}
+// Message: At most one access-control tag may be present on a jsdoc block.
+
+/**
+ * @public
+ * @private
+ */
+function quux (foo) {
+
+}
+// Message: At most one access-control tag may be present on a jsdoc block.
+
+/**
+ * @public
+ * @public
+ */
+function quux (foo) {
+
+}
+// Message: At most one access-control tag may be present on a jsdoc block.
+````
+
+The following patterns are not considered problems:
+
+````js
+/**
+ *
+ */
+function quux (foo) {
+
+}
+
+/**
+ * @access public
+ */
+function quux (foo) {
+
+}
+
+/**
+ * @accessLevel package
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"tagNamePreference":{"access":"accessLevel"}}}
+
+class MyClass {
+  /**
+   * @access private
+   */
+  myClassField = 1
+}
+
+/**
+ * @public
+ */
+function quux (foo) {
+
+}
+````
+
+
 <a name="eslint-plugin-jsdoc-rules-check-alignment"></a>
 ### <code>check-alignment</code>
 

src/index.js

@@ -1,4 +1,5 @@
 /* eslint-disable import/max-dependencies */
+import checkAccess from './rules/checkAccess';
 import checkAlignment from './rules/checkAlignment';
 import checkExamples from './rules/checkExamples';
 import checkIndentation from './rules/checkIndentation';
@@ -32,6 +33,7 @@ export default {
     recommended: {
       plugins: ['jsdoc'],
       rules: {
+        'jsdoc/check-access': 'warn',
         'jsdoc/check-alignment': 'warn',
         'jsdoc/check-examples': 'off',
         'jsdoc/check-indentation': 'off',
@@ -63,6 +65,7 @@ export default {
     },
   },
   rules: {
+    'check-access': checkAccess,
     'check-alignment': checkAlignment,
     'check-examples': checkExamples,
     'check-indentation': checkIndentation,

src/iterateJsdoc.js

@@ -30,7 +30,7 @@ const parseComment = (commentNode, indent, trim = true) => {
       skipSeeLink(commentParser.PARSERS.parse_type),
       skipSeeLink(
         (str, data) => {
-          if (['example', 'return', 'returns', 'throws', 'exception'].includes(data.tag)) {
+          if (['example', 'return', 'returns', 'throws', 'exception', 'access'].includes(data.tag)) {
             return null;
           }
 

src/rules/checkAccess.js

@@ -0,0 +1,39 @@
+import iterateJsdoc from '../iterateJsdoc';
+
+const accessLevels = ['package', 'private', 'protected', 'public'];
+
+export default iterateJsdoc(({
+  report,
+  utils,
+}) => {
+  utils.forEachPreferredTag('access', (jsdocParameter, targetTagName) => {
+    const desc = targetTagName === 'access' ?
+      jsdocParameter.description :
+      jsdocParameter.name + ' ' + jsdocParameter.description;
+
+    if (!accessLevels.includes(desc.trim())) {
+      report(
+        `Missing valid JSDoc @${targetTagName} level.`,
+        null,
+        jsdocParameter,
+      );
+    }
+  });
+  const accessLength = utils.getTags('access').length;
+  const individualTagLength = utils.getPresentTags(accessLevels).length;
+  if (accessLength && individualTagLength) {
+    report(
+      'The @access tag may not be used with specific access-control tags (@package, @private, @protected, or @public).',
+    );
+  }
+  if (accessLength > 1 || individualTagLength > 1) {
+    report(
+      'At most one access-control tag may be present on a jsdoc block.',
+    );
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    type: 'suggestion',
+  },
+});