js-build-tools 6.2.0 → 6.3.0

package/dist/partials/typeDocsFor.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.writeDocEntries = exports.typeDocsFor = exports.loadTypeDoc = exports.describeFolder = exports.describeFile = exports.describeExports = void 0;
+require("core-js/modules/es.array.includes.js");
 require("core-js/modules/es.json.stringify.js");
 require("core-js/modules/esnext.iterator.constructor.js");
 require("core-js/modules/esnext.iterator.filter.js");
@@ -42,12 +43,19 @@ exports.loadTypeDoc = loadTypeDoc;
 const isSource = fileName => /\.(ts|tsx|mts|cts)$/.test(fileName) && !/\.d\.[cm]?ts$/.test(fileName) && !/\.(test|spec)\./.test(fileName);
 const listSources = dirPath => _nodeFs.default.readdirSync(dirPath, {
   withFileTypes: true
-}).flatMap(entry => {
-  const entryPath = _nodePath.default.join(dirPath, entry.name);
-  if (entry.isDirectory()) {
-    return entry.name === 'node_modules' ? [] : listSources(entryPath);
-  }
-  return isSource(entry.name) ? [entryPath] : [];
+}).filter(entry => entry.isFile() && isSource(entry.name)).map(entry => _nodePath.default.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 = '') => _nodeFs.default.readdirSync(dirPath, {
+  withFileTypes: true
+}).filter(entry => entry.isDirectory() && entry.name !== 'node_modules').flatMap(entry => {
+  const folderPath = _nodePath.default.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');
 const toModulePath = filePath => filePath.replace(/\.[cm]?tsx?$/, '').split(_nodePath.default.sep).join('/');
@@ -127,11 +135,12 @@ 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.
@@ -145,18 +154,10 @@ const writeDocEntries = (ts, srcDir, entryDir) => {
   _nodeFs.default.mkdirSync(entryDir, {
     recursive: true
   });
-  const folders = _nodeFs.default.readdirSync(absoluteSrc, {
-    withFileTypes: true
-  }).filter(entry => entry.isDirectory() && entry.name !== 'node_modules').map(entry => ({
-    name: entry.name,
-    path: _nodePath.default.join(absoluteSrc, entry.name),
-    files: listSources(_nodePath.default.join(absoluteSrc, entry.name))
-  })).filter(folder => folder.files.length);
-  const rootFiles = _nodeFs.default.readdirSync(absoluteSrc, {
-    withFileTypes: true
-  }).filter(entry => entry.isFile() && isSource(entry.name) && !/^(index|main)\./.test(entry.name)).map(entry => _nodePath.default.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(_nodePath.default.basename(file))));
+  const rootFiles = listSources(absoluteSrc).filter(file => !/^(index|main|browser)\./.test(_nodePath.default.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, ...rootFiles.map(file => ({
     name: toIdentifier(_nodePath.default.basename(file).replace(/\.[cm]?tsx?$/, '')),
     files: [file],
@@ -178,8 +179,13 @@ 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 = _nodePath.default.join(entryDir, `${group.name}.ts`);
+    _nodeFs.default.mkdirSync(_nodePath.default.dirname(entryPath), {
+      recursive: true
+    });
     _nodeFs.default.writeFileSync(entryPath, moduleComment + lines.join('\n') + '\n');
     return entryPath;
   });
@@ -225,7 +231,7 @@ const typeDocsFor = (srcPath = gulpConfig.get('docs.from'), outPath = gulpConfig
           ...(projectConfig ? {
             extends: _nodePath.default.resolve(projectConfig)
           } : {}),
-          include: [_nodePath.default.join(workDir, 'entries', '*.ts').split(_nodePath.default.sep).join('/'), _nodePath.default.resolve(srcPath).split(_nodePath.default.sep).join('/') + '/**/*.ts'],
+          include: [_nodePath.default.join(workDir, 'entries', '**', '*.ts').split(_nodePath.default.sep).join('/'), _nodePath.default.resolve(srcPath).split(_nodePath.default.sep).join('/') + '/**/*.ts'],
           exclude: [_nodePath.default.resolve(srcPath).split(_nodePath.default.sep).join('/') + '/**/*.test.*']
         }));
         const indexFile = gulpConfig.get('docs.index');

package/dist/partials.js

@@ -63,6 +63,24 @@ Object.defineProperty(exports, "importPeer", {
     return _loadPeer.importPeer;
   }
 });
+Object.defineProperty(exports, "jsdocDocsFor", {
+  enumerable: true,
+  get: function () {
+    return _jsdocDocsFor.jsdocDocsFor;
+  }
+});
+Object.defineProperty(exports, "launchBrowser", {
+  enumerable: true,
+  get: function () {
+    return _loadPlaywright.launchBrowser;
+  }
+});
+Object.defineProperty(exports, "loadPlaywright", {
+  enumerable: true,
+  get: function () {
+    return _loadPlaywright.loadPlaywright;
+  }
+});
 Object.defineProperty(exports, "minifyFor", {
   enumerable: true,
   get: function () {
@@ -93,6 +111,12 @@ Object.defineProperty(exports, "requirePeer", {
     return _loadPeer.requirePeer;
   }
 });
+Object.defineProperty(exports, "resolveDocsMethod", {
+  enumerable: true,
+  get: function () {
+    return _resolveDocsMethod.resolveDocsMethod;
+  }
+});
 Object.defineProperty(exports, "runOnChange", {
   enumerable: true,
   get: function () {
@@ -105,6 +129,12 @@ Object.defineProperty(exports, "sassFor", {
     return _sassFor.sassFor;
   }
 });
+Object.defineProperty(exports, "serveStatic", {
+  enumerable: true,
+  get: function () {
+    return _serveStatic.serveStatic;
+  }
+});
 Object.defineProperty(exports, "tsFor", {
   enumerable: true,
   get: function () {
@@ -126,11 +156,15 @@ var _distForSrc = require("./partials/distForSrc.js");
 var _distSeries = require("./partials/distSeries.js");
 var _imagesFor = require("./partials/imagesFor.js");
 var _loadPeer = require("./partials/loadPeer.js");
+var _jsdocDocsFor = require("./partials/jsdocDocsFor.js");
+var _loadPlaywright = require("./partials/loadPlaywright.js");
 var _minifyFor = require("./partials/minifyFor.js");
 var _neostandardLint = require("./partials/neostandardLint.js");
 var _readmeTemplate = require("./partials/readmeTemplate.js");
 var _removeDirectory = require("./partials/removeDirectory.js");
+var _resolveDocsMethod = require("./partials/resolveDocsMethod.js");
 var _runOnChange = require("./partials/runOnChange.js");
 var _sassFor = require("./partials/sassFor.js");
+var _serveStatic = require("./partials/serveStatic.js");
 var _tsFor = require("./partials/tsFor.js");
 var _typeDocsFor = require("./partials/typeDocsFor.js");

package/dist/partials.min.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),Object.defineProperty(exports,"addToReadme",{enumerable:!0,get:function(){return _addToReadme.addToReadme}}),Object.defineProperty(exports,"beginWatcher",{enumerable:!0,get:function(){return _beginWatcher.beginWatcher}}),Object.defineProperty(exports,"clean",{enumerable:!0,get:function(){return _clean.clean}}),Object.defineProperty(exports,"copyFor",{enumerable:!0,get:function(){return _copyFor.copyFor}}),Object.defineProperty(exports,"distFor",{enumerable:!0,get:function(){return _distFor.distFor}}),Object.defineProperty(exports,"distForSrc",{enumerable:!0,get:function(){return _distForSrc.distForSrc}}),Object.defineProperty(exports,"distSeries",{enumerable:!0,get:function(){return _distSeries.distSeries}}),Object.defineProperty(exports,"imagesFor",{enumerable:!0,get:function(){return _imagesFor.imagesFor}}),Object.defineProperty(exports,"importModule",{enumerable:!0,get:function(){return _loadPeer.importModule}}),Object.defineProperty(exports,"importPeer",{enumerable:!0,get:function(){return _loadPeer.importPeer}}),Object.defineProperty(exports,"minifyFor",{enumerable:!0,get:function(){return _minifyFor.minifyFor}}),Object.defineProperty(exports,"neostandardLint",{enumerable:!0,get:function(){return _neostandardLint.neostandardLint}}),Object.defineProperty(exports,"readmeTemplate",{enumerable:!0,get:function(){return _readmeTemplate.readmeTemplate}}),Object.defineProperty(exports,"removeDirectory",{enumerable:!0,get:function(){return _removeDirectory.removeDirectory}}),Object.defineProperty(exports,"requirePeer",{enumerable:!0,get:function(){return _loadPeer.requirePeer}}),Object.defineProperty(exports,"runOnChange",{enumerable:!0,get:function(){return _runOnChange.runOnChange}}),Object.defineProperty(exports,"sassFor",{enumerable:!0,get:function(){return _sassFor.sassFor}}),Object.defineProperty(exports,"tsFor",{enumerable:!0,get:function(){return _tsFor.tsFor}}),Object.defineProperty(exports,"typeDocsFor",{enumerable:!0,get:function(){return _typeDocsFor.typeDocsFor}});var _addToReadme=require("./partials/addToReadme.js"),_beginWatcher=require("./partials/beginWatcher.js"),_clean=require("./partials/clean.js"),_copyFor=require("./partials/copyFor.js"),_distFor=require("./partials/distFor.js"),_distForSrc=require("./partials/distForSrc.js"),_distSeries=require("./partials/distSeries.js"),_imagesFor=require("./partials/imagesFor.js"),_loadPeer=require("./partials/loadPeer.js"),_minifyFor=require("./partials/minifyFor.js"),_neostandardLint=require("./partials/neostandardLint.js"),_readmeTemplate=require("./partials/readmeTemplate.js"),_removeDirectory=require("./partials/removeDirectory.js"),_runOnChange=require("./partials/runOnChange.js"),_sassFor=require("./partials/sassFor.js"),_tsFor=require("./partials/tsFor.js"),_typeDocsFor=require("./partials/typeDocsFor.js");
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),Object.defineProperty(exports,"addToReadme",{enumerable:!0,get:function(){return _addToReadme.addToReadme}}),Object.defineProperty(exports,"beginWatcher",{enumerable:!0,get:function(){return _beginWatcher.beginWatcher}}),Object.defineProperty(exports,"clean",{enumerable:!0,get:function(){return _clean.clean}}),Object.defineProperty(exports,"copyFor",{enumerable:!0,get:function(){return _copyFor.copyFor}}),Object.defineProperty(exports,"distFor",{enumerable:!0,get:function(){return _distFor.distFor}}),Object.defineProperty(exports,"distForSrc",{enumerable:!0,get:function(){return _distForSrc.distForSrc}}),Object.defineProperty(exports,"distSeries",{enumerable:!0,get:function(){return _distSeries.distSeries}}),Object.defineProperty(exports,"imagesFor",{enumerable:!0,get:function(){return _imagesFor.imagesFor}}),Object.defineProperty(exports,"importModule",{enumerable:!0,get:function(){return _loadPeer.importModule}}),Object.defineProperty(exports,"importPeer",{enumerable:!0,get:function(){return _loadPeer.importPeer}}),Object.defineProperty(exports,"jsdocDocsFor",{enumerable:!0,get:function(){return _jsdocDocsFor.jsdocDocsFor}}),Object.defineProperty(exports,"launchBrowser",{enumerable:!0,get:function(){return _loadPlaywright.launchBrowser}}),Object.defineProperty(exports,"loadPlaywright",{enumerable:!0,get:function(){return _loadPlaywright.loadPlaywright}}),Object.defineProperty(exports,"minifyFor",{enumerable:!0,get:function(){return _minifyFor.minifyFor}}),Object.defineProperty(exports,"neostandardLint",{enumerable:!0,get:function(){return _neostandardLint.neostandardLint}}),Object.defineProperty(exports,"readmeTemplate",{enumerable:!0,get:function(){return _readmeTemplate.readmeTemplate}}),Object.defineProperty(exports,"removeDirectory",{enumerable:!0,get:function(){return _removeDirectory.removeDirectory}}),Object.defineProperty(exports,"requirePeer",{enumerable:!0,get:function(){return _loadPeer.requirePeer}}),Object.defineProperty(exports,"resolveDocsMethod",{enumerable:!0,get:function(){return _resolveDocsMethod.resolveDocsMethod}}),Object.defineProperty(exports,"runOnChange",{enumerable:!0,get:function(){return _runOnChange.runOnChange}}),Object.defineProperty(exports,"sassFor",{enumerable:!0,get:function(){return _sassFor.sassFor}}),Object.defineProperty(exports,"serveStatic",{enumerable:!0,get:function(){return _serveStatic.serveStatic}}),Object.defineProperty(exports,"tsFor",{enumerable:!0,get:function(){return _tsFor.tsFor}}),Object.defineProperty(exports,"typeDocsFor",{enumerable:!0,get:function(){return _typeDocsFor.typeDocsFor}});var _addToReadme=require("./partials/addToReadme.js"),_beginWatcher=require("./partials/beginWatcher.js"),_clean=require("./partials/clean.js"),_copyFor=require("./partials/copyFor.js"),_distFor=require("./partials/distFor.js"),_distForSrc=require("./partials/distForSrc.js"),_distSeries=require("./partials/distSeries.js"),_imagesFor=require("./partials/imagesFor.js"),_loadPeer=require("./partials/loadPeer.js"),_jsdocDocsFor=require("./partials/jsdocDocsFor.js"),_loadPlaywright=require("./partials/loadPlaywright.js"),_minifyFor=require("./partials/minifyFor.js"),_neostandardLint=require("./partials/neostandardLint.js"),_readmeTemplate=require("./partials/readmeTemplate.js"),_removeDirectory=require("./partials/removeDirectory.js"),_resolveDocsMethod=require("./partials/resolveDocsMethod.js"),_runOnChange=require("./partials/runOnChange.js"),_sassFor=require("./partials/sassFor.js"),_serveStatic=require("./partials/serveStatic.js"),_tsFor=require("./partials/tsFor.js"),_typeDocsFor=require("./partials/typeDocsFor.js");

package/dist/test-helpers/setUp.js

@@ -76,6 +76,12 @@ 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/dist/utilities/convertMjsFilesForDocs.js

@@ -22,6 +22,7 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
  * @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
  */
 const convertMjsFilesForDocs = (mjsFilePaths = []) => {
   if (mjsFilePaths.length === 0) {

package/dist/utilities/dotGet.js

@@ -14,6 +14,7 @@ var _strBefore = require("./strBefore.js");
  * @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
  */
 const dotGet = (arrayObject = {}, dotNotation = '', defaultValue = null) => {
   if (!dotNotation) {

package/dist/utilities/dotNotate.js

@@ -11,12 +11,14 @@ var _isObject = require("./isObject.js");
  * 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;
   }
@@ -28,6 +30,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)) {
@@ -45,6 +48,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) {
@@ -70,6 +74,7 @@ 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
  */
 const dotNotate = (arrayObject, retainObjects = []) => performDotNotate(arrayObject, handleRetainObjects(retainObjects));
 exports.dotNotate = dotNotate;

package/dist/utilities/dotSet.js

@@ -14,6 +14,7 @@ var _strBefore = require("./strBefore.js");
  * @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
  */
 const dotSet = (arrayObject, dotNotation, value = null) => {
   let key = (0, _strBefore.strBefore)(dotNotation, '.');

package/dist/utilities/esmNamedExportsToCjs.js

@@ -18,6 +18,7 @@ exports.esmNamedExportsToCjs = void 0;
  * @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
  */
 const esmNamedExportsToCjs = source => {
   const exportedNames = [];

package/dist/utilities/getBundleConfigs.js

@@ -18,6 +18,7 @@ function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e;
  * specify what's actually different about it.
  * @memberOf module:utilities
  * @returns {Array<{name: string, main: string, ignore: Array, exclude: Array}>}
+ * @private
  */
 const getBundleConfigs = () => {
   const primary = {

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

@@ -10,6 +10,7 @@ import { parallel, series } from 'gulp'
 import * as gulpConfig from '../gulp.config.mjs'
 import { copyFonts } from './copyFonts.mjs'
 import { images } from './images.mjs'
+import { resolveDocsMethod } from './partials/resolveDocsMethod.mjs'
 import { sass } from './sass.mjs'
 import { testFull } from './testFull.mjs'
 
@@ -23,10 +24,7 @@ import { testFull } from './testFull.mjs'
 export const build = (done = null) => {
   const buildActions = [distSeries(), distMinify]
   const generateDocs = gulpConfig.get('docs.enabled')
-  // docs.method picks the engine 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.
-  const docsMethod = gulpConfig.get('docs.method') || (gulpConfig.get('typescript.enabled') ? 'typedoc' : 'jsdoc')
+  const docsMethod = resolveDocsMethod()
   if (generateDocs) {
     // The documentation is generated from the source itself, the readme is written by hand
     buildActions.push(docsMethod === 'jsdoc' ? jsdocDocs : typeDocs)

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

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

package/functions/docs.test.mjs

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

package/functions/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()