feat(check-values): add checking of kind

Also, updates jsdoccomment and devDeps.
gajus · Feb 11, 2022 · eb92080 · eb92080
1 parent a5ad499
commit eb92080
Show file tree

Hide file tree

Showing 5 changed files with 113 additions and 5 deletions.
diff --git a/.README/rules/check-values.md b/.README/rules/check-values.md
@@ -13,6 +13,9 @@ This rule checks the values for a handful of tags:
 5. `@variation` - If `numericOnlyVariation` is set, will checks that there
     is a value present, and that it is an integer (otherwise, jsdoc allows any
     value).
+6. `@kind` - Insists that it be one of the allowed values: 'class',
+    'constant', 'event', 'external', 'file', 'function', 'member', 'mixin',
+    'module', 'namespace', 'typedef',
 
 #### Options
 
@@ -47,7 +50,7 @@ Whether to enable validation that `@variation` must be a number. Defaults to
 |||
 |---|---|
 |Context|everywhere|
-|Tags|`@version`, `@since`, `@license`, `@author`, `@variation`|
+|Tags|`@version`, `@since`, `@kind`, `@license`, `@author`, `@variation`|
 |Recommended|true|
 |Options|`allowedAuthors`, `allowedLicenses`, `licensePattern`|
 |Settings|`tagNamePreference`|

diff --git a/README.md b/README.md
@@ -5818,6 +5818,9 @@ This rule checks the values for a handful of tags:
 5. `@variation` - If `numericOnlyVariation` is set, will checks that there
     is a value present, and that it is an integer (otherwise, jsdoc allows any
     value).
+6. `@kind` - Insists that it be one of the allowed values: 'class',
+    'constant', 'event', 'external', 'file', 'function', 'member', 'mixin',
+    'module', 'namespace', 'typedef',
 
 <a name="eslint-plugin-jsdoc-rules-check-values-options-8"></a>
 #### Options
@@ -5857,7 +5860,7 @@ Whether to enable validation that `@variation` must be a number. Defaults to
 |||
 |---|---|
 |Context|everywhere|
-|Tags|`@version`, `@since`, `@license`, `@author`, `@variation`|
+|Tags|`@version`, `@since`, `@kind`, `@license`, `@author`, `@variation`|
 |Recommended|true|
 |Options|`allowedAuthors`, `allowedLicenses`, `licensePattern`|
 |Settings|`tagNamePreference`|
@@ -5881,6 +5884,22 @@ function quux (foo) {
 }
 // Message: Invalid JSDoc @version: "3.1".
 
+/**
+ * @kind
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @kind value.
+
+/**
+ * @kind -3
+ */
+function quux (foo) {
+
+}
+// Message: Invalid JSDoc @kind: "-3"; must be one of: class, constant, event, external, file, function, member, mixin, module, namespace, typedef.
+
 /**
  * @variation -3
  */
@@ -6108,6 +6127,13 @@ function quux (foo) {
  * @license MIT
  */
 'use strict';
+
+/**
+ * @kind function
+ */
+function quux (foo) {
+
+}
 ````
 
 

diff --git a/package.json b/package.json
@@ -5,7 +5,7 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "~0.18.0",
+    "@es-joy/jsdoccomment": "~0.19.0",
     "comment-parser": "1.3.0",
     "debug": "^4.3.3",
     "escape-string-regexp": "^4.0.0",
@@ -17,15 +17,15 @@
   "description": "JSDoc linting rules for ESLint.",
   "devDependencies": {
     "@babel/cli": "^7.17.0",
-    "@babel/core": "^7.17.0",
+    "@babel/core": "^7.17.2",
     "@babel/eslint-parser": "^7.17.0",
     "@babel/node": "^7.16.8",
     "@babel/plugin-syntax-class-properties": "^7.12.13",
     "@babel/plugin-transform-flow-strip-types": "^7.16.7",
     "@babel/preset-env": "^7.16.11",
     "@babel/register": "^7.17.0",
     "@hkdobrev/run-if-changed": "^0.3.1",
-    "@typescript-eslint/parser": "^5.10.2",
+    "@typescript-eslint/parser": "^5.11.0",
     "babel-plugin-add-module-exports": "^1.0.4",
     "babel-plugin-istanbul": "^6.1.1",
     "camelcase": "^6.3.0",

diff --git a/src/rules/checkValues.js b/src/rules/checkValues.js
@@ -2,6 +2,20 @@ import semver from 'semver';
 import spdxExpressionParse from 'spdx-expression-parse';
 import iterateJsdoc from '../iterateJsdoc';
 
+const allowedKinds = new Set([
+  'class',
+  'constant',
+  'event',
+  'external',
+  'file',
+  'function',
+  'member',
+  'mixin',
+  'module',
+  'namespace',
+  'typedef',
+]);
+
 export default iterateJsdoc(({
   utils,
   report,
@@ -31,6 +45,27 @@ export default iterateJsdoc(({
       );
     }
   });
+
+  utils.forEachPreferredTag('kind', (jsdocParameter, targetTagName) => {
+    const kind = utils.getTagDescription(jsdocParameter).trim();
+    if (!kind) {
+      report(
+        `Missing JSDoc @${targetTagName} value.`,
+        null,
+        jsdocParameter,
+      );
+    } else if (!allowedKinds.has(kind)) {
+      report(
+        `Invalid JSDoc @${targetTagName}: "${utils.getTagDescription(jsdocParameter)}"; ` +
+        `must be one of: ${[
+          ...allowedKinds,
+        ].join(', ')}.`,
+        null,
+        jsdocParameter,
+      );
+    }
+  });
+
   if (numericOnlyVariation) {
     utils.forEachPreferredTag('variation', (jsdocParameter, targetTagName) => {
       const variation = utils.getTagDescription(jsdocParameter).trim();

diff --git a/test/rules/assertions/checkValues.js b/test/rules/assertions/checkValues.js
@@ -32,6 +32,40 @@ export default {
         },
       ],
     },
+    {
+      code: `
+      /**
+       * @kind
+       */
+      function quux (foo) {
+
+      }
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Missing JSDoc @kind value.',
+        },
+      ],
+    },
+    {
+      code: `
+      /**
+       * @kind -3
+       */
+      function quux (foo) {
+
+      }
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Invalid JSDoc @kind: "-3"; must be one of: class, ' +
+            'constant, event, external, file, function, member, mixin, ' +
+            'module, namespace, typedef.',
+        },
+      ],
+    },
     {
       code: `
       /**
@@ -458,5 +492,15 @@ export default {
       'use strict';
       `,
     },
+    {
+      code: `
+      /**
+       * @kind function
+       */
+      function quux (foo) {
+
+      }
+      `,
+    },
   ],
 };