js-build-tools 6.2.2 → 6.3.0

package/dist/utilities/isObject.js

@@ -9,6 +9,7 @@ exports.isObject = void 0;
  * Original source concepts from {@link https://github.com/jheagle/si-funciona/blob/main/src/helpers/objects/isObject.ts Sí, funciona}
  * @param {*} object
  * @returns {boolean}
+ * @private
  */
 const isObject = object => typeof object === 'object' && object !== null;
 exports.isObject = isObject;

package/dist/utilities/strAfter.js

@@ -10,6 +10,7 @@ exports.strAfter = void 0;
  * @param {string} str
  * @param {string} search
  * @returns {string}
+ * @private
  */
 const strAfter = (str, search) => {
   const index = str.indexOf(search);

package/dist/utilities/strBefore.js

@@ -10,6 +10,7 @@ exports.strBefore = void 0;
  * @param {string} str
  * @param {string} search
  * @returns {string}
+ * @private
  */
 const strBefore = (str, search) => {
   const index = str.indexOf(search);

package/functions/bundle.mjs

@@ -14,7 +14,7 @@ import { getBundleConfigs } from './utilities/getBundleConfigs.mjs'
  *
  * A bundle's name does double duty: it names the output file (name.js) and, via browserify's
  * `standalone` option, is also the name its exports are exposed under - as a global when loaded
- * with a bare <script> tag, or as the module when required via CommonJS/AMD. Without this, a
+ * with a bare `<script>` tag, or as the module when required via CommonJS/AMD. Without this, a
  * bundle built from a real entry point (one that actually exports something) builds successfully
  * but exposes nothing a consumer can reach.
  *

package/functions/jsdocEsmExports.test.mjs

@@ -0,0 +1,24 @@
+import path from 'node:path'
+import jsdocBase from '../jsdoc.base.js'
+import { handlers } from '../jsdoc.esmExports.js'
+
+describe('jsdoc.esmExports', () => {
+  test('is one of the plugins in jsdoc.base', () => {
+    expect(jsdocBase.plugins).toContain(path.resolve('jsdoc.esmExports.js'))
+  })
+
+  test('drops the exports. jsdoc gives a documented export of a file without its own @module tag', () => {
+    const doclet = { name: 'exports.build', longname: 'module:js-build-tools.exports.build' }
+    handlers.newDoclet({ doclet })
+    expect(doclet).toEqual({ name: 'build', longname: 'module:js-build-tools.build' })
+  })
+
+  test('leaves every other name as it is', () => {
+    const doclet = { name: 'build', longname: 'module:js-build-tools.build' }
+    handlers.newDoclet({ doclet })
+    expect(doclet).toEqual({ name: 'build', longname: 'module:js-build-tools.build' })
+    const exportsless = { name: 'exportsThing', longname: 'exportsThing' }
+    handlers.newDoclet({ doclet: exportsless })
+    expect(exportsless).toEqual({ name: 'exportsThing', longname: 'exportsThing' })
+  })
+})

package/functions/partials/jsdocDocsFor.mjs

@@ -6,14 +6,16 @@ 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).
+// jsdoc.base.js is CommonJS (it's also required directly by consuming projects' own .jsdoc.conf.js) - 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 escapeHtml = text => String(text).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+
 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}`
 
@@ -60,11 +62,9 @@ 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).
+ * Resolve a jsdoc theme package's own template directory, for jsdoc's own opts.template config key: the folder
+ * holding its publish.js. That is the package root for a classic jsdoc template (clean-jsdoc-theme 4.x included),
+ * but `dist` for a bundled one (clean-jsdoc-theme 5.x).
  * @memberOf module:partials
  * @param {string} name
  * @param {string} [projectPath=process.cwd()]
@@ -72,7 +72,8 @@ export const resolveJsdocBin = (projectPath = process.cwd()) =>
  */
 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
+  const distDir = path.join(packageDir, 'dist')
+  return fs.existsSync(path.join(distDir, 'publish.js')) ? distDir : packageDir
 }
 
 /**
@@ -82,7 +83,8 @@ export const resolveJsdocTheme = (name, projectPath = process.cwd()) => {
  * 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|Array<string>} [srcPath=gulpConfig.get('docs.from')] - The directory (or directories and files) 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.
@@ -100,12 +102,13 @@ export const jsdocDocsFor = (
       const theme = gulpConfig.get('docs.theme') || 'clean-jsdoc-theme'
       const themeDir = resolveJsdocTheme(theme)
       const indexFile = gulpConfig.get('docs.index')
+      const title = gulpConfig.get('docs.title')
       await removeDirectory(outPath)
       const config = {
         ...jsdocBase,
         source: {
           ...jsdocBase.source,
-          include: [path.resolve(srcPath)]
+          include: [].concat(srcPath).map(includePath => path.resolve(includePath))
         },
         opts: {
           destination: path.resolve(outPath),
@@ -114,6 +117,9 @@ export const jsdocDocsFor = (
           // quick-start example, which sets this explicitly, not assumed from jsdoc's own classic defaults.
           recurse: true,
           template: themeDir,
+          // clean-jsdoc-theme's own option for the name in its header. Given as a link: a plain-text title links to the
+          // site root ("/"), while every page is in one folder, so index.html is the home page wherever they are served
+          ...(title ? { theme_opts: { title: `<a href="index.html" class="sidebar-title sidebar-title-anchor">${escapeHtml(title)}</a>` } } : {}),
           ...(indexFile && fs.existsSync(indexFile) ? { readme: path.resolve(indexFile) } : {})
         }
       }
@@ -122,7 +128,13 @@ export const jsdocDocsFor = (
         const configPath = path.join(workDir, 'jsdoc.conf.json')
         fs.writeFileSync(configPath, JSON.stringify(config))
         const bin = resolveJsdocBin()
-        await runJsdoc(bin, ['-c', configPath])
+        // Pass on what jsdoc and the theme report (warnings such as a page which failed to render), which would
+        // otherwise be lost with the captured output
+        const { stdout = '', stderr = '' } = (await runJsdoc(bin, ['-c', configPath])) || {}
+        const report = `${stdout}${stderr}`.trim()
+        if (report) {
+          console.warn(report)
+        }
       } finally {
         await removeDirectory(workDir)
       }

package/functions/partials/jsdocDocsFor.test.mjs

@@ -2,6 +2,7 @@ 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
@@ -57,6 +58,53 @@ describe('jsdocDocsFor', () => {
     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 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>'
+    })
+
+    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 () => {

package/functions/partials/loadPlaywright.mjs

@@ -0,0 +1,23 @@
+import { requirePeer } from './loadPeer.mjs'
+
+const installHint = 'Install it in your project with: npm install --save-dev playwright'
+
+/**
+ * Find Playwright (headless-browser automation) of the project being built, an optional peer dependency only
+ * needed by whatever actually drives a real browser - projects which never do never need it installed.
+ * @memberOf module:partials
+ * @param {string} [projectPath=process.cwd()] The folder of the project (which has the package.json) being built.
+ * @returns {Object} The Playwright module.
+ * @throws {Error} With install instructions when playwright is not installed.
+ */
+export const loadPlaywright = (projectPath = process.cwd()) => requirePeer('playwright', { task: 'browser automation', installHint, projectPath })
+
+/**
+ * Launch a real headless Chromium browser via Playwright. See {@link loadPlaywright}.
+ * @memberOf module:partials
+ * @param {Function} [load=loadPlaywright] Which Playwright to launch - swappable in tests.
+ * @param {string} [projectPath=process.cwd()] The folder of the project (which has the package.json) being built.
+ * @returns {Promise<Browser>} The running Playwright browser - close it yourself (browser.close()) once done with it.
+ * @throws {Error} With install instructions when playwright is not installed.
+ */
+export const launchBrowser = (load = loadPlaywright, projectPath = process.cwd()) => load(projectPath).chromium.launch()

package/functions/partials/loadPlaywright.test.mjs

@@ -0,0 +1,71 @@
+import fs from 'fs'
+import path from 'node:path'
+import * as setUp from '../test-helpers/setUp.mjs'
+import { loadPlaywright, launchBrowser } from './loadPlaywright.mjs'
+import { serveStatic } from './serveStatic.mjs'
+
+setUp.setDefaults('test-load-playwright')
+const gulpConfig = setUp.gulpConfig
+
+beforeEach(setUp.beforeEach)
+afterEach(setUp.afterEach)
+
+describe('loadPlaywright', () => {
+  test('explains how to install playwright when the project does not have it', () => {
+    expect(() => loadPlaywright('/')).toThrow(/optional peer dependency playwright.*npm install --save-dev playwright/)
+  })
+
+  // Unlike typedoc (ESM-only, see typeDocsFor.test.mjs), playwright is CommonJS-compatible, so its real loading can
+  // be tested directly here rather than only end to end.
+  test('loads the real playwright module from this project (its own devDependency)', () => {
+    const playwright = loadPlaywright()
+    expect(typeof playwright.chromium.launch).toBe('function')
+  })
+})
+
+describe('launchBrowser', () => {
+  test('resolves playwright (via the given loader) and launches its chromium', async () => {
+    const launch = jest.fn(() => Promise.resolve('a-real-browser'))
+    const load = jest.fn(() => ({ chromium: { launch } }))
+    await expect(launchBrowser(load, '/some/project')).resolves.toBe('a-real-browser')
+    expect(load).toHaveBeenCalledWith('/some/project')
+    expect(launch).toHaveBeenCalledTimes(1)
+  })
+
+  test('defaults to the real loadPlaywright and launches a real, working browser', async () => {
+    const browser = await launchBrowser()
+    expect(browser.isConnected()).toBe(true)
+    await browser.close()
+  }, 30000)
+})
+
+describe('a real page, served and loaded end to end', () => {
+  // The exact real-world case that motivated this partial: a page using a root-relative asset path
+  // (/style.css), which a bare file:// load resolves against the filesystem root instead of the page's own
+  // directory - serveStatic + a real browser is what actually proves this resolves correctly, not jsdom
+  // (which cannot execute <script type="module"> at all, the limitation this whole capability exists to close).
+  test('a page with a root-relative asset path loads correctly through a real server and a real browser', async () => {
+    const srcPath = gulpConfig.get('srcPath')
+    fs.mkdirSync(`${srcPath}/browser`, { recursive: true })
+    fs.writeFileSync(`${srcPath}/browser/style.css`, 'body { background-color: rgb(1, 2, 3); }')
+    fs.writeFileSync(`${srcPath}/index.html`, [
+      '<!doctype html><html><head>',
+      '<link rel="stylesheet" href="/browser/style.css">',
+      '<script type="module">document.title = \'loaded via a real module script\'</script>',
+      '</head><body></body></html>'
+    ].join(''))
+
+    const { server, url } = await serveStatic(srcPath)
+    const browser = await launchBrowser()
+    try {
+      const page = await browser.newPage()
+      await page.goto(`${url}/index.html`)
+      expect(await page.title()).toBe('loaded via a real module script')
+      const backgroundColor = await page.evaluate(() => getComputedStyle(document.body).backgroundColor)
+      expect(backgroundColor).toBe('rgb(1, 2, 3)')
+    } finally {
+      await browser.close()
+      server.close()
+    }
+  }, 30000)
+})

package/functions/partials/neostandardLint.mjs

@@ -13,6 +13,7 @@ const importNeostandard = () => importModule('neostandard')
  * migrating from `standard` keeps its globals (jest, browser, ...) without touching package.json.
  * @param {string} cwd
  * @returns {Array<string>}
+ * @private
  */
 const readEnv = cwd => {
   try {
@@ -34,7 +35,8 @@ const readEnv = cwd => {
  * @param {boolean} options.ts
  * @param {boolean} options.fix
  * @param {Object<string, *>} [options.rules={}]
- * @returns {Promise<import('eslint').ESLint>}
+ * @returns {Promise<ESLint>} eslint's ESLint instance
+ * @private
  */
 const buildEslint = async ({ cwd, ts, fix, rules = {} }) => {
   const { neostandard, defaultFilePatterns } = await importNeostandard()
@@ -53,7 +55,7 @@ const buildEslint = async ({ cwd, ts, fix, rules = {} }) => {
 /**
  * Print a file's lint messages, if it has any.
  * @memberOf module:partials
- * @param {import('vinyl')} file
+ * @param {Vinyl} file
  * @param {{messages: Array<{line: number, column: number, message: string}>, errorCount: number, warningCount: number}} result
  * @returns {undefined}
  */
@@ -82,7 +84,7 @@ const printFileReport = (file, result) => {
  * @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}
+ * @returns {stream.Transform}
  */
 export const neostandardLint = (
   { fix = true, ts = false, rules = {} } = {},

package/functions/partials/serveStatic.mjs

@@ -0,0 +1,47 @@
+import fs from 'node:fs'
+import http from 'node:http'
+import path from 'node:path'
+
+// A real, previously-undiscovered bug fixed here: without a Content-Type header, a browser enforces strict MIME
+// checking on <script type="module"> and refuses to load it at all - exactly the case this partial exists for.
+const contentTypes = {
+  '.css': 'text/css',
+  '.gif': 'image/gif',
+  '.html': 'text/html',
+  '.ico': 'image/x-icon',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.js': 'text/javascript',
+  '.json': 'application/json',
+  '.mjs': 'text/javascript',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2'
+}
+
+/**
+ * Serve a directory's real files over plain HTTP, for anything that needs a page loaded from a real URL rather
+ * than a bare file:// path - most commonly, a page using root-relative asset paths (/browser/...), which a
+ * file:// load resolves against the filesystem root instead of the page's own directory.
+ * @memberOf module:partials
+ * @param {string} rootDir - The directory to serve.
+ * @param {number} [port=0] - The port to listen on; 0 picks any free port.
+ * @returns {Promise<{server: http.Server, url: string}>} The running server, and its base URL - close the
+ * server yourself (server.close()) once done with it.
+ */
+export const serveStatic = (rootDir, port = 0) => new Promise((resolve, reject) => {
+  const server = http.createServer((req, res) => {
+    const filePath = path.join(rootDir, decodeURIComponent(req.url.split('?')[0]))
+    fs.readFile(filePath, (error, data) => {
+      if (error) {
+        res.statusCode = 404
+        return res.end(`Not found: ${req.url}`)
+      }
+      res.setHeader('Content-Type', contentTypes[path.extname(filePath)] || 'application/octet-stream')
+      res.end(data)
+    })
+  })
+  server.once('error', reject)
+  server.listen(port, '127.0.0.1', () => resolve({ server, url: `http://127.0.0.1:${server.address().port}` }))
+})

package/functions/partials/serveStatic.test.mjs

@@ -0,0 +1,71 @@
+import fs from 'fs'
+import path from 'node:path'
+import * as setUp from '../test-helpers/setUp.mjs'
+import { serveStatic } from './serveStatic.mjs'
+
+setUp.setDefaults('test-serve-static')
+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}/index.html`, '<!doctype html><html><body>hello</body></html>')
+    write(`${srcPath}/sub/page.html`, '<!doctype html><html><body>nested</body></html>')
+    write(`${srcPath}/module.js`, 'export default 1')
+  })
+)
+
+afterEach(setUp.afterEach)
+
+describe('serveStatic', () => {
+  test('serves real files from the given directory over a real local HTTP server', async () => {
+    const { server, url } = await serveStatic(gulpConfig.get('srcPath'))
+    try {
+      expect(url).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/)
+      const root = await fetch(`${url}/index.html`)
+      expect(await root.text()).toBe('<!doctype html><html><body>hello</body></html>')
+      const nested = await fetch(`${url}/sub/page.html`)
+      expect(await nested.text()).toBe('<!doctype html><html><body>nested</body></html>')
+    } finally {
+      server.close()
+    }
+  })
+
+  test('sends a real Content-Type, not a blank one - a browser refuses to load a <script type="module"> without one', async () => {
+    const { server, url } = await serveStatic(gulpConfig.get('srcPath'))
+    try {
+      const html = await fetch(`${url}/index.html`)
+      expect(html.headers.get('content-type')).toBe('text/html')
+      const script = await fetch(`${url}/module.js`)
+      expect(script.headers.get('content-type')).toBe('text/javascript')
+    } finally {
+      server.close()
+    }
+  })
+
+  test('responds 404 for a file that does not exist, rather than hanging or throwing', async () => {
+    const { server, url } = await serveStatic(gulpConfig.get('srcPath'))
+    try {
+      const response = await fetch(`${url}/nothing-here.html`)
+      expect(response.status).toBe(404)
+    } finally {
+      server.close()
+    }
+  })
+
+  test('two servers for the same directory each get their own free port', async () => {
+    const first = await serveStatic(gulpConfig.get('srcPath'))
+    const second = await serveStatic(gulpConfig.get('srcPath'))
+    try {
+      expect(first.url).not.toBe(second.url)
+    } finally {
+      first.server.close()
+      second.server.close()
+    }
+  })
+})

package/functions/partials/tsFor.mjs

@@ -9,7 +9,7 @@ const importGulpTsCompile = () => importModule('gulp-ts-compile')
 /**
  * Wrap a stream in a promise that resolves once it finishes writing.
  * @memberOf module:partials
- * @param {import('node:stream').Stream} stream
+ * @param {stream.Stream} stream
  * @returns {Promise<void>}
  */
 const installHint = 'Install it in your project with: npm install --save-dev typescript'
@@ -36,7 +36,7 @@ const streamToPromise = (stream) => new Promise((resolve, reject) => {
  * gulp-typescript when a removed API call started throwing under TypeScript 7.
  * @memberOf module:partials
  * @param {string} configPath - Path to a tsconfig.json file.
- * @returns {import('typescript').CompilerOptions}
+ * @returns {ts.CompilerOptions} TypeScript's compiler options
  */
 const readCompilerOptions = (ts, configPath) => {
   const configFile = ts.readConfigFile(configPath, ts.sys.readFile)

package/functions/partials/typeDocsFor.mjs

@@ -20,13 +20,18 @@ export const loadTypeDoc = (projectPath = process.cwd()) => importPeer('typedoc'
 
 const isSource = fileName => /\.(ts|tsx|mts|cts)$/.test(fileName) && !/\.d\.[cm]?ts$/.test(fileName) && !/\.(test|spec)\./.test(fileName)
 
-const listSources = dirPath => fs.readdirSync(dirPath, { withFileTypes: true }).flatMap(entry => {
-  const entryPath = path.join(dirPath, entry.name)
-  if (entry.isDirectory()) {
-    return entry.name === 'node_modules' ? [] : listSources(entryPath)
-  }
-  return isSource(entry.name) ? [entryPath] : []
-})
+const listSources = dirPath => fs.readdirSync(dirPath, { withFileTypes: true })
+  .filter(entry => entry.isFile() && isSource(entry.name))
+  .map(entry => path.join(dirPath, entry.name))
+
+// Every folder below dirPath (at any depth), named by its path from dirPath, with the source files directly in it
+const listFolders = (dirPath, prefix = '') => fs.readdirSync(dirPath, { withFileTypes: true })
+  .filter(entry => entry.isDirectory() && entry.name !== 'node_modules')
+  .flatMap(entry => {
+    const folderPath = path.join(dirPath, entry.name)
+    const name = `${prefix}${entry.name}`
+    return [{ name, path: folderPath, files: listSources(folderPath) }, ...listFolders(folderPath, `${name}/`)]
+  })
 
 const toIdentifier = fileName => fileName.replace(/[^\w$]+(\w)?/g, (match, letter) => (letter || '').toUpperCase()).replace(/^(\d)/, '_$1')
 
@@ -102,11 +107,12 @@ export const describeFile = filePath => {
 
 /**
  * Write one entry file per folder of the source directory into the entry directory. TypeDoc makes a module of every
- * entry file, so the modules of the documentation mirror the folders. The default export of each source file is
+ * entry file, so the modules of the documentation mirror the folders. Nested folders are modules of their own, named
+ * by their path (utilities/parsers), and a folder's module holds only the files directly in it. The default export of each source file is
  * re-exported under the name of the file (the source files hold one function each), and anything else a file exports
  * is re-exported as it is (that is where the types.ts files go). Index files (the barrels), tests and declaration
  * files are left out, but the first doc comment of a folder's index file becomes the description of its module.
- * A file which sits beside the folders (not an index or main file) is a module of its own, described by its header
+ * A file which sits beside the folders (not an index, main or browser file) is a module of its own, described by its header
  * comment. A source directory with no folders gets a single entry called index.
  * @memberOf module:partials
  * @param {Object} ts - The TypeScript compiler API.
@@ -117,15 +123,10 @@ export const describeFile = filePath => {
 export const writeDocEntries = (ts, srcDir, entryDir) => {
   const absoluteSrc = path.resolve(srcDir)
   fs.mkdirSync(entryDir, { recursive: true })
-  const folders = fs.readdirSync(absoluteSrc, { withFileTypes: true })
-    .filter(entry => entry.isDirectory() && entry.name !== 'node_modules')
-    .map(entry => ({ name: entry.name, path: path.join(absoluteSrc, entry.name), files: listSources(path.join(absoluteSrc, entry.name)) }))
-    .filter(folder => folder.files.length)
-  const rootFiles = fs.readdirSync(absoluteSrc, { withFileTypes: true })
-    .filter(entry => entry.isFile() && isSource(entry.name) && !/^(index|main)\./.test(entry.name))
-    .map(entry => path.join(absoluteSrc, entry.name))
-  // Folders make modules, and so do the files which sit beside them (except the barrel: index and main). A source
-  // directory with no folders gets a single module called index which holds its files.
+  const folders = listFolders(absoluteSrc).filter(folder => folder.files.some(file => !/^index\./.test(path.basename(file))))
+  const rootFiles = listSources(absoluteSrc).filter(file => !/^(index|main|browser)\./.test(path.basename(file)))
+  // Folders make modules, and so do the files which sit beside them (except the barrels: index, main and browser, the
+  // browser bundle's entry). A source directory with no folders gets a single module called index which holds its files.
   const groups = folders.length
     ? [
         ...folders,
@@ -149,8 +150,11 @@ export const writeDocEntries = (ts, srcDir, entryDir) => {
       })
     const description = group.description ?? (group.path ? describeFolder(group.path) : '')
     // TypeDoc takes the first comment of an entry file which has the @module tag as the description of the module
-    const moduleComment = description ? `/**\n${description.split('\n').map(line => ` * ${line}`.trimEnd()).join('\n')}\n * @module\n */\n\n` : ''
+    // A nested folder's module is named by its path (utilities/parsers), so it is not mistaken for its parent's
+    const moduleName = group.name.includes('/') ? ` ${group.name}` : ''
+    const moduleComment = description || moduleName ? `/**\n${description ? description.split('\n').map(line => ` * ${line}`.trimEnd()).join('\n') + '\n' : ''} * @module${moduleName}\n */\n\n` : ''
     const entryPath = path.join(entryDir, `${group.name}.ts`)
+    fs.mkdirSync(path.dirname(entryPath), { recursive: true })
     fs.writeFileSync(entryPath, moduleComment + lines.join('\n') + '\n')
     return entryPath
   })
@@ -196,7 +200,7 @@ export const typeDocsFor = (
         const tsconfig = path.join(workDir, 'tsconfig.json')
         fs.writeFileSync(tsconfig, JSON.stringify({
           ...(projectConfig ? { extends: path.resolve(projectConfig) } : {}),
-          include: [path.join(workDir, 'entries', '*.ts').split(path.sep).join('/'), path.resolve(srcPath).split(path.sep).join('/') + '/**/*.ts'],
+          include: [path.join(workDir, 'entries', '**', '*.ts').split(path.sep).join('/'), path.resolve(srcPath).split(path.sep).join('/') + '/**/*.ts'],
           exclude: [path.resolve(srcPath).split(path.sep).join('/') + '/**/*.test.*']
         }))
         const indexFile = gulpConfig.get('docs.index')

package/functions/partials/typeDocsFor.test.mjs

@@ -120,6 +120,7 @@ describe('writeDocEntries', () => {
     const srcPath = gulpConfig.get('srcPath')
     write(`${srcPath}/simulate.ts`, "/**\n * Simulate what a user does.\n */\nimport add from './point/add'\nexport const click = () => add(1, 2)\nexport default { click }\n")
     write(`${srcPath}/simulate.test.ts`, "test('x', () => {})\n")
+    write(`${srcPath}/browser.ts`, "export * from './main'\n")
     const entryDir = `${srcPath}/../entries`
     const entries = writeDocEntries(ts, srcPath, entryDir)
     expect(entries.map(entry => path.basename(entry)).sort()).toEqual(['line.ts', 'point.ts', 'simulate.ts'])
@@ -129,6 +130,28 @@ describe('writeDocEntries', () => {
     )
   })
 
+  test('makes a module of each nested folder, named by its path, holding only the files directly in it', () => {
+    const srcPath = gulpConfig.get('srcPath')
+    write(`${srcPath}/point/polar/to-polar.ts`, 'export default (x: number): number => x\n')
+    write(`${srcPath}/point/polar/index.ts`, "/**\n * Polar coordinates.\n */\nexport * from './to-polar'\n")
+    write(`${srcPath}/point/deep/index.ts`, "export * from './deeper/far'\n")
+    write(`${srcPath}/point/deep/deeper/far.ts`, 'export const far = 1\n')
+    const entryDir = `${srcPath}/../entries`
+    const entries = writeDocEntries(ts, srcPath, entryDir)
+    const absoluteEntries = path.resolve(entryDir)
+    expect(entries.map(entry => path.relative(absoluteEntries, entry).split(path.sep).join('/')).sort())
+      .toEqual(['line.ts', 'point.ts', 'point/deep/deeper.ts', 'point/polar.ts'])
+    const absoluteSrc = path.resolve(srcPath).split(path.sep).join('/')
+    expect(fs.readFileSync(`${entryDir}/point.ts`, 'utf8')).not.toMatch(/polar|deep/)
+    expect(fs.readFileSync(`${entryDir}/point/polar.ts`, 'utf8')).toBe(
+      `/**\n * Polar coordinates.\n * @module point/polar\n */\n\nexport { default as toPolar } from '${absoluteSrc}/point/polar/to-polar'\n`
+    )
+    // A folder with only an index file (point/deep) has no module, and one without a description is still named
+    expect(fs.readFileSync(`${entryDir}/point/deep/deeper.ts`, 'utf8')).toBe(
+      `/**\n * @module point/deep/deeper\n */\n\nexport * from '${absoluteSrc}/point/deep/deeper/far'\n`
+    )
+  })
+
   test('makes one entry called index when the source has no folders', () => {
     const flat = `${gulpConfig.get('srcPath')}/../flat`
     write(`${flat}/one.ts`, 'export default 1\n')

package/functions/partials.mjs

@@ -17,6 +17,7 @@ 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 { loadPlaywright, launchBrowser } from './partials/loadPlaywright.mjs'
 export { minifyFor } from './partials/minifyFor.mjs'
 export { neostandardLint } from './partials/neostandardLint.mjs'
 export { readmeTemplate } from './partials/readmeTemplate.mjs'
@@ -24,5 +25,6 @@ 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 { serveStatic } from './partials/serveStatic.mjs'
 export { tsFor } from './partials/tsFor.mjs'
 export { typeDocsFor } from './partials/typeDocsFor.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(21)
+    expect(Object.keys(partials).length).toBe(24)
   })
 })