From 9d097f79ee6061196543fdd33b84bd3b9d87935a Mon Sep 17 00:00:00 2001 From: Ben Perlmutter Date: Sun, 27 Nov 2022 15:33:32 -0500 Subject: [PATCH] add formatter text generation --- Makefile.js | 4 +- lib/cli-engine/formatters/manifest.js | 68 +++++++++++++++++++++++++++ templates/formatter-examples.md.ejs | 23 ++++++--- 3 files changed, 88 insertions(+), 7 deletions(-) create mode 100644 lib/cli-engine/formatters/manifest.js diff --git a/Makefile.js b/Makefile.js index e85514db9d9..b8aa6ff9b6b 100644 --- a/Makefile.js +++ b/Makefile.js @@ -447,6 +447,7 @@ function lintMarkdown(files) { */ function getFormatterResults() { const stripAnsi = require("strip-ansi"); + const formattersMetadata = require("./lib/cli-engine/formatters/manifest"); const formatterFiles = fs.readdirSync("./lib/cli-engine/formatters/"), rules = { @@ -489,7 +490,8 @@ function getFormatterResults() { ); data.formatterResults[name] = { - result: stripAnsi(formattedOutput) + result: stripAnsi(formattedOutput), + description: formattersMetadata.find(formatter => formatter.name === name).description }; } return data; diff --git a/lib/cli-engine/formatters/manifest.js b/lib/cli-engine/formatters/manifest.js new file mode 100644 index 00000000000..d95dfce75ae --- /dev/null +++ b/lib/cli-engine/formatters/manifest.js @@ -0,0 +1,68 @@ +/** + * @fileoverview Metadata about built-in formatters + * @author Ben Perlmutter + */ +"use strict"; + +/** + * @typedef Formatter + * @type {Object} + * @property {string} name Name of formatter. + * @property {string} description Description of formatter in Markdown. + */ + +/** + * @type {Array} Array of Formatter metadata objects + */ +const formatterMetadata = [ + { + name: "checkstyle", + description: "Outputs results to the [Checkstyle](https://checkstyle.sourceforge.io/) format." + }, + { + name: "compact", + description: "Human-readable output format. Mimics the default output of JSHint." + }, + { + name: "html", + description: "Outputs results to HTML. The `html` formatter is useful for visual presentation in the browser." + }, + { + name: "jslint-xml", + description: "Outputs results to format compatible with the [JSLint Jenkins plugin](https://plugins.jenkins.io/jslint/)." + }, + { + name: "json-with-metadata", + description: `Outputs JSON-serialized results. The \`json-with-meta\` provides the same linting results as the [\`json\`](#json) formatter with additional metadata about the rules applied. The linting results are included in the \`"results"\` property and the rules metadata is included in the \`"metadata"\` property. + +Alternatively, you can use the [ESLint Node.js API](../../developer-guide/nodejs-api.md) to programmatically use ESLint.` + }, + { + name: "json", + description: `Outputs JSON-serialized results. The \`json\` formatter is useful when you want to programmatically work with the CLI's linting results. + +Alternatively, you can use the [ESLint Node.js API](../../developer-guide/nodejs-api.md) to programmatically use ESLint.` + }, + { + name: "junit", + description: "Outputs results to format compatible with the [JUnit Jenkins plugin](https://plugins.jenkins.io/junit/)." + }, + { + name: "stylish", + description: "Human-readable output format. This is the default formatter." + }, + { + name: "tap", + description: "Outputs results to the [Test Anything Protocol (TAP)](https://testanything.org/) specification format." + }, + { + name: "unix", + description: "Outputs results to a format similar to many commands in UNIX-like systems. Parsable with tools such as [grep](https://www.gnu.org/software/grep/manual/grep.html), [sed](https://www.gnu.org/software/sed/manual/sed.html), and [awk](https://www.gnu.org/software/gawk/manual/gawk.html)." + }, + { + name: "visualstudio", + description: "Outputs results to format compatible with the integrated terminal of the [Visual Studio](https://visualstudio.microsoft.com/) IDE. When using Visual Studio, you can click on the linting results in the integrated terminal to go to the issue in the source code." + } +]; + +module.exports = formatterMetadata; diff --git a/templates/formatter-examples.md.ejs b/templates/formatter-examples.md.ejs index 218cd8777c3..34345637c59 100644 --- a/templates/formatter-examples.md.ejs +++ b/templates/formatter-examples.md.ejs @@ -10,7 +10,7 @@ edit_link: https://github.com/eslint/eslint/edit/main/templates/formatter-exampl ESLint comes with several built-in formatters to control the appearance of the linting results, and supports third-party formatters as well. -You can specify a formatter using the `--format` or `-f` flag on the command line. For example, `--format json` uses the `json` formatter. +You can specify a formatter using the `--format` or `-f` flag in the CLI. For example, `--format json` uses the `json` formatter. The built-in formatter options are: @@ -22,7 +22,7 @@ The built-in formatter options are: Examples of each formatter were created from linting `fullOfProblems.js` using the `.eslintrc` configuration shown below. -### `fullOfProblems.js` +`fullOfProblems.js`: ```js function addOne(i) { @@ -34,7 +34,7 @@ function addOne(i) { }; ``` -### `.eslintrc` +`.eslintrc.json`: ```json { @@ -49,17 +49,28 @@ function addOne(i) { } ``` -## Output Examples +Tests the formatters with the CLI: + +```shell +npx eslint --formatter fullOfProblems.js +``` + +## Built-In Formatter Options + <% Object.keys(formatterResults).forEach(function(formatterName) { -%> ### <%= formatterName %> -<% if (formatterName !== "html") { -%> +<%= formatterResults[formatterName].description %> + +Example output: + +<% if (formatterName !== "html") { -%> ```text <%= formatterResults[formatterName].result %> ``` <% } else {-%> - <% } -%> + <% }) -%>