js-build-tools 6.1.0 → 6.2.2

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

@@ -0,0 +1,13 @@
+import { jsdocDocs } from './jsdocDocs.mjs'
+import { resolveDocsMethod } from './partials/resolveDocsMethod.mjs'
+import { typeDocs } from './typeDocs.mjs'
+
+/**
+ * Generate the HTML documentation with whichever engine docs.method (or its typescript.enabled-based default)
+ * resolves to - see {@link module:partials.resolveDocsMethod}. The standalone counterpart to build's own
+ * internal branching, for running `gulp docs` directly instead of as part of a full build.
+ * @memberOf module:js-build-tools
+ * @param {Function} [done]
+ * @returns {*}
+ */
+export const docs = (done = null) => (resolveDocsMethod() === 'jsdoc' ? jsdocDocs : typeDocs)(done)

package/functions/docs.test.mjs

@@ -0,0 +1,45 @@
+import * as setUp from './test-helpers/setUp.mjs'
+import { docs } from './docs.mjs'
+import { typeDocs } from './typeDocs.mjs'
+import { jsdocDocs } from './jsdocDocs.mjs'
+
+const genericFunction = () => Promise.resolve(true)
+
+jest.mock('./typeDocs.mjs', () => ({ typeDocs: jest.fn(genericFunction) }))
+jest.mock('./jsdocDocs.mjs', () => ({ jsdocDocs: jest.fn(genericFunction) }))
+
+setUp.setDefaults('test-docs')
+const gulpConfig = setUp.gulpConfig
+
+beforeEach(() => setUp.beforeEach().then(() => {
+  typeDocs.mockClear()
+  jsdocDocs.mockClear()
+}))
+
+afterEach(setUp.afterEach)
+
+describe('docs', () => {
+  test('runs jsdocDocs when resolveDocsMethod infers jsdoc', async () => {
+    gulpConfig.set('typescript.enabled', false)
+    gulpConfig.set('docs.method', false)
+    await docs()
+    expect(jsdocDocs).toHaveBeenCalledTimes(1)
+    expect(typeDocs).not.toHaveBeenCalled()
+  })
+
+  test('runs typeDocs when resolveDocsMethod infers typedoc', async () => {
+    gulpConfig.set('typescript.enabled', true)
+    gulpConfig.set('docs.method', false)
+    await docs()
+    expect(typeDocs).toHaveBeenCalledTimes(1)
+    expect(jsdocDocs).not.toHaveBeenCalled()
+  })
+
+  test('docs.method overrides the typescript.enabled inference either way', async () => {
+    gulpConfig.set('typescript.enabled', true)
+    gulpConfig.set('docs.method', 'jsdoc')
+    await docs()
+    expect(jsdocDocs).toHaveBeenCalledTimes(1)
+    expect(typeDocs).not.toHaveBeenCalled()
+  })
+})

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

@@ -0,0 +1,10 @@
+import * as gulpConfig from '../../gulp.config.mjs'
+
+/**
+ * Pick which engine generates the HTML documentation: docs.method picks it explicitly; left unset (false, the
+ * default), it's inferred from typescript.enabled - every existing TypeScript project's config, which never
+ * sets method, keeps producing TypeDoc output exactly as it always has.
+ * @memberOf module:partials
+ * @returns {'typedoc'|'jsdoc'}
+ */
+export const resolveDocsMethod = () => gulpConfig.get('docs.method') || (gulpConfig.get('typescript.enabled') ? 'typedoc' : 'jsdoc')

package/functions/partials/resolveDocsMethod.test.mjs

@@ -0,0 +1,33 @@
+import * as setUp from '../test-helpers/setUp.mjs'
+import { resolveDocsMethod } from './resolveDocsMethod.mjs'
+
+setUp.setDefaults('test-resolve-docs-method')
+const gulpConfig = setUp.gulpConfig
+
+beforeEach(setUp.beforeEach)
+
+afterEach(setUp.afterEach)
+
+describe('resolveDocsMethod', () => {
+  test('infers jsdoc when typescript.enabled is false and docs.method is unset', () => {
+    gulpConfig.set('typescript.enabled', false)
+    gulpConfig.set('docs.method', false)
+    expect(resolveDocsMethod()).toBe('jsdoc')
+  })
+
+  test('infers typedoc when typescript.enabled is true and docs.method is unset', () => {
+    gulpConfig.set('typescript.enabled', true)
+    gulpConfig.set('docs.method', false)
+    expect(resolveDocsMethod()).toBe('typedoc')
+  })
+
+  test('docs.method overrides the typescript.enabled inference either way', () => {
+    gulpConfig.set('typescript.enabled', true)
+    gulpConfig.set('docs.method', 'jsdoc')
+    expect(resolveDocsMethod()).toBe('jsdoc')
+
+    gulpConfig.set('typescript.enabled', false)
+    gulpConfig.set('docs.method', 'typedoc')
+    expect(resolveDocsMethod()).toBe('typedoc')
+  })
+})

package/functions/partials.mjs

@@ -16,10 +16,12 @@ export { distForSrc } from './partials/distForSrc.mjs'
 export { distSeries } from './partials/distSeries.mjs'
 export { imagesFor } from './partials/imagesFor.mjs'
 export { importModule, importPeer, requirePeer } from './partials/loadPeer.mjs'
+export { jsdocDocsFor } from './partials/jsdocDocsFor.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 { resolveDocsMethod } from './partials/resolveDocsMethod.mjs'
 export { runOnChange } from './partials/runOnChange.mjs'
 export { sassFor } from './partials/sassFor.mjs'
 export { tsFor } from './partials/tsFor.mjs'

package/functions/partials.test.mjs

@@ -2,6 +2,6 @@ import * as partials from './partials.mjs'
 
 describe('partials', () => {
   test('is object with all partial exports', () => {
-    expect(Object.keys(partials).length).toBe(19)
+    expect(Object.keys(partials).length).toBe(21)
   })
 })

package/gulp.config.mjs

@@ -45,6 +45,15 @@ import { fileExists } from 'test-filesystem'
  * Any single configuration option is a Setting.
  * @typedef {ArrayableSetting|BooleanSetting|FlagsSetting|StringSetting} Setting
  */
+/**
+ * One copy-files entry: a glob (or array of globs) to copy, and where to copy it.
+ * @typedef {Object} module:gulpConfig~CopyFilesEntry
+ * @property {ArrayableSetting} from - The glob pattern(s) of files to copy.
+ * @property {StringSetting} to - The directory to copy them into.
+ * @property {FlagStringSetting} base - Optional base for gulp's own src(pattern, {base}), to preserve a glob's
+ * own subdirectory structure in the destination instead of flattening it. false (the default) uses gulp's own
+ * default base behaviour.
+ */
 /**
  * Configurations for building the browser files.
  * @typedef {Object<string, Setting>} module:gulpConfig~BrowserConfig
@@ -119,16 +128,24 @@ import { fileExists } from 'test-filesystem'
  * @property {StringSetting} to - The directory to output the readme file in.
  */
 /**
- * Configurations for generating the HTML documentation of a TypeScript project (with TypeDoc, from the source).
+ * Configurations for generating the HTML documentation of a project's own source, with either TypeDoc (real
+ * TypeScript types) or jsdoc (a modern theme over jsdoc's own classic default) - see docs.method.
  * @typedef {Object<string, Setting>} module:gulpConfig~DocsConfig
- * @property {BooleanSetting} enabled - Toggle generating the documentation from the TypeScript source. When it is on the
+ * @property {BooleanSetting} enabled - Toggle generating the documentation from the source. When it is on the
  * build does this instead of generating the readme from the jsdoc comments of the compiled files.
- * @property {StringSetting} from - The directory holding the TypeScript source, each folder in it becomes a module.
+ * @property {StringSetting} from - The directory holding the source, each folder in it becomes a module (TypeDoc) or
+ * is scanned recursively (jsdoc).
  * @property {StringSetting} index - The markdown file used as the front page of the documentation.
- * @property {StringSetting} logLevel - How much TypeDoc reports: Verbose, Info, Warn, Error or None.
+ * @property {StringSetting} logLevel - How much TypeDoc reports: Verbose, Info, Warn, Error or None. Not used by jsdoc.
+ * @property {FlagStringSetting} method - 'typedoc' or 'jsdoc'. False (the default) infers it from typescript.enabled -
+ * 'typedoc' when on, 'jsdoc' when off - so an existing TypeScript project's config needs no change to keep working
+ * exactly as it already does; set this explicitly to override that inference either way.
+ * @property {StringSetting} theme - The jsdoc theme package to use (only meaningful when method is 'jsdoc' - TypeDoc
+ * keeps its own default regardless). Defaults to 'clean-jsdoc-theme'.
  * @property {StringSetting} title - The name of the documentation, defaults to the name in the package.json.
  * @property {StringSetting} to - The directory to generate the documentation in (it is cleared first).
- * @property {FlagStringSetting} tsconfig - The tsconfig file to read the source with, defaults to the one of typescript.config.
+ * @property {FlagStringSetting} tsconfig - The tsconfig file to read the source with (TypeDoc only), defaults to the
+ * one of typescript.config.
  */
 /**
  * Configurations to compile and copy the sass files into css.
@@ -159,6 +176,9 @@ import { fileExists } from 'test-filesystem'
  * @typedef {Object<string, Setting>} module:gulpConfig~Configurations
  * @property {BrowserConfig} browser - Browser bundling configuration group.
  * @property {ArrayableSetting} cleanPaths - The paths for directories to delete before build.
+ * @property {Array<CopyFilesEntry>} copyFiles - Files to copy elsewhere, run via the copyFiles task - never
+ * automatically as part of build, since what this copies is often the live, publicly-reachable version of
+ * something (e.g. a bundle), and publishing it should be a deliberate step.
  * @property {DistConfig} dist - Distribution file generation configuration group.
  * @property {DocsConfig} docs - Generate the documentation of a TypeScript project configuration group.
  * @property {FontConfig} fonts - Fonts copy configuration group.
@@ -187,6 +207,7 @@ const setDefaults = {
     to: 'browser',
   },
   cleanPaths: ['dist', 'browser'],
+  copyFiles: [],
   dist: {
     from: 'src/**/!(*.test).js',
     main: 'dist/main',
@@ -197,6 +218,8 @@ const setDefaults = {
     from: 'src',
     index: 'MAIN.md',
     logLevel: 'Warn',
+    method: false,
+    theme: 'clean-jsdoc-theme',
     title: '',
     to: 'docs',
     tsconfig: false,