From 258eb498810819b465371166271003f0aa0aa27b Mon Sep 17 00:00:00 2001 From: Brandon Mills Date: Tue, 23 Mar 2021 00:31:29 -0400 Subject: [PATCH 1/6] Chore: Upgrade eslint-plugin-jsdoc to v25 This is a Chore instead of an Upgrade because it's in `devDependencies`. v25 is the first release of `eslint-plugin-jsdoc` to bump the `eslint` peer dependency to allow `eslint@7`. Once it's upgraded, we won't have to use `--legacy-peer-deps` to install dependencies with npm v7. The newer version was unsatisfied with the `cliOptions` param to `translateOptions` typed as just `Object`, so I turned our Optionator config into a JSDoc typedef. --- lib/cli.js | 5 ++++- lib/options.js | 46 ++++++++++++++++++++++++++++++++++++++++++++++ package.json | 2 +- 3 files changed, 51 insertions(+), 2 deletions(-) diff --git a/lib/cli.js b/lib/cli.js index 4216126b6ce..228fa075408 100644 --- a/lib/cli.js +++ b/lib/cli.js @@ -32,6 +32,7 @@ const debug = require("debug")("eslint:cli"); /** @typedef {import("./eslint/eslint").ESLintOptions} ESLintOptions */ /** @typedef {import("./eslint/eslint").LintMessage} LintMessage */ /** @typedef {import("./eslint/eslint").LintResult} LintResult */ +/** @typedef {import("./options").ParsedCLIOptions} ParsedCLIOptions */ //------------------------------------------------------------------------------ // Helpers @@ -54,7 +55,7 @@ function quietFixPredicate(message) { /** * Translates the CLI options into the options expected by the CLIEngine. - * @param {Object} cliOptions The CLI options to translate. + * @param {ParsedCLIOptions} cliOptions The CLI options to translate. * @returns {ESLintOptions} The options object for the CLIEngine. * @private */ @@ -221,6 +222,8 @@ const cli = { if (Array.isArray(args)) { debug("CLI args: %o", args.slice(2)); } + + /** @type {ParsedCLIOptions} */ let options; try { diff --git a/lib/options.js b/lib/options.js index 99a38a7700c..aca0d5b20b7 100644 --- a/lib/options.js +++ b/lib/options.js @@ -11,6 +11,52 @@ const optionator = require("optionator"); +//------------------------------------------------------------------------------ +// Typedefs +//------------------------------------------------------------------------------ + +/** + * The options object parsed by Optionator. + * @typedef {Object} CLIOptions + * @property {boolean} cache Only check changed files + * @property {string} cacheFile Path to the cache file. Deprecated: use --cache-location + * @property {string} [cacheLocation] Path to the cache file or directory + * @property {"metadata" | "content"} cacheStrategy Strategy to use for detecting changed files in the cache + * @property {boolean} [color] Force enabling/disabling of color + * @property {string} [config] Use this configuration, overriding .eslintrc.* config options if present + * @property {boolean} debug Output debugging information + * @property {string[]} [env] Specify environments + * @property {boolean} envInfo Output execution environment information + * @property {boolean} errorOnUnmatchedPattern Prevent errors when pattern is unmatched + * @property {boolean} [eslintrc] Disable use of configuration from .eslintrc.* + * @property {string[]} [ext] Specify JavaScript file extensions + * @property {boolean} fix Automatically fix problems + * @property {boolean} fixDryRun Automatically fix problems without saving the changes to the file system + * @property {("problem" | "suggestion" | "layout")[]} fixType Specify the types of fixes to apply (problem, suggestion, layout) + * @property {string} format Use a specific output format + * @property {string[]} [global] Define global variables + * @property {boolean} [help] Show help + * @property {boolean} ignore Disable use of ignore files and patterns + * @property {string} [ignorePath] Specify path of ignore file + * @property {string[]} [ignorePattern] Pattern of files to ignore (in addition to those in .eslintignore) + * @property {boolean} init Run config initialization wizard + * @property {boolean} [inlineConfig] Prevent comments from changing config or rules + * @property {number} maxWarnings Number of warnings to trigger nonzero exit code + * @property {string} [outputFile] Specify file to write report to + * @property {string} [parser] Specify the parser to be used + * @property {Object} [parserOptions] Specify parser options + * @property {string[]} [plugin] Specify plugins + * @property {string} [printConfig] Print the configuration for the given file + * @property {boolean | undefined} reportUnusedDisableDirectives Adds reported errors for unused eslint-disable directives + * @property {string} [resolvePluginsRelativeTo] A folder where plugins should be resolved from, CWD by default + * @property {Object} [rule] Specify rules + * @property {string[]} [rulesdir] Use additional rules from this directory + * @property {boolean} stdin Lint code provided on + * @property {string} [stdinFilename] Specify filename to process STDIN as + * @property {boolean} [quiet] Report errors only + * @property {boolean} [version] Output the version number + */ + //------------------------------------------------------------------------------ // Initialization and Public Interface //------------------------------------------------------------------------------ diff --git a/package.json b/package.json index ee525151db3..4da8d58e93f 100644 --- a/package.json +++ b/package.json @@ -100,7 +100,7 @@ "eslint-config-eslint": "file:packages/eslint-config-eslint", "eslint-plugin-eslint-plugin": "^2.2.1", "eslint-plugin-internal-rules": "file:tools/internal-rules", - "eslint-plugin-jsdoc": "^22.1.0", + "eslint-plugin-jsdoc": "^25.4.3", "eslint-plugin-node": "^11.1.0", "eslint-release": "^2.0.0", "eslump": "^2.0.0", From bfb6da42223f6dbe1fc97e241cd9ce641950578c Mon Sep 17 00:00:00 2001 From: Brandon Mills Date: Tue, 23 Mar 2021 00:35:23 -0400 Subject: [PATCH 2/6] Chore: npm v7 no longer needs --legacy-peer-deps (refs #13844) `eslint-plugin-jsdoc` was the last upgrade needed to be compatible with the new peer dependency resolution in npm v7. --- .github/workflows/ci.yml | 4 ---- 1 file changed, 4 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 460130a5658..3de5fc7cd29 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -40,10 +40,6 @@ jobs: node-version: ${{ matrix.node }} - name: Install Packages run: npm install - if: ${{ !startswith(matrix.node, '15') }} - - name: Install Packages - run: npm install --legacy-peer-deps - if: ${{ startswith(matrix.node, '15') }} - name: Test run: node Makefile mocha - name: Fuzz Test From ca538884471add94bb71b194d0803fdb347ba5de Mon Sep 17 00:00:00 2001 From: Brandon Mills Date: Tue, 23 Mar 2021 22:25:54 -0400 Subject: [PATCH 3/6] Docs: Make ParsedCLIOptions typedef name consistent Co-authored-by: Milos Djermanovic --- lib/options.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/options.js b/lib/options.js index aca0d5b20b7..eadc42c9e31 100644 --- a/lib/options.js +++ b/lib/options.js @@ -17,7 +17,7 @@ const optionator = require("optionator"); /** * The options object parsed by Optionator. - * @typedef {Object} CLIOptions + * @typedef {Object} ParsedCLIOptions * @property {boolean} cache Only check changed files * @property {string} cacheFile Path to the cache file. Deprecated: use --cache-location * @property {string} [cacheLocation] Path to the cache file or directory From 9add528522361e6640f8b10f7594c3001002da7c Mon Sep 17 00:00:00 2001 From: Brandon Mills Date: Tue, 23 Mar 2021 22:28:20 -0400 Subject: [PATCH 4/6] Docs: Properties with default values are non-optional Co-authored-by: Milos Djermanovic --- lib/options.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/options.js b/lib/options.js index eadc42c9e31..2a0f23015ee 100644 --- a/lib/options.js +++ b/lib/options.js @@ -28,7 +28,7 @@ const optionator = require("optionator"); * @property {string[]} [env] Specify environments * @property {boolean} envInfo Output execution environment information * @property {boolean} errorOnUnmatchedPattern Prevent errors when pattern is unmatched - * @property {boolean} [eslintrc] Disable use of configuration from .eslintrc.* + * @property {boolean} eslintrc Disable use of configuration from .eslintrc.* * @property {string[]} [ext] Specify JavaScript file extensions * @property {boolean} fix Automatically fix problems * @property {boolean} fixDryRun Automatically fix problems without saving the changes to the file system @@ -40,7 +40,7 @@ const optionator = require("optionator"); * @property {string} [ignorePath] Specify path of ignore file * @property {string[]} [ignorePattern] Pattern of files to ignore (in addition to those in .eslintignore) * @property {boolean} init Run config initialization wizard - * @property {boolean} [inlineConfig] Prevent comments from changing config or rules + * @property {boolean} inlineConfig Prevent comments from changing config or rules * @property {number} maxWarnings Number of warnings to trigger nonzero exit code * @property {string} [outputFile] Specify file to write report to * @property {string} [parser] Specify the parser to be used @@ -53,7 +53,7 @@ const optionator = require("optionator"); * @property {string[]} [rulesdir] Use additional rules from this directory * @property {boolean} stdin Lint code provided on * @property {string} [stdinFilename] Specify filename to process STDIN as - * @property {boolean} [quiet] Report errors only + * @property {boolean} quiet Report errors only * @property {boolean} [version] Output the version number */ From 5333fbedddf43ec28f3318645f21d579381435ac Mon Sep 17 00:00:00 2001 From: Brandon Mills Date: Tue, 23 Mar 2021 22:35:58 -0400 Subject: [PATCH 5/6] Docs: Add _ filenames/patterns to ParsedCLIOptions typedef --- lib/options.js | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/options.js b/lib/options.js index 2a0f23015ee..cee983ef1f1 100644 --- a/lib/options.js +++ b/lib/options.js @@ -55,6 +55,7 @@ const optionator = require("optionator"); * @property {string} [stdinFilename] Specify filename to process STDIN as * @property {boolean} quiet Report errors only * @property {boolean} [version] Output the version number + * @property {string[]} _ Positional filenames or patterns */ //------------------------------------------------------------------------------ From 836ec79b49ee218b5dd29917149af1505664b520 Mon Sep 17 00:00:00 2001 From: Brandon Mills Date: Wed, 24 Mar 2021 20:17:00 -0400 Subject: [PATCH 6/6] Docs: ParsedCLIOptions.fixType is optional Co-authored-by: Milos Djermanovic --- lib/options.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/options.js b/lib/options.js index cee983ef1f1..92c140bd3c8 100644 --- a/lib/options.js +++ b/lib/options.js @@ -32,7 +32,7 @@ const optionator = require("optionator"); * @property {string[]} [ext] Specify JavaScript file extensions * @property {boolean} fix Automatically fix problems * @property {boolean} fixDryRun Automatically fix problems without saving the changes to the file system - * @property {("problem" | "suggestion" | "layout")[]} fixType Specify the types of fixes to apply (problem, suggestion, layout) + * @property {("problem" | "suggestion" | "layout")[]} [fixType] Specify the types of fixes to apply (problem, suggestion, layout) * @property {string} format Use a specific output format * @property {string[]} [global] Define global variables * @property {boolean} [help] Show help