js-build-tools 6.0.0 → 6.2.0

package/functions/build.test.mjs

@@ -4,6 +4,7 @@ import { build } from './build.mjs'
 import { clean } from './partials/clean.mjs'
 import { testFull } from './testFull.mjs'
 import { typeDocs } from './typeDocs.mjs'
+import { jsdocDocs } from './jsdocDocs.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.
@@ -16,8 +17,11 @@ const genericFunction = () => Promise.resolve(true)
 
 jest.mock('./partials/clean.mjs', () => ({ clean: jest.fn(genericFunction) }))
 jest.mock('./testFull.mjs', () => ({ testFull: jest.fn(genericFunction) }))
-// The documentation is generated by TypeDoc, whose own tests cover that (see typeDocsFor.test.mjs)
+// The documentation is generated by TypeDoc or jsdoc, whose own tests cover that (see typeDocsFor.test.mjs /
+// jsdocDocsFor.test.mjs) - jsdocDocs in particular shells out to a real CLI, far too slow for a build.mjs unit
+// test to actually run.
 jest.mock('./typeDocs.mjs', () => ({ typeDocs: jest.fn(genericFunction) }))
+jest.mock('./jsdocDocs.mjs', () => ({ jsdocDocs: jest.fn(genericFunction) }))
 // tsFor's real implementation loads gulp-ts-compile (a genuine ESM-only package) via a dynamic import() hidden
 // from babel's static analysis - necessary for production correctness (see tsFor.mjs's own comments), but this
 // project's current CommonJS-transform-based Jest setup can't execute a real dynamic import at all: it doesn't
@@ -638,6 +642,7 @@ describe('build', () => {
     expect.assertions(3)
     build(() => {
       gulpConfig.set('docs.enabled', false)
+      gulpConfig.set('typescript.enabled', false)
       expect(typeDocs).toHaveBeenCalledTimes(1)
       // The readme is not generated, it is written by hand
       expect(fs.existsSync(`${readmePath}/${readmeFile}`)).toBe(false)
@@ -646,6 +651,50 @@ describe('build', () => {
     })
   }, 30000)
 
+  test('when docs.enabled is set without typescript.enabled: generates the documentation with jsdoc, inferred from docs.method being unset', done => {
+    const readmePath = gulpConfig.get('readme.to')
+    const readmeFile = gulpConfig.get('readme.file')
+    fs.rmSync(`${readmePath}/${readmeFile}`, { force: true })
+    jsdocDocs.mockClear()
+    gulpConfig.set('browser.enabled', false)
+    gulpConfig.set('typescript.enabled', false)
+    gulpConfig.set('docs.enabled', true)
+    expect.assertions(3)
+    build(() => {
+      gulpConfig.set('docs.enabled', false)
+      expect(jsdocDocs).toHaveBeenCalledTimes(1)
+      // The readme is not generated, it is written by hand - same as the TypeDoc path above
+      expect(fs.existsSync(`${readmePath}/${readmeFile}`)).toBe(false)
+      expect(testFull).toHaveBeenCalled()
+      done()
+    })
+  }, 30000)
+
+  test('docs.method overrides the typescript.enabled inference either way', done => {
+    const srcPath = gulpConfig.get('srcPath')
+    const rootPath = gulpConfig.get('rootPath')
+    const tsConfig = `${rootPath}/tsconfig.json`
+    fs.writeFileSync(`${srcPath}/main.ts`, mainTypescript)
+    fs.writeFileSync(tsConfig, tsConfigContents)
+    typeDocs.mockClear()
+    jsdocDocs.mockClear()
+    gulpConfig.set('browser.enabled', false)
+    gulpConfig.set('typescript.config', tsConfig)
+    gulpConfig.set('typescript.enabled', true)
+    gulpConfig.set('docs.enabled', true)
+    // typescript.enabled is true, which would normally infer 'typedoc' - method forces 'jsdoc' instead.
+    gulpConfig.set('docs.method', 'jsdoc')
+    expect.assertions(2)
+    build(() => {
+      gulpConfig.set('docs.enabled', false)
+      gulpConfig.set('docs.method', false)
+      gulpConfig.set('typescript.enabled', false)
+      expect(jsdocDocs).toHaveBeenCalledTimes(1)
+      expect(typeDocs).not.toHaveBeenCalled()
+      done()
+    })
+  }, 30000)
+
   test('finishes clean before starting the tasks that write into the output folders', done => {
     const srcPath = gulpConfig.get('srcPath')
     const sourcesPath = `${srcPath}/sources`

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

@@ -0,0 +1,32 @@
+import { copyFor } from './partials/copyFor.mjs'
+import * as gulpConfig from '../gulp.config.mjs'
+
+/**
+ * Copy files from one place to another - any number of { from, to, base? } entries, configured via copyFiles.
+ * A project with no copyFiles entries gets a task that does nothing. Meant to be run explicitly (its own script,
+ * e.g. `gulp copyFiles`), not folded into the default build - a bundle (or any other file this copies) is often
+ * the live, publicly-reachable version of something, so publishing it elsewhere should be a deliberate step, not
+ * a side effect of every routine local build.
+ *
+ * Reuses copyFor (already shared with copyFonts) rather than a fresh src()/dest() pair - that keeps its existing
+ * encoding: false fix (Gulp 5's default utf8 handling corrupts binary files such as fonts or a minified bundle)
+ * instead of silently losing it in a parallel implementation.
+ *
+ * Each entry runs as its own independent copyFor(), awaited via Promise.all rather than merged into one combined
+ * stream (mergeStream, the pattern bundle.mjs uses) - that pattern assumes every merged stream ends up at the
+ * same shared destination; here, each entry can have a genuinely different one, and merging streams that each
+ * already terminate at their own separate dest() hit a real "write after end" error in practice.
+ * @memberOf module:js-build-tools
+ * @returns {Promise<void>}
+ */
+export const copyFiles = () => {
+  const copies = gulpConfig.get('copyFiles', [])
+  if (!copies.length) {
+    return Promise.resolve()
+  }
+  return Promise.all(copies.map(({ from, to, base }) => new Promise((resolve, reject) => {
+    copyFor(from, to, { base })
+      .on('finish', resolve)
+      .on('error', reject)
+  }))).then(() => {})
+}

package/functions/copyFiles.test.mjs

@@ -0,0 +1,78 @@
+import fs from 'fs'
+import * as setUp from './test-helpers/setUp.mjs'
+import { copyFiles } from './copyFiles.mjs'
+
+setUp.setDefaults('test-copy-files')
+const gulpConfig = setUp.gulpConfig
+
+beforeEach(() => setUp.beforeEach())
+afterEach(() => {
+  gulpConfig.set('copyFiles', [])
+  return setUp.afterEach()
+})
+
+describe('copyFiles', () => {
+  test('with no entries configured, does nothing and resolves', async () => {
+    await expect(copyFiles()).resolves.toBeUndefined()
+  })
+
+  test('copies a file from one place to another', async () => {
+    const sourceDir = `${gulpConfig.get('rootPath')}copy-source`
+    const destDir = `${gulpConfig.get('rootPath')}copy-dest`
+    fs.mkdirSync(sourceDir, { recursive: true })
+    fs.writeFileSync(`${sourceDir}/one.txt`, 'one file\n')
+    gulpConfig.set('copyFiles', [{ from: `${sourceDir}/*.txt`, to: destDir }])
+
+    await copyFiles()
+
+    expect(fs.readFileSync(`${destDir}/one.txt`).toString()).toBe('one file\n')
+  })
+
+  test('copies several configured entries, each to its own destination', async () => {
+    const sourceDirA = `${gulpConfig.get('rootPath')}copy-source-a`
+    const sourceDirB = `${gulpConfig.get('rootPath')}copy-source-b`
+    const destDirA = `${gulpConfig.get('rootPath')}copy-dest-a`
+    const destDirB = `${gulpConfig.get('rootPath')}copy-dest-b`
+    fs.mkdirSync(sourceDirA, { recursive: true })
+    fs.mkdirSync(sourceDirB, { recursive: true })
+    fs.writeFileSync(`${sourceDirA}/a.txt`, 'from a\n')
+    fs.writeFileSync(`${sourceDirB}/b.txt`, 'from b\n')
+    gulpConfig.set('copyFiles', [
+      { from: `${sourceDirA}/*.txt`, to: destDirA },
+      { from: `${sourceDirB}/*.txt`, to: destDirB }
+    ])
+
+    await copyFiles()
+
+    expect(fs.readFileSync(`${destDirA}/a.txt`).toString()).toBe('from a\n')
+    expect(fs.readFileSync(`${destDirB}/b.txt`).toString()).toBe('from b\n')
+  })
+
+  test('base preserves the glob\'s own subdirectory structure in the destination', async () => {
+    const sourceDir = `${gulpConfig.get('rootPath')}copy-source-nested`
+    const destDir = `${gulpConfig.get('rootPath')}copy-dest-nested`
+    fs.mkdirSync(`${sourceDir}/inner`, { recursive: true })
+    fs.writeFileSync(`${sourceDir}/inner/deep.txt`, 'nested file\n')
+    gulpConfig.set('copyFiles', [{ from: `${sourceDir}/**/*.txt`, to: destDir, base: sourceDir }])
+
+    await copyFiles()
+
+    expect(fs.readFileSync(`${destDir}/inner/deep.txt`).toString()).toBe('nested file\n')
+  })
+
+  // The real bug this guards against: a fresh src()/dest() pair (what this used to do) loses copyFor.mjs's own
+  // encoding: false fix - Gulp 5's default utf8 handling corrupts binary files such as fonts or a minified
+  // bundle. Reusing copyFor instead of duplicating its logic keeps that fix automatically.
+  test('copies binary files byte for byte, including bytes above 0x7f', async () => {
+    const sourceDir = `${gulpConfig.get('rootPath')}copy-source-binary`
+    const destDir = `${gulpConfig.get('rootPath')}copy-dest-binary`
+    fs.mkdirSync(sourceDir, { recursive: true })
+    const original = Buffer.from(Array.from({ length: 512 }, (_, i) => i % 256))
+    fs.writeFileSync(`${sourceDir}/font.woff`, original)
+    gulpConfig.set('copyFiles', [{ from: `${sourceDir}/*.woff`, to: destDir }])
+
+    await copyFiles()
+
+    expect(fs.readFileSync(`${destDir}/font.woff`).equals(original)).toBe(true)
+  })
+})

package/functions/jsdocDocs.mjs

@@ -0,0 +1,10 @@
+import { jsdocDocsFor } from './partials/jsdocDocsFor.mjs'
+
+/**
+ * Generate the HTML documentation of a plain-JavaScript project from its source, with a modern jsdoc theme
+ * instead of jsdoc's own classic default. Turn it on with docs.enabled and docs.method: 'jsdoc' (the default
+ * when typescript.enabled is off), see {@link module:partials.jsdocDocsFor}.
+ * @memberOf module:js-build-tools
+ * @returns {Function}
+ */
+export const jsdocDocs = jsdocDocsFor()

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

@@ -5,8 +5,11 @@ import { dest, src } from 'gulp'
  * @memberOf module:partials
  * @param {string|array} srcPath
  * @param {string} destPath
+ * @param {Object} [options]
+ * @param {string} [options.base] - Passed through to gulp's own src(pattern, {base}), to preserve srcPath's own
+ * subdirectory structure in destPath instead of flattening it.
  * @returns {stream.Stream}
  */
 // encoding: false copies the bytes untouched - Gulp 5's default utf8 handling corrupts binary files such as fonts.
-export const copyFor = (srcPath, destPath) => src(srcPath, { encoding: false })
+export const copyFor = (srcPath, destPath, { base } = {}) => src(srcPath, { encoding: false, ...(base ? { base } : {}) })
   .pipe(dest(destPath))

package/functions/partials/jsdocDocsFor.mjs

@@ -0,0 +1,132 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { createRequire } from 'node:module'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import * as gulpConfig from '../../gulp.config.mjs'
+import { removeDirectory } from './removeDirectory.mjs'
+// jsdoc.base.js is CommonJS (it's also required directly by consuming projects' own .jsdoc.conf.js, and by this
+// project's own legacy htmldocs script) - Node's ESM loader imports a CJS module's module.exports as the default
+// export directly, no createRequire/import.meta needed (import.meta.url tripped up this project's own Babel CJS
+// transform, which Jest relies on to run .mjs test files - confirmed by removing it and nothing else changing).
+import jsdocBase from '../../jsdoc.base.js'
+
+const execFileAsync = promisify(execFile)
+
+const jsdocInstallHint = 'Install it in your project with: npm install --save-dev jsdoc'
+const themeInstallHint = name => `Install it in your project with: npm install --save-dev ${name}`
+
+/**
+ * Resolve the installed directory of an optional peer dependency, from the project being built rather than from
+ * this package. Deliberately not requirePeer/importPeer's own `require(name + '/package.json')` approach - that
+ * breaks for any package whose own package.json restricts its exports map and does not expose that subpath
+ * (clean-jsdoc-theme does; confirmed live, not assumed - resolving its own package.json throws
+ * ERR_PACKAGE_PATH_NOT_EXPORTED in plain Node, and a differently-shaped MODULE_NOT_FOUND under Jest's own
+ * resolver, which still is not "not installed" either way). Walking Node's own real module-lookup directories
+ * (require.resolve.paths) and checking each on disk sidesteps the exports map entirely - this only ever reads
+ * whether `<dir>/<name>/package.json` exists, never asks the module system to resolve a restricted subpath.
+ * @memberOf module:partials
+ * @param {string} name - The package name.
+ * @param {Object} options
+ * @param {string} options.task
+ * @param {string} options.installHint
+ * @param {string} [options.projectPath=process.cwd()]
+ * @returns {string}
+ * @throws {Error} With install instructions when the package is not installed.
+ */
+const resolvePeerDir = (name, { task, installHint, projectPath = process.cwd() }) => {
+  const req = createRequire(path.join(projectPath, 'package.json'))
+  const found = (req.resolve.paths(name) || [])
+    .map(dir => path.join(dir, name))
+    .find(dir => fs.existsSync(path.join(dir, 'package.json')))
+  if (!found) {
+    throw new Error(`The ${task} task needs the optional peer dependency ${name}, which is not installed. ${installHint}`)
+  }
+  return found
+}
+
+/**
+ * Resolve jsdoc's own CLI entry point. jsdoc has no stable programmatic Node API for generating HTML docs (unlike
+ * TypeDoc's Application.bootstrap()/convert()/generateDocs()) - gulp-jsdoc3, the established gulp wrapper, is
+ * stale, and its own README admits jsdoc does not support piped input in the first place, a real anti-pattern for
+ * this project's own gulp-stream conventions. Running its real CLI via child_process is the portable way in -
+ * confirmed via `npm view jsdoc bin`, which reports "jsdoc.js" at the package root.
+ * @memberOf module:partials
+ * @param {string} [projectPath=process.cwd()]
+ * @returns {string}
+ */
+export const resolveJsdocBin = (projectPath = process.cwd()) =>
+  path.join(resolvePeerDir('jsdoc', { task: 'docs', installHint: jsdocInstallHint, projectPath }), 'jsdoc.js')
+
+/**
+ * Resolve a jsdoc theme package's own template directory, for jsdoc's own opts.template config key. Not
+ * necessarily the package's own root - clean-jsdoc-theme's own docs say to point opts.template at its `dist`
+ * subdirectory specifically, confirmed by reading its real README rather than assuming every theme follows the
+ * classic jsdoc template layout (a bare package root with its own tmpl/static folders) - clean-jsdoc-theme does
+ * not (it is a modern, self-contained, server-rendered theme with no such folders at its package root at all).
+ * @memberOf module:partials
+ * @param {string} name
+ * @param {string} [projectPath=process.cwd()]
+ * @returns {string}
+ */
+export const resolveJsdocTheme = (name, projectPath = process.cwd()) => {
+  const packageDir = resolvePeerDir(name, { task: 'docs', installHint: themeInstallHint(name), projectPath })
+  return name === 'clean-jsdoc-theme' ? path.join(packageDir, 'dist') : packageDir
+}
+
+/**
+ * Generate the HTML documentation of a plain-JavaScript project with jsdoc, using jsdoc.base.js's own shared
+ * config (plugins, includePattern/excludePattern) as the starting point rather than a parallel one - the same
+ * base a project's own .jsdoc.conf.js has always been able to extend, just with source.include and the output
+ * options generated here instead of hand-maintained per project. Configure this with 'docs.from', 'docs.to',
+ * 'docs.index', 'docs.theme' and 'docs.title'.
+ * @memberOf module:partials
+ * @param {string} [srcPath=gulpConfig.get('docs.from')] - The directory (or glob) holding the JS source.
+ * @param {string} [outPath=gulpConfig.get('docs.to')] - The directory the documentation is generated into (cleared first).
+ * @param {function(string, Array<string>): Promise<Object>} [runJsdoc] - Runs the jsdoc CLI, tests can inject a stand-in.
+ * @returns {Function} A gulp task, it accepts an optional callback and returns a promise.
+ */
+export const jsdocDocsFor = (
+  srcPath = gulpConfig.get('docs.from'),
+  outPath = gulpConfig.get('docs.to'),
+  runJsdoc = (bin, args) => execFileAsync(process.execPath, [bin, ...args])
+) => {
+  if (gulpConfig.get('docs.enabled') === false) {
+    return () => {}
+  }
+  return (done) => {
+    const generate = async () => {
+      const theme = gulpConfig.get('docs.theme') || 'clean-jsdoc-theme'
+      const themeDir = resolveJsdocTheme(theme)
+      const indexFile = gulpConfig.get('docs.index')
+      await removeDirectory(outPath)
+      const config = {
+        ...jsdocBase,
+        source: {
+          ...jsdocBase.source,
+          include: [path.resolve(srcPath)]
+        },
+        opts: {
+          destination: path.resolve(outPath),
+          // jsdoc does not recurse into source.include's own subdirectories by default - without this, only
+          // the top level of docs.from would ever be scanned. Confirmed from clean-jsdoc-theme's own README
+          // quick-start example, which sets this explicitly, not assumed from jsdoc's own classic defaults.
+          recurse: true,
+          template: themeDir,
+          ...(indexFile && fs.existsSync(indexFile) ? { readme: path.resolve(indexFile) } : {})
+        }
+      }
+      const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jsdocdocs-'))
+      try {
+        const configPath = path.join(workDir, 'jsdoc.conf.json')
+        fs.writeFileSync(configPath, JSON.stringify(config))
+        const bin = resolveJsdocBin()
+        await runJsdoc(bin, ['-c', configPath])
+      } finally {
+        await removeDirectory(workDir)
+      }
+    }
+    return typeof done === 'function' ? generate().then(() => done(), done) : generate()
+  }
+}

package/functions/partials/jsdocDocsFor.test.mjs

@@ -0,0 +1,101 @@
+import fs from 'fs'
+import path from 'node:path'
+import * as setUp from '../test-helpers/setUp.mjs'
+import { jsdocDocsFor, resolveJsdocBin, resolveJsdocTheme } from './jsdocDocsFor.mjs'
+
+setUp.setDefaults('test-jsdoc-docs-for')
+const gulpConfig = setUp.gulpConfig
+
+const write = (file, contents) => {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, contents)
+}
+
+beforeEach(
+  () => setUp.beforeEach().then(() => {
+    const srcPath = gulpConfig.get('srcPath')
+    write(`${srcPath}/add.js`, '/**\n * Add two numbers.\n * @param {number} a\n * @param {number} b\n * @returns {number}\n */\nconst add = (a, b) => a + b\n\nmodule.exports = add\n')
+  })
+)
+
+afterEach(setUp.afterEach)
+
+describe('resolveJsdocBin / resolveJsdocTheme', () => {
+  test('resolves the real installed jsdoc CLI entry', () => {
+    const bin = resolveJsdocBin()
+    expect(fs.existsSync(bin)).toBe(true)
+    expect(path.basename(bin)).toBe('jsdoc.js')
+  })
+
+  test('resolves the real installed theme directory', () => {
+    const themeDir = resolveJsdocTheme('clean-jsdoc-theme')
+    expect(fs.existsSync(themeDir)).toBe(true)
+  })
+
+  test('throws a clear, install-hint error for a package that is not installed', () => {
+    expect(() => resolveJsdocTheme('not-a-real-jsdoc-theme-package')).toThrow(/npm install --save-dev/)
+  })
+})
+
+describe('jsdocDocsFor', () => {
+  const fakeRunJsdoc = calls => (bin, args) => {
+    calls.bin = bin
+    calls.args = args
+    calls.config = JSON.parse(fs.readFileSync(args[args.indexOf('-c') + 1], 'utf8'))
+    fs.mkdirSync(calls.config.opts.destination, { recursive: true })
+    fs.writeFileSync(`${calls.config.opts.destination}/index.html`, '<html></html>')
+    return Promise.resolve()
+  }
+
+  test('generates the documentation into the output directory, clearing what was there', async () => {
+    gulpConfig.set('docs.enabled', true)
+    const outPath = `${gulpConfig.get('srcPath')}/../docs`
+    write(`${outPath}/stale.html`, 'old')
+    const calls = {}
+    await jsdocDocsFor(gulpConfig.get('srcPath'), outPath, fakeRunJsdoc(calls))()
+    expect(fs.existsSync(`${outPath}/stale.html`)).toBe(false)
+    expect(fs.existsSync(`${outPath}/index.html`)).toBe(true)
+    expect(calls.config.opts.destination).toBe(path.resolve(outPath))
+    expect(calls.config.source.include).toEqual([path.resolve(gulpConfig.get('srcPath'))])
+  })
+
+  test('uses the configured theme as the template directory', async () => {
+    gulpConfig.set('docs.enabled', true)
+    gulpConfig.set('docs.theme', 'clean-jsdoc-theme')
+    const calls = {}
+    await jsdocDocsFor(gulpConfig.get('srcPath'), `${gulpConfig.get('srcPath')}/../docs`, fakeRunJsdoc(calls))()
+    expect(calls.config.opts.template).toBe(resolveJsdocTheme('clean-jsdoc-theme'))
+  })
+
+  test('uses the front page from docs.index when it exists, and leaves readme unset when it does not', async () => {
+    gulpConfig.set('docs.enabled', true)
+    gulpConfig.set('docs.index', `${gulpConfig.get('srcPath')}/../MAIN.md`)
+    write(`${gulpConfig.get('srcPath')}/../MAIN.md`, '# hello\n')
+    const calls = {}
+    await jsdocDocsFor(gulpConfig.get('srcPath'), `${gulpConfig.get('srcPath')}/../docs`, fakeRunJsdoc(calls))()
+    expect(calls.config.opts.readme).toBe(path.resolve(`${gulpConfig.get('srcPath')}/../MAIN.md`))
+
+    gulpConfig.set('docs.index', 'does-not-exist.md')
+    await jsdocDocsFor(gulpConfig.get('srcPath'), `${gulpConfig.get('srcPath')}/../docs`, fakeRunJsdoc(calls))()
+    expect(calls.config.opts.readme).toBeUndefined()
+  })
+
+  test('skips if docs.enabled is false', () => {
+    gulpConfig.set('docs.enabled', false)
+    const result = jsdocDocsFor()
+    expect(result).toBeInstanceOf(Function)
+    expect(result.length).toBe(0)
+  })
+})
+
+describe('jsdocDocsFor, end to end with the real jsdoc CLI and clean-jsdoc-theme', () => {
+  test('produces a real browsable HTML page from real JSDoc comments', async () => {
+    gulpConfig.set('docs.enabled', true)
+    const outPath = `${gulpConfig.get('srcPath')}/../docs`
+    await jsdocDocsFor(gulpConfig.get('srcPath'), outPath)()
+    // clean-jsdoc-theme nests its real output under its own route folders (global/, source/...), not flat at
+    // outPath's own root - confirmed by actually running it, not assumed from the classic jsdoc template shape.
+    const files = fs.readdirSync(outPath, { recursive: true })
+    expect(files.some(file => file.endsWith('.html'))).toBe(true)
+  }, 30000)
+})

package/functions/partials/neostandardLint.mjs

@@ -6,7 +6,7 @@ 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)
+const importNeostandard = () => importModule('neostandard')
 
 /**
  * Read the `env` a project already declared for Standard (the `standard` field in its package.json), so a project
@@ -23,20 +23,30 @@ const readEnv = cwd => {
 }
 
 /**
- * Build an ESLint instance configured with neostandard, honoring the project's own package.json `standard.env`.
+ * 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 }) => {
-  const neostandard = await importNeostandard()
+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: neostandard({ ts, env: readEnv(cwd) })
+    baseConfig
   })
 }
 
@@ -67,13 +77,15 @@ const printFileReport = (file, result) => {
  * @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 } = {},
+  { fix = true, ts = false, rules = {} } = {},
   loadEslint = buildEslint
 ) => {
   const totals = { errors: 0, warnings: 0 }
@@ -89,7 +101,7 @@ export const neostandardLint = (
         return
       }
       if (!eslintPromise) {
-        eslintPromise = loadEslint({ cwd: file.cwd, ts, fix })
+        eslintPromise = loadEslint({ cwd: file.cwd, ts, fix, rules })
       }
       eslintPromise
         .then(eslint => eslint.lintText(file.contents.toString(), { filePath: file.path }))

package/functions/partials/neostandardLint.test.mjs

@@ -61,7 +61,15 @@ describe('neostandardLint', () => {
     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 })
+    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 () => {

package/functions/sourceLint.mjs

@@ -19,6 +19,6 @@ export const sourceLint = () => {
     patterns.push(`${srcPath}/**/*.ts`)
   }
   return src(patterns)
-    .pipe(neostandardLint({ fix: true, ts }))
+    .pipe(neostandardLint({ fix: true, ts, rules: gulpConfig.get('lint.rules') }))
     .pipe(dest(srcPath))
 }

package/functions/sourceLint.test.mjs

@@ -51,6 +51,30 @@ describe('sourceLint', () => {
       })
   }, 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)

package/functions/test-helpers/neostandardLintWithRealNeostandard.mjs

@@ -6,9 +6,11 @@ import path from 'node:path'
 // 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 } from \'neostandard\'\n' +
-  'const { text, filePath, cwd, fix, ts, env } = JSON.parse(readFileSync(0, \'utf8\'))\n' +
-  'const eslint = new ESLint({ cwd, fix, overrideConfigFile: true, baseConfig: neostandard({ ts, env }) })\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 => {
@@ -19,12 +21,12 @@ const readEnv = cwd => {
   }
 }
 
-export const loadEslintViaSubprocess = ({ cwd, ts, fix }) => Promise.resolve({
+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) }),
+      input: JSON.stringify({ text, filePath, cwd, fix, ts, env: readEnv(cwd), rules }),
       encoding: 'utf8',
       cwd,
       maxBuffer: 256 * 1024 * 1024

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
     }