js-build-tools 5.7.0 → 6.1.0

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/bundle.mjs

@@ -28,10 +28,10 @@ import { getBundleConfigs } from './utilities/getBundleConfigs.mjs'
 export const bundle = () => mergeStream(
   getBundleConfigs().map(({ name, main, ignore, exclude }) => {
     const bundler = browserify(main, { standalone: name })
-    if (ignore && ignore.length) {
+    if (ignore.length) {
       bundler.ignore(ignore)
     }
-    if (exclude && exclude.length) {
+    if (exclude.length) {
       bundler.exclude(exclude)
     }
     return bundler

package/functions/partials/addToReadme.mjs

@@ -15,7 +15,7 @@ import { convertMjsFilesForDocs } from '../utilities/convertMjsFilesForDocs.mjs'
  * @returns {string|Uint8Array}
  */
 export const addToReadme = () => {
-  const { filePaths: esmFilePaths, cleanUp } = convertMjsFilesForDocs(globSync(gulpConfig.get('readme.fromEsm') || []))
+  const { filePaths: esmFilePaths, cleanUp } = convertMjsFilesForDocs(globSync(gulpConfig.get('readme.fromEsm')))
   return jsdoc2md
     .render({ files: [...globSync(gulpConfig.get('readme.from')), ...esmFilePaths] })
     .finally(cleanUp)

package/functions/partials/neostandardLint.mjs

@@ -0,0 +1,130 @@
+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>}
+ */
+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<import('eslint').ESLint>}
+ */
+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 {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 {Object<string, *>} [options.rules={}] - ESLint rule overrides layered on top of neostandard's own rules
+ * (see gulp.config.mjs's `lint.rules`).
+ * @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, rules = {} } = {},
+  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, 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`)
+      callback()
+    }
+  )
+}

package/functions/partials/neostandardLint.test.mjs

@@ -0,0 +1,117 @@
+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, rules: {} })
+  })
+
+  test('passes rule overrides through to the loader', async () => {
+    expect.assertions(1)
+    const loadEslint = jest.fn(() => Promise.resolve(fakeEslint(() => [{ messages: [], errorCount: 0, warningCount: 0 }])))
+    const rules = { 'no-template-curly-in-string': 'off' }
+    await run(neostandardLint({ rules }, loadEslint), [makeFile(Buffer.from('x'))])
+    expect(loadEslint).toHaveBeenCalledWith({ cwd: '/project', ts: false, fix: true, rules })
+  })
+
+  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'

package/functions/sourceLint.mjs

@@ -0,0 +1,24 @@
+import * as gulpConfig from '../gulp.config.mjs'
+import { dest, src } from 'gulp'
+import { neostandardLint } from './partials/neostandardLint.mjs'
+
+/**
+ * Applies neostandard linting (js-build-tools' chosen style) to the real, hand-written source - not the compiled
+ * dist/browser output, which is generated and so was never going to pass a hand-authored-code style check (every
+ * compiler/bundler emits its own boilerplate - import aliasing, interop headers - that only looks like a style
+ * violation). Includes test files: there is no reason to hold tests to a lower style bar than the rest of the
+ * source. When typescript.enabled, the real TypeScript source is linted too, with type-aware rules.
+ * @memberOf module:js-build-tools
+ * @returns {*}
+ */
+export const sourceLint = () => {
+  const srcPath = gulpConfig.get('srcPath')
+  const ts = gulpConfig.get('typescript.enabled')
+  const patterns = [`${srcPath}/**/*.js`]
+  if (ts) {
+    patterns.push(`${srcPath}/**/*.ts`)
+  }
+  return src(patterns)
+    .pipe(neostandardLint({ fix: true, ts, rules: gulpConfig.get('lint.rules') }))
+    .pipe(dest(srcPath))
+}

package/functions/sourceLint.test.mjs

@@ -0,0 +1,97 @@
+import fs from 'fs'
+import * as setUp from './test-helpers/setUp.mjs'
+import { sourceLint } from './sourceLint.mjs'
+import { countMatches } from 'test-filesystem'
+
+// 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-source-lint')
+const gulpConfig = setUp.gulpConfig
+
+const lintableContents = 'const x = "a";\n' +
+  '\n' +
+  'module.exports = x;\n'
+
+const lintableTestContents = 'const y = "b";\n' +
+  '\n' +
+  'module.exports = y;\n'
+
+beforeEach(
+  () => setUp.beforeEach()
+    .then(
+      async () => {
+        const srcPath = gulpConfig.get('srcPath')
+        await fs.mkdirSync(srcPath, { recursive: true })
+        fs.writeFileSync(`${srcPath}/example.js`, lintableContents)
+        return fs.writeFileSync(`${srcPath}/example.test.js`, lintableTestContents)
+      }
+    )
+)
+
+afterEach(setUp.afterEach)
+
+describe('sourceLint', () => {
+  test('fixes the real source in place, including test files', done => {
+    const srcPath = gulpConfig.get('srcPath')
+    expect.assertions(4)
+    sourceLint()
+      .on('finish', () => {
+        const linted = fs.readFileSync(`${srcPath}/example.js`).toString()
+        expect(countMatches(linted, '"')).toEqual(0)
+        expect(countMatches(linted, ';')).toEqual(0)
+        const lintedTest = fs.readFileSync(`${srcPath}/example.test.js`).toString()
+        expect(countMatches(lintedTest, '"')).toEqual(0)
+        expect(countMatches(lintedTest, ';')).toEqual(0)
+        done()
+      })
+      .on('error', error => {
+        console.error('Encountered error', error)
+        done(error)
+      })
+  }, 20000)
+
+  test('lint.rules actually suppresses a real neostandard finding', done => {
+    const srcPath = gulpConfig.get('srcPath')
+    // A fixture string containing literal ${...} text (simulating real module source, not an accidental
+    // non-template string) - neostandard's no-template-curly-in-string rule flags this as an error by default.
+    const fixtureContents = 'const fixture = \'import(`imagemin-${pluginName}`)\'\n\nmodule.exports = fixture\n'
+    fs.writeFileSync(`${srcPath}/fixture.js`, fixtureContents)
+    gulpConfig.set('lint.rules', { 'no-template-curly-in-string': 'off' })
+    const logSpy = jest.spyOn(console, 'log').mockImplementation(() => {})
+    expect.assertions(1)
+    sourceLint()
+      .on('finish', () => {
+        gulpConfig.set('lint.rules', {})
+        expect(logSpy.mock.calls.flat().join('\n')).not.toMatch(/no-template-curly-in-string|template string expression/)
+        logSpy.mockRestore()
+        done()
+      })
+      .on('error', error => {
+        gulpConfig.set('lint.rules', {})
+        logSpy.mockRestore()
+        console.error('Encountered error', error)
+        done(error)
+      })
+  }, 20000)
+
+  test('also lints .ts source when typescript.enabled', done => {
+    const srcPath = gulpConfig.get('srcPath')
+    gulpConfig.set('typescript.enabled', true)
+    fs.writeFileSync(`${srcPath}/example.ts`, 'const z: string = "c";\n\nexport default z;\n')
+    expect.assertions(2)
+    sourceLint()
+      .on('finish', () => {
+        gulpConfig.set('typescript.enabled', false)
+        const linted = fs.readFileSync(`${srcPath}/example.ts`).toString()
+        expect(countMatches(linted, '"')).toEqual(0)
+        expect(countMatches(linted, ';')).toEqual(0)
+        done()
+      })
+      .on('error', error => {
+        gulpConfig.set('typescript.enabled', false)
+        console.error('Encountered error', error)
+        done(error)
+      })
+  }, 20000)
+})

package/functions/test-helpers/neostandardLintWithRealNeostandard.mjs

@@ -0,0 +1,40 @@
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+// Jest's CommonJS transform cannot load `neostandard` (ESM-only) or run a real dynamic import(), so tests that need
+// genuine neostandard behavior run the actual package in a plain Node subprocess instead of faking it.
+const script = 'import { readFileSync } from \'node:fs\'\n' +
+  'import { ESLint } from \'eslint\'\n' +
+  'import { neostandard, defaultFilePatterns } from \'neostandard\'\n' +
+  'const { text, filePath, cwd, fix, ts, env, rules } = JSON.parse(readFileSync(0, \'utf8\'))\n' +
+  'const baseConfig = neostandard({ ts, env })\n' +
+  'if (Object.keys(rules).length) { baseConfig.push({ files: defaultFilePatterns.all, rules }) }\n' +
+  'const eslint = new ESLint({ cwd, fix, overrideConfigFile: true, baseConfig })\n' +
+  'process.stdout.write(JSON.stringify(await eslint.lintText(text, { filePath })))\n'
+
+const readEnv = cwd => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')).standard?.env ?? []
+  } catch {
+    return []
+  }
+}
+
+export const loadEslintViaSubprocess = ({ cwd, ts, fix, rules = {} }) => Promise.resolve({
+  lintText: (text, { filePath }) => Promise.resolve().then(() => JSON.parse(execFileSync(
+    process.execPath,
+    ['--input-type=module', '--eval', script],
+    {
+      input: JSON.stringify({ text, filePath, cwd, fix, ts, env: readEnv(cwd), rules }),
+      encoding: 'utf8',
+      cwd,
+      maxBuffer: 256 * 1024 * 1024
+    }
+  )))
+})
+
+const actual = jest.requireActual('../partials/neostandardLint.mjs')
+
+// Drop-in replacement for the partial module (see jest.mock in the lint/build tests): same API, real neostandard.
+export const neostandardLint = (options) => actual.neostandardLint(options, loadEslintViaSubprocess)

package/functions/utilities/dotNotate.mjs

@@ -46,7 +46,9 @@ const performDotNotate = (arrayObject, didRetain, prepend = '', results = {}) =>
     if (didRetain(currentKey, value, results)) {
       continue
     }
-    if (isObject(value)) {
+    // An empty object/array has no keys to flatten into - recursing into one would silently drop currentKey
+    // from the result entirely, rather than keeping it as the empty value it actually is. Treat it as a leaf.
+    if (isObject(value) && Object.keys(value).length) {
       performDotNotate(value, didRetain, `${currentKey}.`, results)
       continue
     }

package/functions/utilities/dotNotate.test.mjs

@@ -0,0 +1,34 @@
+import { dotNotate } from './dotNotate.mjs'
+
+describe('dotNotate', () => {
+  test('flattens a nested object into dot-notation leaves', () => {
+    expect(dotNotate({ a: { b: 'c', d: { e: 'f' } } })).toEqual({ 'a.b': 'c', 'a.d.e': 'f' })
+  })
+
+  test('flattens a non-empty array into index-numbered leaves, same as a plain object', () => {
+    expect(dotNotate({ a: ['x', 'y'] })).toEqual({ 'a.0': 'x', 'a.1': 'y' })
+  })
+
+  test('keeps a primitive value (including null) as its own leaf, unflattened', () => {
+    expect(dotNotate({ a: 1, b: 'two', c: null })).toEqual({ a: 1, b: 'two', c: null })
+  })
+
+  test('keeps an empty object as a leaf value, rather than silently dropping its key', () => {
+    expect(dotNotate({ a: {}, b: 'c' })).toEqual({ a: {}, b: 'c' })
+  })
+
+  test('keeps an empty array as a leaf value, rather than silently dropping its key', () => {
+    expect(dotNotate({ a: [], b: 'c' })).toEqual({ a: [], b: 'c' })
+  })
+
+  test('keeps an empty object/array as a leaf even nested inside other objects', () => {
+    expect(dotNotate({ a: { b: [], c: {} } })).toEqual({ 'a.b': [], 'a.c': {} })
+  })
+
+  test('retains a matching key as a whole object instead of flattening into it', () => {
+    expect(dotNotate({ a: { b: 'c' }, options: { fix: true } }, ['options'])).toEqual({
+      'a.b': 'c',
+      options: { fix: true }
+    })
+  })
+})

package/functions/utilities/getBundleConfigs.mjs

@@ -16,7 +16,7 @@ export const getBundleConfigs = () => {
     ignore: gulpConfig.get('browser.ignore'),
     exclude: gulpConfig.get('browser.exclude')
   }
-  const additional = gulpConfig.get('browser.bundles') || []
+  const additional = gulpConfig.get('browser.bundles')
   return [
     primary,
     ...additional.map((bundleConfig) => ({