eslint: adding readme (common and plugin-gradle)

simschla · simschla · commit 3f3705395fac · 2023-01-04T13:06:02.000+01:00
diff --git a/CHANGES.md b/CHANGES.md
@@ -10,6 +10,9 @@ This document is intended for Spotless developers.
 We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (starting after version `1.27.0`).
 
 ## [Unreleased]
+### Added
+* Added support for npm-based [ESLint](https://eslint.org/)-formatter for javascript and typescript ([#1433](https://github.com/diffplug/spotless/pull/1433))
+
 ### Changes
 * Bump the dev version of Gradle from `7.5.1` to `7.6` ([#1409](https://github.com/diffplug/spotless/pull/1409))
   * We also removed the no-longer-required dependency `org.codehaus.groovy:groovy-xml`
diff --git a/README.md b/README.md
@@ -69,6 +69,7 @@ lib('kotlin.KtfmtStep')                          +'{{yes}}       | {{yes}}
 lib('kotlin.DiktatStep')                         +'{{yes}}       | {{yes}}      | {{no}}       | {{no}}  |',
 lib('markdown.FreshMarkStep')                    +'{{yes}}       | {{no}}       | {{no}}       | {{no}}  |',
 lib('markdown.FlexmarkStep')                     +'{{no}}        | {{yes}}      | {{no}}       | {{no}}  |',
+lib('npm.EslintFormatterStep')                   +'{{yes}}       | {{yes}}      | {{no}}       | {{no}}  |',
 lib('npm.PrettierFormatterStep')                 +'{{yes}}       | {{yes}}      | {{no}}       | {{no}}  |',
 lib('npm.TsFmtFormatterStep')                    +'{{yes}}       | {{yes}}      | {{no}}       | {{no}}  |',
 lib('pom.SortPomStep')                           +'{{no}}        | {{yes}}      | {{no}}       | {{no}}  |',
@@ -113,6 +114,7 @@ extra('wtp.EclipseWtpFormatterStep')             +'{{yes}}       | {{yes}}
 | [`kotlin.DiktatStep`](lib/src/main/java/com/diffplug/spotless/kotlin/DiktatStep.java) | :+1:       | :+1:      | :white_large_square:       | :white_large_square:  |
 | [`markdown.FreshMarkStep`](lib/src/main/java/com/diffplug/spotless/markdown/FreshMarkStep.java) | :+1:       | :white_large_square:       | :white_large_square:       | :white_large_square:  |
 | [`markdown.FlexmarkStep`](lib/src/main/java/com/diffplug/spotless/markdown/FlexmarkStep.java) | :white_large_square:        | :+1:      | :white_large_square:       | :white_large_square:  |
+| [`npm.EslintFormatterStep`](lib/src/main/java/com/diffplug/spotless/npm/EslintFormatterStep.java) | :+1:       | :+1:      | :white_large_square:       | :white_large_square:  |
 | [`npm.PrettierFormatterStep`](lib/src/main/java/com/diffplug/spotless/npm/PrettierFormatterStep.java) | :+1:       | :+1:      | :white_large_square:       | :white_large_square:  |
 | [`npm.TsFmtFormatterStep`](lib/src/main/java/com/diffplug/spotless/npm/TsFmtFormatterStep.java) | :+1:       | :+1:      | :white_large_square:       | :white_large_square:  |
 | [`pom.SortPomStep`](lib/src/main/java/com/diffplug/spotless/pom/SortPomStep.java) | :white_large_square:        | :+1:      | :white_large_square:       | :white_large_square:  |
diff --git a/plugin-gradle/CHANGES.md b/plugin-gradle/CHANGES.md
@@ -3,6 +3,8 @@
 We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (starting after version `3.27.0`).
 
 ## [Unreleased]
+### Added
+* Added support for npm-based [ESLint](https://eslint.org/) formatter for javascript and typescript ([#1433](https://github.com/diffplug/spotless/pull/1433))
 ### Fixed
 * Prevent tool configurations from being resolved outside project ([#1447](https://github.com/diffplug/spotless/pull/1447) fixes [#1215](https://github.com/diffplug/spotless/issues/1215))
 
diff --git a/plugin-gradle/README.md b/plugin-gradle/README.md
@@ -69,7 +69,8 @@ Spotless supports all of Gradle's built-in performance features (incremental bui
   - [FreshMark](#freshmark) aka markdown
   - [Antlr4](#antlr4) ([antlr4formatter](#antlr4formatter))
   - [SQL](#sql) ([dbeaver](#dbeaver), [prettier](#prettier))
-  - [Typescript](#typescript) ([tsfmt](#tsfmt), [prettier](#prettier))
+  - [Typescript](#typescript) ([tsfmt](#tsfmt), [prettier](#prettier), [eslint](#eslint--typescript-))
+  - [Javascript](#javascript) ([prettier](#prettier), [eslint](#eslint--javascript-))
   - [JSON](#json)
   - Multiple languages
     - [Prettier](#prettier) ([plugins](#prettier-plugins), [npm detection](#npm-detection), [`.npmrc` detection](#npmrc-detection))
@@ -576,6 +577,7 @@ spotless {
 
     tsfmt()    // has its own section below
     prettier() // has its own section below
+    eslint() // has its own section below
 
     licenseHeader '/* (C) $YEAR */', '(import|const|declare|export|var) ' // or licenseHeaderFile
     // note the '(import|const|...' argument - this is a regex which identifies the top
@@ -608,6 +610,122 @@ spotless {
 
 For details, see the [npm detection](#npm-detection) and [`.npmrc` detection](#npmrc-detection) sections of prettier, which apply also to tsfmt.
 
+### eslint (Typescript)
+
+[npm](https://www.npmjs.com/package/eslint). [changelog](https://github.com/eslint/eslint/blob/main/CHANGELOG.md). *Please note:*
+The auto-discovery of config files (up the file tree) will not work when using eslint within spotless,
+hence you are required to provide resolvable file paths for config files, or alternatively provide the configuration inline.
+
+The configuration is very similar to the [eslint (Javascript)](#eslint--javascript-) configuration. It differs in supported
+styleguides and the requirement for a tsconfigFile.
+
+```gradle
+spotless {
+  typescript {
+    eslint('8.30.0') // version is optional
+    eslint(['my-eslint-fork': '1.2.3', 'my-eslint-plugin': '1.2.1']) // can specify exactly which npm packages to use
+
+    eslint()
+      // optional: use a popular eslint styleguide for typescript
+      .styleGuide('standard-with-typescript') // or 'xo-typescript'
+      // configuration is mandatory. Provide inline config or a config file.
+      // a) inline-configuration
+      .configJs('''
+        {
+          env: {
+            browser: true,
+            es2021: true
+          },
+          extends: 'standard-with-typescript',
+          overrides: [
+          ],
+          parserOptions: {
+            ecmaVersion: 'latest',
+            sourceType: 'module',
+            project: './tsconfig.json',
+          },
+          rules: {
+          }
+        }
+      ''')
+      // b) config file
+      .configFile('.eslintrc.js')
+      // recommended: provide a tsconfig.json - especially when using the styleguides
+      .tsconfigFile('tsconfig.json')
+  }
+}
+```
+
+**Prerequisite: eslint requires a working NodeJS version**
+
+For details, see the [npm detection](#npm-detection) and [`.npmrc` detection](#npmrc-detection) sections of prettier, which apply also to eslint.
+
+## Javascript
+
+- `com.diffplug.gradle.spotless.JavascriptExtension` [javadoc](https://javadoc.io/doc/com.diffplug.spotless/spotless-plugin-gradle/6.12.0/com/diffplug/gradle/spotless/JavascriptExtension.html), [code](https://github.com/diffplug/spotless/blob/main/plugin-gradle/src/main/java/com/diffplug/gradle/spotless/JavascriptExtension.java)
+
+```gradle
+spotless {
+  javascript {
+    target 'src/**/*.js' // you have to set the target manually
+
+    prettier() // has its own section below
+    eslint() // has its own section below
+
+    licenseHeader '/* (C) $YEAR */', 'REGEX_TO_DEFINE_TOP_OF_FILE' // or licenseHeaderFile
+  }
+}
+```
+
+### eslint (Javascript)
+
+[npm](https://www.npmjs.com/package/eslint). [changelog](https://github.com/eslint/eslint/blob/main/CHANGELOG.md). *Please note:*
+The auto-discovery of config files (up the file tree) will not work when using eslint within spotless,
+hence you are required to provide resolvable file paths for config files, or alternatively provide the configuration inline.
+
+The configuration is very similar to the [eslint (Typescript)](#eslint--typescript-) configuration. It differs in supported
+styleguides and no requirement for a tsconfig (of course).
+
+```gradle
+
+```gradle
+spotless {
+  javascript {
+    eslint('8.30.0') // version is optional
+    eslint(['my-eslint-fork': '1.2.3', 'my-eslint-plugin': '1.2.1']) // can specify exactly which npm packages to use
+
+    eslint()
+      // optional: use a popular eslint styleguide for javascript
+      .styleGuide('standard') // or 'airbnb', 'google', 'xo'
+      // configuration is mandatory. Provide inline config or a config file.
+      // a) inline-configuration
+      .configJs('''
+        {
+          env: {
+            browser: true,
+            es2021: true
+          },
+          extends: 'standard',
+          overrides: [
+          ],
+          parserOptions: {
+            ecmaVersion: 'latest',
+            sourceType: 'module'
+          },
+          rules: {
+          }
+        }
+      ''')
+      // b) config file
+      .configFile('.eslintrc.js')
+  }
+}
+```
+
+**Prerequisite: eslint requires a working NodeJS version**
+
+For details, see the [npm detection](#npm-detection) and [`.npmrc` detection](#npmrc-detection) sections of prettier, which apply also to eslint.
+
 ## JSON
 
 - `com.diffplug.gradle.spotless.JsonExtension` [javadoc](https://javadoc.io/doc/com.diffplug.spotless/spotless-plugin-gradle/6.12.1/com/diffplug/gradle/spotless/JsonExtension.html), [code](https://github.com/diffplug/spotless/blob/main/plugin-gradle/src/main/java/com/diffplug/gradle/spotless/JsonExtension.java)
