js-build-tools 6.2.2 → 6.3.1

package/dist/partials.js

@@ -1,150 +1,170 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "addToReadme", {
-  enumerable: true,
-  get: function () {
-    return _addToReadme.addToReadme;
-  }
-});
-Object.defineProperty(exports, "beginWatcher", {
-  enumerable: true,
-  get: function () {
-    return _beginWatcher.beginWatcher;
-  }
-});
-Object.defineProperty(exports, "clean", {
-  enumerable: true,
-  get: function () {
-    return _clean.clean;
-  }
-});
-Object.defineProperty(exports, "copyFor", {
-  enumerable: true,
-  get: function () {
-    return _copyFor.copyFor;
-  }
-});
-Object.defineProperty(exports, "distFor", {
-  enumerable: true,
-  get: function () {
-    return _distFor.distFor;
-  }
-});
-Object.defineProperty(exports, "distForSrc", {
-  enumerable: true,
-  get: function () {
-    return _distForSrc.distForSrc;
-  }
-});
-Object.defineProperty(exports, "distSeries", {
-  enumerable: true,
-  get: function () {
-    return _distSeries.distSeries;
-  }
-});
-Object.defineProperty(exports, "imagesFor", {
-  enumerable: true,
-  get: function () {
-    return _imagesFor.imagesFor;
-  }
-});
-Object.defineProperty(exports, "importModule", {
-  enumerable: true,
-  get: function () {
-    return _loadPeer.importModule;
-  }
-});
-Object.defineProperty(exports, "importPeer", {
-  enumerable: true,
-  get: function () {
-    return _loadPeer.importPeer;
-  }
-});
-Object.defineProperty(exports, "jsdocDocsFor", {
-  enumerable: true,
-  get: function () {
-    return _jsdocDocsFor.jsdocDocsFor;
-  }
-});
-Object.defineProperty(exports, "minifyFor", {
-  enumerable: true,
-  get: function () {
-    return _minifyFor.minifyFor;
-  }
-});
-Object.defineProperty(exports, "neostandardLint", {
-  enumerable: true,
-  get: function () {
-    return _neostandardLint.neostandardLint;
-  }
-});
-Object.defineProperty(exports, "readmeTemplate", {
-  enumerable: true,
-  get: function () {
-    return _readmeTemplate.readmeTemplate;
-  }
-});
-Object.defineProperty(exports, "removeDirectory", {
-  enumerable: true,
-  get: function () {
-    return _removeDirectory.removeDirectory;
-  }
-});
-Object.defineProperty(exports, "requirePeer", {
-  enumerable: true,
-  get: function () {
-    return _loadPeer.requirePeer;
-  }
-});
-Object.defineProperty(exports, "resolveDocsMethod", {
-  enumerable: true,
-  get: function () {
-    return _resolveDocsMethod.resolveDocsMethod;
-  }
-});
-Object.defineProperty(exports, "runOnChange", {
-  enumerable: true,
-  get: function () {
-    return _runOnChange.runOnChange;
-  }
-});
-Object.defineProperty(exports, "sassFor", {
-  enumerable: true,
-  get: function () {
-    return _sassFor.sassFor;
-  }
-});
-Object.defineProperty(exports, "tsFor", {
-  enumerable: true,
-  get: function () {
-    return _tsFor.tsFor;
-  }
-});
-Object.defineProperty(exports, "typeDocsFor", {
-  enumerable: true,
-  get: function () {
-    return _typeDocsFor.typeDocsFor;
-  }
-});
-var _addToReadme = require("./partials/addToReadme.js");
-var _beginWatcher = require("./partials/beginWatcher.js");
-var _clean = require("./partials/clean.js");
-var _copyFor = require("./partials/copyFor.js");
-var _distFor = require("./partials/distFor.js");
-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 _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 _tsFor = require("./partials/tsFor.js");
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "addToReadme", {
+  enumerable: true,
+  get: function () {
+    return _addToReadme.addToReadme;
+  }
+});
+Object.defineProperty(exports, "beginWatcher", {
+  enumerable: true,
+  get: function () {
+    return _beginWatcher.beginWatcher;
+  }
+});
+Object.defineProperty(exports, "clean", {
+  enumerable: true,
+  get: function () {
+    return _clean.clean;
+  }
+});
+Object.defineProperty(exports, "copyFor", {
+  enumerable: true,
+  get: function () {
+    return _copyFor.copyFor;
+  }
+});
+Object.defineProperty(exports, "distFor", {
+  enumerable: true,
+  get: function () {
+    return _distFor.distFor;
+  }
+});
+Object.defineProperty(exports, "distForSrc", {
+  enumerable: true,
+  get: function () {
+    return _distForSrc.distForSrc;
+  }
+});
+Object.defineProperty(exports, "distSeries", {
+  enumerable: true,
+  get: function () {
+    return _distSeries.distSeries;
+  }
+});
+Object.defineProperty(exports, "imagesFor", {
+  enumerable: true,
+  get: function () {
+    return _imagesFor.imagesFor;
+  }
+});
+Object.defineProperty(exports, "importModule", {
+  enumerable: true,
+  get: function () {
+    return _loadPeer.importModule;
+  }
+});
+Object.defineProperty(exports, "importPeer", {
+  enumerable: true,
+  get: function () {
+    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 () {
+    return _minifyFor.minifyFor;
+  }
+});
+Object.defineProperty(exports, "neostandardLint", {
+  enumerable: true,
+  get: function () {
+    return _neostandardLint.neostandardLint;
+  }
+});
+Object.defineProperty(exports, "readmeTemplate", {
+  enumerable: true,
+  get: function () {
+    return _readmeTemplate.readmeTemplate;
+  }
+});
+Object.defineProperty(exports, "removeDirectory", {
+  enumerable: true,
+  get: function () {
+    return _removeDirectory.removeDirectory;
+  }
+});
+Object.defineProperty(exports, "requirePeer", {
+  enumerable: true,
+  get: function () {
+    return _loadPeer.requirePeer;
+  }
+});
+Object.defineProperty(exports, "resolveDocsMethod", {
+  enumerable: true,
+  get: function () {
+    return _resolveDocsMethod.resolveDocsMethod;
+  }
+});
+Object.defineProperty(exports, "runOnChange", {
+  enumerable: true,
+  get: function () {
+    return _runOnChange.runOnChange;
+  }
+});
+Object.defineProperty(exports, "sassFor", {
+  enumerable: true,
+  get: function () {
+    return _sassFor.sassFor;
+  }
+});
+Object.defineProperty(exports, "serveStatic", {
+  enumerable: true,
+  get: function () {
+    return _serveStatic.serveStatic;
+  }
+});
+Object.defineProperty(exports, "tsFor", {
+  enumerable: true,
+  get: function () {
+    return _tsFor.tsFor;
+  }
+});
+Object.defineProperty(exports, "typeDocsFor", {
+  enumerable: true,
+  get: function () {
+    return _typeDocsFor.typeDocsFor;
+  }
+});
+var _addToReadme = require("./partials/addToReadme.js");
+var _beginWatcher = require("./partials/beginWatcher.js");
+var _clean = require("./partials/clean.js");
+var _copyFor = require("./partials/copyFor.js");
+var _distFor = require("./partials/distFor.js");
+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,"jsdocDocsFor",{enumerable:!0,get:function(){return _jsdocDocsFor.jsdocDocsFor}}),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,"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"),_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"),_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/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,17 @@ 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 options for the name in its header and the home page's <title> (otherwise "Home").
+          // The header is 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. Both are printed unescaped by the theme.
+          ...(title
+            ? {
+                theme_opts: {
+                  title: `<a href="index.html" class="sidebar-title sidebar-title-anchor">${escapeHtml(title)}</a>`,
+                  homepageTitle: escapeHtml(title)
+                }
+              }
+            : {}),
           ...(indexFile && fs.existsSync(indexFile) ? { readme: path.resolve(indexFile) } : {})
         }
       }
@@ -122,7 +136,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)
       }