js-build-tools 6.2.0 → 6.3.0

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/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/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

@@ -16,11 +16,15 @@ 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 { loadPlaywright, launchBrowser } from './partials/loadPlaywright.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 { 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(19)
+    expect(Object.keys(partials).length).toBe(24)
   })
 })

package/functions/test-helpers/setUp.mjs

@@ -23,6 +23,12 @@ export const setDefaults = (testDir = 'test-temp') => {
   gulpConfig.set('dist.from', `${srcPath}/**/!(*.test).js`)
   gulpConfig.set('dist.main', `${distPath}/main`)
   gulpConfig.set('dist.to', distPath)
+  // Reset explicitly, for the same reason as readme.fromEsm below: this project's own build-tools.config.json turns
+  // docs on and points them at the website checkout, which would leak into every test that never sets these itself.
+  gulpConfig.set('docs.enabled', false)
+  gulpConfig.set('docs.from', srcPath)
+  gulpConfig.set('docs.to', `${tempDir}docs`)
+  gulpConfig.set('docs.title', '')
   gulpConfig.set('fonts.from', `${srcPath}/fonts/**/*`)
   gulpConfig.set('fonts.to', `${browserPath}/fonts`)
   gulpConfig.set('images.from', `${srcPath}/img/**/*.+(png|jpg|jpeg|gif|svg)`)

package/functions/utilities/convertMjsFilesForDocs.mjs

@@ -14,6 +14,7 @@ import { esmNamedExportsToCjs } from './esmNamedExportsToCjs.mjs'
  * @param {Array<string>} mjsFilePaths - Real `.mjs` files to convert. An empty array is a safe, cheap no-op.
  * @returns {{filePaths: Array<string>, cleanUp: function(): void}} The temp `.js` file paths to pass to
  * jsdoc-to-markdown instead of the real `.mjs` ones, and a function to remove the temp directory afterward.
+ * @private
  */
 export const convertMjsFilesForDocs = (mjsFilePaths = []) => {
   if (mjsFilePaths.length === 0) {

package/functions/utilities/dotGet.mjs

@@ -9,6 +9,7 @@ import { strBefore } from './strBefore.mjs'
  * @param {string} [dotNotation=''] - The path to the property
  * @param {string|null} [defaultValue=null] - The default value to return if the property is not found
  * @returns {*} The value of the property
+ * @private
  */
 export const dotGet = (arrayObject = {}, dotNotation= '', defaultValue = null) => {
   if (!dotNotation) {

package/functions/utilities/dotNotate.mjs

@@ -4,12 +4,14 @@ import { isObject } from './isObject.mjs'
  * Convert an array of keys into a regex, return a function to test if incoming keys match.
  * @param {Array.<string>} [retainObjects=[]] - An array of keys to retain as objects
  * @returns {Function} The dot-notated array
+ * @private
  */
 const handleRetainObjects = (retainObjects = []) => {
   if (!retainObjects.length) {
     /**
      * Bypass the test function if there are no retainObjects.
      * @returns {false}
+     * @private
      */
     return (currentKey, value, results) => false
   }
@@ -21,6 +23,7 @@ const handleRetainObjects = (retainObjects = []) => {
    * @param {*} value - The value of the key
    * @param {Object} results - The result object to add to
    * @returns {boolean}
+   * @private
    */
   return (currentKey, value, results) => {
     if (!currentKey.match(retainRegex)) {
@@ -38,6 +41,7 @@ const handleRetainObjects = (retainObjects = []) => {
  * @param {string} [prepend=''] - The path for the property being processed
  * @param {Object<string, *>} [results={}] - The final notated object to return
  * @returns {Object<string, *>} The dot-notated object
+ * @private
  */
 const performDotNotate = (arrayObject, didRetain, prepend = '', results = {}) => {
   for (let key in arrayObject) {
@@ -64,5 +68,6 @@ const performDotNotate = (arrayObject, didRetain, prepend = '', results = {}) =>
  * @param {Object} arrayObject - The array or object to dot-notate
  * @param {Array.<string>} [retainObjects=[]] - An array of keys to retain as objects
  * @returns {Object<string, *>} The dot-notated object
+ * @private
  */
 export const dotNotate = (arrayObject, retainObjects = []) => performDotNotate(arrayObject, handleRetainObjects(retainObjects))

package/functions/utilities/dotSet.mjs

@@ -9,6 +9,7 @@ import { strBefore } from './strBefore.mjs'
  * @param {string} dotNotation - The path for the property
  * @param {*} value - The default value to return if the property is not found
  * @returns {Object} The modified object
+ * @private
  */
 export const dotSet = (arrayObject, dotNotation, value = null) => {
   let key = strBefore(dotNotation, '.')

package/functions/utilities/esmNamedExportsToCjs.mjs

@@ -12,6 +12,7 @@
  * @memberOf module:utilities
  * @param {string} source - The raw ESM source text (never executed, just rewritten as text).
  * @returns {string} The rewritten text, safe to write out with a `.js` extension for jsdoc-to-markdown to read.
+ * @private
  */
 export const esmNamedExportsToCjs = (source) => {
   const exportedNames = []

package/functions/utilities/getBundleConfigs.mjs

@@ -8,6 +8,7 @@ import * as gulpConfig from '../../gulp.config.mjs'
  * specify what's actually different about it.
  * @memberOf module:utilities
  * @returns {Array<{name: string, main: string, ignore: Array, exclude: Array}>}
+ * @private
  */
 export const getBundleConfigs = () => {
   const primary = {

package/functions/utilities/isObject.mjs

@@ -3,5 +3,6 @@
  * 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
  */
 export const isObject = (object) => typeof object === 'object' && object !== null

package/functions/utilities/strAfter.mjs

@@ -4,6 +4,7 @@
  * @param {string} str
  * @param {string} search
  * @returns {string}
+ * @private
  */
 export const strAfter = (str, search) => {
   const index = str.indexOf(search)

package/functions/utilities/strBefore.mjs

@@ -4,6 +4,7 @@
  * @param {string} str
  * @param {string} search
  * @returns {string}
+ * @private
  */
 export const strBefore = (str, search) => {
   const index = str.indexOf(search)

package/gulp.config.mjs

@@ -133,8 +133,8 @@ import { fileExists } from 'test-filesystem'
  * @typedef {Object<string, Setting>} module:gulpConfig~DocsConfig
  * @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 source, each folder in it becomes a module (TypeDoc) or
- * is scanned recursively (jsdoc).
+ * @property {ArrayableSetting} from - The directory holding the source, each folder in it becomes a module (TypeDoc) or
+ * is scanned recursively (jsdoc). jsdoc also takes a list of directories and files.
  * @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. Not used by jsdoc.
  * @property {FlagStringSetting} method - 'typedoc' or 'jsdoc'. False (the default) infers it from typescript.enabled -

package/gulpfile.base.mjs

@@ -1,8 +1,6 @@
 /**
- * import these functions to your own project to customize your build pipeline.
- * @file
+ * Import these functions to your own project to customize your build pipeline.
  * @author Joshua Heagle <joshuaheagle@gmail.com>
- * @version 3.0.0
  * @module js-build-tools
  */
 export { build } from './functions/build.mjs'
@@ -13,6 +11,7 @@ export { copyFiles } from './functions/copyFiles.mjs'
 export { copyFonts } from './functions/copyFonts.mjs'
 export { defaultCmd } from './functions/default.mjs'
 export { dist } from './functions/dist.mjs'
+export { docs } from './functions/docs.mjs'
 export { distMinify } from './functions/distMinify.mjs'
 export * as gulpConfig from './gulp.config.mjs'
 export { images } from './functions/images.mjs'
@@ -23,7 +22,7 @@ export { sourceLint } from './functions/sourceLint.mjs'
 export { testFull } from './functions/testFull.mjs'
 export * as testHelpers from './functions/testHelpers.mjs'
 export { testQuick } from './functions/testQuick.mjs'
-export { typeDocs as docs } from './functions/typeDocs.mjs'
+export { typeDocs } from './functions/typeDocs.mjs'
 export { typeScript as typescript } from './functions/typeScript.mjs'
 export { watchFull } from './functions/watchFull.mjs'
 export { watchTest } from './functions/watchTest.mjs'

package/jsdoc.base.js

@@ -1,10 +1,16 @@
+const path = require('path')
 const gulpConfig = require('./gulp.config.js')
 
 module.exports = {
-  plugins: ['plugins/markdown'],
+  plugins: ['plugins/markdown', path.join(__dirname, 'jsdoc.esmExports.js')],
+  // Give markdown headings ids (the README / docs.index front page), so they can be linked to and a theme's
+  // table of contents can follow them
+  markdown: { idInHeadings: true },
   source: {
     include: [gulpConfig.get('dist.to')],
-    includePattern: '.+\\.js(doc|x)?$',
-    excludePattern: '((^|\\/|\\\\)_|.+\\.test\\..*)'
+    // .mjs / .cjs too, so ES module source can be documented as it is, not only its compiled CommonJS
+    includePattern: '.+\\.[cm]?js(doc|x)?$',
+    // Files starting with _, tests, and minified copies (which only repeat what their unminified file documents)
+    excludePattern: '((^|\\/|\\\\)_|.+\\.test\\..*|.+\\.min\\.[cm]?js$)'
   },
 }