js-build-tools 6.5.0 → 6.7.0

package/functions/partials/jsdocDocsFor.test.mjs

@@ -1,152 +1,182 @@
-import fs from 'fs'
-import path from 'node:path'
-import * as setUp from '../test-helpers/setUp.mjs'
-import { jsdocDocsFor, resolveJsdocBin, resolveJsdocTheme } from './jsdocDocsFor.mjs'
-import jsdocBase from '../../jsdoc.base.js'
-
-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'))])
-    // Headings of the front page get ids, so the theme's table of contents can follow them
-    expect(calls.config.markdown).toEqual({ idInHeadings: true })
-  })
-
-  test('passes on what jsdoc reports', async () => {
-    gulpConfig.set('docs.enabled', true)
-    const srcPath = gulpConfig.get('srcPath')
-    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
-    const calls = {}
-    const reporting = (bin, args) => fakeRunJsdoc(calls)(bin, args).then(() => ({ stdout: '', stderr: 'WARNING: a page failed\n' }))
-    await jsdocDocsFor(srcPath, `${srcPath}/../docs`, reporting)()
-    expect(warn).toHaveBeenCalledWith('WARNING: a page failed')
-    warn.mockClear()
-    await jsdocDocsFor(srcPath, `${srcPath}/../docs`, fakeRunJsdoc(calls))()
-    expect(warn).not.toHaveBeenCalled()
-    warn.mockRestore()
-  })
-
-  test('takes a list of directories and files to document', async () => {
-    gulpConfig.set('docs.enabled', true)
-    const srcPath = gulpConfig.get('srcPath')
-    const calls = {}
-    await jsdocDocsFor([srcPath, `${srcPath}/../gulp.config.mjs`], `${srcPath}/../docs`, fakeRunJsdoc(calls))()
-    expect(calls.config.source.include).toEqual([path.resolve(srcPath), path.resolve(`${srcPath}/../gulp.config.mjs`)])
-  })
-
-  test('documents .js, .mjs and .cjs files, but not tests or minified copies', () => {
-    const include = new RegExp(jsdocBase.source.includePattern)
-    const exclude = new RegExp(jsdocBase.source.excludePattern)
-    const documented = file => include.test(file) && !exclude.test(file)
-    expect(['a.js', 'a.mjs', 'a.cjs', 'dir/a.mjs'].filter(documented)).toEqual(['a.js', 'a.mjs', 'a.cjs', 'dir/a.mjs'])
-    expect(['a.test.mjs', 'a.min.js', 'a.min.mjs', 'dir/_private.mjs', 'a.ts'].filter(documented)).toEqual([])
-  })
-
-  test('passes docs.title to the theme as a link to the home page of the docs and as its page title, and leaves it out when unset', async () => {
-    gulpConfig.set('docs.enabled', true)
-    const srcPath = gulpConfig.get('srcPath')
-    const calls = {}
-    gulpConfig.set('docs.title', 'Tom & Jerry <Tools>')
-    await jsdocDocsFor(srcPath, `${srcPath}/../docs`, fakeRunJsdoc(calls))()
-    expect(calls.config.opts.theme_opts).toEqual({
-      title: '<a href="index.html" class="sidebar-title sidebar-title-anchor">Tom &amp; Jerry &lt;Tools&gt;</a>',
-      homepageTitle: 'Tom &amp; Jerry &lt;Tools&gt;'
-    })
-
-    gulpConfig.set('docs.title', '')
-    await jsdocDocsFor(srcPath, `${srcPath}/../docs`, fakeRunJsdoc(calls))()
-    expect(calls.config.opts.theme_opts).toBeUndefined()
-  })
-
-  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)
-    gulpConfig.set('docs.title', 'Tom & Jerry')
-    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)
-    expect(fs.readFileSync(`${outPath}/index.html`, 'utf8')).toMatch(/<title>\s*Tom &amp; Jerry\s*<\/title>/)
-  }, 30000)
-})
+import fs from 'fs'
+import path from 'node:path'
+import * as setUp from '../test-helpers/setUp.mjs'
+import { jsdocDocsFor, resolveJsdocBin, resolveJsdocTheme } from './jsdocDocsFor.mjs'
+import jsdocBase from '../../jsdoc.base.js'
+
+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'))
+    calls.readme = fs.readFileSync(calls.config.opts.readme, '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'))])
+    // Headings of the front page get ids, so the theme's table of contents can follow them
+    expect(calls.config.markdown).toEqual({ idInHeadings: true })
+  })
+
+  test('passes on what jsdoc reports', async () => {
+    gulpConfig.set('docs.enabled', true)
+    const srcPath = gulpConfig.get('srcPath')
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+    const calls = {}
+    const reporting = (bin, args) => fakeRunJsdoc(calls)(bin, args).then(() => ({ stdout: '', stderr: 'WARNING: a page failed\n' }))
+    await jsdocDocsFor(srcPath, `${srcPath}/../docs`, reporting)()
+    expect(warn).toHaveBeenCalledWith('WARNING: a page failed')
+    warn.mockClear()
+    await jsdocDocsFor(srcPath, `${srcPath}/../docs`, fakeRunJsdoc(calls))()
+    expect(warn).not.toHaveBeenCalled()
+    warn.mockRestore()
+  })
+
+  test('takes a list of directories and files to document', async () => {
+    gulpConfig.set('docs.enabled', true)
+    const srcPath = gulpConfig.get('srcPath')
+    const calls = {}
+    await jsdocDocsFor([srcPath, `${srcPath}/../gulp.config.mjs`], `${srcPath}/../docs`, fakeRunJsdoc(calls))()
+    expect(calls.config.source.include).toEqual([path.resolve(srcPath), path.resolve(`${srcPath}/../gulp.config.mjs`)])
+  })
+
+  test('documents .js, .mjs and .cjs files, but not tests or minified copies', () => {
+    const include = new RegExp(jsdocBase.source.includePattern)
+    const exclude = new RegExp(jsdocBase.source.excludePattern)
+    const documented = file => include.test(file) && !exclude.test(file)
+    expect(['a.js', 'a.mjs', 'a.cjs', 'dir/a.mjs'].filter(documented)).toEqual(['a.js', 'a.mjs', 'a.cjs', 'dir/a.mjs'])
+    expect(['a.test.mjs', 'a.min.js', 'a.min.mjs', 'dir/_private.mjs', 'a.ts'].filter(documented)).toEqual([])
+  })
+
+  test('passes docs.title to the theme as a link to the home page of the docs and as its page title, and leaves it out when unset', async () => {
+    gulpConfig.set('docs.enabled', true)
+    const srcPath = gulpConfig.get('srcPath')
+    const calls = {}
+    gulpConfig.set('docs.title', 'Tom & Jerry <Tools>')
+    await jsdocDocsFor(srcPath, `${srcPath}/../docs`, fakeRunJsdoc(calls))()
+    expect(calls.config.opts.theme_opts).toEqual({
+      title: '<a href="index.html" class="sidebar-title sidebar-title-anchor">Tom &amp; Jerry &lt;Tools&gt;</a>',
+      homepageTitle: 'Tom &amp; Jerry &lt;Tools&gt;'
+    })
+
+    expect(calls.config.opts.siteName).toBe('Tom & Jerry <Tools>')
+
+    gulpConfig.set('docs.title', '')
+    await jsdocDocsFor(srcPath, `${srcPath}/../docs`, fakeRunJsdoc(calls))()
+    expect(calls.config.opts.theme_opts).toBeUndefined()
+    expect(calls.config.opts.siteName).toBeUndefined()
+  })
+
+  test('passes docs.basePath to the theme, and leaves it out when unset', async () => {
+    gulpConfig.set('docs.enabled', true)
+    const srcPath = gulpConfig.get('srcPath')
+    const calls = {}
+    gulpConfig.set('docs.basePath', '/projects/tools/docs/')
+    await jsdocDocsFor(srcPath, `${srcPath}/../docs`, fakeRunJsdoc(calls))()
+    expect(calls.config.opts.basePath).toBe('/projects/tools/docs/')
+
+    gulpConfig.set('docs.basePath', false)
+    await jsdocDocsFor(srcPath, `${srcPath}/../docs`, fakeRunJsdoc(calls))()
+    expect(calls.config.opts.basePath).toBeUndefined()
+  })
+
+  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 falls back to one with the title 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')
+    gulpConfig.set('docs.title', 'Tom & Jerry')
+    await jsdocDocsFor(gulpConfig.get('srcPath'), `${gulpConfig.get('srcPath')}/../docs`, fakeRunJsdoc(calls))()
+    expect(calls.readme).toBe('# Tom & Jerry\n')
+    // The fallback is written to a temporary folder, which is removed afterwards
+    expect(fs.existsSync(calls.config.opts.readme)).toBe(false)
+  })
+
+  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)
+    gulpConfig.set('docs.title', 'Tom & Jerry')
+    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)
+    expect(fs.readFileSync(`${outPath}/index.html`, 'utf8')).toMatch(/<title>[^<]*Tom &amp; Jerry\s*<\/title>/)
+  }, 30000)
+
+  test('starts every link at docs.basePath, for documentation served below the site root', async () => {
+    gulpConfig.set('docs.enabled', true)
+    gulpConfig.set('docs.basePath', '/projects/tools/docs/')
+    const outPath = `${gulpConfig.get('srcPath')}/../docs`
+    await jsdocDocsFor(gulpConfig.get('srcPath'), outPath)()
+    const links = [...fs.readFileSync(`${outPath}/index.html`, 'utf8').matchAll(/(?:href|src)="(\/[^"]*)"/g)].map(match => match[1])
+    expect(links.length).toBeGreaterThan(0)
+    expect(links.filter(link => !link.startsWith('/projects/tools/docs'))).toEqual([])
+  }, 30000)
+})

package/functions/partials/lintSource.mjs

@@ -1,41 +1,41 @@
-import * as gulpConfig from '../../gulp.config.mjs'
-import { dest, src } from 'gulp'
-import { neostandardLint } from './neostandardLint.mjs'
-import { Transform } from 'node:stream'
-
-/**
- * Lint the project's source (srcPath: .js, .mjs and .cjs, plus .ts when typescript.enabled) with neostandard and
- * write the automatic fixes back in place. Shared by the sourceLint (build) and lint (standalone) tasks.
- * @memberOf module:partials
- * @param {Object} [options={}]
- * @param {boolean} [options.failOnError=false] - Fail once linting finishes if any errors could not be fixed.
- * @returns {stream.Stream}
- */
-export const lintSource = ({ failOnError = false } = {}) => {
-  const srcPath = gulpConfig.get('srcPath')
-  const ts = gulpConfig.get('typescript.enabled')
-  const patterns = [`${srcPath}/**/*.{js,mjs,cjs}`]
-  if (ts) {
-    patterns.push(`${srcPath}/**/*.ts`)
-  }
-  const linter = neostandardLint({ fix: true, ts, rules: gulpConfig.get('lint.rules') })
-  // Fail only once dest() has written every fixed file: gulp exits as soon as a task fails, so failing from the
-  // linter itself (before dest() finished) could leave a file that dest() had opened, but not yet written, empty.
-  // dest() passes each file on only after writing it, so this last step's flush runs after the final write. Files
-  // are consumed here rather than passed on, so nothing downstream has to read them.
-  const written = new Transform({
-    objectMode: true,
-    transform: (file, enc, callback) => callback(),
-    flush: callback => failOnError && linter.totals.errors
-      ? callback(new Error(`neostandard found ${linter.totals.errors} lint error(s) that could not be fixed automatically.`))
-      : callback()
-  })
-  const saved = src(patterns)
-    .pipe(linter)
-    .pipe(dest(srcPath))
-  saved.pipe(written)
-  // pipe() does not forward errors, and gulp only watches the returned stream, so pass any failure along.
-  linter.on('error', error => written.destroy(error))
-  saved.on('error', error => written.destroy(error))
-  return written
-}
+import * as gulpConfig from '../../gulp.config.mjs'
+import { dest, src } from 'gulp'
+import { neostandardLint } from './neostandardLint.mjs'
+import { Transform } from 'node:stream'
+
+/**
+ * Lint the project's source (srcPath: .js, .mjs and .cjs, plus .ts when typescript.enabled) with neostandard and
+ * write the automatic fixes back in place. Shared by the sourceLint (build) and lint (standalone) tasks.
+ * @memberOf module:partials
+ * @param {Object} [options={}]
+ * @param {boolean} [options.failOnError=false] - Fail once linting finishes if any errors could not be fixed.
+ * @returns {stream.Stream}
+ */
+export const lintSource = ({ failOnError = false } = {}) => {
+  const srcPath = gulpConfig.get('srcPath')
+  const ts = gulpConfig.get('typescript.enabled')
+  const patterns = [`${srcPath}/**/*.{js,mjs,cjs}`]
+  if (ts) {
+    patterns.push(`${srcPath}/**/*.ts`)
+  }
+  const linter = neostandardLint({ fix: true, ts, rules: gulpConfig.get('lint.rules') })
+  // Fail only once dest() has written every fixed file: gulp exits as soon as a task fails, so failing from the
+  // linter itself (before dest() finished) could leave a file that dest() had opened, but not yet written, empty.
+  // dest() passes each file on only after writing it, so this last step's flush runs after the final write. Files
+  // are consumed here rather than passed on, so nothing downstream has to read them.
+  const written = new Transform({
+    objectMode: true,
+    transform: (file, enc, callback) => callback(),
+    flush: callback => failOnError && linter.totals.errors
+      ? callback(new Error(`neostandard found ${linter.totals.errors} lint error(s) that could not be fixed automatically.`))
+      : callback()
+  })
+  const saved = src(patterns)
+    .pipe(linter)
+    .pipe(dest(srcPath))
+  saved.pipe(written)
+  // pipe() does not forward errors, and gulp only watches the returned stream, so pass any failure along.
+  linter.on('error', error => written.destroy(error))
+  saved.on('error', error => written.destroy(error))
+  return written
+}

package/functions/partials/loadPeer.mjs

@@ -1,76 +1,76 @@
-import { createRequire } from 'node:module'
-import path from 'node:path'
-import { pathToFileURL } from 'node:url'
-
-// Several dependencies ship ESM-only (standard, gulp-ts-compile, typedoc), but this package also publishes a CommonJS
-// build (dist/*.js) whose babel transform would turn even a dynamic import() into a require() that cannot load an ES
-// module. Hiding the import() inside a Function constructor keeps it a genuine dynamic import that works from either
-// build, because babel cannot see (and so cannot rewrite) an import expression which only exists as a runtime string.
-// eslint-disable-next-line no-new-func -- deliberate, see above
-const dynamicImport = new Function('specifier', 'return import(specifier)')
-
-/**
- * Import an ES module (or any module) with a real dynamic import(), whichever build (ESM or CommonJS) this runs from.
- * @memberOf module:partials
- * @param {string} specifier - The package name, or the URL of a file.
- * @returns {Promise<Object>} The module namespace.
- */
-export const importModule = specifier => dynamicImport(specifier)
-
-const isMissing = (error, name) => error.code === 'MODULE_NOT_FOUND' && error.message.includes(`'${name}'`)
-
-const notInstalled = (name, { task, installHint }) => new Error(
-  `The ${task} task needs the optional peer dependency ${name}, which is not installed. ${installHint}`
-)
-
-/**
- * Load an optional peer dependency (one which is only needed once a task runs, so projects which never use that task
- * do not have to install it) with require(), from the project being built rather than from this package. When it is
- * missing the error explains how to install it.
- * @memberOf module:partials
- * @param {string} name - The package name.
- * @param {Object} options
- * @param {string} options.task - The task which needs the package, for the error message.
- * @param {string} options.installHint - How to install it, for the error message.
- * @param {string} [options.esmOnlyMessage] - The error message when the package turns out to be ESM-only (it cannot be require()d).
- * @param {string} [options.projectPath=process.cwd()] - The folder of the project (which has the package.json) being built.
- * @returns {*} Whatever the package exports.
- * @throws {Error} With install instructions when the package is not installed.
- */
-export const requirePeer = (name, { task, installHint, esmOnlyMessage, projectPath = process.cwd() }) => {
-  try {
-    return createRequire(path.join(projectPath, 'package.json'))(name)
-  } catch (error) {
-    if (isMissing(error, name)) {
-      throw notInstalled(name, { task, installHint })
-    }
-    if (error.code === 'ERR_REQUIRE_ESM' && esmOnlyMessage) {
-      throw new Error(esmOnlyMessage)
-    }
-    throw error
-  }
-}
-
-/**
- * Import an optional peer dependency which ships ESM-only, from the project being built. See {@link requirePeer}.
- * @memberOf module:partials
- * @param {string} name - The package name.
- * @param {Object} options
- * @param {string} options.task - The task which needs the package, for the error message.
- * @param {string} options.installHint - How to install it, for the error message.
- * @param {string} [options.projectPath=process.cwd()] - The folder of the project (which has the package.json) being built.
- * @returns {Promise<Object>} The module namespace.
- * @throws {Error} With install instructions when the package is not installed.
- */
-export const importPeer = async (name, { task, installHint, projectPath = process.cwd() }) => {
-  let resolved
-  try {
-    resolved = createRequire(path.join(projectPath, 'package.json')).resolve(name)
-  } catch (error) {
-    if (isMissing(error, name)) {
-      throw notInstalled(name, { task, installHint })
-    }
-    throw error
-  }
-  return importModule(pathToFileURL(resolved).href)
-}
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+// Several dependencies ship ESM-only (standard, gulp-ts-compile, typedoc), but this package also publishes a CommonJS
+// build (dist/*.js) whose babel transform would turn even a dynamic import() into a require() that cannot load an ES
+// module. Hiding the import() inside a Function constructor keeps it a genuine dynamic import that works from either
+// build, because babel cannot see (and so cannot rewrite) an import expression which only exists as a runtime string.
+// eslint-disable-next-line no-new-func -- deliberate, see above
+const dynamicImport = new Function('specifier', 'return import(specifier)')
+
+/**
+ * Import an ES module (or any module) with a real dynamic import(), whichever build (ESM or CommonJS) this runs from.
+ * @memberOf module:partials
+ * @param {string} specifier - The package name, or the URL of a file.
+ * @returns {Promise<Object>} The module namespace.
+ */
+export const importModule = specifier => dynamicImport(specifier)
+
+const isMissing = (error, name) => error.code === 'MODULE_NOT_FOUND' && error.message.includes(`'${name}'`)
+
+const notInstalled = (name, { task, installHint }) => new Error(
+  `The ${task} task needs the optional peer dependency ${name}, which is not installed. ${installHint}`
+)
+
+/**
+ * Load an optional peer dependency (one which is only needed once a task runs, so projects which never use that task
+ * do not have to install it) with require(), from the project being built rather than from this package. When it is
+ * missing the error explains how to install it.
+ * @memberOf module:partials
+ * @param {string} name - The package name.
+ * @param {Object} options
+ * @param {string} options.task - The task which needs the package, for the error message.
+ * @param {string} options.installHint - How to install it, for the error message.
+ * @param {string} [options.esmOnlyMessage] - The error message when the package turns out to be ESM-only (it cannot be require()d).
+ * @param {string} [options.projectPath=process.cwd()] - The folder of the project (which has the package.json) being built.
+ * @returns {*} Whatever the package exports.
+ * @throws {Error} With install instructions when the package is not installed.
+ */
+export const requirePeer = (name, { task, installHint, esmOnlyMessage, projectPath = process.cwd() }) => {
+  try {
+    return createRequire(path.join(projectPath, 'package.json'))(name)
+  } catch (error) {
+    if (isMissing(error, name)) {
+      throw notInstalled(name, { task, installHint })
+    }
+    if (error.code === 'ERR_REQUIRE_ESM' && esmOnlyMessage) {
+      throw new Error(esmOnlyMessage)
+    }
+    throw error
+  }
+}
+
+/**
+ * Import an optional peer dependency which ships ESM-only, from the project being built. See {@link requirePeer}.
+ * @memberOf module:partials
+ * @param {string} name - The package name.
+ * @param {Object} options
+ * @param {string} options.task - The task which needs the package, for the error message.
+ * @param {string} options.installHint - How to install it, for the error message.
+ * @param {string} [options.projectPath=process.cwd()] - The folder of the project (which has the package.json) being built.
+ * @returns {Promise<Object>} The module namespace.
+ * @throws {Error} With install instructions when the package is not installed.
+ */
+export const importPeer = async (name, { task, installHint, projectPath = process.cwd() }) => {
+  let resolved
+  try {
+    resolved = createRequire(path.join(projectPath, 'package.json')).resolve(name)
+  } catch (error) {
+    if (isMissing(error, name)) {
+      throw notInstalled(name, { task, installHint })
+    }
+    throw error
+  }
+  return importModule(pathToFileURL(resolved).href)
+}