Chore: Update jsdoc plugin and tweak rules in effect (#14814)

* Chore: Remove explicit rule declarations that are already inherited

* Chore: Add eslint-comments plugin

* Chore: Add peerDeps to eslint-config-eslint

* Chore: Avoid single-file disable directives in favor of setting to "off"

* Chore: Remove rules already included by recommended configs

.eslintrc.js

@@ -51,7 +51,7 @@ module.exports = {
         "plugin:eslint-plugin/recommended"
     ],
     parserOptions: {
-        ecmaVersion: 2020
+        ecmaVersion: 2021
     },
 
     /*

Makefile.js

@@ -962,14 +962,20 @@ function createConfigForPerformanceTest() {
     content.join("\n").to(PERF_ESLINTRC);
 }
 
+/**
+ * @callback TimeCallback
+ * @param {?int[]} results
+ * @returns {void}
+ */
+
 /**
  * Calculates the time for each run for performance
  * @param {string} cmd cmd
  * @param {int} runs Total number of runs to do
  * @param {int} runNumber Current run number
  * @param {int[]} results Collection results from each run
- * @param {Function} cb Function to call when everything is done
- * @returns {int[]} calls the cb with all the results
+ * @param {TimeCallback} cb Function to call when everything is done
+ * @returns {void} calls the cb with all the results
  * @private
  */
 function time(cmd, runs, runNumber, results, cb) {

lib/cli-engine/cli-engine.js

@@ -55,8 +55,8 @@ const validFixTypes = new Set(["directive", "problem", "suggestion", "layout"]);
 /** @typedef {import("../shared/types").Plugin} Plugin */
 /** @typedef {import("../shared/types").RuleConf} RuleConf */
 /** @typedef {import("../shared/types").Rule} Rule */
-/** @typedef {ReturnType<CascadingConfigArrayFactory["getConfigArrayForFile"]>} ConfigArray */
-/** @typedef {ReturnType<ConfigArray["extractConfig"]>} ExtractedConfig */
+/** @typedef {ReturnType<CascadingConfigArrayFactory.getConfigArrayForFile>} ConfigArray */
+/** @typedef {ReturnType<ConfigArray.extractConfig>} ExtractedConfig */
 
 /**
  * The options to configure a CLI engine with.
@@ -480,6 +480,7 @@ function getCacheFile(cacheFile, cwd) {
  * @param {string[]|null} keys The keys to assign true.
  * @param {boolean} defaultValue The default value for each property.
  * @param {string} displayName The property name which is used in error message.
+ * @throws {Error} Requires array.
  * @returns {Record<string,boolean>} The boolean map.
  */
 function toBooleanMap(keys, defaultValue, displayName) {
@@ -543,6 +544,7 @@ function createConfigDataFromOptions(options) {
 /**
  * Checks whether a directory exists at the given location
  * @param {string} resolvedPath A path from the CWD
+ * @throws {Error} As thrown by `fs.statSync` or `fs.isDirectory`.
  * @returns {boolean} `true` if a directory exists
  */
 function directoryExists(resolvedPath) {
@@ -742,6 +744,7 @@ class CLIEngine {
     /**
      * Executes the current configuration on an array of file and directory names.
      * @param {string[]} patterns An array of file and directory names.
+     * @throws {Error} As may be thrown by `fs.unlinkSync`.
      * @returns {LintReport} The results for all files that were linted.
      */
     executeOnFiles(patterns) {
@@ -948,6 +951,7 @@ class CLIEngine {
      * This is the same logic used by the ESLint CLI executable to determine
      * configuration for each file it processes.
      * @param {string} filePath The path of the file to retrieve a config object for.
+     * @throws {Error} If filepath a directory path.
      * @returns {ConfigData} A configuration object for the file.
      */
     getConfigForFile(filePath) {
@@ -996,6 +1000,7 @@ class CLIEngine {
      * Returns the formatter representing the given format or null if the `format` is not a string.
      * @param {string} [format] The name of the format to load or the path to a
      *      custom formatter.
+     * @throws {any} As may be thrown by requiring of formatter
      * @returns {(Function|null)} The formatter function or null if the `format` is not a string.
      */
     getFormatter(format) {

lib/cli-engine/file-enumerator.js

@@ -60,7 +60,7 @@ const IGNORED_SILENTLY = 1;
 const IGNORED = 2;
 
 // For VSCode intellisense
-/** @typedef {ReturnType<CascadingConfigArrayFactory["getConfigArrayForFile"]>} ConfigArray */
+/** @typedef {ReturnType<CascadingConfigArrayFactory.getConfigArrayForFile>} ConfigArray */
 
 /**
  * @typedef {Object} FileEnumeratorOptions
@@ -114,6 +114,7 @@ function isGlobPattern(pattern) {
 /**
  * Get stats of a given path.
  * @param {string} filePath The path to target file.
+ * @throws {Error} As may be thrown by `fs.statSync`.
  * @returns {fs.Stats|null} The stats.
  * @private
  */
@@ -132,6 +133,7 @@ function statSafeSync(filePath) {
 /**
  * Get filenames in a given path to a directory.
  * @param {string} directoryPath The path to target directory.
+ * @throws {Error} As may be thrown by `fs.readdirSync`.
  * @returns {import("fs").Dirent[]} The filenames.
  * @private
  */
@@ -270,6 +272,7 @@ class FileEnumerator {
     /**
      * Iterate files which are matched by given glob patterns.
      * @param {string|string[]} patternOrPatterns The glob patterns to iterate files.
+     * @throws {NoFilesFoundError|AllFilesIgnoredError} On an unmatched pattern.
      * @returns {IterableIterator<FileAndConfig>} The found files.
      */
     *iterateFiles(patternOrPatterns) {

lib/config/rule-validator.js

@@ -19,6 +19,7 @@ const ajv = require("../shared/ajv")();
  * Finds a rule with the given ID in the given config.
  * @param {string} ruleId The ID of the rule to find.
  * @param {Object} config The config to search in.
+ * @throws {TypeError} For missing plugin or rule.
  * @returns {{create: Function, schema: (Array|null)}} THe rule object.
  */
 function findRuleDefinition(ruleId, config) {
@@ -98,7 +99,6 @@ class RuleValidator {
          * A collection of compiled validators for rules that have already
          * been validated.
          * @type {WeakMap}
-         * @property validators
          */
         this.validators = new WeakMap();
     }

lib/eslint/eslint.js

@@ -151,6 +151,7 @@ class ESLintInvalidOptionsError extends Error {
 /**
  * Validates and normalizes options for the wrapped CLIEngine instance.
  * @param {ESLintOptions} options The options to process.
+ * @throws {ESLintInvalidOptionsError} If of any of a variety of type errors.
  * @returns {ESLintOptions} The normalized options.
  */
 function processOptions({

lib/init/autoconfig.js

@@ -36,9 +36,9 @@ const MAX_CONFIG_COMBINATIONS = 17, // 16 combinations + 1 for severity only
 /**
  * Information about a rule configuration, in the context of a Registry.
  * @typedef {Object}     registryItem
- * @param   {ruleConfig} config        A valid configuration for the rule
- * @param   {number}     specificity   The number of elements in the ruleConfig array
- * @param   {number}     errorCount    The number of errors encountered when linting with the config
+ * @property   {ruleConfig} config        A valid configuration for the rule
+ * @property   {number}     specificity   The number of elements in the ruleConfig array
+ * @property   {number}     errorCount    The number of errors encountered when linting with the config
  */
 
 /**

lib/init/config-initializer.js

@@ -163,6 +163,7 @@ function getModulesList(config, installESLint) {
  * the original config parameter.
  * @param   {Object} answers  answers received from enquirer
  * @param   {Object} config   config object
+ * @throws {Error} If source code retrieval fails or source code file count is 0.
  * @returns {Object}          config object with configured rules
  */
 function configureRules(answers, config) {
@@ -428,7 +429,7 @@ function installModules(modules) {
  * Ask user to install modules.
  * @param   {string[]} modules Array of modules to be installed.
  * @param   {boolean} packageJsonExists Indicates if package.json is existed.
- * @returns {Promise} Answer that indicates if user wants to install.
+ * @returns {Promise<void>} Answer that indicates if user wants to install.
  */
 function askInstallModules(modules, packageJsonExists) {
 
@@ -464,7 +465,7 @@ function askInstallModules(modules, packageJsonExists) {
 /* istanbul ignore next: no need to test enquirer */
 /**
  * Ask use a few questions on command prompt
- * @returns {Promise} The promise with the result of the prompt
+ * @returns {Promise<void>} The promise with the result of the prompt
  */
 function promptUser() {
 

lib/init/npm-utils.js

@@ -91,6 +91,7 @@ function fetchPeerDependencies(packageName) {
  * @param   {boolean} opt.dependencies    Set to true to check for direct dependencies
  * @param   {boolean} opt.devDependencies Set to true to check for development dependencies
  * @param   {boolean} opt.startdir        Directory to begin searching from
+ * @throws {Error} If cannot find valid `package.json` file.
  * @returns {Object}                      An object whose keys are the module names
  *                                        and values are booleans indicating installation.
  */

lib/init/source-code-utils.js

@@ -35,6 +35,7 @@ const debug = require("debug")("eslint:source-code-utils");
  * Get the SourceCode object for a single file
  * @param   {string}     filename The fully resolved filename to get SourceCode from.
  * @param   {Object}     engine  A CLIEngine.
+ * @throws {Error} Upon fatal errors from execution.
  * @returns {Array}               Array of the SourceCode object representing the file
  *                                and fatal error message.
  */

lib/linter/code-path-analysis/code-path-state.js

@@ -360,6 +360,7 @@ class CodePathState {
 
     /**
      * Pops the last choice context and finalizes it.
+     * @throws {Error} (Unreachable.)
      * @returns {ChoiceContext} The popped context.
      */
     popChoiceContext() {
@@ -450,6 +451,7 @@ class CodePathState {
     /**
      * Makes a code path segment of the right-hand operand of a logical
      * expression.
+     * @throws {Error} (Unreachable.)
      * @returns {void}
      */
     makeLogicalRight() {
@@ -965,6 +967,7 @@ class CodePathState {
      *   `WhileStatement`, `DoWhileStatement`, `ForStatement`, `ForInStatement`,
      *   and `ForStatement`.
      * @param {string|null} label A label of the node which was triggered.
+     * @throws {Error} (Unreachable - unknown type.)
      * @returns {void}
      */
     pushLoopContext(type, label) {
@@ -1036,6 +1039,7 @@ class CodePathState {
 
     /**
      * Pops the last context of a loop statement and finalizes it.
+     * @throws {Error} (Unreachable - unknown type.)
      * @returns {void}
      */
     popLoopContext() {

lib/linter/config-comment-parser.js

@@ -3,7 +3,7 @@
  * @author Nicholas C. Zakas
  */
 
-/* eslint-disable class-methods-use-this*/
+/* eslint class-methods-use-this: off */
 "use strict";
 
 //------------------------------------------------------------------------------

lib/linter/linter.js

@@ -50,8 +50,8 @@ const parserSymbol = Symbol.for("eslint.RuleTester.parser");
 // Typedefs
 //------------------------------------------------------------------------------
 
-/** @typedef {InstanceType<import("../cli-engine/config-array")["ConfigArray"]>} ConfigArray */
-/** @typedef {InstanceType<import("../cli-engine/config-array")["ExtractedConfig"]>} ExtractedConfig */
+/** @typedef {InstanceType<import("../cli-engine/config-array").ConfigArray>} ConfigArray */
+/** @typedef {InstanceType<import("../cli-engine/config-array").ExtractedConfig>} ExtractedConfig */
 /** @typedef {import("../shared/types").ConfigData} ConfigData */
 /** @typedef {import("../shared/types").Environment} Environment */
 /** @typedef {import("../shared/types").GlobalConf} GlobalConf */
@@ -60,17 +60,19 @@ const parserSymbol = Symbol.for("eslint.RuleTester.parser");
 /** @typedef {import("../shared/types").Processor} Processor */
 /** @typedef {import("../shared/types").Rule} Rule */
 
+/* eslint-disable jsdoc/valid-types -- https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser/issues/4#issuecomment-778805577 */
 /**
  * @template T
  * @typedef {{ [P in keyof T]-?: T[P] }} Required
  */
+/* eslint-enable jsdoc/valid-types */
 
 /**
  * @typedef {Object} DisableDirective
- * @property {("disable"|"enable"|"disable-line"|"disable-next-line")} type
- * @property {number} line
- * @property {number} column
- * @property {(string|null)} ruleId
+ * @property {("disable"|"enable"|"disable-line"|"disable-next-line")} type Type of directive
+ * @property {number} line The line number
+ * @property {number} column The column number
+ * @property {(string|null)} ruleId The rule ID
  */
 
 /**
@@ -98,12 +100,12 @@ const parserSymbol = Symbol.for("eslint.RuleTester.parser");
  * @typedef {Object} ProcessorOptions
  * @property {(filename:string, text:string) => boolean} [filterCodeBlock] the
  *      predicate function that selects adopt code blocks.
- * @property {Processor["postprocess"]} [postprocess] postprocessor for report
+ * @property {Processor.postprocess} [postprocess] postprocessor for report
  *      messages. If provided, this should accept an array of the message lists
  *      for each code block returned from the preprocessor, apply a mapping to
  *      the messages as appropriate, and return a one-dimensional array of
  *      messages.
- * @property {Processor["preprocess"]} [preprocess] preprocessor for source text.
+ * @property {Processor.preprocess} [preprocess] preprocessor for source text.
  *      If provided, this should accept a string of source text, and return an
  *      array of code blocks to lint.
  */
@@ -764,6 +766,7 @@ function markVariableAsUsed(scopeManager, currentNode, parserOptions, name) {
  * Runs a rule, and gets its listeners
  * @param {Rule} rule A normalized rule with a `create` method
  * @param {Context} ruleContext The context that should be passed to the rule
+ * @throws {any} Any error during the rule's `create`
  * @returns {Object} A map of selector listeners provided by the rule
  */
 function createRuleListeners(rule, ruleContext) {
@@ -1092,6 +1095,7 @@ class Linter {
      * @param {string|SourceCode} textOrSourceCode The text to parse or a SourceCode object.
      * @param {ConfigData} providedConfig An ESLintConfig instance to configure everything.
      * @param {VerifyOptions} [providedOptions] The optional filename of the file being checked.
+     * @throws {Error} If during rule execution.
      * @returns {LintMessage[]} The results as an array of messages or an empty array if no messages.
      */
     _verifyWithoutProcessors(textOrSourceCode, providedConfig, providedOptions) {

lib/linter/report-translator.js

@@ -32,18 +32,18 @@ const interpolate = require("./interpolate");
 /**
  * Information about the report
  * @typedef {Object} ReportInfo
- * @property {string} ruleId
- * @property {(0|1|2)} severity
- * @property {(string|undefined)} message
- * @property {(string|undefined)} [messageId]
- * @property {number} line
- * @property {number} column
- * @property {(number|undefined)} [endLine]
- * @property {(number|undefined)} [endColumn]
- * @property {(string|null)} nodeType
- * @property {string} source
- * @property {({text: string, range: (number[]|null)}|null)} [fix]
- * @property {Array<{text: string, range: (number[]|null)}|null>} [suggestions]
+ * @property {string} ruleId The rule ID
+ * @property {(0|1|2)} severity Severity of the error
+ * @property {(string|undefined)} message The message
+ * @property {(string|undefined)} [messageId] The message ID
+ * @property {number} line The line number
+ * @property {number} column The column number
+ * @property {(number|undefined)} [endLine] The ending line number
+ * @property {(number|undefined)} [endColumn] The ending column number
+ * @property {(string|null)} nodeType Type of node
+ * @property {string} source Source text
+ * @property {({text: string, range: (number[]|null)}|null)} [fix] The fix object
+ * @property {Array<{text: string, range: (number[]|null)}|null>} [suggestions] Suggestion info
  */
 
 //------------------------------------------------------------------------------

lib/linter/safe-emitter.js

@@ -12,8 +12,8 @@
 /**
  * An event emitter
  * @typedef {Object} SafeEmitter
- * @property {function(eventName: string, listenerFunc: Function): void} on Adds a listener for a given event name
- * @property {function(eventName: string, arg1?: any, arg2?: any, arg3?: any)} emit Emits an event with a given name.
+ * @property {(eventName: string, listenerFunc: Function) => void} on Adds a listener for a given event name
+ * @property {(eventName: string, arg1?: any, arg2?: any, arg3?: any) => void} emit Emits an event with a given name.
  * This calls all the listeners that were listening for that name, with `arg1`, `arg2`, and `arg3` as arguments.
  * @property {function(): string[]} eventNames Gets the list of event names that have registered listeners.
  */

lib/linter/timing.js

@@ -126,7 +126,7 @@ module.exports = (function() {
 
     /**
      * Time the run
-     * @param {*} key key from the data object
+     * @param {any} key key from the data object
      * @param {Function} fn function to be called
      * @returns {Function} function to be executed
      * @private