feat(check-values): ensure @variation is a positive integer

gajus · May 15, 2021 · 56577ce · 56577ce
1 parent 37d755c
commit 56577ce
Show file tree

Hide file tree

Showing 4 changed files with 116 additions and 4 deletions.
diff --git a/.README/rules/check-values.md b/.README/rules/check-values.md
@@ -7,9 +7,11 @@ This rule checks the values for a handful of tags:
 2. `@since` - As with `@version`
 3. `@license` - Checks that there is a present and valid SPDX identifier
     or is present within an `allowedLicenses` option.
-4. `@author` - Checks there is a value present, and if the option
+4. `@author` - Checks that there is a value present, and if the option
     `allowedAuthors` is present, ensure that the author value is one
     of these array items.
+5. `@variation` - Checks that there iis a value present, and that it is
+    an integer.
 
 #### Options
 
@@ -39,7 +41,7 @@ your expression as a string, but like a literal, e.g., `/^mit$/ui`.
 |||
 |---|---|
 |Context|everywhere|
-|Tags|`@version`, `@since`, `@license`, `@author`|
+|Tags|`@version`, `@since`, `@license`, `@author`, `@variation`|
 |Recommended|true|
 |Options|`allowedAuthors`, `allowedLicenses`, `licensePattern`|
 |Settings|`tagNamePreference`|

diff --git a/README.md b/README.md
@@ -5567,9 +5567,11 @@ This rule checks the values for a handful of tags:
 2. `@since` - As with `@version`
 3. `@license` - Checks that there is a present and valid SPDX identifier
     or is present within an `allowedLicenses` option.
-4. `@author` - Checks there is a value present, and if the option
+4. `@author` - Checks that there is a value present, and if the option
     `allowedAuthors` is present, ensure that the author value is one
     of these array items.
+5. `@variation` - Checks that there iis a value present, and that it is
+    an integer.
 
 <a name="eslint-plugin-jsdoc-rules-check-values-options-8"></a>
 #### Options
@@ -5603,7 +5605,7 @@ your expression as a string, but like a literal, e.g., `/^mit$/ui`.
 |||
 |---|---|
 |Context|everywhere|
-|Tags|`@version`, `@since`, `@license`, `@author`|
+|Tags|`@version`, `@since`, `@license`, `@author`, `@variation`|
 |Recommended|true|
 |Options|`allowedAuthors`, `allowedLicenses`, `licensePattern`|
 |Settings|`tagNamePreference`|
@@ -5627,6 +5629,14 @@ function quux (foo) {
 }
 // Message: Invalid JSDoc @version: "3.1".
 
+/**
+ * @variation -3
+ */
+function quux (foo) {
+
+}
+// Message: Invalid JSDoc @variation: "-3".
+
 /**
  * @since
  */
@@ -5712,6 +5722,22 @@ function quux (foo) {
 }
 // "jsdoc/check-values": ["error"|"warn", {"allowedAuthors":["Gajus Kuizinas","golopot"]}]
 // Message: Invalid JSDoc @author: "Brett Zamir"; expected one of Gajus Kuizinas, golopot.
+
+/**
+ * @variation
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @variation.
+
+/**
+ * @variation 5.2
+ */
+function quux (foo) {
+
+}
+// Message: Invalid JSDoc @variation: "5.2".
 ````
 
 The following patterns are not considered problems:
@@ -5806,6 +5832,13 @@ function quux (foo) {
 
 }
 // "jsdoc/check-values": ["error"|"warn", {"allowedAuthors":["Gajus Kuizinas","golopot","Brett Zamir"]}]
+
+/**
+ * @variation 3
+ */
+function quux (foo) {
+
+}
 ````
 
 

diff --git a/src/rules/checkValues.js b/src/rules/checkValues.js
@@ -30,6 +30,25 @@ export default iterateJsdoc(({
       );
     }
   });
+  utils.forEachPreferredTag('variation', (jsdocParameter, targetTagName) => {
+    const variation = utils.getTagDescription(jsdocParameter).trim();
+    if (!variation) {
+      report(
+        `Missing JSDoc @${targetTagName}.`,
+        null,
+        jsdocParameter,
+      );
+    } else if (
+      !Number.isInteger(Number(variation)) ||
+      Number(variation) <= 0
+    ) {
+      report(
+        `Invalid JSDoc @${targetTagName}: "${utils.getTagDescription(jsdocParameter)}".`,
+        null,
+        jsdocParameter,
+      );
+    }
+  });
   utils.forEachPreferredTag('since', (jsdocParameter, targetTagName) => {
     const version = utils.getTagDescription(jsdocParameter).trim();
     if (!version) {

diff --git a/test/rules/assertions/checkValues.js b/test/rules/assertions/checkValues.js
@@ -32,6 +32,22 @@ export default {
         },
       ],
     },
+    {
+      code: `
+      /**
+       * @variation -3
+       */
+      function quux (foo) {
+
+      }
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Invalid JSDoc @variation: "-3".',
+        },
+      ],
+    },
     {
       code: `
       /**
@@ -209,6 +225,38 @@ export default {
         },
       ],
     },
+    {
+      code: `
+      /**
+       * @variation
+       */
+      function quux (foo) {
+
+      }
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Missing JSDoc @variation.',
+        },
+      ],
+    },
+    {
+      code: `
+      /**
+       * @variation 5.2
+       */
+      function quux (foo) {
+
+      }
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Invalid JSDoc @variation: "5.2".',
+        },
+      ],
+    },
   ],
   valid: [
     {
@@ -353,5 +401,15 @@ export default {
         },
       ],
     },
+    {
+      code: `
+      /**
+       * @variation 3
+       */
+      function quux (foo) {
+
+      }
+      `,
+    },
   ],
 };