From 33fc3af47aaf2b5b70d5e6147f8de2842bb9f626 Mon Sep 17 00:00:00 2001 From: Francesco Trotta Date: Fri, 25 Mar 2022 21:46:28 +0100 Subject: [PATCH 1/2] chore: disambiguate types `FormatterFunction` and `LoadedFormatter` Fixes #15654 --- docs/developer-guide/nodejs-api.md | 22 ++++++++--------- .../working-with-custom-formatters.md | 6 ++--- lib/cli-engine/cli-engine.js | 4 +++- lib/eslint/eslint.js | 23 ++++-------------- lib/shared/types.js | 24 +++++++++++++++++++ 5 files changed, 45 insertions(+), 34 deletions(-) diff --git a/docs/developer-guide/nodejs-api.md b/docs/developer-guide/nodejs-api.md index 826e012ae70..cfd841e9517 100644 --- a/docs/developer-guide/nodejs-api.md +++ b/docs/developer-guide/nodejs-api.md @@ -21,7 +21,7 @@ While ESLint is designed to be run on the command line, it's possible to use ESL * [LintMessage type][lintmessage] * [SuppressedLintMessage type][suppressedlintmessage] * [EditInfo type][editinfo] - * [Formatter type][formatter] + * [LoadedFormatter type][loadedformatter] * [SourceCode](#sourcecode) * [splitLines()](#sourcecodesplitlines) * [Linter](#linter) @@ -56,8 +56,8 @@ const { ESLint } = require("eslint"); const results = await eslint.lintFiles(["lib/**/*.js"]); // 3. Format the results. - const formatter = await eslint.loadFormatter("stylish"); - const resultText = formatter.format(results); + const loadedFormatter = await eslint.loadFormatter("stylish"); + const resultText = loadedFormatter.format(results); // 4. Output it. console.log(resultText); @@ -83,8 +83,8 @@ const { ESLint } = require("eslint"); await ESLint.outputFixes(results); // 4. Format the results. - const formatter = await eslint.loadFormatter("stylish"); - const resultText = formatter.format(results); + const loadedFormatter = await eslint.loadFormatter("stylish"); + const resultText = loadedFormatter.format(results); // 5. Output it. console.log(resultText); @@ -268,7 +268,7 @@ This method checks if a given file is ignored by your configuration. ### ◆ eslint.loadFormatter(nameOrPath) ```js -const formatter = await eslint.loadFormatter(nameOrPath); +const loadedFormatter = await eslint.loadFormatter(nameOrPath); ``` This method loads a formatter. Formatters convert lint results to a human- or machine-readable string. @@ -287,8 +287,8 @@ This method loads a formatter. Formatters convert lint results to a human- or ma #### Return Value -* (`Promise`)
- The promise that will be fulfilled with a [Formatter] object. +* (`Promise`)
+ The promise that will be fulfilled with a [LoadedFormatter] object. ### ◆ ESLint.version @@ -430,9 +430,9 @@ The `EditInfo` value is information to edit text. The `fix` and `suggestions` pr This edit information means replacing the range of the `range` property by the `text` property value. It's like `sourceCodeText.slice(0, edit.range[0]) + edit.text + sourceCodeText.slice(edit.range[1])`. Therefore, it's an add if the `range[0]` and `range[1]` property values are the same value, and it's removal if the `text` property value is empty string. -### ◆ Formatter type +### ◆ LoadedFormatter type -The `Formatter` value is the object to convert the [LintResult] objects to text. The [eslint.loadFormatter()][eslint-loadformatter] method returns it. It has the following method: +The `LoadedFormatter` value is the object to convert the [LintResult] objects to text. The [eslint.loadFormatter()][eslint-loadformatter] method returns it. It has the following method: * `format` (`(results: LintResult[]) => string | Promise`)
The method to convert the [LintResult] objects to text. @@ -960,5 +960,5 @@ ruleTester.run("my-rule", myRule, { [lintmessage]: #-lintmessage-type [suppressedlintmessage]: #-suppressedlintmessage-type [editinfo]: #-editinfo-type -[formatter]: #-formatter-type +[loadedformatter]: #-loadedformatter-type [linter]: #linter diff --git a/docs/developer-guide/working-with-custom-formatters.md b/docs/developer-guide/working-with-custom-formatters.md index e157bb07941..bdcbdb12f6a 100644 --- a/docs/developer-guide/working-with-custom-formatters.md +++ b/docs/developer-guide/working-with-custom-formatters.md @@ -2,7 +2,7 @@ While ESLint has some built-in formatters available to format the linting results, it's also possible to create and distribute your own custom formatters. You can include custom formatters in your project directly or create an npm package to distribute them separately. -Each formatter is just a function that receives a `results` object and returns a string. For example, the following is how the `json` built-in formatter is implemented: +Each formatter is just a function that receives a `results` object and a `context` and returns a string. For example, the following is how the `json` built-in formatter is implemented: ```js //my-awesome-formatter.js @@ -11,7 +11,7 @@ module.exports = function(results, context) { }; ``` -Formatter can also be an async function (from ESLint v8.4.0), the following shows a simple example: +A formatter can also be an async function (from ESLint v8.4.0), the following shows a simple example: ```js //my-awesome-formatter.js @@ -280,7 +280,7 @@ warning no-unused-vars (https://eslint.org/docs/rules/no-unused-vars) ## Passing Arguments to Formatters -While custom formatter do not receive arguments in addition to the results object, it is possible to pass additional data into formatters. +While formatter functions do not receive arguments in addition to the results object and the context, it is possible to pass additional data into custom formatters using the methods described below. ## Using Environment Variables diff --git a/lib/cli-engine/cli-engine.js b/lib/cli-engine/cli-engine.js index 92b8755783f..b073f20f0c1 100644 --- a/lib/cli-engine/cli-engine.js +++ b/lib/cli-engine/cli-engine.js @@ -56,6 +56,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 {import("../shared/types").LintResult} LintResult */ +/** @typedef {import("../shared/types").FormatterFunction} FormatterFunction */ /** @typedef {ReturnType} ConfigArray */ /** @typedef {ReturnType} ExtractedConfig */ @@ -1002,7 +1004,7 @@ class CLIEngine { * @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. + * @returns {(FormatterFunction|null)} The formatter function or null if the `format` is not a string. */ getFormatter(format) { diff --git a/lib/eslint/eslint.js b/lib/eslint/eslint.js index 1e5a8f8b13f..927b60802a3 100644 --- a/lib/eslint/eslint.js +++ b/lib/eslint/eslint.js @@ -35,10 +35,11 @@ const { version } = require("../../package.json"); /** @typedef {import("../shared/types").SuppressedLintMessage} SuppressedLintMessage */ /** @typedef {import("../shared/types").Plugin} Plugin */ /** @typedef {import("../shared/types").Rule} Rule */ +/** @typedef {import("../shared/types").LintResult} LintResult */ /** * The main formatter object. - * @typedef Formatter + * @typedef LoadedFormatter * @property {function(LintResult[]): string | Promise} format format function. */ @@ -74,22 +75,6 @@ const { version } = require("../../package.json"); * @property {Object} definition The plugin definition. */ -/** - * A linting result. - * @typedef {Object} LintResult - * @property {string} filePath The path to the file that was linted. - * @property {LintMessage[]} messages All of the messages for the result. - * @property {SuppressedLintMessage[]} suppressedMessages All of the suppressed messages for the result. - * @property {number} errorCount Number of errors for the result. - * @property {number} fatalErrorCount Number of fatal errors for the result. - * @property {number} warningCount Number of warnings for the result. - * @property {number} fixableErrorCount Number of fixable errors for the result. - * @property {number} fixableWarningCount Number of fixable warnings for the result. - * @property {string} [source] The source code of the file that was linted. - * @property {string} [output] The source code of the file that was linted, with as many fixes applied as possible. - * @property {DeprecatedRuleInfo[]} usedDeprecatedRules The list of used deprecated rules. - */ - /** * Private members for the `ESLint` instance. * @typedef {Object} ESLintPrivateMembers @@ -619,7 +604,7 @@ class ESLint { * - `@foo` → `@foo/eslint-formatter` * - `@foo/bar` → `@foo/eslint-formatter-bar` * - A file path ... Load the file. - * @returns {Promise} A promise resolving to the formatter object. + * @returns {Promise} A promise resolving to the formatter object. * This promise will be rejected if the given formatter was not found or not * a function. */ @@ -639,7 +624,7 @@ class ESLint { /** * The main formatter method. - * @param {LintResults[]} results The lint results to format. + * @param {LintResult[]} results The lint results to format. * @returns {string | Promise} The formatted lint results. */ format(results) { diff --git a/lib/shared/types.js b/lib/shared/types.js index c407c4fb120..34c3e24ecca 100644 --- a/lib/shared/types.js +++ b/lib/shared/types.js @@ -173,3 +173,27 @@ module.exports = {}; * @property {string} ruleId The rule ID. * @property {string[]} replacedBy The rule IDs that replace this deprecated rule. */ + +/** + * A linting result. + * @typedef {Object} LintResult + * @property {string} filePath The path to the file that was linted. + * @property {LintMessage[]} messages All of the messages for the result. + * @property {SuppressedLintMessage[]} suppressedMessages All of the suppressed messages for the result. + * @property {number} errorCount Number of errors for the result. + * @property {number} fatalErrorCount Number of fatal errors for the result. + * @property {number} warningCount Number of warnings for the result. + * @property {number} fixableErrorCount Number of fixable errors for the result. + * @property {number} fixableWarningCount Number of fixable warnings for the result. + * @property {string} [source] The source code of the file that was linted. + * @property {string} [output] The source code of the file that was linted, with as many fixes applied as possible. + * @property {DeprecatedRuleInfo[]} usedDeprecatedRules The list of used deprecated rules. + */ + +/** + * A formatter function. + * @callback FormatterFunction + * @param {LintResult[]} results The list of linting results. + * @param {{cwd: string, rulesMeta: Record}} [context] A context object. If the formatter is used with the legacy API, this argument may be unspecified or have a different value. + * @returns {string | Promise} Formatted text. + */ From 1c0ad3d96330174b3d139d10a39c45c9010dacc4 Mon Sep 17 00:00:00 2001 From: Francesco Trotta Date: Fri, 1 Apr 2022 16:01:20 +0200 Subject: [PATCH 2/2] Code review update * Remove redundant `LintResult` type import * Remove note about `context` argument of `FormatterFunction` from JSDoc * docs: Revert to using variable name `formatter` in code examples --- docs/developer-guide/nodejs-api.md | 10 +++++----- lib/cli-engine/cli-engine.js | 1 - lib/shared/types.js | 2 +- 3 files changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/developer-guide/nodejs-api.md b/docs/developer-guide/nodejs-api.md index cfd841e9517..fc63072ad62 100644 --- a/docs/developer-guide/nodejs-api.md +++ b/docs/developer-guide/nodejs-api.md @@ -56,8 +56,8 @@ const { ESLint } = require("eslint"); const results = await eslint.lintFiles(["lib/**/*.js"]); // 3. Format the results. - const loadedFormatter = await eslint.loadFormatter("stylish"); - const resultText = loadedFormatter.format(results); + const formatter = await eslint.loadFormatter("stylish"); + const resultText = formatter.format(results); // 4. Output it. console.log(resultText); @@ -83,8 +83,8 @@ const { ESLint } = require("eslint"); await ESLint.outputFixes(results); // 4. Format the results. - const loadedFormatter = await eslint.loadFormatter("stylish"); - const resultText = loadedFormatter.format(results); + const formatter = await eslint.loadFormatter("stylish"); + const resultText = formatter.format(results); // 5. Output it. console.log(resultText); @@ -268,7 +268,7 @@ This method checks if a given file is ignored by your configuration. ### ◆ eslint.loadFormatter(nameOrPath) ```js -const loadedFormatter = await eslint.loadFormatter(nameOrPath); +const formatter = await eslint.loadFormatter(nameOrPath); ``` This method loads a formatter. Formatters convert lint results to a human- or machine-readable string. diff --git a/lib/cli-engine/cli-engine.js b/lib/cli-engine/cli-engine.js index b073f20f0c1..f7aa9e2242a 100644 --- a/lib/cli-engine/cli-engine.js +++ b/lib/cli-engine/cli-engine.js @@ -56,7 +56,6 @@ 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 {import("../shared/types").LintResult} LintResult */ /** @typedef {import("../shared/types").FormatterFunction} FormatterFunction */ /** @typedef {ReturnType} ConfigArray */ /** @typedef {ReturnType} ExtractedConfig */ diff --git a/lib/shared/types.js b/lib/shared/types.js index 34c3e24ecca..0335423f284 100644 --- a/lib/shared/types.js +++ b/lib/shared/types.js @@ -194,6 +194,6 @@ module.exports = {}; * A formatter function. * @callback FormatterFunction * @param {LintResult[]} results The list of linting results. - * @param {{cwd: string, rulesMeta: Record}} [context] A context object. If the formatter is used with the legacy API, this argument may be unspecified or have a different value. + * @param {{cwd: string, rulesMeta: Record}} [context] A context object. * @returns {string | Promise} Formatted text. */