feat: disableReporting and markVariablesAsUsed options

gajus · May 9, 2023 · 3bcee32 · 3bcee32
1 parent 7016f02
commit 3bcee32
Show file tree

Hide file tree

Showing 4 changed files with 90 additions and 14 deletions.
diff --git a/.README/rules/no-undefined-types.md b/.README/rules/no-undefined-types.md
@@ -47,11 +47,18 @@ array's items will be considered as defined for the purposes of that tag.
 
 ## Options
 
-An option object may have the following key:
+An option object may have the following keys:
 
 - `definedTypes` - This array can be populated to indicate other types which
   are automatically considered as defined (in addition to globals, etc.).
   Defaults to an empty array.
+- `markVariablesAsUsed` - Whether to mark variables as used for the purposes
+  of the `no-unused-vars` rule when they are not found to be undefined.
+  Defaults to `true`. May be set to `false` to enforce a practice of not
+  importing types unless used in code.
+- `disableReporting` - Whether to disable reporting of errors. Defaults to
+  `false`. This may be set to `true` in order to take advantage of only
+  marking defined variables as used.
 
 ## Context and settings
 
@@ -62,7 +69,7 @@ An option object may have the following key:
 |Aliases|`constructor`, `const`, `extends`, `var`, `arg`, `argument`, `prop`, `return`, `exception`, `yield`|
 |Closure-only|`package`, `private`, `protected`, `public`, `static`|
 |Recommended|true|
-|Options|`definedTypes`|
+|Options|`definedTypes`, `markVariablesAsUsed`, `disableReporting`|
 |Settings|`preferredTypes`, `mode`, `structuredTags`|
 
 

diff --git a/docs/rules/no-undefined-types.md b/docs/rules/no-undefined-types.md
@@ -55,11 +55,18 @@ array's items will be considered as defined for the purposes of that tag.
 <a name="no-undefined-types-options"></a>
 ## Options
 
-An option object may have the following key:
+An option object may have the following keys:
 
 - `definedTypes` - This array can be populated to indicate other types which
   are automatically considered as defined (in addition to globals, etc.).
   Defaults to an empty array.
+- `markVariablesAsUsed` - Whether to mark variables as used for the purposes
+  of the `no-unused-vars` rule when they are not found to be undefined.
+  Defaults to `true`. May be set to `false` to enforce a practice of not
+  importing types unless used in code.
+- `disableReporting` - Whether to disable reporting of errors. Defaults to
+  `false`. This may be set to `true` in order to take advantage of only
+  marking defined variables as used.
 
 <a name="user-content-no-undefined-types-context-and-settings"></a>
 <a name="no-undefined-types-context-and-settings"></a>
@@ -72,7 +79,7 @@ An option object may have the following key:
 |Aliases|`constructor`, `const`, `extends`, `var`, `arg`, `argument`, `prop`, `return`, `exception`, `yield`|
 |Closure-only|`package`, `private`, `protected`, `public`, `static`|
 |Recommended|true|
-|Options|`definedTypes`|
+|Options|`definedTypes`, `markVariablesAsUsed`, `disableReporting`|
 |Settings|`preferredTypes`, `mode`, `structuredTags`|
 
 
@@ -354,7 +361,7 @@ import {MyType} from 'my-library';
  * @param {object<string, number>} foo
  * @param {Array<string>} baz
  */
-  function quux(foo, bar, baz) {
+function quux(foo, bar, baz) {
 
 }
 
@@ -727,5 +734,16 @@ class Foo {
   }
 }
 // Settings: {"jsdoc":{"mode":"typescript"}}
+
+import {MyType} from 'my-library';
+
+/**
+ * @param {MyType} foo - Bar.
+ * @param {AnUndefinedType} bar
+ */
+function quux(foo, bar) {
+
+}
+// "jsdoc/no-undefined-types": ["error"|"warn", {"disableReporting":true}]
 ````
 
diff --git a/src/rules/noUndefinedTypes.js b/src/rules/noUndefinedTypes.js
@@ -64,6 +64,8 @@ export default iterateJsdoc(({
 
   const {
     definedTypes = [],
+    disableReporting = false,
+    markVariablesAsUsed = true,
   } = context.options[0] || {};
 
   let definedPreferredTypes = [];
@@ -209,8 +211,10 @@ export default iterateJsdoc(({
         if (!allDefinedTypes.has(value) &&
           (!Array.isArray(structuredTypes) || !structuredTypes.includes(value))
         ) {
-          report(`The type '${value}' is undefined.`, null, tag);
-        } else if (!extraTypes.includes(value)) {
+          if (!disableReporting) {
+            report(`The type '${value}' is undefined.`, null, tag);
+          }
+        } else if (markVariablesAsUsed && !extraTypes.includes(value)) {
           context.markVariableAsUsed(value);
         }
       }
@@ -233,6 +237,12 @@ export default iterateJsdoc(({
             },
             type: 'array',
           },
+          disableReporting: {
+            type: 'boolean',
+          },
+          markVariablesAsUsed: {
+            type: 'boolean',
+          },
         },
         type: 'object',
       },

diff --git a/test/rules/assertions/noUndefinedTypes.js b/test/rules/assertions/noUndefinedTypes.js
@@ -65,9 +65,6 @@ export default {
           message: 'The type \'strnig\' is undefined.',
         },
       ],
-      rules: {
-        'no-undef': 'error',
-      },
     },
     {
       code: `
@@ -248,9 +245,6 @@ export default {
           message: 'The type \'strnig\' is undefined.',
         },
       ],
-      rules: {
-        'no-undef': 'error',
-      },
     },
     {
       code: `
@@ -585,7 +579,7 @@ export default {
          * @param {object<string, number>} foo
          * @param {Array<string>} baz
          */
-          function quux(foo, bar, baz) {
+        function quux(foo, bar, baz) {
 
         }
       `,
@@ -1283,5 +1277,52 @@ export default {
         },
       },
     },
+    {
+      code: `
+          // THIS SHOULD CAUSE ERRORS, BUT DUE TO ESLINT TESTER
+          //  LIMITATIONS, WE CAN'T TEST THE \`no-unused-vars\` RULE;
+          //  WE PUT IT HERE FOR COVERAGE
+
+          import {MyInterface} from 'xyz';
+          /**
+           * @type {MyInterface}
+           */
+          function quux(foo) {
+            console.log(foo);
+          }
+
+          quux(0);
+      `,
+      ignoreReadme: true,
+      options: [
+        {
+          markVariablesAsUsed: false,
+        },
+      ],
+      parserOptions: {
+        sourceType: 'module',
+      },
+    },
+    {
+      code: `
+      import {MyType} from 'my-library';
+
+      /**
+       * @param {MyType} foo - Bar.
+       * @param {AnUndefinedType} bar
+       */
+      function quux(foo, bar) {
+
+      }
+      `,
+      options: [
+        {
+          disableReporting: true,
+        },
+      ],
+      parserOptions: {
+        sourceType: 'module',
+      },
+    },
   ],
 };