js-build-tools 6.3.0 → 6.3.1

package/dist/partials/jsdocDocsFor.js

@@ -1,36 +1,36 @@
-"use strict";
-
-require("core-js/modules/esnext.weak-map.delete-all.js");
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.resolveJsdocTheme = exports.resolveJsdocBin = exports.jsdocDocsFor = void 0;
-require("core-js/modules/es.json.stringify.js");
-require("core-js/modules/esnext.iterator.constructor.js");
-require("core-js/modules/esnext.iterator.find.js");
-require("core-js/modules/esnext.iterator.map.js");
-var _nodeFs = _interopRequireDefault(require("node:fs"));
-var _nodeOs = _interopRequireDefault(require("node:os"));
-var _nodePath = _interopRequireDefault(require("node:path"));
-var _nodeModule = require("node:module");
-var _nodeChild_process = require("node:child_process");
-var _nodeUtil = require("node:util");
-var gulpConfig = _interopRequireWildcard(require("../../gulp.config.js"));
-var _removeDirectory = require("./removeDirectory.js");
-var _jsdocBase = _interopRequireDefault(require("../../jsdoc.base.js"));
-var cache;
-function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-// 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).
-
-const execFileAsync = (0, _nodeUtil.promisify)(_nodeChild_process.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}`;
-
+"use strict";
+
+require("core-js/modules/esnext.weak-map.delete-all.js");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.resolveJsdocTheme = exports.resolveJsdocBin = exports.jsdocDocsFor = void 0;
+require("core-js/modules/es.json.stringify.js");
+require("core-js/modules/esnext.iterator.constructor.js");
+require("core-js/modules/esnext.iterator.find.js");
+require("core-js/modules/esnext.iterator.map.js");
+var _nodeFs = _interopRequireDefault(require("node:fs"));
+var _nodeOs = _interopRequireDefault(require("node:os"));
+var _nodePath = _interopRequireDefault(require("node:path"));
+var _nodeModule = require("node:module");
+var _nodeChild_process = require("node:child_process");
+var _nodeUtil = require("node:util");
+var gulpConfig = _interopRequireWildcard(require("../../gulp.config.js"));
+var _removeDirectory = require("./removeDirectory.js");
+var _jsdocBase = _interopRequireDefault(require("../../jsdoc.base.js"));
+var cache;
+function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// 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).
+
+const execFileAsync = (0, _nodeUtil.promisify)(_nodeChild_process.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}`;
+
 /**
  * Resolve the installed directory of an optional peer dependency, from the project being built rather than from
  * this package. Deliberately not requirePeer/importPeer's own `require(name + '/package.json')` approach - that
@@ -48,20 +48,20 @@ const themeInstallHint = name => `Install it in your project with: npm install -
  * @param {string} [options.projectPath=process.cwd()]
  * @returns {string}
  * @throws {Error} With install instructions when the package is not installed.
- */
-const resolvePeerDir = (name, {
-  task,
-  installHint,
-  projectPath = process.cwd()
-}) => {
-  const req = (0, _nodeModule.createRequire)(_nodePath.default.join(projectPath, 'package.json'));
-  const found = (req.resolve.paths(name) || []).map(dir => _nodePath.default.join(dir, name)).find(dir => _nodeFs.default.existsSync(_nodePath.default.join(dir, 'package.json')));
-  if (!found) {
-    throw new Error(`The ${task} task needs the optional peer dependency ${name}, which is not installed. ${installHint}`);
-  }
-  return found;
-};
-
+ */
+const resolvePeerDir = (name, {
+  task,
+  installHint,
+  projectPath = process.cwd()
+}) => {
+  const req = (0, _nodeModule.createRequire)(_nodePath.default.join(projectPath, 'package.json'));
+  const found = (req.resolve.paths(name) || []).map(dir => _nodePath.default.join(dir, name)).find(dir => _nodeFs.default.existsSync(_nodePath.default.join(dir, 'package.json')));
+  if (!found) {
+    throw new Error(`The ${task} task needs the optional peer dependency ${name}, which is not installed. ${installHint}`);
+  }
+  return found;
+};
+
 /**
  * Resolve jsdoc's own CLI entry point. jsdoc has no stable programmatic Node API for generating HTML docs (unlike
  * TypeDoc's Application.bootstrap()/convert()/generateDocs()) - gulp-jsdoc3, the established gulp wrapper, is
@@ -71,13 +71,13 @@ const resolvePeerDir = (name, {
  * @memberOf module:partials
  * @param {string} [projectPath=process.cwd()]
  * @returns {string}
- */
-const resolveJsdocBin = (projectPath = process.cwd()) => _nodePath.default.join(resolvePeerDir('jsdoc', {
-  task: 'docs',
-  installHint: jsdocInstallHint,
-  projectPath
-}), 'jsdoc.js');
-
+ */
+const resolveJsdocBin = (projectPath = process.cwd()) => _nodePath.default.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: the folder
  * holding its publish.js. That is the package root for a classic jsdoc template (clean-jsdoc-theme 4.x included),
@@ -86,18 +86,18 @@ const resolveJsdocBin = (projectPath = process.cwd()) => _nodePath.default.join(
  * @param {string} name
  * @param {string} [projectPath=process.cwd()]
  * @returns {string}
- */
-exports.resolveJsdocBin = resolveJsdocBin;
-const resolveJsdocTheme = (name, projectPath = process.cwd()) => {
-  const packageDir = resolvePeerDir(name, {
-    task: 'docs',
-    installHint: themeInstallHint(name),
-    projectPath
-  });
-  const distDir = _nodePath.default.join(packageDir, 'dist');
-  return _nodeFs.default.existsSync(_nodePath.default.join(distDir, 'publish.js')) ? distDir : packageDir;
-};
-
+ */
+exports.resolveJsdocBin = resolveJsdocBin;
+const resolveJsdocTheme = (name, projectPath = process.cwd()) => {
+  const packageDir = resolvePeerDir(name, {
+    task: 'docs',
+    installHint: themeInstallHint(name),
+    projectPath
+  });
+  const distDir = _nodePath.default.join(packageDir, 'dist');
+  return _nodeFs.default.existsSync(_nodePath.default.join(distDir, 'publish.js')) ? distDir : packageDir;
+};
+
 /**
  * Generate the HTML documentation of a plain-JavaScript project with jsdoc, using jsdoc.base.js's own shared
  * config (plugins, includePattern/excludePattern) as the starting point rather than a parallel one - the same
@@ -110,64 +110,66 @@ const resolveJsdocTheme = (name, projectPath = process.cwd()) => {
  * @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.
- */
-exports.resolveJsdocTheme = resolveJsdocTheme;
-const jsdocDocsFor = (srcPath = gulpConfig.get('docs.from'), outPath = gulpConfig.get('docs.to'), runJsdoc = (bin, args) => execFileAsync(process.execPath, [bin, ...args])) => {
-  if (gulpConfig.get('docs.enabled') === false) {
-    return () => {};
-  }
-  return done => {
-    const generate = async () => {
-      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 (0, _removeDirectory.removeDirectory)(outPath);
-      const config = {
-        ..._jsdocBase.default,
-        source: {
-          ..._jsdocBase.default.source,
-          include: [].concat(srcPath).map(includePath => _nodePath.default.resolve(includePath))
-        },
-        opts: {
-          destination: _nodePath.default.resolve(outPath),
-          // jsdoc does not recurse into source.include's own subdirectories by default - without this, only
-          // the top level of docs.from would ever be scanned. Confirmed from clean-jsdoc-theme's own README
-          // 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 && _nodeFs.default.existsSync(indexFile) ? {
-            readme: _nodePath.default.resolve(indexFile)
-          } : {})
-        }
-      };
-      const workDir = _nodeFs.default.mkdtempSync(_nodePath.default.join(_nodeOs.default.tmpdir(), 'jsdocdocs-'));
-      try {
-        const configPath = _nodePath.default.join(workDir, 'jsdoc.conf.json');
-        _nodeFs.default.writeFileSync(configPath, JSON.stringify(config));
-        const bin = resolveJsdocBin();
-        // 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 (0, _removeDirectory.removeDirectory)(workDir);
-      }
-    };
-    return typeof done === 'function' ? generate().then(() => done(), done) : generate();
-  };
-};
+ */
+exports.resolveJsdocTheme = resolveJsdocTheme;
+const jsdocDocsFor = (srcPath = gulpConfig.get('docs.from'), outPath = gulpConfig.get('docs.to'), runJsdoc = (bin, args) => execFileAsync(process.execPath, [bin, ...args])) => {
+  if (gulpConfig.get('docs.enabled') === false) {
+    return () => {};
+  }
+  return done => {
+    const generate = async () => {
+      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 (0, _removeDirectory.removeDirectory)(outPath);
+      const config = {
+        ..._jsdocBase.default,
+        source: {
+          ..._jsdocBase.default.source,
+          include: [].concat(srcPath).map(includePath => _nodePath.default.resolve(includePath))
+        },
+        opts: {
+          destination: _nodePath.default.resolve(outPath),
+          // jsdoc does not recurse into source.include's own subdirectories by default - without this, only
+          // the top level of docs.from would ever be scanned. Confirmed from clean-jsdoc-theme's own README
+          // 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 && _nodeFs.default.existsSync(indexFile) ? {
+            readme: _nodePath.default.resolve(indexFile)
+          } : {})
+        }
+      };
+      const workDir = _nodeFs.default.mkdtempSync(_nodePath.default.join(_nodeOs.default.tmpdir(), 'jsdocdocs-'));
+      try {
+        const configPath = _nodePath.default.join(workDir, 'jsdoc.conf.json');
+        _nodeFs.default.writeFileSync(configPath, JSON.stringify(config));
+        const bin = resolveJsdocBin();
+        // 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 (0, _removeDirectory.removeDirectory)(workDir);
+      }
+    };
+    return typeof done === 'function' ? generate().then(() => done(), done) : generate();
+  };
+};
 exports.jsdocDocsFor = jsdocDocsFor;

package/functions/partials/jsdocDocsFor.mjs

@@ -117,9 +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 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>` } } : {}),
+          // 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) } : {})
         }
       }

package/functions/partials/jsdocDocsFor.test.mjs

@@ -92,14 +92,15 @@ describe('jsdocDocsFor', () => {
     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 () => {
+  test('passes docs.title to the theme as a link to the home page of the docs and as its page title, and leaves it out when unset', async () => {
     gulpConfig.set('docs.enabled', true)
     const srcPath = gulpConfig.get('srcPath')
     const calls = {}
     gulpConfig.set('docs.title', 'Tom & Jerry <Tools>')
     await jsdocDocsFor(srcPath, `${srcPath}/../docs`, fakeRunJsdoc(calls))()
     expect(calls.config.opts.theme_opts).toEqual({
-      title: '<a href="index.html" class="sidebar-title sidebar-title-anchor">Tom &amp; Jerry &lt;Tools&gt;</a>'
+      title: '<a href="index.html" class="sidebar-title sidebar-title-anchor">Tom &amp; Jerry &lt;Tools&gt;</a>',
+      homepageTitle: 'Tom &amp; Jerry &lt;Tools&gt;'
     })
 
     gulpConfig.set('docs.title', '')
@@ -139,11 +140,13 @@ describe('jsdocDocsFor', () => {
 describe('jsdocDocsFor, end to end with the real jsdoc CLI and clean-jsdoc-theme', () => {
   test('produces a real browsable HTML page from real JSDoc comments', async () => {
     gulpConfig.set('docs.enabled', true)
+    gulpConfig.set('docs.title', 'Tom & Jerry')
     const outPath = `${gulpConfig.get('srcPath')}/../docs`
     await jsdocDocsFor(gulpConfig.get('srcPath'), outPath)()
     // clean-jsdoc-theme nests its real output under its own route folders (global/, source/...), not flat at
     // outPath's own root - confirmed by actually running it, not assumed from the classic jsdoc template shape.
     const files = fs.readdirSync(outPath, { recursive: true })
     expect(files.some(file => file.endsWith('.html'))).toBe(true)
+    expect(fs.readFileSync(`${outPath}/index.html`, 'utf8')).toMatch(/<title>\s*Tom &amp; Jerry\s*<\/title>/)
   }, 30000)
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-build-tools",
-  "version": "6.3.0",
+  "version": "6.3.1",
   "description": "Standardised build process with gulp.",
   "main": "gulpfile.base.js",
   "exports": {