Skip to content
Permalink
Browse files
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
  • Loading branch information
brettz9 committed Aug 20, 2021
1 parent 81c60f4 commit 58840ac844a61c72eabb603ecfb761812b82a7ed
Show file tree
Hide file tree
Showing 52 changed files with 234 additions and 113 deletions.
@@ -51,7 +51,7 @@ module.exports = {
"plugin:eslint-plugin/recommended"
],
parserOptions: {
ecmaVersion: 2020
ecmaVersion: 2021
},

/*
@@ -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) {
@@ -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) {
@@ -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) {
@@ -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();
}
@@ -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({
@@ -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
*/

/**
@@ -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() {

@@ -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.
*/
@@ -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.
*/
@@ -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() {
@@ -3,7 +3,7 @@
* @author Nicholas C. Zakas
*/

/* eslint-disable class-methods-use-this*/
/* eslint class-methods-use-this: off */
"use strict";

//------------------------------------------------------------------------------
@@ -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) {
@@ -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
*/

//------------------------------------------------------------------------------
@@ -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.
*/
@@ -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

0 comments on commit 58840ac

Please sign in to comment.