gulp-eslint-new 1.3.0 → 1.4.2

package/README.md

@@ -46,6 +46,8 @@ Or use the plugin API to do things like:
 gulp.src(['**/*.js', '!node_modules/**'])
     .pipe(gulpESLintNew({
         overrideConfig: {
+            plugins: ['json'],
+            extends: ['plugin:json/recommended'],
             rules: {
                 'my-custom-rule': 1,
                 'strict': 2
@@ -75,7 +77,7 @@ For additional examples, look through the [example directory](https://github.com
 
 Param type: `Object`
 
-Supported options include all [linting options][linting options] and [autofix options](https://eslint.org/docs/developer-guide/nodejs-api#autofix) of the `ESLint` constructor.
+Supported options include all [linting options](https://eslint.org/docs/developer-guide/nodejs-api#linting) and [autofix options](https://eslint.org/docs/developer-guide/nodejs-api#autofix) of the `ESLint` constructor.
 Please, refer to the ESLint documentation for information about the usage of those options.
 Check also the notes about the [Autofix Function](#autofix-function).
 Additionally, gulp-eslint-new supports the options listed below.
@@ -100,7 +102,7 @@ When `false`, ESLint will not respect `.eslintignore` files or ignore patterns i
 
 ##### `options.ignorePath`
 
-Type: `string | null`
+Type: `string`
 
 The path to a file ESLint uses instead of `.eslintignore` in the current working directory.
 
@@ -124,62 +126,28 @@ For example, since ESLint automatically ignores file paths inside a `node_module
 
 #### Legacy Options
 
-The following options are provided for backward compatibility with [gulp-eslint][gulp-eslint].
-Their usage is discouraged because preferable alternatives exist, that are more in line with the present ESLint conventions.
-
-##### `options.configFile`
-
-Type: `string`
-
-_A legacy synonym for `options.overrideConfigFile` (see [linting options][linting options])._
-
-##### `options.envs`
-
-Type: `string[]`
-
-Specify a list of environments to be applied.
-
-_Prefer using [`options.overrideConfig.env`](https://eslint.org/docs/user-guide/configuring/language-options#specifying-environments) instead. Note the different option name and format._
-
-##### `options.globals`
-
-Type: `string[]`
-
-Specify a list of global variables to declare.
-Variables declared with this option are considered readonly.
-
-_Prefer using [`options.overrideConfig.globals`](https://eslint.org/docs/user-guide/configuring/language-options#specifying-globals) instead. Note the different format._
-
-##### `options.parser`
-
-Type: `string`
-
-_Prefer using [`options.overrideConfig.parser`](https://eslint.org/docs/user-guide/configuring/plugins#specifying-parser) instead._
-
-##### `options.parserOptions`
-
-Type: `Object`
-
-_Prefer using [`options.overrideConfig.parserOptions`](https://eslint.org/docs/user-guide/configuring/language-options#specifying-parser-options) instead._
-
-##### `options.rules`
-
-Type: `Object`
-
-_Prefer using [`options.overrideConfig.rules`](https://eslint.org/docs/user-guide/configuring/rules) instead._
-
-##### `options.warnFileIgnored`
-
-Type: `boolean`
-
-_A legacy synonym for [`options.warnIgnored`](#optionswarnignored)._
+The following legacy options are provided for backward compatibility with [gulp-eslint][gulp-eslint].
+When `gulpESLintNew` is passed any of these options, it will map them automatically as shown in the table to match the new ESLint conventions.
+
+| Legacy option     | Migrated to                     | Notes |
+|-------------------|---------------------------------|-|
+| `configFile`      | `overrideConfigFile`            | New option name. |
+| `envs`            | `overrideConfig.env`            | New option name and format. `overrideConfig.env` should be an object as explained in the [documentation](https://eslint.org/docs/user-guide/configuring/language-options#specifying-environments). |
+| `extends`         | `overrideConfig.extends`        | |
+| `globals`         | `overrideConfig.globals`        | The new option format requires `overrideConfig.globals` to be an object as explained in the [documentation](https://eslint.org/docs/user-guide/configuring/language-options#specifying-globals). |
+| `ignorePattern`   | `overrideConfig.ignorePatterns` | New option name. |
+| `parser`          | `overrideConfig.parser`         | |
+| `parserOptions`   | `overrideConfig.parserOptions`  | |
+| `plugins`         | `overrideConfig.plugins`        | `plugins` as an array of strings is migrated to `overrideConfig.plugins`. In contrast, `plugins` as an object that maps strings to plugin implementations has different semantics and is not migrated. |
+| `rules`           | `overrideConfig.rules`          | |
+| `warnFileIgnored` | `warnIgnored`                   | New option name. |
 
 #### Autofix Function
 
 When the `fix` option is specified, fixes are applied to the gulp stream.
 The fixed content can be saved to file using [`gulpESLintNew.fix()`](#gulpeslintnewfix) (See [example/fix.js](https://github.com/fasttime/gulp-eslint-new/blob/main/example/fix.js)).
 Rules that are fixable can be found in ESLint's [rules list](https://eslint.org/docs/rules/).
-When fixes are applied, a "fixed" property is set to `true` on the fixed file's ESLint result.
+When fixes are applied, a `fixed` property is set to `true` on the fixed file's ESLint result.
 
 ### `gulpESLintNew(overrideConfigFile)`
 
@@ -337,7 +305,7 @@ gulpESLintNew.format('junit', process.stdout)
 Format each linted file individually.
 This should be used in the stream after piping through `gulpESLintNew`; otherwise, this will find no ESLint results to format.
 
-The arguments for `formatEach` are the same as the arguments for `format`.
+The arguments for `gulpESLintNew.formatEach` are the same as the arguments for [`gulpESLintNew.format`](#gulpeslintnewformatformatter-writer).
 
 ### `gulpESLintNew.fix()`
 
@@ -359,9 +327,8 @@ ESLint may be configured explicity by using any of the supported [configuration
 
 ESLint results are attached as an `eslint` property to the Vinyl files that pass through a gulp stream pipeline.
 This is available to streams that follow the initial gulp-eslint-new stream.
-The [`gulpESLintNew.result`](#gulpeslintnewresultaction) and [`gulpESLintNew.results`](#gulpeslintnewresultsaction) methods are made available to support extensions and custom handling of ESLint results.
+The functions [`gulpESLintNew.result`](#gulpeslintnewresultaction) and [`gulpESLintNew.results`](#gulpeslintnewresultsaction) are made available to support extensions and custom handling of ESLint results.
 
 [gulp-eslint]: https://github.com/adametry/gulp-eslint
-[linting options]: https://eslint.org/docs/developer-guide/nodejs-api#linting
 [npm badge]: https://badge.fury.io/js/gulp-eslint-new.svg
 [npm URL]: https://www.npmjs.com/package/gulp-eslint-new

package/index.d.ts

@@ -2,8 +2,12 @@ import { ESLint, Linter }    from 'eslint';
 import                            'node';
 import { TransformCallback } from 'stream';
 
-export type GulpESLintAction<Type>
-	= ((value: Type, callback: TransformCallback) => unknown) | ((value: Type) => Promise<unknown>);
+type FormatterFunction =
+	(results: ESLint.LintResult[], data?: ESLint.LintResultData) => string | Promise<string>;
+
+type LintResultStreamFunction<Type>
+	= ((action: (value: Type, callback: TransformCallback) => void) => NodeJS.ReadWriteStream)
+	& ((action: (value: Type) => unknown | Promise<unknown>) => NodeJS.ReadWriteStream);
 
 export type GulpESLintOptions =
 	Omit<
@@ -14,33 +18,50 @@ export type GulpESLintOptions =
 	| 'errorOnUnmatchedPattern'
 	| 'extensions'
 	| 'globInputPaths'
+	| 'plugins'
 	>
 	& {
 		/** @deprecated Use `overrideConfigFile` instead. */
-		configFile?: string | undefined;
+		configFile?: ESLint.Options['overrideConfigFile'];
 
 		/**
 		 * @deprecated
-		 * Use `overrideConfig.env` instead. Note the different option name and format.
+		 * Use `overrideConfig.env` or `baseConfig.env` instead.
+		 * Note the different option name and format.
 		 */
 		envs?: string[] | undefined;
 
-		/** @deprecated Use `overrideConfig.globals` instead. Note the different format. */
+		/** @deprecated Use `overrideConfig.extends` or `baseConfig.extends` instead. */
+		extends?: Linter.Config['extends'];
+
+		/**
+		 * @deprecated
+		 * Use `overrideConfig.globals` or `baseConfig.globals` instead. Note the different format.
+		 */
 		globals?: string[] | undefined;
 
-		/** @deprecated Use `overrideConfig.parser` instead. */
-		parser?: string | undefined;
+		/**
+		 * @deprecated
+		 * Use `overrideConfig.ignorePatterns` or `baseConfig.ignorePatterns` instead.
+		 * Note the different option name.
+		 */
+		ignorePattern?: Linter.Config['ignorePatterns'];
 
-		/** @deprecated Use `overrideConfig.parserOptions` instead. */
+		/** @deprecated Use `overrideConfig.parser` or `baseConfig.parser` instead. */
+		parser?: Linter.Config['parser'];
+
+		/** @deprecated Use `overrideConfig.parserOptions` or `baseConfig.parserOptions` instead. */
 		parserOptions?: Linter.ParserOptions | undefined;
 
+		plugins?: ESLint.Options['plugins'] | Linter.Config['plugins'];
+
 		quiet?:
 		| boolean
 		| ((message: Linter.LintMessage, index: number, list: Linter.LintMessage[]) => unknown)
 		| undefined;
 
-		/** @deprecated Use `overrideConfig.rules` instead. */
-		rules?: Partial<Linter.RulesRecord> | undefined;
+		/** @deprecated Use `overrideConfig.rules` or `baseConfig.rules` instead. */
+		rules?: Linter.Config['rules'];
 
 		/** @deprecated Use `warnIgnored` instead. */
 		warnFileIgnored?: boolean | undefined;
@@ -66,7 +87,7 @@ declare const gulpESLintNew: {
 	/**
 	 * Append ESLint result to each file.
 	 *
-	 * @param options Options for gulp-eslint-new.
+	 * @param options - Options for gulp-eslint-new.
 	 * @returns gulp file stream.
 	 */
 	(options?: GulpESLintOptions): NodeJS.ReadWriteStream;
@@ -74,7 +95,7 @@ declare const gulpESLintNew: {
 	/**
 	 * Append ESLint result to each file.
 	 *
-	 * @param overrideConfigFile The path to a configuration file.
+	 * @param overrideConfigFile - The path to a configuration file.
 	 * @returns gulp file stream.
 	 */
 	(overrideConfigFile?: string): NodeJS.ReadWriteStream;
@@ -85,7 +106,7 @@ declare const gulpESLintNew: {
 	 * @param action - A function to handle each ESLint result.
 	 * @returns gulp file stream.
 	 */
-	result(action: GulpESLintAction<GulpESLintResult>): NodeJS.ReadWriteStream;
+	result: LintResultStreamFunction<GulpESLintResult>;
 
 	/**
 	 * Handle all ESLint results at the end of the stream.
@@ -93,7 +114,7 @@ declare const gulpESLintNew: {
 	 * @param action - A function to handle all ESLint results.
 	 * @returns gulp file stream.
 	 */
-	results(action: GulpESLintAction<GulpESLintResults>): NodeJS.ReadWriteStream;
+	results: LintResultStreamFunction<GulpESLintResults>;
 
 	/**
 	 * Fail when an ESLint error is found in an ESLint result.
@@ -112,33 +133,40 @@ declare const gulpESLintNew: {
 	/**
 	 * Format the results of each file individually.
 	 *
-	 * @param formatter
+	 * @param formatter -
 	 * A name or path of a formatter, a formatter object or a formatter function.
 	 * Defaults to the [stylish](https://eslint.org/docs/user-guide/formatters/#stylish) formatter.
-	 * @param writer
+	 * @param writer -
 	 * A funtion or stream to write the formatted ESLint results.
 	 * Defaults to gulp's [fancy-log](https://github.com/gulpjs/fancy-log#readme).
 	 * @returns gulp file stream.
 	 */
 	formatEach(
-		formatter?: string | ESLint.Formatter | ESLint.Formatter['format'],
+		formatter?: string | ESLint.Formatter | FormatterFunction,
 		writer?: GulpESLintWriter | NodeJS.WritableStream
 	): NodeJS.ReadWriteStream;
 
 	/**
 	 * Wait until all files have been linted and format all results at once.
 	 *
-	 * @param formatter
+	 * @param formatter -
 	 * A name or path of a formatter, a formatter object or a formatter function.
 	 * Defaults to the [stylish](https://eslint.org/docs/user-guide/formatters/#stylish) formatter.
-	 * @param writer
+	 * @param writer -
 	 * A funtion or stream to write the formatted ESLint results.
 	 * Defaults to gulp's [fancy-log](https://github.com/gulpjs/fancy-log#readme).
 	 * @returns gulp file stream.
 	 */
 	format(
-		formatter?: string | ESLint.Formatter | ESLint.Formatter['format'],
+		formatter?: string | ESLint.Formatter | FormatterFunction,
 		writer?: GulpESLintWriter | NodeJS.WritableStream
 	): NodeJS.ReadWriteStream;
+
+	/**
+	 * Overwrite source files with the fixed content provided by ESLint if present.
+	 *
+	 * @returns gulp file stream.
+	 */
+	fix(): NodeJS.ReadWriteStream;
 };
 export default gulpESLintNew;

package/index.js

@@ -9,6 +9,7 @@ const {
 	hasOwn,
 	isErrorMessage,
 	migrateOptions,
+	resolveFormatter,
 	resolveWriter,
 	writeResults
 } = require('./util');
@@ -16,14 +17,6 @@ const { ESLint }    = require('eslint');
 const { promisify } = require('util');
 const { dest }      = require('vinyl-fs');
 
-function getESLintInfo(file) {
-	const eslintInfo = file._eslintInfo;
-	if (eslintInfo != null) {
-		return eslintInfo;
-	}
-	throw createPluginError({ fileName: file.path, message: 'ESLint information not available' });
-}
-
 function wrapAction(action) {
 	if (typeof action !== 'function') {
 		throw TypeError('Argument is not a function');
@@ -34,6 +27,52 @@ function wrapAction(action) {
 	return action;
 }
 
+const createResultStream = action => {
+	action = wrapAction(action);
+	return createTransform(
+		async file => {
+			const { eslint } = file;
+			if (eslint) {
+				await action(eslint);
+			}
+		}
+	);
+};
+
+const createResultsStream = action => {
+	action = wrapAction(action);
+	const results = [];
+	results.errorCount          = 0;
+	results.warningCount        = 0;
+	results.fixableErrorCount   = 0;
+	results.fixableWarningCount = 0;
+	results.fatalErrorCount     = 0;
+	return createTransform(
+		({ eslint }) => {
+			if (eslint) {
+				results.push(eslint);
+				// Collect total error/warning count.
+				results.errorCount          += eslint.errorCount;
+				results.warningCount        += eslint.warningCount;
+				results.fixableErrorCount   += eslint.fixableErrorCount;
+				results.fixableWarningCount += eslint.fixableWarningCount;
+				results.fatalErrorCount     += eslint.fatalErrorCount;
+			}
+		},
+		async () => {
+			await action(results);
+		}
+	);
+};
+
+function getESLintInfo(file) {
+	const eslintInfo = file._eslintInfo;
+	if (eslintInfo != null) {
+		return eslintInfo;
+	}
+	throw createPluginError({ fileName: file.path, message: 'ESLint information not available' });
+}
+
 async function lintFile(eslintInfo, file, quiet, warnIgnored) {
 	if (file.isNull()) {
 		return;
@@ -83,45 +122,11 @@ module.exports = exports = options => {
 	return createTransform(file => lintFile(eslintInfo, file, quiet, warnIgnored));
 };
 
-exports.result = action => {
-	action = wrapAction(action);
-	return createTransform(
-		async file => {
-			const { eslint } = file;
-			if (eslint) {
-				await action(eslint);
-			}
-		}
-	);
-};
+exports.result = createResultStream;
 
-exports.results = action => {
-	action = wrapAction(action);
-	const results = [];
-	results.errorCount          = 0;
-	results.warningCount        = 0;
-	results.fixableErrorCount   = 0;
-	results.fixableWarningCount = 0;
-	results.fatalErrorCount     = 0;
-	return createTransform(
-		({ eslint }) => {
-			if (eslint) {
-				results.push(eslint);
-				// Collect total error/warning count.
-				results.errorCount          += eslint.errorCount;
-				results.warningCount        += eslint.warningCount;
-				results.fixableErrorCount   += eslint.fixableErrorCount;
-				results.fixableWarningCount += eslint.fixableWarningCount;
-				results.fatalErrorCount     += eslint.fatalErrorCount;
-			}
-		},
-		async () => {
-			await action(results);
-		}
-	);
-};
+exports.results = createResultsStream;
 
-exports.failOnError = () => exports.result(result => {
+function failOnErrorAction(result) {
 	const { messages } = result;
 	if (messages) {
 		const error = messages.find(isErrorMessage);
@@ -134,30 +139,46 @@ exports.failOnError = () => exports.result(result => {
 			});
 		}
 	}
-});
+}
 
-exports.failAfterError = () => exports.results(({ errorCount }) => {
+exports.failOnError = () => createResultStream(failOnErrorAction);
+
+function failAfterErrorAction({ errorCount }) {
 	if (errorCount) {
 		throw createPluginError({
 			name: 'ESLintError',
 			message: `Failed with ${errorCount} ${errorCount === 1 ? 'error' : 'errors'}`
 		});
 	}
-});
+}
+
+exports.failAfterError = () => createResultsStream(failAfterErrorAction);
 
 exports.formatEach = (formatter, writer) => {
 	writer = resolveWriter(writer);
+	const eslintToFormatterMap = new Map();
 	return createTransform(
 		async file => {
-			const { eslint } = file;
-			if (eslint) {
+			const result = file.eslint;
+			if (result) {
 				const eslintInfo = getESLintInfo(file);
-				await writeResults([eslint], eslintInfo, formatter, writer);
+				const { eslint } = eslintInfo;
+				let formatterObj = eslintToFormatterMap.get(eslint);
+				if (!formatterObj) {
+					formatterObj = await resolveFormatter(eslintInfo, formatter);
+					eslintToFormatterMap.set(eslint, formatterObj);
+				}
+				await writeResults([result], formatterObj, writer);
 			}
 		}
 	);
 };
 
+const ERROR_MULTIPLE_ESLINT_INSTANCES = {
+	name: 'ESLintError',
+	message: 'The files in the stream were not processed by the same instance of ESLint'
+};
+
 exports.format = (formatter, writer) => {
 	writer = resolveWriter(writer);
 	const results = [];
@@ -171,11 +192,7 @@ exports.format = (formatter, writer) => {
 					commonInfo = eslintInfo;
 				} else {
 					if (eslintInfo !== commonInfo) {
-						throw createPluginError({
-							name: 'ESLintError',
-							message: 'The files in the stream were not processed by the same '
-								+ 'instance of ESLint'
-						});
+						throw createPluginError(ERROR_MULTIPLE_ESLINT_INSTANCES);
 					}
 				}
 				results.push(eslint);
@@ -183,7 +200,8 @@ exports.format = (formatter, writer) => {
 		},
 		async () => {
 			if (results.length) {
-				await writeResults(results, commonInfo, formatter, writer);
+				const formatterObj = await resolveFormatter(commonInfo, formatter);
+				await writeResults(results, formatterObj, writer);
 			}
 		}
 	);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gulp-eslint-new",
-	"version": "1.3.0",
+	"version": "1.4.2",
 	"description": "A gulp plugin to lint code with ESLint 8",
 	"keywords": [
 		"gulpplugin",
@@ -35,25 +35,27 @@
 		"build": "npm install && gulp",
 		"coverage": "c8 --reporter=html --reporter=text-summary npm test",
 		"lint": "eslint .",
-		"test": "mocha --check-leaks test/*.spec.js"
+		"test": "mocha --check-leaks test/*.spec.js",
+		"ts-test": "tsc --noEmit --strict test/ts-defs-test.ts"
 	},
 	"dependencies": {
 		"@types/eslint": "^8.4.1",
-		"@types/node": "^17.0.15",
-		"eslint": "^8.8.0",
+		"@types/node": "^17.0.21",
+		"eslint": "^8.10.0",
 		"fancy-log": "^2.0.0",
 		"plugin-error": "^1.0.1",
 		"ternary-stream": "^3.0.0",
 		"vinyl-fs": "^3.0.3"
 	},
 	"devDependencies": {
-		"@typescript-eslint/eslint-plugin": "^5.10.2",
-		"@typescript-eslint/parser": "^5.10.2",
+		"@typescript-eslint/eslint-plugin": "^5.12.1",
+		"@typescript-eslint/parser": "^5.12.1",
 		"c8": "^7.11.0",
 		"eslint-plugin-eslint-comments": "^3.2.0",
+		"eslint-plugin-tsdoc": "^0.2.14",
 		"gulp": "^4.0.2",
-		"mocha": "^9.1.4",
-		"typescript": "^4.5.4",
+		"mocha": "^9.2.1",
+		"typescript": "^4.5.5",
 		"vinyl": "^2.2.1"
 	},
 	"engines": {

package/util.js

@@ -1,13 +1,12 @@
 'use strict';
 
 /**
- * @typedef {import('eslint').ESLint}             ESLint
- * @typedef {import('eslint').ESLint.Formatter}   ESLint.Formatter
- * @typedef {import('eslint').ESLint.LintResult}  ESLint.LintResult
- * @typedef {ESLint.Formatter['format']}          FormatterFunction
- * @typedef {import('.').GulpESLintWriter}        GulpESLintWriter
- * @typedef {import('eslint').Linter}             Linter
- * @typedef {import('eslint').Linter.LintMessage} Linter.LintMessage
+ * @typedef {import('eslint').ESLint}                 ESLint
+ * @typedef {import('eslint').ESLint.Formatter}       ESLint.Formatter
+ * @typedef {import('eslint').ESLint.LintResult}      ESLint.LintResult
+ * @typedef {import('.').GulpESLintWriter}            GulpESLintWriter
+ * @typedef {import('eslint').Linter}                 Linter
+ * @typedef {import('eslint').Linter.LintMessage}     Linter.LintMessage
  */
 
 const fancyLog      = require('fancy-log');
@@ -71,7 +70,7 @@ function isWarningMessage({ severity }) {
  * @param {{ cwd: string, eslint: ESLint }} eslintInfo
  * Current directory and instance of ESLint used to load and configure the formatter.
  *
- * @param {string|ESLint.Formatter|FormatterFunction} [formatter]
+ * @param {string|ESLint.Formatter|Function} [formatter]
  * A name or path of a formatter, a formatter object or a formatter function.
  *
  * @returns {Promise<ESLint.Formatter>} An ESLint formatter.
@@ -286,9 +285,9 @@ function throwInvalidOptionError(message) {
 /**
  * Convert a string array to a boolean map.
  *
- * @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.
+ * @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.
  * @returns {Record<string,boolean>} The boolean map.
  */
 function toBooleanMap(keys, defaultValue, displayName) {
@@ -357,6 +356,7 @@ exports.migrateOptions = (options = { }) => {
 		}
 	}
 	migrateOption('envs', 'env', envs => toBooleanMap(envs, true, 'envs'));
+	migrateOption('extends');
 	migrateOption('globals', undefined, globals => toBooleanMap(globals, false, 'globals'));
 	migrateOption('ignorePattern', 'ignorePatterns');
 	migrateOption('parser');
@@ -395,17 +395,13 @@ exports.resolveWriter = (writer = fancyLog) => {
  * @param {ESLint.LintResult[]} results
  * A list of ESLint results.
  *
- * @param {{ cwd: string, eslint: ESLint }} eslintInfo
- * Current directory and instance of ESLint used to load and configure the formatter.
- *
- * @param {string|ESLint.Formatter|FormatterFunction} [formatter]
- * A name or path of a formatter, a formatter object or a formatter function.
+ * @param {ESLint.Formatter} formatterObj
+ * A formatter object.
  *
  * @param {GulpESLintWriter} [writer]
  * A function used to write formatted ESLint messages.
  */
-exports.writeResults = async (results, eslintInfo, formatter, writer) => {
-	const formatterObj = await resolveFormatter(eslintInfo, formatter);
+exports.writeResults = async (results, formatterObj, writer) => {
 	const message = await formatterObj.format(results);
 	if (writer && message != null && message !== '') {
 		await writer(message);