gulp-eslint-new 1.2.0 → 1.3.0

package/README.md

@@ -208,11 +208,11 @@ gulp.src(['**/*.js', '!node_modules/**'])
     }));
 ```
 
-Type: `(result: Object, callback: Function) => void`
+Param Type: `(result: Object, callback: Function) => void`
 
 Call an asynchronous, Node-style callback-based function for each ESLint file result. The callback must be called for the stream to finish. If an error is passed to the callback, it will be wrapped in a gulp `PluginError` and emitted from the stream.
 
-Type: `(result: Object) => Promise<void>`
+Param Type: `(result: Object) => Promise<void>`
 
 Call an asynchronous, promise-based function for each ESLint file result. If the promise is rejected, the rejection reason will be wrapped in a gulp `PluginError` and emitted from the stream.
 
@@ -292,16 +292,18 @@ gulp.src(['**/*.js', '!node_modules/**'])
     .pipe(gulpESLintNew.failAfterError());
 ```
 
-### `gulpESLintNew.format(formatter, output)`
+### `gulpESLintNew.format(formatter, writer)`
 
 Format all linted files once.
 This should be used in the stream after piping through `gulpESLintNew`; otherwise, this will find no ESLint results to format.
 
-The `formatter` argument may be a `string`, `Function`, or `undefined`.
-As a `string`, a formatter module by that name or path will be resolved.
-The resolved formatter will be either one of the [built-in ESLint formatters](https://eslint.org/docs/user-guide/formatters/#eslint-formatters), or a formatter exported by a module with the specied path (located relative to the ESLint working directory), or a formatter exported by a package installed as a dependency (the prefix "eslint-formatter-" in the package name can be omitted).
-If `undefined`, the ESLint "stylish" formatter will be resolved.
-A `Function` will be called with an `Array` of file linting results to format.
+`formatter` param type: `string | Object | Function | undefined`
+
+The `formatter` argument determines the [ESLint formatter](https://eslint.org/docs/user-guide/formatters/) used to format linting results.
+If a `string` is provided, a formatter module by that name or path will be resolved.
+The resolved formatter will be either one of the built-in ESLint formatters, or a formatter exported by a module with the specified path (located relative to the ESLint working directory), or a formatter exported by a package installed as a dependency (the prefix "eslint-formatter-" in the package name can be omitted).
+Instead of providing a string, it is also possible to specify a formatter object as resolved by the ESLint method [`loadFormatter`](https://eslint.org/docs/developer-guide/nodejs-api#-eslintloadformatternameorpath), or a formatter function directly.
+If `undefined` is specified, the ESLint "stylish" formatter will be used.
 
 ```javascript
 // Use the default "stylish" ESLint formatter.
@@ -315,9 +317,12 @@ gulpESLintNew.format('checkstyle')
 gulpESLintNew.format('pretty')
 ```
 
-The `output` argument may be a writable stream, `Function`, or `undefined`. As a writable stream, the formatter results will be written to the stream.
-If `undefined`, the formatter results will be written to [gulp's log](https://github.com/gulpjs/fancy-log#logmsg).
-A `Function` will be called with the formatter results as the only parameter.
+`writer` param type: `NodeJS.WritableStream | Function | undefined`
+
+The `writer` argument may be a writable stream, `Function`, or `undefined`.
+As a writable stream, the formatter output will be written to the stream.
+If `undefined`, the formatter output will be written to [gulp's log](https://github.com/gulpjs/fancy-log#logmsg).
+A `Function` will be called with the formatter output as the only parameter.
 
 ```javascript
 // write to gulp's log (default)
@@ -327,7 +332,7 @@ gulpESLintNew.format()
 gulpESLintNew.format('junit', process.stdout)
 ```
 
-### `gulpESLintNew.formatEach(formatter, output)`
+### `gulpESLintNew.formatEach(formatter, writer)`
 
 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.
@@ -338,7 +343,7 @@ The arguments for `formatEach` are the same as the arguments for `format`.
 
 Overwrite files with the fixed content provided by ESLint.
 This should be used in conjunction with the option `fix` in [`gulpESLintNew(options)`](#gulpeslintnewoptions).
-Files without a fixed content will be ignored.
+Files without a fix and files that were not processed by ESLint will be left untouched.
 
 ```javascript
 gulp.src(['**/*.js', '!node_modules/**'])

package/index.d.ts

@@ -3,7 +3,7 @@ import                            'node';
 import { TransformCallback } from 'stream';
 
 export type GulpESLintAction<Type>
-	= ((value: Type, callback: TransformCallback) => void) | ((value: Type) => Promise<void>);
+	= ((value: Type, callback: TransformCallback) => unknown) | ((value: Type) => Promise<unknown>);
 
 export type GulpESLintOptions =
 	Omit<
@@ -60,7 +60,9 @@ export type GulpESLintResults =
 		fixableWarningCount: number;
 	};
 
-declare const gulpESLint: {
+export type GulpESLintWriter = (str: string) => unknown | Promise<unknown>;
+
+declare const gulpESLintNew: {
 	/**
 	 * Append ESLint result to each file.
 	 *
@@ -111,32 +113,32 @@ declare const gulpESLint: {
 	 * Format the results of each file individually.
 	 *
 	 * @param formatter
-	 * The name or function for an ESLint result 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 writable
+	 * @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['format'],
-		writable?: ((str: string) => void) | NodeJS.WritableStream
+		formatter?: string | ESLint.Formatter | ESLint.Formatter['format'],
+		writer?: GulpESLintWriter | NodeJS.WritableStream
 	): NodeJS.ReadWriteStream;
 
 	/**
 	 * Wait until all files have been linted and format all results at once.
 	 *
 	 * @param formatter
-	 * The name or function for an ESLint result 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 writable
+	 * @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['format'],
-		writable?: ((str: string) => void) | NodeJS.WritableStream
+		formatter?: string | ESLint.Formatter | ESLint.Formatter['format'],
+		writer?: GulpESLintWriter | NodeJS.WritableStream
 	): NodeJS.ReadWriteStream;
 };
-export default gulpESLint;
+export default gulpESLintNew;

package/index.js

@@ -9,7 +9,7 @@ const {
 	hasOwn,
 	isErrorMessage,
 	migrateOptions,
-	resolveWritable,
+	resolveWriter,
 	writeResults
 } = require('./util');
 const { ESLint }    = require('eslint');
@@ -145,21 +145,21 @@ exports.failAfterError = () => exports.results(({ errorCount }) => {
 	}
 });
 
-exports.formatEach = (formatter, writable) => {
-	writable = resolveWritable(writable);
+exports.formatEach = (formatter, writer) => {
+	writer = resolveWriter(writer);
 	return createTransform(
 		async file => {
 			const { eslint } = file;
 			if (eslint) {
 				const eslintInfo = getESLintInfo(file);
-				await writeResults([eslint], eslintInfo, formatter, writable);
+				await writeResults([eslint], eslintInfo, formatter, writer);
 			}
 		}
 	);
 };
 
-exports.format = (formatter, writable) => {
-	writable = resolveWritable(writable);
+exports.format = (formatter, writer) => {
+	writer = resolveWriter(writer);
 	const results = [];
 	let commonInfo;
 	return createTransform(
@@ -183,7 +183,7 @@ exports.format = (formatter, writable) => {
 		},
 		async () => {
 			if (results.length) {
-				await writeResults(results, commonInfo, formatter, writable);
+				await writeResults(results, commonInfo, formatter, writer);
 			}
 		}
 	);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gulp-eslint-new",
-	"version": "1.2.0",
+	"version": "1.3.0",
 	"description": "A gulp plugin to lint code with ESLint 8",
 	"keywords": [
 		"gulpplugin",
@@ -39,7 +39,7 @@
 	},
 	"dependencies": {
 		"@types/eslint": "^8.4.1",
-		"@types/node": "^17.0.13",
+		"@types/node": "^17.0.15",
 		"eslint": "^8.8.0",
 		"fancy-log": "^2.0.0",
 		"plugin-error": "^1.0.1",
@@ -47,8 +47,8 @@
 		"vinyl-fs": "^3.0.3"
 	},
 	"devDependencies": {
-		"@typescript-eslint/eslint-plugin": "^5.10.0",
-		"@typescript-eslint/parser": "^5.10.0",
+		"@typescript-eslint/eslint-plugin": "^5.10.2",
+		"@typescript-eslint/parser": "^5.10.2",
 		"c8": "^7.11.0",
 		"eslint-plugin-eslint-comments": "^3.2.0",
 		"gulp": "^4.0.2",

package/util.js

@@ -1,5 +1,15 @@
 '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
+ */
+
 const fancyLog      = require('fancy-log');
 const { relative }  = require('path');
 const PluginError   = require('plugin-error');
@@ -41,6 +51,8 @@ function isErrorMessage({ severity }) {
 	return severity > 1;
 }
 
+const isObject = value => Object(value) === value;
+
 /**
  * Determine if a message is a warning.
  *
@@ -52,19 +64,22 @@ function isWarningMessage({ severity }) {
 }
 
 /**
- * Resolve formatter from string.
- * If a function is specified, it will be treated as an ESLint 6 style formatter function and
- * wrapped into an object appropriately.
+ * Resolve a formatter from a string.
+ * If a function is specified, it will be treated as a formatter function and wrapped in an object
+ * appropriately.
  *
  * @param {{ cwd: string, eslint: ESLint }} eslintInfo
  * Current directory and instance of ESLint used to load and configure the formatter.
  *
- * @param {string|Function} [formatter]
- * A name or path of a formatter, or an ESLint 6 style formatter function to resolve as a formatter.
+ * @param {string|ESLint.Formatter|FormatterFunction} [formatter]
+ * A name or path of a formatter, a formatter object or a formatter function.
  *
  * @returns {Promise<ESLint.Formatter>} An ESLint formatter.
  */
 function resolveFormatter({ cwd, eslint }, formatter) {
+	if (isObject(formatter) && typeof formatter.format === 'function') {
+		return formatter;
+	}
 	if (typeof formatter === 'function') {
 		return {
 			format: results => {
@@ -142,7 +157,7 @@ async function awaitHandler(handler, data, done) {
 /**
  * Create a transform stream in object mode from synchronous or asynchronous handler functions.
  * All files are passed through the stream.
- * Errors thrown by the handlers will be wrapped inside a `PluginError` and emitted from the stream.
+ * Errors thrown by the handlers will be wrapped in a `PluginError` and emitted from the stream.
  *
  * @param {Function} handleFile
  * A function that is called for each file, with the file object as the only parameter.
@@ -153,7 +168,7 @@ async function awaitHandler(handler, data, done) {
  * A function that is called with no parameters before closing the stream.
  * If the function returns a promise, the stream will be closed after the promise is resolved.
  *
- * @returns {Stream} A transform stream.
+ * @returns {Transform} A transform stream.
  */
 exports.createTransform = (handleFile, handleFinal) => {
 	const transform = (file, enc, done) => void awaitHandler(() => handleFile(file), file, done);
@@ -358,22 +373,24 @@ exports.migrateOptions = (options = { }) => {
 exports.resolveFormatter = resolveFormatter;
 
 /**
- * Resolve writable.
+ * Resolve a writer function used to write formatted ESLint messages.
  *
- * @param {Function|Stream} [writable=fancyLog]
+ * @param {GulpESLintWriter|NodeJS.WritableStream} [writer=fancyLog]
  * A stream or function to resolve as a format writer.
- * @returns {Function} A function that writes formatted messages.
+ * @returns {GulpESLintWriter} A function that writes formatted messages.
  */
-exports.resolveWritable = (writable = fancyLog) => {
-	const { write } = writable;
-	if (typeof write === 'function') {
-		writable = write.bind(writable);
+exports.resolveWriter = (writer = fancyLog) => {
+	if (isObject(writer)) {
+		const { write } = writer;
+		if (typeof write === 'function') {
+			writer = write.bind(writer);
+		}
 	}
-	return writable;
+	return writer;
 };
 
 /**
- * Write formatter results to writable/output.
+ * Write formatted ESLint messages.
  *
  * @param {ESLint.LintResult[]} results
  * A list of ESLint results.
@@ -381,16 +398,16 @@ exports.resolveWritable = (writable = fancyLog) => {
  * @param {{ cwd: string, eslint: ESLint }} eslintInfo
  * Current directory and instance of ESLint used to load and configure the formatter.
  *
- * @param {string|Function} [formatter]
- * A name or path of a formatter, or an ESLint 6 style formatter function to resolve as a formatter.
+ * @param {string|ESLint.Formatter|FormatterFunction} [formatter]
+ * A name or path of a formatter, a formatter object or a formatter function.
  *
- * @param {Function} [writable]
- * A function used to write formatted ESLint results.
+ * @param {GulpESLintWriter} [writer]
+ * A function used to write formatted ESLint messages.
  */
-exports.writeResults = async (results, eslintInfo, formatter, writable) => {
+exports.writeResults = async (results, eslintInfo, formatter, writer) => {
 	const formatterObj = await resolveFormatter(eslintInfo, formatter);
 	const message = await formatterObj.format(results);
-	if (writable && message != null && message !== '') {
-		writable(message);
+	if (writer && message != null && message !== '') {
+		await writer(message);
 	}
 };