eslint 8.0.0-beta.0 → 8.0.0

package/README.md

@@ -123,7 +123,7 @@ Yes, ESLint natively supports parsing JSX syntax (this must be enabled in [confi
 
 ### What ECMAScript versions does ESLint support?
 
-ESLint has full support for ECMAScript 3, 5 (default), 2015, 2016, 2017, 2018, 2019, and 2020. You can set your desired ECMAScript syntax (and other settings, like global variables or your target environments) through [configuration](https://eslint.org/docs/user-guide/configuring).
+ESLint has full support for ECMAScript 3, 5 (default), 2015, 2016, 2017, 2018, 2019, 2020, 2021 and 2022. You can set your desired ECMAScript syntax (and other settings, like global variables or your target environments) through [configuration](https://eslint.org/docs/user-guide/configuring).
 
 ### What about experimental features?
 
@@ -296,9 +296,9 @@ The following companies, organizations, and individuals support ESLint's ongoing
 <!--sponsorsstart-->
 <h3>Platinum Sponsors</h3>
 <p><a href="https://automattic.com"><img src="https://images.opencollective.com/photomatt/d0ef3e1/logo.png" alt="Automattic" height="undefined"></a></p><h3>Gold Sponsors</h3>
-<p><a href="https://nx.dev"><img src="https://images.opencollective.com/nx/0efbe42/logo.png" alt="Nx (by Nrwl)" height="96"></a> <a href="https://google.com/chrome"><img src="https://images.opencollective.com/chrome/dc55bd4/logo.png" alt="Chrome's Web Framework & Tools Performance Fund" height="96"></a> <a href="https://www.salesforce.com"><img src="https://images.opencollective.com/salesforce/ca8f997/logo.png" alt="Salesforce" height="96"></a> <a href="https://www.airbnb.com/"><img src="https://images.opencollective.com/airbnb/d327d66/logo.png" alt="Airbnb" height="96"></a> <a href="https://coinbase.com"><img src="https://avatars.githubusercontent.com/u/1885080?v=4" alt="Coinbase" height="96"></a> <a href="https://substack.com/"><img src="https://avatars.githubusercontent.com/u/53023767?v=4" alt="Substack" height="96"></a></p><h3>Silver Sponsors</h3>
-<p><a href="https://retool.com/"><img src="https://images.opencollective.com/retool/98ea68e/logo.png" alt="Retool" height="64"></a> <a href="https://liftoff.io/"><img src="https://images.opencollective.com/liftoff/5c4fa84/logo.png" alt="Liftoff" height="64"></a></p><h3>Bronze Sponsors</h3>
-<p><a href="https://troypoint.com"><img src="https://images.opencollective.com/troypoint/080f96f/avatar.png" alt="TROYPOINT" height="32"></a> <a href="https://mobilen.nu"><img src="https://images.opencollective.com/mobilen/e19860d/logo.png" alt="Mobilen" height="32"></a> <a href="https://www.crosswordsolver.org/anagram-solver/"><img src="https://images.opencollective.com/anagram-solver/2666271/logo.png" alt="Anagram Solver" height="32"></a> <a href="null"><img src="https://images.opencollective.com/bugsnag-stability-monitoring/c2cef36/logo.png" alt="Bugsnag Stability Monitoring" height="32"></a> <a href="https://mixpanel.com"><img src="https://images.opencollective.com/mixpanel/cd682f7/logo.png" alt="Mixpanel" height="32"></a> <a href="https://www.vpsserver.com"><img src="https://images.opencollective.com/vpsservercom/logo.png" alt="VPS Server" height="32"></a> <a href="https://icons8.com"><img src="https://images.opencollective.com/icons8/7fa1641/logo.png" alt="Icons8: free icons, photos, illustrations, and music" height="32"></a> <a href="https://discord.com"><img src="https://images.opencollective.com/discordapp/f9645d9/logo.png" alt="Discord" height="32"></a> <a href="https://themeisle.com"><img src="https://images.opencollective.com/themeisle/d5592fe/logo.png" alt="ThemeIsle" height="32"></a> <a href="https://www.firesticktricks.com"><img src="https://images.opencollective.com/fire-stick-tricks/b8fbe2c/logo.png" alt="Fire Stick Tricks" height="32"></a> <a href="https://www.practiceignition.com"><img src="https://avatars.githubusercontent.com/u/5753491?v=4" alt="Practice Ignition" height="32"></a></p>
+<p><a href="https://nx.dev"><img src="https://images.opencollective.com/nx/0efbe42/logo.png" alt="Nx (by Nrwl)" height="96"></a> <a href="https://google.com/chrome"><img src="https://images.opencollective.com/chrome/dc55bd4/logo.png" alt="Chrome's Web Framework & Tools Performance Fund" height="96"></a> <a href="https://www.salesforce.com"><img src="https://images.opencollective.com/salesforce/ca8f997/logo.png" alt="Salesforce" height="96"></a> <a href="https://www.airbnb.com/"><img src="https://images.opencollective.com/airbnb/d327d66/logo.png" alt="Airbnb" height="96"></a> <a href="https://coinbase.com"><img src="https://avatars.githubusercontent.com/u/1885080?v=4" alt="Coinbase" height="96"></a> <a href="https://americanexpress.io"><img src="https://avatars.githubusercontent.com/u/3853301?v=4" alt="American Express" height="96"></a> <a href="https://substack.com/"><img src="https://avatars.githubusercontent.com/u/53023767?v=4" alt="Substack" height="96"></a></p><h3>Silver Sponsors</h3>
+<p><a href="https://liftoff.io/"><img src="https://images.opencollective.com/liftoff/5c4fa84/logo.png" alt="Liftoff" height="64"></a></p><h3>Bronze Sponsors</h3>
+<p><a href="https://launchdarkly.com"><img src="https://images.opencollective.com/launchdarkly/574bb9e/logo.png" alt="launchdarkly" height="32"></a> <a href="https://troypoint.com"><img src="https://images.opencollective.com/troypoint/080f96f/avatar.png" alt="TROYPOINT" height="32"></a> <a href="https://mobilen.nu"><img src="https://images.opencollective.com/mobilen/e19860d/logo.png" alt="Mobilen" height="32"></a> <a href="https://www.crosswordsolver.org/anagram-solver/"><img src="https://images.opencollective.com/anagram-solver/2666271/logo.png" alt="Anagram Solver" height="32"></a> <a href="null"><img src="https://images.opencollective.com/bugsnag-stability-monitoring/c2cef36/logo.png" alt="Bugsnag Stability Monitoring" height="32"></a> <a href="https://mixpanel.com"><img src="https://images.opencollective.com/mixpanel/cd682f7/logo.png" alt="Mixpanel" height="32"></a> <a href="https://www.vpsserver.com"><img src="https://images.opencollective.com/vpsservercom/logo.png" alt="VPS Server" height="32"></a> <a href="https://icons8.com"><img src="https://images.opencollective.com/icons8/7fa1641/logo.png" alt="Icons8: free icons, photos, illustrations, and music" height="32"></a> <a href="https://discord.com"><img src="https://images.opencollective.com/discordapp/f9645d9/logo.png" alt="Discord" height="32"></a> <a href="https://themeisle.com"><img src="https://images.opencollective.com/themeisle/d5592fe/logo.png" alt="ThemeIsle" height="32"></a> <a href="https://www.firesticktricks.com"><img src="https://images.opencollective.com/fire-stick-tricks/b8fbe2c/logo.png" alt="Fire Stick Tricks" height="32"></a> <a href="https://www.practiceignition.com"><img src="https://avatars.githubusercontent.com/u/5753491?v=4" alt="Practice Ignition" height="32"></a></p>
 <!--sponsorsend-->
 
 ## <a name="technology-sponsors"></a>Technology Sponsors

package/bin/eslint.js

@@ -5,7 +5,7 @@
  * @author Nicholas C. Zakas
  */
 
-/* eslint no-console:off */
+/* eslint no-console:off -- CLI */
 
 "use strict";
 

package/conf/eslint-recommended.js

@@ -6,7 +6,7 @@
 
 "use strict";
 
-/* eslint sort-keys: ["error", "asc"] */
+/* eslint sort-keys: ["error", "asc"] -- Long, so make more readable */
 
 /** @type {import("../lib/shared/types").ConfigData} */
 module.exports = {

package/conf/{category-list.json → rule-type-list.json}

@@ -1,11 +1,8 @@
 {
-    "categories": [
-        { "name": "Possible Errors", "description": "These rules relate to possible syntax or logic errors in JavaScript code:" },
-        { "name": "Best Practices", "description": "These rules relate to better ways of doing things to help you avoid problems:" },
-        { "name": "Strict Mode", "description": "These rules relate to strict mode directives:" },
-        { "name": "Variables", "description": "These rules relate to variable declarations:" },
-        { "name": "Stylistic Issues", "description": "These rules relate to style guidelines, and are therefore quite subjective:" },
-        { "name": "ECMAScript 6", "description": "These rules relate to ES6, also known as ES2015:" }
+    "types": [
+        { "name": "problem", "displayName": "Possible Problems", "description": "These rules relate to possible logic errors in code:" },
+        { "name": "suggestion", "displayName": "Suggestions", "description": "These rules suggest alternate ways of doing things:" },
+        { "name": "layout", "displayName": "Layout & Formatting", "description": "These rules care about how the code looks rather than how it executes:" }
     ],
     "deprecated": {
         "name": "Deprecated",

package/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.
@@ -280,7 +280,7 @@ function verifyText({
 /**
  * Returns result with warning by ignore settings
  * @param {string} filePath File path of checked code
- * @param {string} baseDir  Absolute path of base directory
+ * @param {string} baseDir Absolute path of base directory
  * @returns {LintResult} Result with single warning
  * @private
  */
@@ -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) {
@@ -560,6 +562,9 @@ function directoryExists(resolvedPath) {
 // Public Interface
 //------------------------------------------------------------------------------
 
+/**
+ * Core CLI.
+ */
 class CLIEngine {
 
     /**
@@ -742,6 +747,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 +954,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 +1003,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) {

package/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
  */
@@ -173,7 +175,6 @@ function createExtensionRegExp(extensions) {
  */
 class NoFilesFoundError extends Error {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {string} pattern The glob pattern which was not found.
      * @param {boolean} globDisabled If `true` then the pattern was a glob pattern, but glob was disabled.
@@ -190,7 +191,6 @@ class NoFilesFoundError extends Error {
  */
 class AllFilesIgnoredError extends Error {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {string} pattern The glob pattern which was not found.
      */
@@ -270,6 +270,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) {

package/lib/cli-engine/formatters/html.js

@@ -281,8 +281,8 @@ function resultTemplate(it) {
 `.trimLeft();
 }
 
-// eslint-disable-next-line jsdoc/require-description
 /**
+ * Render the results.
  * @param {Array} results Test results.
  * @param {Object} rulesMeta Dictionary containing metadata for each rule executed by the analysis.
  * @returns {string} HTML string describing the results.

package/lib/cli-engine/hash.js

@@ -21,8 +21,8 @@ const murmur = require("imurmurhash");
 
 /**
  * hash the given string
- * @param  {string} str the string to hash
- * @returns {string}    the hash
+ * @param {string} str the string to hash
+ * @returns {string} the hash
  */
 function hash(str) {
     return murmur(str).result().toString(36);

package/lib/cli-engine/xml-escape.js

@@ -15,7 +15,7 @@
  * @private
  */
 module.exports = function(s) {
-    return (`${s}`).replace(/[<>&"'\x00-\x1F\x7F\u0080-\uFFFF]/gu, c => { // eslint-disable-line no-control-regex
+    return (`${s}`).replace(/[<>&"'\x00-\x1F\x7F\u0080-\uFFFF]/gu, c => { // eslint-disable-line no-control-regex -- Converting controls to entities
         switch (c) {
             case "<":
                 return "&lt;";

package/lib/config/flat-config-array.js

@@ -61,7 +61,7 @@ class FlatConfigArray extends ConfigArray {
         this.unshift(baseConfig);
     }
 
-    /* eslint-disable class-methods-use-this */
+    /* eslint-disable class-methods-use-this -- Desired as instance method */
     /**
      * Replaces a config with another config to allow us to put strings
      * in the config array that will be replaced by objects before
@@ -118,7 +118,7 @@ class FlatConfigArray extends ConfigArray {
 
         return config;
     }
-    /* eslint-enable class-methods-use-this */
+    /* eslint-enable class-methods-use-this -- Desired as instance method */
 
 }
 

package/lib/config/flat-config-schema.js

@@ -336,7 +336,7 @@ const rulesSchema = {
             // avoid hairy edge case
             if (ruleId === "__proto__") {
 
-                /* eslint-disable-next-line no-proto */
+                /* eslint-disable-next-line no-proto -- Though deprecated, may still be present */
                 delete result.__proto__;
                 continue;
             }

package/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) {
@@ -34,16 +35,33 @@ function findRuleDefinition(ruleId, config) {
         pluginName = ruleIdParts.join("/");
     }
 
-    if (!config.plugins || !config.plugins[pluginName]) {
-        throw new TypeError(`Key "rules": Key "${ruleId}": Could not find plugin "${pluginName}".`);
-    }
+    const errorMessageHeader = `Key "rules": Key "${ruleId}"`;
+    let errorMessage = `${errorMessageHeader}: Could not find plugin "${pluginName}".`;
 
-    if (!config.plugins[pluginName].rules || !config.plugins[pluginName].rules[ruleName]) {
-        throw new TypeError(`Key "rules": Key "${ruleId}": Could not find "${ruleName}" in plugin "${pluginName}".`);
-    }
+    // if the plugin exists then we need to check if the rule exists
+    if (config.plugins && config.plugins[pluginName]) {
+
+        const plugin = config.plugins[pluginName];
+
+        // first check for exact rule match
+        if (plugin.rules && plugin.rules[ruleName]) {
+            return config.plugins[pluginName].rules[ruleName];
+        }
 
-    return config.plugins[pluginName].rules[ruleName];
+        errorMessage = `${errorMessageHeader}: Could not find "${ruleName}" in plugin "${pluginName}".`;
+
+        // otherwise, let's see if we can find the rule name elsewhere
+        for (const [otherPluginName, otherPlugin] of Object.entries(config.plugins)) {
+            if (otherPlugin.rules && otherPlugin.rules[ruleName]) {
+                errorMessage += ` Did you mean "${otherPluginName}/${ruleName}"?`;
+                break;
+            }
+        }
+
+        // falls through to throw error
+    }
 
+    throw new TypeError(errorMessage);
 }
 
 /**
@@ -98,7 +116,6 @@ class RuleValidator {
          * A collection of compiled validators for rules that have already
          * been validated.
          * @type {WeakMap}
-         * @property validators
          */
         this.validators = new WeakMap();
     }

package/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({
@@ -421,6 +422,9 @@ function compareResultsByFilePath(a, b) {
     return 0;
 }
 
+/**
+ * Main API.
+ */
 class ESLint {
 
     /**

package/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
  */
 
 /**
@@ -49,8 +49,8 @@ const MAX_CONFIG_COMBINATIONS = 17, // 16 combinations + 1 for severity only
 
 /**
  * Create registryItems for rules
- * @param   {rulesConfig} rulesConfig Hash of rule names and arrays of ruleConfig items
- * @returns {Object}                  registryItems for each rule in provided rulesConfig
+ * @param {rulesConfig} rulesConfig Hash of rule names and arrays of ruleConfig items
+ * @returns {Object} registryItems for each rule in provided rulesConfig
  */
 function makeRegistryItems(rulesConfig) {
     return Object.keys(rulesConfig).reduce((accumulator, ruleId) => {
@@ -73,7 +73,6 @@ function makeRegistryItems(rulesConfig) {
  */
 class Registry {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {rulesConfig} [rulesConfig] Hash of rule names and arrays of possible configurations
      */
@@ -104,7 +103,7 @@ class Registry {
      * configurations.
      *
      * The length of the returned array will be <= MAX_CONFIG_COMBINATIONS.
-     * @returns {Object[]}          "rules" configurations to use for linting
+     * @returns {Object[]} "rules" configurations to use for linting
      */
     buildRuleSets() {
         let idx = 0;
@@ -116,7 +115,7 @@ class Registry {
          *
          * This is broken out into its own function so that it doesn't need to be
          * created inside of the while loop.
-         * @param   {string} rule The ruleId to add.
+         * @param {string} rule The ruleId to add.
          * @returns {void}
          */
         const addRuleToRuleSet = function(rule) {
@@ -203,7 +202,7 @@ class Registry {
      * Creates a registry of rules which had no error-free configs.
      * The new registry is intended to be analyzed to determine whether its rules
      * should be disabled or set to warning.
-     * @returns {Registry}  A registry of failing rules.
+     * @returns {Registry} A registry of failing rules.
      */
     getFailingRulesRegistry() {
         const ruleIds = Object.keys(this.rules),
@@ -240,8 +239,8 @@ class Registry {
 
     /**
      * Return a cloned registry containing only configs with a desired specificity
-     * @param   {number} specificity Only keep configs with this specificity
-     * @returns {Registry}           A registry of rules
+     * @param {number} specificity Only keep configs with this specificity
+     * @returns {Registry} A registry of rules
      */
     filterBySpecificity(specificity) {
         const ruleIds = Object.keys(this.rules),
@@ -257,10 +256,10 @@ class Registry {
 
     /**
      * Lint SourceCodes against all configurations in the registry, and record results
-     * @param   {Object[]} sourceCodes  SourceCode objects for each filename
-     * @param   {Object}   config       ESLint config object
-     * @param   {progressCallback} [cb] Optional callback for reporting execution status
-     * @returns {Registry}              New registry with errorCount populated
+     * @param {Object[]} sourceCodes SourceCode objects for each filename
+     * @param {Object} config ESLint config object
+     * @param {progressCallback} [cb] Optional callback for reporting execution status
+     * @returns {Registry} New registry with errorCount populated
      */
     lintSourceCode(sourceCodes, config, cb) {
         let lintedRegistry = new Registry();
@@ -305,7 +304,7 @@ class Registry {
                 ruleSetIdx += 1;
 
                 if (cb) {
-                    cb(totalFilesLinting); // eslint-disable-line node/callback-return
+                    cb(totalFilesLinting); // eslint-disable-line node/callback-return -- End of function
                 }
             });
 
@@ -322,8 +321,8 @@ class Registry {
  *
  * This will return a new config with `["extends": [ ..., "eslint:recommended"]` and
  * only the rules which have configurations different from the recommended config.
- * @param   {Object} config config object
- * @returns {Object}        config object using `"extends": ["eslint:recommended"]`
+ * @param {Object} config config object
+ * @returns {Object} config object using `"extends": ["eslint:recommended"]`
  */
 function extendFromRecommended(config) {
     const newConfig = Object.assign({}, config);

package/lib/init/config-file.js

@@ -23,9 +23,9 @@ const debug = require("debug")("eslint:config-file");
  * Determines sort order for object keys for json-stable-stringify
  *
  * see: https://github.com/samn/json-stable-stringify#cmp
- * @param   {Object} a The first comparison object ({key: akey, value: avalue})
- * @param   {Object} b The second comparison object ({key: bkey, value: bvalue})
- * @returns {number}   1 or -1, used in stringify cmp method
+ * @param {Object} a The first comparison object ({key: akey, value: avalue})
+ * @param {Object} b The second comparison object ({key: bkey, value: bvalue})
+ * @returns {number} 1 or -1, used in stringify cmp method
  */
 function sortByKey(a, b) {
     return a.key > b.key ? 1 : -1;

package/lib/init/config-initializer.js

@@ -102,8 +102,8 @@ getPeerDependencies.cache = new Map();
 
 /**
  * Return necessary plugins, configs, parsers, etc. based on the config
- * @param   {Object} config  config object
- * @param   {boolean} [installESLint=true]  If `false` is given, it does not install eslint.
+ * @param {Object} config config object
+ * @param {boolean} [installESLint=true] If `false` is given, it does not install eslint.
  * @returns {string[]} An array of modules to be installed.
  */
 function getModulesList(config, installESLint) {
@@ -161,9 +161,10 @@ function getModulesList(config, installESLint) {
  *
  * Note: This clones the config object and returns a new config to avoid mutating
  * the original config parameter.
- * @param   {Object} answers  answers received from enquirer
- * @param   {Object} config   config object
- * @returns {Object}          config object with configured rules
+ * @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) {
     const BAR_TOTAL = 20,
@@ -415,7 +416,7 @@ function hasESLintVersionConflict(answers) {
 
 /**
  * Install modules.
- * @param   {string[]} modules Modules to be installed.
+ * @param {string[]} modules Modules to be installed.
  * @returns {void}
  */
 function installModules(modules) {
@@ -426,9 +427,9 @@ function installModules(modules) {
 /* istanbul ignore next: no need to test enquirer */
 /**
  * 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.
+ * @param {string[]} modules Array of modules to be installed.
+ * @param {boolean} packageJsonExists Indicates if package.json is existed.
+ * @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() {
 

package/lib/init/config-rule.js

@@ -17,8 +17,8 @@ const builtInRules = require("../rules");
 
 /**
  * Wrap all of the elements of an array into arrays.
- * @param   {*[]}     xs Any array.
- * @returns {Array[]}    An array of arrays.
+ * @param {*[]} xs Any array.
+ * @returns {Array[]} An array of arrays.
  */
 function explodeArray(xs) {
     return xs.reduce((accumulator, x) => {
@@ -33,9 +33,9 @@ function explodeArray(xs) {
  *
  * For example:
  * combineArrays([a, [b, c]], [x, y]); // -> [[a, x], [a, y], [b, c, x], [b, c, y]]
- * @param   {Array} arr1 The first array to combine.
- * @param   {Array} arr2 The second array to combine.
- * @returns {Array}      A mixture of the elements of the first and second arrays.
+ * @param {Array} arr1 The first array to combine.
+ * @param {Array} arr2 The second array to combine.
+ * @returns {Array} A mixture of the elements of the first and second arrays.
  */
 function combineArrays(arr1, arr2) {
     const res = [];
@@ -70,8 +70,8 @@ function combineArrays(arr1, arr2) {
  *     [{before: true}, {before: false}],
  *     [{after: true}, {after: false}]
  * ]
- * @param   {Object[]} objects Array of objects, each with one property/value pair
- * @returns {Array[]}          Array of arrays of objects grouped by property
+ * @param {Object[]} objects Array of objects, each with one property/value pair
+ * @returns {Array[]} Array of arrays of objects grouped by property
  */
 function groupByProperty(objects) {
     const groupedObj = objects.reduce((accumulator, obj) => {
@@ -97,7 +97,7 @@ function groupByProperty(objects) {
  * Configs may also have one or more additional elements to specify rule
  * configuration or options.
  * @typedef {Array|number} ruleConfig
- * @param {number}  0  The rule's severity (0, 1, 2).
+ * @param {number} 0 The rule's severity (0, 1, 2).
  */
 
 /**
@@ -131,9 +131,9 @@ function groupByProperty(objects) {
  *     {before: false, after: true},
  *     {before: false, after: false}
  * ]
- * @param   {Object[]} objArr1 Single key/value objects, all with the same key
- * @param   {Object[]} objArr2 Single key/value objects, all with another key
- * @returns {Object[]}         Combined objects for each combination of input properties and values
+ * @param {Object[]} objArr1 Single key/value objects, all with the same key
+ * @param {Object[]} objArr2 Single key/value objects, all with another key
+ * @returns {Object[]} Combined objects for each combination of input properties and values
  */
 function combinePropertyObjects(objArr1, objArr2) {
     const res = [];
@@ -174,7 +174,6 @@ function combinePropertyObjects(objArr1, objArr2) {
  */
 class RuleConfigSet {
 
-    // eslint-disable-next-line jsdoc/require-description
     /**
      * @param {ruleConfig[]} configs Valid rule configurations
      */
@@ -206,7 +205,7 @@ class RuleConfigSet {
 
     /**
      * Add rule configs from an array of strings (schema enums)
-     * @param  {string[]} enums Array of valid rule options (e.g. ["always", "never"])
+     * @param {string[]} enums Array of valid rule options (e.g. ["always", "never"])
      * @returns {void}
      */
     addEnums(enums) {
@@ -215,7 +214,7 @@ class RuleConfigSet {
 
     /**
      * Add rule configurations from a schema object
-     * @param  {Object} obj Schema item with type === "object"
+     * @param {Object} obj Schema item with type === "object"
      * @returns {boolean} true if at least one schema for the object could be generated, false otherwise
      */
     addObject(obj) {
@@ -260,8 +259,8 @@ class RuleConfigSet {
 
 /**
  * Generate valid rule configurations based on a schema object
- * @param   {Object} schema  A rule's schema object
- * @returns {Array[]}        Valid rule configurations
+ * @param {Object} schema A rule's schema object
+ * @returns {Array[]} Valid rule configurations
  */
 function generateConfigsFromSchema(schema) {
     const configSet = new RuleConfigSet();