From 3bcee32ef6d8081f6bb3f811ef06a60ffdb1aa9c Mon Sep 17 00:00:00 2001 From: Brett Zamir Date: Sun, 7 May 2023 15:28:35 -0700 Subject: [PATCH] feat: `disableReporting` and `markVariablesAsUsed` options --- .README/rules/no-undefined-types.md | 11 ++++- docs/rules/no-undefined-types.md | 24 ++++++++-- src/rules/noUndefinedTypes.js | 14 +++++- test/rules/assertions/noUndefinedTypes.js | 55 ++++++++++++++++++++--- 4 files changed, 90 insertions(+), 14 deletions(-) diff --git a/.README/rules/no-undefined-types.md b/.README/rules/no-undefined-types.md index bc5935714..5f830ca8e 100644 --- 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 index 05e774a73..f0321a0d9 100644 --- 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. ## 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. @@ -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} foo * @param {Array} 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 index 5dcc64d62..873068443 100644 --- 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 index d5ba59fc4..85a43aafc 100644 --- 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} foo * @param {Array} 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', + }, + }, ], };