js-build-tools 5.6.0 → 6.0.0

package/dist/utilities/esmNamedExportsToCjs.js

@@ -0,0 +1,33 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.esmNamedExportsToCjs = void 0;
+/**
+ * Rewrites named `export const`/`export function`/`export class` declarations to plain declarations plus a
+ * trailing `module.exports = { ... }` - the same shape jsdoc-to-markdown already documents cleanly (a plain
+ * declaration with its own `@memberOf` tag, exported all at once at the bottom), rather than the "exports.name"
+ * longname jsdoc-to-markdown's own ESM-compat layer produces for an inline `export const name = ...`.
+ *
+ * This is a narrow, text-level rewrite for documentation purposes only - it does not execute the module, so it
+ * only has to look enough like the real thing for jsdoc-to-markdown's parser. It handles the common named-export
+ * forms (`export const`, `export function`, `export class`) and leaves everything else (including `export
+ * default`, re-exports, and `export { a, b }` lists) untouched in place - a file using one of those keeps its
+ * own export line as-is, which jsdoc-to-markdown will document however it already does for ESM.
+ * @memberOf module:utilities
+ * @param {string} source - The raw ESM source text (never executed, just rewritten as text).
+ * @returns {string} The rewritten text, safe to write out with a `.js` extension for jsdoc-to-markdown to read.
+ */
+const esmNamedExportsToCjs = source => {
+  const exportedNames = [];
+  const rewritten = source.replace(/^export (const|function|class) (\w+)/gm, (match, keyword, name) => {
+    exportedNames.push(name);
+    return `${keyword} ${name}`;
+  });
+  if (exportedNames.length === 0) {
+    return rewritten;
+  }
+  return `${rewritten}\n\nmodule.exports = { ${exportedNames.join(', ')} }\n`;
+};
+exports.esmNamedExportsToCjs = esmNamedExportsToCjs;

package/dist/utilities/getBundleConfigs.js

@@ -1,14 +1,14 @@
-"use strict";
-
-require("core-js/modules/esnext.weak-map.delete-all.js");
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.getBundleConfigs = void 0;
-require("core-js/modules/esnext.iterator.constructor.js");
-require("core-js/modules/esnext.iterator.map.js");
-var gulpConfig = _interopRequireWildcard(require("../../gulp.config.js"));
-function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+"use strict";
+
+require("core-js/modules/esnext.weak-map.delete-all.js");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getBundleConfigs = void 0;
+require("core-js/modules/esnext.iterator.constructor.js");
+require("core-js/modules/esnext.iterator.map.js");
+var gulpConfig = _interopRequireWildcard(require("../../gulp.config.js"));
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 /**
  * Build the full list of bundles to produce for this project: the primary bundle (browser.name /
  * dist.main / browser.ignore / browser.exclude, exactly as before browser.bundles existed) plus
@@ -17,20 +17,20 @@ function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r
  * specify what's actually different about it.
  * @memberOf module:utilities
  * @returns {Array<{name: string, main: string, ignore: Array, exclude: Array}>}
- */
-const getBundleConfigs = () => {
-  const primary = {
-    name: gulpConfig.get('browser.name'),
-    main: gulpConfig.get('dist.main'),
-    ignore: gulpConfig.get('browser.ignore'),
-    exclude: gulpConfig.get('browser.exclude')
-  };
-  const additional = gulpConfig.get('browser.bundles') || [];
-  return [primary, ...additional.map(bundleConfig => ({
-    name: bundleConfig.name,
-    main: bundleConfig.main || primary.main,
-    ignore: bundleConfig.ignore || primary.ignore,
-    exclude: bundleConfig.exclude || primary.exclude
-  }))];
-};
+ */
+const getBundleConfigs = () => {
+  const primary = {
+    name: gulpConfig.get('browser.name'),
+    main: gulpConfig.get('dist.main'),
+    ignore: gulpConfig.get('browser.ignore'),
+    exclude: gulpConfig.get('browser.exclude')
+  };
+  const additional = gulpConfig.get('browser.bundles') || [];
+  return [primary, ...additional.map(bundleConfig => ({
+    name: bundleConfig.name,
+    main: bundleConfig.main || primary.main,
+    ignore: bundleConfig.ignore || primary.ignore,
+    exclude: bundleConfig.exclude || primary.exclude
+  }))];
+};
 exports.getBundleConfigs = getBundleConfigs;

package/dist/watchFull.js

@@ -1,14 +1,14 @@
-'use strict'
+"use strict";
 
-Object.defineProperty(exports, '__esModule', {
+Object.defineProperty(exports, "__esModule", {
   value: true
-})
-exports.watchFull = void 0
-const _partials = require('./partials.js')
+});
+exports.watchFull = void 0;
+var _partials = require("./partials.js");
 /**
  * Watch for changes and run the distribution for the changed files, then bundle and test the changed files.
  * @memberOf module:js-build-tools
  * @returns {FSWatcher}
  */
-const watchFull = () => (0, _partials.beginWatcher)().on('change', _partials.runOnChange)
-exports.watchFull = watchFull
+const watchFull = () => (0, _partials.beginWatcher)().on('change', _partials.runOnChange);
+exports.watchFull = watchFull;

package/dist/watchTest.js

@@ -1,14 +1,14 @@
-'use strict'
+"use strict";
 
-require('core-js/modules/esnext.weak-map.delete-all.js')
-Object.defineProperty(exports, '__esModule', {
+require("core-js/modules/esnext.weak-map.delete-all.js");
+Object.defineProperty(exports, "__esModule", {
   value: true
-})
-exports.watchTest = void 0
-const gulpConfig = _interopRequireWildcard(require('../gulp.config.js'))
-const _gulp = require('gulp')
-const _testQuick = require('./testQuick.js')
-function _interopRequireWildcard (e, t) { if (typeof WeakMap === 'function') var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; let o; let i; const f = { __proto__: null, default: e }; if (e === null || typeof e !== 'object' && typeof e !== 'function') return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f) } for (const t in e) t !== 'default' && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f })(e, t) }
+});
+exports.watchTest = void 0;
+var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
+var _gulp = require("gulp");
+var _testQuick = require("./testQuick.js");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 /**
  * Watch for changes and run the tests.
  * @memberOf module:js-build-tools
@@ -16,5 +16,5 @@ function _interopRequireWildcard (e, t) { if (typeof WeakMap === 'function') var
  */
 const watchTest = () => (0, _gulp.watch)(gulpConfig.get('test.watch'), {
   ignoreInitial: false
-}, _testQuick.testQuick)
-exports.watchTest = watchTest
+}, _testQuick.testQuick);
+exports.watchTest = watchTest;

package/functions/build.mjs

@@ -1,11 +1,10 @@
 import { bundle } from './bundle.mjs'
-import { bundleLint } from './bundleLint.mjs'
 import { bundleMinify } from './bundleMinify.mjs'
 import { clean, distSeries } from './partials.mjs'
 import { compileReadme } from './compileReadme.mjs'
 import { typeDocs } from './typeDocs.mjs'
-import { distLint } from './distLint.mjs'
 import { distMinify } from './distMinify.mjs'
+import { sourceLint } from './sourceLint.mjs'
 import { parallel, series } from 'gulp'
 import * as gulpConfig from '../gulp.config.mjs'
 import { copyFonts } from './copyFonts.mjs'
@@ -15,14 +14,13 @@ import { testFull } from './testFull.mjs'
 
 /**
  * Runs several processes to build and validate the project.
- * Cleans, distributes (lint and minify), bundles (lint and minify), creates the readme, then runs the tests.
+ * Cleans and lints the source, distributes and minifies, bundles and minifies, creates the readme, then runs the
+ * tests.
  * @memberOf module:js-build-tools
  * @returns {stream.Stream}
  */
 export const build = (done = null) => {
-  const distLintMinify = parallel(distLint, distMinify)
-  const bundleLintMinify = parallel(bundleLint, bundleMinify)
-  const buildActions = [distSeries(), distLintMinify]
+  const buildActions = [distSeries(), distMinify]
   const generateDocs = gulpConfig.get('docs.enabled')
   if (generateDocs) {
     // The documentation is generated from the TypeScript source itself, the readme is written by hand
@@ -34,7 +32,7 @@ export const build = (done = null) => {
   if (gulpConfig.get('browser.enabled')) {
     // If not 'nodeOnly' then we also want to bundle for browser after we complete the dist directory
     buildActions.push(bundle)
-    buildActions.push(bundleLintMinify)
+    buildActions.push(bundleMinify)
   }
   const runActions = [
     series(...buildActions),
@@ -58,8 +56,11 @@ export const build = (done = null) => {
   }
   // clean has to finish before anything writes into the output folders - images, fonts and sass all write into
   // browser/, so running clean in parallel with them races (ENOTEMPTY errors from clean, or output deleted mid-write).
+  // sourceLint fixes the real source in place before anything compiles from it (distSeries, tsFor inside it), so a
+  // build never reads a mix of pre- and post-fix content; clean only touches dist/browser output, so the two can
+  // run alongside each other.
   return series(
-    clean,
+    parallel(clean, sourceLint),
     parallel(...runActions)
   )(done)
 }

package/functions/build.test.mjs

@@ -6,8 +6,8 @@ import { testFull } from './testFull.mjs'
 import { typeDocs } from './typeDocs.mjs'
 import { countMatches } from 'test-filesystem'
 
-// Run the real Standard (in a subprocess) - Jest's CommonJS transform can't load the ESM-only package itself.
-jest.mock('./partials/standardLint.mjs', () => require('./test-helpers/standardLintWithRealStandard.mjs'))
+// Run the real neostandard (in a subprocess) - Jest's CommonJS transform can't load the ESM-only package itself.
+jest.mock('./partials/neostandardLint.mjs', () => require('./test-helpers/neostandardLintWithRealNeostandard.mjs'))
 
 setUp.setDefaults('test-build')
 const gulpConfig = setUp.gulpConfig
@@ -266,7 +266,7 @@ beforeEach(
 afterEach(setUp.afterEach)
 
 describe('build', () => {
-  test('when browser.enabled false: calls clean, distSeries, distLint, distMinify, compileReadme, testFull', done => {
+  test('when browser.enabled false: calls clean, sourceLint, distSeries, distMinify, compileReadme, testFull', done => {
     const srcPath = gulpConfig.get('srcPath')
     const sourcesPath = `${srcPath}/sources`
     const distPath = gulpConfig.get('dist.to')
@@ -288,16 +288,15 @@ describe('build', () => {
       // Minify the dist files (distMinify)
       expect(fs.existsSync(`${distPath}/main.min.js`)).toBeTruthy()
       const babelifiedMain = fs.readFileSync(`${distPath}/main.js`).toString()
-      // Used single quotes because of distLint
-      expect(countMatches(babelifiedMain, '\'use strict\'')).toEqual(1)
+      expect(babelifiedMain.includes('use strict')).toBe(true)
 
       expect(fs.existsSync(`${distSourcesPath}/file1.min.js`)).toBeTruthy()
       const babelifiedFile1 = fs.readFileSync(`${distSourcesPath}/file1.js`).toString()
-      expect(countMatches(babelifiedFile1, '\'use strict\'')).toEqual(1)
+      expect(babelifiedFile1.includes('use strict')).toBe(true)
 
       expect(fs.existsSync(`${distSourcesPath}/file2.min.js`)).toBeTruthy()
       const babelifiedFile2 = fs.readFileSync(`${distSourcesPath}/file2.js`).toString()
-      expect(countMatches(babelifiedFile2, '\'use strict\'')).toEqual(1)
+      expect(babelifiedFile2.includes('use strict')).toBe(true)
 
       // Generated README.md (compileReadme)
       const readmeContents = fs.readFileSync(`${readmePath}/${readmeFile}`).toString()
@@ -312,7 +311,7 @@ describe('build', () => {
     })
   }, 30000)
 
-  test('when browser.enabled true: calls clean, distSeries, distLint, distMinify, bundle, bundleLint, bundleMinify, compileReadme, testFull', done => {
+  test('when browser.enabled true: calls clean, sourceLint, distSeries, distMinify, bundle, bundleMinify, compileReadme, testFull', done => {
     const srcPath = gulpConfig.get('srcPath')
     const sourcesPath = `${srcPath}/sources`
     const distPath = gulpConfig.get('dist.to')
@@ -336,8 +335,7 @@ describe('build', () => {
       // Minify the dist files (distMinify)
       expect(fs.existsSync(`${distPath}/main.min.js`)).toBeTruthy()
       const babelifiedMain = fs.readFileSync(`${distPath}/main.js`).toString()
-      // Used single quotes because of distLint
-      expect(countMatches(babelifiedMain, '\'use strict\'')).toEqual(1)
+      expect(babelifiedMain.includes('use strict')).toBe(true)
 
       // Created browser directory (bundle)
       expect(fs.existsSync(browserPath)).toBeTruthy()
@@ -361,7 +359,7 @@ describe('build', () => {
     })
   }, 30000)
 
-  test('when browser.enabled true and fonts.enabled true: calls clean, distSeries, distLint, distMinify, bundle, bundleLint, bundleMinify, compileReadme, testFull, copyFonts', done => {
+  test('when browser.enabled true and fonts.enabled true: calls clean, sourceLint, distSeries, distMinify, bundle, bundleMinify, compileReadme, testFull, copyFonts', done => {
     const srcPath = gulpConfig.get('srcPath')
     const sourcesPath = `${srcPath}/sources`
     const distPath = gulpConfig.get('dist.to')
@@ -388,8 +386,7 @@ describe('build', () => {
       // Minify the dist files (distMinify)
       expect(fs.existsSync(`${distPath}/main.min.js`)).toBeTruthy()
       const babelifiedMain = fs.readFileSync(`${distPath}/main.js`).toString()
-      // Used single quotes because of distLint
-      expect(countMatches(babelifiedMain, '\'use strict\'')).toEqual(1)
+      expect(babelifiedMain.includes('use strict')).toBe(true)
 
       // Created browser directory (bundle)
       expect(fs.existsSync(browserPath)).toBeTruthy()
@@ -419,7 +416,7 @@ describe('build', () => {
     })
   }, 30000)
 
-  test('when browser.enabled true and images.enabled true: calls clean, distSeries, distLint, distMinify, bundle, bundleLint, bundleMinify, compileReadme, testFull, images', done => {
+  test('when browser.enabled true and images.enabled true: calls clean, sourceLint, distSeries, distMinify, bundle, bundleMinify, compileReadme, testFull, images', done => {
     const srcPath = gulpConfig.get('srcPath')
     const sourcesPath = `${srcPath}/sources`
     const distPath = gulpConfig.get('dist.to')
@@ -446,8 +443,7 @@ describe('build', () => {
       // Minify the dist files (distMinify)
       expect(fs.existsSync(`${distPath}/main.min.js`)).toBeTruthy()
       const babelifiedMain = fs.readFileSync(`${distPath}/main.js`).toString()
-      // Used single quotes because of distLint
-      expect(countMatches(babelifiedMain, '\'use strict\'')).toEqual(1)
+      expect(babelifiedMain.includes('use strict')).toBe(true)
 
       // Created browser directory (bundle)
       expect(fs.existsSync(browserPath)).toBeTruthy()
@@ -477,7 +473,7 @@ describe('build', () => {
     })
   }, 30000)
 
-  test('when browser.enabled true and sass.enabled true: calls clean, distSeries, distLint, distMinify, bundle, bundleLint, bundleMinify, compileReadme, testFull, sass', done => {
+  test('when browser.enabled true and sass.enabled true: calls clean, sourceLint, distSeries, distMinify, bundle, bundleMinify, compileReadme, testFull, sass', done => {
     const srcPath = gulpConfig.get('srcPath')
     const sourcesPath = `${srcPath}/sources`
     const distPath = gulpConfig.get('dist.to')
@@ -504,8 +500,7 @@ describe('build', () => {
       // Minify the dist files (distMinify)
       expect(fs.existsSync(`${distPath}/main.min.js`)).toBeTruthy()
       const babelifiedMain = fs.readFileSync(`${distPath}/main.js`).toString()
-      // Used single quotes because of distLint
-      expect(countMatches(babelifiedMain, '\'use strict\'')).toEqual(1)
+      expect(babelifiedMain.includes('use strict')).toBe(true)
 
       // Created browser directory (bundle)
       expect(fs.existsSync(browserPath)).toBeTruthy()
@@ -537,7 +532,7 @@ describe('build', () => {
     })
   }, 30000)
 
-  test('when browser.enabled false and typescript.enabled set: calls clean, tsFor, distFor, distLint, distMinify, compileReadme, testFull', done => {
+  test('when browser.enabled false and typescript.enabled set: calls clean, sourceLint, tsFor, distFor, distMinify, compileReadme, testFull', done => {
     const srcPath = gulpConfig.get('srcPath')
     const rootPath = gulpConfig.get('rootPath')
     const tsConfig = `${rootPath}/tsconfig.json`
@@ -563,8 +558,7 @@ describe('build', () => {
       // Minify the dist files (distMinify)
       expect(fs.existsSync(`${distPath}/main.min.js`)).toBeTruthy()
       const babelifiedMain = fs.readFileSync(`${distPath}/main.js`).toString()
-      // Used single quotes because of distLint
-      expect(countMatches(babelifiedMain, '\'use strict\'')).toEqual(1)
+      expect(babelifiedMain.includes('use strict')).toBe(true)
 
       // Generated README.md (compileReadme)
       const readmeContents = fs.readFileSync(`${readmePath}/${readmeFile}`).toString()
@@ -577,7 +571,7 @@ describe('build', () => {
     })
   }, 30000)
 
-  test('when browser.enabled true and typescript.enabled set: calls clean, tsFor, distFor, distLint, distMinify, bundle, bundleLint, bundleMinify, compileReadme, testFull', done => {
+  test('when browser.enabled true and typescript.enabled set: calls clean, sourceLint, tsFor, distFor, distMinify, bundle, bundleMinify, compileReadme, testFull', done => {
     const srcPath = gulpConfig.get('srcPath')
     const rootPath = gulpConfig.get('rootPath')
     const tsConfig = `${rootPath}/tsconfig.json`
@@ -606,8 +600,7 @@ describe('build', () => {
       // Minify the dist files (distMinify)
       expect(fs.existsSync(`${distPath}/main.min.js`)).toBeTruthy()
       const babelifiedMain = fs.readFileSync(`${distPath}/main.js`).toString()
-      // Used single quotes because of distLint
-      expect(countMatches(babelifiedMain, '\'use strict\'')).toEqual(1)
+      expect(babelifiedMain.includes('use strict')).toBe(true)
 
       // Created browser directory (bundle)
       expect(fs.existsSync(browserPath)).toBeTruthy()

package/functions/partials/addToReadme.mjs

@@ -2,15 +2,24 @@ import fs from 'fs'
 import * as gulpConfig from '../../gulp.config.mjs'
 import jsdoc2md from 'jsdoc-to-markdown'
 import { globSync } from 'glob'
+import { convertMjsFilesForDocs } from '../utilities/convertMjsFilesForDocs.mjs'
 
 /**
  * Appends all the jsdoc comments to the readme file. Assumes empty or templated file.
  * Configure this with 'readmeSearch', 'readmePath', 'readmeFile', and 'readmeOptions'.
+ *
+ * jsdoc-to-markdown only recognizes `.js` files, even though it parses real ESM syntax just fine once it reads
+ * one - `readme.fromEsm` (empty by default) names `.mjs` files to include anyway, converted on the fly (see
+ * {@link convertMjsFilesForDocs}) and cleaned up again once this has read them, win or lose.
  * @memberOf module:partials
  * @returns {string|Uint8Array}
  */
-export const addToReadme = () => jsdoc2md
-  .render({ files: globSync(gulpConfig.get('readme.from')) })
-  .then(
-    readme => fs.appendFileSync(gulpConfig.get('readme.to') + gulpConfig.get('readme.file'), readme, gulpConfig.get('readmeOptions'))
-  )
+export const addToReadme = () => {
+  const { filePaths: esmFilePaths, cleanUp } = convertMjsFilesForDocs(globSync(gulpConfig.get('readme.fromEsm') || []))
+  return jsdoc2md
+    .render({ files: [...globSync(gulpConfig.get('readme.from')), ...esmFilePaths] })
+    .finally(cleanUp)
+    .then(
+      readme => fs.appendFileSync(gulpConfig.get('readme.to') + gulpConfig.get('readme.file'), readme, gulpConfig.get('readmeOptions'))
+    )
+}

package/functions/partials/neostandardLint.mjs

@@ -0,0 +1,118 @@
+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').then(({ neostandard }) => 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>}
+ */
+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`.
+ * @param {Object} options
+ * @param {string} options.cwd
+ * @param {boolean} options.ts
+ * @param {boolean} options.fix
+ * @returns {Promise<import('eslint').ESLint>}
+ */
+const buildEslint = async ({ cwd, ts, fix }) => {
+  const neostandard = await importNeostandard()
+  return new ESLint({
+    cwd,
+    fix,
+    overrideConfigFile: true,
+    baseConfig: neostandard({ ts, env: readEnv(cwd) })
+  })
+}
+
+/**
+ * Print a file's lint messages, if it has any.
+ * @memberOf module:partials
+ * @param {import('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 never fail the 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 {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 {import('stream').Transform}
+ */
+export const neostandardLint = (
+  { fix = true, ts = false } = {},
+  loadEslint = buildEslint
+) => {
+  const totals = { errors: 0, warnings: 0 }
+  let eslintPromise = null
+  return 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 })
+      }
+      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`)
+      callback()
+    }
+  )
+}

package/functions/partials/neostandardLint.test.mjs

@@ -0,0 +1,109 @@
+import Vinyl from 'vinyl'
+import { Readable } from 'node:stream'
+import { neostandardLint } from './neostandardLint.mjs'
+
+const makeFile = (contents, filePath = '/project/src/example.js') => new Vinyl({
+  cwd: '/project',
+  base: '/project/src',
+  path: filePath,
+  contents
+})
+
+const run = (transform, files) => new Promise((resolve, reject) => {
+  const out = []
+  transform.on('data', file => out.push(file)).on('end', () => resolve(out)).on('error', reject)
+  files.forEach(file => transform.write(file))
+  transform.end()
+})
+
+const fakeEslint = (resultFor) => ({
+  lintText: jest.fn((text, options) => Promise.resolve(resultFor(text, options)))
+})
+
+let logSpy
+
+beforeEach(() => {
+  logSpy = jest.spyOn(console, 'log').mockImplementation(() => {})
+})
+
+afterEach(() => {
+  logSpy.mockRestore()
+})
+
+describe('neostandardLint', () => {
+  test('replaces file contents with the fixed output and hands ESLint the file path', async () => {
+    expect.assertions(3)
+    const eslint = fakeEslint((text) => [{ messages: [], errorCount: 0, warningCount: 0, output: text.replace(/"/g, '\'') }])
+    const [linted] = await run(neostandardLint({ fix: true }, () => Promise.resolve(eslint)), [makeFile(Buffer.from('const a = "b"'))])
+    expect(linted.contents.toString()).toEqual('const a = \'b\'')
+    expect(eslint.lintText).toHaveBeenCalledWith('const a = "b"', { filePath: '/project/src/example.js' })
+    expect(linted.path).toEqual('/project/src/example.js')
+  })
+
+  test('leaves the contents alone when ESLint has no fixed output (nothing needed fixing)', async () => {
+    expect.assertions(1)
+    const eslint = fakeEslint(() => [{ messages: [], errorCount: 0, warningCount: 0 }])
+    const [linted] = await run(neostandardLint({}, () => Promise.resolve(eslint)), [makeFile(Buffer.from('const a = 1'))])
+    expect(linted.contents.toString()).toEqual('const a = 1')
+  })
+
+  test('builds the linter once per stream, from the first file, and reuses it for the rest', async () => {
+    expect.assertions(1)
+    const loadEslint = jest.fn(() => Promise.resolve(fakeEslint(() => [{ messages: [], errorCount: 0, warningCount: 0 }])))
+    await run(
+      neostandardLint({}, loadEslint),
+      [makeFile(Buffer.from('a'), '/project/src/a.js'), makeFile(Buffer.from('b'), '/project/src/b.js')]
+    )
+    expect(loadEslint).toHaveBeenCalledTimes(1)
+  })
+
+  test('passes fix and ts through to the loader', async () => {
+    expect.assertions(1)
+    const loadEslint = jest.fn(() => Promise.resolve(fakeEslint(() => [{ messages: [], errorCount: 0, warningCount: 0 }])))
+    await run(neostandardLint({ fix: false, ts: true }, loadEslint), [makeFile(Buffer.from('x'))])
+    expect(loadEslint).toHaveBeenCalledWith({ cwd: '/project', ts: true, fix: false })
+  })
+
+  test('passes a file through untouched when the project ignores it (ESLint returns no results)', async () => {
+    expect.assertions(2)
+    const eslint = fakeEslint(() => [])
+    const [linted] = await run(neostandardLint({}, () => Promise.resolve(eslint)), [makeFile(Buffer.from('var x=1'))])
+    expect(linted.contents.toString()).toEqual('var x=1')
+    expect(logSpy).toHaveBeenCalledWith('✖ Errors total: 0')
+  })
+
+  test('skips null-content files without linting them', async () => {
+    expect.assertions(2)
+    const eslint = fakeEslint(() => [])
+    const [passed] = await run(neostandardLint({}, () => Promise.resolve(eslint)), [makeFile(null)])
+    expect(passed.isNull()).toBeTruthy()
+    expect(eslint.lintText).not.toHaveBeenCalled()
+  })
+
+  test('errors on streaming file contents, which cannot be linted', async () => {
+    expect.assertions(1)
+    const streamFile = makeFile(Readable.from(['x']))
+    await expect(run(neostandardLint({}, () => Promise.resolve(fakeEslint(() => []))), [streamFile])).rejects.toThrow(/streaming/)
+  })
+
+  test('prints per-file problems and a summary of totals across all files, without failing', async () => {
+    expect.assertions(5)
+    const eslint = fakeEslint((text, { filePath }) => filePath.endsWith('a.js')
+      ? [{ messages: [{ line: 2, column: 7, message: 'unused b' }, { line: 3, column: 1, message: 'bad thing' }], errorCount: 2, warningCount: 0 }]
+      : [{ messages: [{ line: 1, column: 1, message: 'just a warning' }], errorCount: 0, warningCount: 1 }])
+    const out = await run(
+      neostandardLint({}, () => Promise.resolve(eslint)),
+      [makeFile(Buffer.from('a'), '/project/src/a.js'), makeFile(Buffer.from('b'), '/project/src/b.js')]
+    )
+    expect(out).toHaveLength(2)
+    expect(logSpy).toHaveBeenCalledWith('src/a.js')
+    expect(logSpy).toHaveBeenCalledWith('line 2:7\tunused b')
+    expect(logSpy).toHaveBeenCalledWith('✖ Errors total: 2')
+    expect(logSpy).toHaveBeenCalledWith('⚠ Warnings total: 1\n')
+  })
+
+  test('surfaces a failure to load or run the linter as a stream error', async () => {
+    expect.assertions(1)
+    await expect(run(neostandardLint({}, () => Promise.reject(new Error('cannot load'))), [makeFile(Buffer.from('x'))])).rejects.toThrow('cannot load')
+  })
+})

package/functions/partials.mjs

@@ -17,10 +17,10 @@ export { distSeries } from './partials/distSeries.mjs'
 export { imagesFor } from './partials/imagesFor.mjs'
 export { importModule, importPeer, requirePeer } from './partials/loadPeer.mjs'
 export { minifyFor } from './partials/minifyFor.mjs'
+export { neostandardLint } from './partials/neostandardLint.mjs'
 export { readmeTemplate } from './partials/readmeTemplate.mjs'
 export { removeDirectory } from './partials/removeDirectory.mjs'
 export { runOnChange } from './partials/runOnChange.mjs'
 export { sassFor } from './partials/sassFor.mjs'
-export { standardLint } from './partials/standardLint.mjs'
 export { tsFor } from './partials/tsFor.mjs'
 export { typeDocsFor } from './partials/typeDocsFor.mjs'