functions/partials/neostandardLint.mjsjavascript
import fs from 'node:fs'
import path from 'node:path'
import through from 'through2'
import { ESLint } from 'eslint'
import { importModule } from './loadPeer.mjs'
// neostandard (js-build-tools' chosen style - a maintained, TypeScript-aware successor to `standard`, see
// https://github.com/neostandard/neostandard) ships ESM-only, see importModule for how it is imported.
const importNeostandard = () => importModule('neostandard')
/**
* Read the `env` a project already declared for Standard (the `standard` field in its package.json), so a project
* migrating from `standard` keeps its globals (jest, browser, ...) without touching package.json.
* @param {string} cwd
* @returns {Array<string>}
* @private
*/
const readEnv = cwd => {
try {
return JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')).standard?.env ?? []
} catch {
return []
}
}
/**
* Build an ESLint instance configured with neostandard, honoring the project's own package.json `standard.env`,
* plus an optional layer of rule overrides (see gulp.config.mjs's `lint.rules`) for a rule that is wrong for this
* project specifically rather than something to fix in its code - for example a test fixture whose content
* neostandard mistakes for a real syntax problem. Scoped to the same files neostandard itself lints (its own
* `defaultFilePatterns.all`), per neostandard's own guidance: an unscoped rule-tweak layer would otherwise apply
* to every lintable file, including ones from an unrelated plugin this project never defined.
* @param {Object} options
* @param {string} options.cwd
* @param {boolean} options.ts
* @param {boolean} options.fix
* @param {Object<string, *>} [options.rules={}]
* @returns {Promise<ESLint>} eslint's ESLint instance
* @private
*/
const buildEslint = async ({ cwd, ts, fix, rules = {} }) => {
const { neostandard, defaultFilePatterns } = await importNeostandard()
const baseConfig = neostandard({ ts, env: readEnv(cwd) })
if (Object.keys(rules).length) {
baseConfig.push({ files: defaultFilePatterns.all, rules })
}
return new ESLint({
cwd,
fix,
overrideConfigFile: true,
baseConfig
})
}
/**
* Print a file's lint messages, if it has any.
* @memberOf module:partials
* @param {Vinyl} file
* @param {{messages: Array<{line: number, column: number, message: string}>, errorCount: number, warningCount: number}} result
* @returns {undefined}
*/
const printFileReport = (file, result) => {
if (!result.messages.length) {
return
}
console.log(path.relative(file.cwd, file.path))
result.messages.forEach(({ line, column, message }) => console.log(`line ${line}:${column}\t${message}`))
console.log(`✖ ${result.errorCount} error\t⚠ ${result.warningCount} warning\n`)
}
/**
* Lint every file streaming through with neostandard and, unless `fix` is false, apply the automatic fixes to the
* file's contents so a following `dest()` writes the fixed version. Remaining problems are printed along with a
* summary once the stream ends; they only fail the stream when `failOnError` is set (the standalone `lint` task),
* never during `build`.
*
* One ESLint instance is built from the first file's own cwd and reused for the rest of the stream, since every
* file in a given lint pass shares the same project (and so the same config).
* @memberOf module:partials
* @param {Object} [options={}]
* @param {boolean} [options.fix=true] - Apply neostandard's automatic fixes to the file contents.
* @param {boolean} [options.ts=false] - Lint `.ts` files too, with type-aware rules (see neostandard's `ts` option).
* @param {Object<string, *>} [options.rules={}] - ESLint rule overrides layered on top of neostandard's own rules
* (see gulp.config.mjs's `lint.rules`).
* @param {boolean} [options.failOnError=false] - Emit an error once the stream ends if any lint errors remain after
* fixing, so a command-line run exits non-zero.
* @param {function(Object): Promise<{lintText: Function}>} [loadEslint] - Resolves an ESLint-shaped linter. Real
* callers should never need to pass this - it exists so tests can supply a stand-in, since this project's
* CommonJS-transform-based Jest setup cannot execute a real dynamic import() of neostandard (ESM-only).
* @returns {stream.Transform} With a `totals` property ({errors, warnings}), complete once the stream ends.
*/
export const neostandardLint = (
{ fix = true, ts = false, rules = {}, failOnError = false } = {},
loadEslint = buildEslint
) => {
const totals = { errors: 0, warnings: 0 }
let eslintPromise = null
const linter = through.obj(
function (file, enc, callback) {
if (file.isNull()) {
callback(null, file)
return
}
if (file.isStream()) {
callback(new Error('neostandardLint: streaming file contents are not supported.'))
return
}
if (!eslintPromise) {
eslintPromise = loadEslint({ cwd: file.cwd, ts, fix, rules })
}
eslintPromise
.then(eslint => eslint.lintText(file.contents.toString(), { filePath: file.path }))
.then(results => {
// No result at all means the file is ignored by the project's ESLint configuration.
const [result] = results
if (result) {
if (typeof result.output === 'string') {
file.contents = Buffer.from(result.output)
}
totals.errors += result.errorCount
totals.warnings += result.warningCount
printFileReport(file, result)
}
callback(null, file)
}, callback)
},
function (callback) {
console.log('neostandard linter results')
console.log('======================================')
console.log(`✖ Errors total: ${totals.errors}`)
console.log(`⚠ Warnings total: ${totals.warnings}\n`)
if (failOnError && totals.errors) {
callback(new Error(`neostandard found ${totals.errors} lint error(s) that could not be fixed automatically.`))
return
}
callback()
}
)
// Read by lintSource, which can only fail once the fixed files have been written, after this stream has ended.
linter.totals = totals
return linter
}