js-build-tools 6.2.2 → 6.3.0

package/README.md

@@ -546,7 +546,7 @@ documentation straight from your source, with either engine:
   are not needed. `typedoc` is an optional peer dependency (like `typescript`), install it in your project with
   `npm install --save-dev typedoc` (this needs a `typescript` version it supports).
 * **jsdoc** (for a plain JavaScript project, where TypeDoc has no real types to read) - scans your source
-  recursively with jsdoc itself, rendered with a modern theme (`clean-jsdoc-theme` by default, used instead of
+  (`.js`, `.mjs` and `.cjs` files, leaving out tests and minified `.min.js` copies) recursively with jsdoc itself, rendered with a modern theme (`clean-jsdoc-theme` by default, used instead of
   jsdoc's own classic default template) instead of the manual `.jsdoc.conf.js` setup described further below.
   `jsdoc` and whichever theme you configure are optional peer dependencies, install them with
   `npm install --save-dev jsdoc clean-jsdoc-theme` (or your own chosen theme package).
@@ -558,7 +558,8 @@ Add the following to the exports in your `build-tools.config.json`:
   "docs": {
     // Generate the documentation from the source
     "enabled": true,
-    // The directory holding the source, each folder in it becomes a module (TypeDoc) or is scanned recursively (jsdoc)
+    // 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, for example ["functions", "gulpfile.base.mjs"]
     "from": "src",
     // The markdown file used as the front page of the documentation (a short overview of your project)
     "index": "MAIN.md",
@@ -569,6 +570,8 @@ Add the following to the exports in your `build-tools.config.json`:
     // Only meaningful when method is (or resolves to) 'jsdoc' - the theme package to render with. TypeDoc
     // always keeps its own default regardless of this setting.
     "theme": "clean-jsdoc-theme",
+    // The name of the documentation (TypeDoc's title, the theme's title for jsdoc), defaults to the package name
+    "title": "",
     // Where the HTML is generated (the directory is cleared first)
     "to": "docs"
   }
@@ -579,6 +582,35 @@ While `docs.enabled` is on, `gulp build` generates the documentation instead of
 hand-written (a short overview which links to the documentation). If you also export `docs` from your gulpfile you can
 run it on its own with `gulp docs`, and can then add the script `"docs": "gulp docs"`.
 
+### Browser automation (optional)
+
+Unlike the rest of this file, this isn't a `build-tools.config.json`-driven feature with its own task - it's a pair
+of plain functions (`partials.loadPlaywright`/`partials.launchBrowser` and `partials.serveStatic`) for whatever your
+own script needs a real browser for: verifying a page that only works correctly in a real browser (for example one
+using `<script type="module">`, which no DOM-simulation library executes at all), or taking a real screenshot.
+
+`playwright` is an optional peer dependency, install it in your project with `npm install --save-dev playwright`,
+then fetch a real browser binary once per machine (not per project) with `npx playwright install chromium` - if
+that fails with "Playwright does not support chromium on <your distro>", your OS is too old for the current
+release; either upgrade it or pin an older `playwright` version known to still support it (confirmed: `1.48.0`
+still installs and runs real headless Chromium on Ubuntu 20.04, which the current release has dropped).
+
+```js
+const { launchBrowser, serveStatic } = require('js-build-tools').partials
+
+const { server, url } = await serveStatic('browser') // serves ./browser/ over a real local HTTP server
+const browser = await launchBrowser()
+const page = await browser.newPage()
+await page.goto(`${url}/index.html`)
+await page.screenshot({ path: 'homepage.png' }) // a real screenshot, to actually look at
+await browser.close()
+server.close()
+```
+
+`serveStatic` exists because a page loaded directly from a `file://` path resolves any root-relative asset path
+(`/browser/...`) against the filesystem root instead of the page's own directory - serving it over real HTTP avoids
+that entirely, and is also the right fix for the exact same problem in a jsdom-based test.
+
 ### Configure lint rule overrides (optional)
 
 `sourceLint` lints your real source directly (not the compiled dist/browser output) with
@@ -613,7 +645,6 @@ In your `package.json` file, add the following scripts:
     "build": "gulp build",
     "dev": "gulp",
     "docs": "gulp docs",
-    "htmldocs": "jsdoc -R MAIN.md -c ./.jsdoc.conf.js -d docs",
     "publish:bundle": "gulp copyFiles",
     "readme": "gulp readme",
     "sass": "gulp sass",
@@ -629,8 +660,6 @@ In your `package.json` file, add the following scripts:
 
 Run any of the above commands with `gulp` or `npm run`.
 
-# Available functions documentation
-
 ## Modules
 
 <dl>
@@ -649,6 +678,146 @@ Export these functions to your own project to customize your build pipeline.
 
 **Version**: 3.0.0  
 **Author**: Joshua Heagle <joshuaheagle@gmail.com>  
+
+* [js-build-tools](#module_js-build-tools)
+    * [.typeScript](#module_js-build-tools.typeScript) ⇒ <code>function</code>
+    * [.typeDocs](#module_js-build-tools.typeDocs) ⇒ <code>function</code>
+    * [.jsdocDocs](#module_js-build-tools.jsdocDocs) ⇒ <code>function</code>
+    * [.compileReadme](#module_js-build-tools.compileReadme) ⇒ <code>stream.Stream</code>
+    * [.watchTest()](#module_js-build-tools.watchTest) ⇒ <code>\*</code>
+    * [.watchFull()](#module_js-build-tools.watchFull) ⇒ <code>FSWatcher</code>
+    * [.testQuick()](#module_js-build-tools.testQuick) ⇒ <code>Promise.&lt;\*&gt;</code>
+    * [.testFull()](#module_js-build-tools.testFull) ⇒ <code>Promise.&lt;\*&gt;</code>
+    * [.sourceLint()](#module_js-build-tools.sourceLint) ⇒ <code>\*</code>
+    * [.images()](#module_js-build-tools.images) ⇒ <code>stream.Stream</code>
+    * [.docs([done])](#module_js-build-tools.docs) ⇒ <code>\*</code>
+    * [.distMinify()](#module_js-build-tools.distMinify) ⇒ <code>\*</code>
+    * [.dist()](#module_js-build-tools.dist) ⇒ <code>\*</code>
+    * [.defaultCmd([done])](#module_js-build-tools.defaultCmd) ⇒ <code>stream.Stream</code>
+    * [.copyFonts()](#module_js-build-tools.copyFonts) ⇒ <code>stream.Stream</code>
+    * [.copyFiles()](#module_js-build-tools.copyFiles) ⇒ <code>Promise.&lt;void&gt;</code>
+    * [.bundleMinify()](#module_js-build-tools.bundleMinify) ⇒ <code>\*</code>
+    * [.bundle()](#module_js-build-tools.bundle) ⇒ <code>stream.Stream</code>
+    * [.build()](#module_js-build-tools.build) ⇒ <code>stream.Stream</code>
+
+<a name="module_js-build-tools.typeScript"></a>
+
+### js-build-tools.typeScript ⇒ <code>function</code>
+Simplified typescript task using tsFor.
+
+**Kind**: static constant of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.typeDocs"></a>
+
+### js-build-tools.typeDocs ⇒ <code>function</code>
+Generate the HTML documentation of a TypeScript project from its source, with the modules mirroring the source
+
+**Kind**: static constant of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.jsdocDocs"></a>
+
+### js-build-tools.jsdocDocs ⇒ <code>function</code>
+Generate the HTML documentation of a plain-JavaScript project from its source, with a modern jsdoc theme
+
+**Kind**: static constant of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.compileReadme"></a>
+
+### js-build-tools.compileReadme ⇒ <code>stream.Stream</code>
+Generate the README.md file based off of the template, then append the generated documentation.
+
+**Kind**: static constant of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.watchTest"></a>
+
+### js-build-tools.watchTest() ⇒ <code>\*</code>
+Watch for changes and run the tests.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.watchFull"></a>
+
+### js-build-tools.watchFull() ⇒ <code>FSWatcher</code>
+Watch for changes and run the distribution for the changed files, then bundle and test the changed files.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.testQuick"></a>
+
+### js-build-tools.testQuick() ⇒ <code>Promise.&lt;\*&gt;</code>
+Run the Jest tests for files which have been modified (based on git status).
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.testFull"></a>
+
+### js-build-tools.testFull() ⇒ <code>Promise.&lt;\*&gt;</code>
+Run all tests with jest.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.sourceLint"></a>
+
+### js-build-tools.sourceLint() ⇒ <code>\*</code>
+Applies neostandard linting (js-build-tools' chosen style) to the real, hand-written source - not the compiled
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.images"></a>
+
+### js-build-tools.images() ⇒ <code>stream.Stream</code>
+Move and optimize the images into the browser folder using configured settings.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.docs"></a>
+
+### js-build-tools.docs([done]) ⇒ <code>\*</code>
+Generate the HTML documentation with whichever engine docs.method (or its typescript.enabled-based default)
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+
+| Param | Type | Default |
+| --- | --- | --- |
+| [done] | <code>function</code> | <code></code> | 
+
+<a name="module_js-build-tools.distMinify"></a>
+
+### js-build-tools.distMinify() ⇒ <code>\*</code>
+Creates minified versions of the dist files.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.dist"></a>
+
+### js-build-tools.dist() ⇒ <code>\*</code>
+Simplified distribution tasks which will use arguments from distFor.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.defaultCmd"></a>
+
+### js-build-tools.defaultCmd([done]) ⇒ <code>stream.Stream</code>
+Recommended as the default task, runs the simple dist and bundle tasks.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+
+| Param | Type | Default |
+| --- | --- | --- |
+| [done] | <code>function</code> | <code></code> | 
+
+<a name="module_js-build-tools.copyFonts"></a>
+
+### js-build-tools.copyFonts() ⇒ <code>stream.Stream</code>
+Move the font files into the browser directory.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.copyFiles"></a>
+
+### js-build-tools.copyFiles() ⇒ <code>Promise.&lt;void&gt;</code>
+Copy files from one place to another - any number of { from, to, base? } entries, configured via copyFiles.
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.bundleMinify"></a>
+
+### js-build-tools.bundleMinify() ⇒ <code>\*</code>
+Creates the minified file for every bundle (the primary bundle, plus any additional ones from
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
+<a name="module_js-build-tools.bundle"></a>
+
+### js-build-tools.bundle() ⇒ <code>stream.Stream</code>
+Starting at each bundle's own entry point (dist.main for the primary bundle, or its own
+
+**Kind**: static method of [<code>js-build-tools</code>](#module_js-build-tools)  
 <a name="module_js-build-tools.build"></a>
 
 ### js-build-tools.build() ⇒ <code>stream.Stream</code>
@@ -804,7 +973,8 @@ Configurations for building the browser files.
 <a name="module_gulpConfig..AdditionalBundleConfig"></a>
 
 ### gulpConfig~AdditionalBundleConfig : <code>Object.&lt;string, Setting&gt;</code>
-One additional bundle - everything but `name` falls back to the primary bundle's own value when omitted, so an
+One additional bundle - everything but `name` falls back to the primary bundle's own value when omitted, so an
+additional bundle only has to specify what's actually different about it.
 
 **Kind**: inner typedef of [<code>gulpConfig</code>](#module_gulpConfig)  
 **Properties**
@@ -861,7 +1031,7 @@ Configurations to minify and copy the images.
 <a name="module_gulpConfig..LintConfig"></a>
 
 ### gulpConfig~LintConfig : <code>Object.&lt;string, Setting&gt;</code>
-Configurations for linting (see [module:partials.neostandardLint](module:partials.neostandardLint)).
+Configurations for linting (see [neostandardLint](#module_partials.neostandardLint)).
 
 **Kind**: inner typedef of [<code>gulpConfig</code>](#module_gulpConfig)  
 **Properties**
@@ -890,7 +1060,8 @@ Configurations to compile and generate the Readme file.
 <a name="module_gulpConfig..DocsConfig"></a>
 
 ### gulpConfig~DocsConfig : <code>Object.&lt;string, Setting&gt;</code>
-Configurations for generating the HTML documentation of a project's own source, with either TypeDoc (real
+Configurations for generating the HTML documentation of a project's own source, with either TypeDoc (real
+TypeScript types) or jsdoc (a modern theme over jsdoc's own classic default) - see docs.method.
 
 **Kind**: inner typedef of [<code>gulpConfig</code>](#module_gulpConfig)  
 **Properties**
@@ -898,7 +1069,7 @@ Configurations for generating the HTML documentation of a project's own source,
 | Name | Type | Description |
 | --- | --- | --- |
 | enabled | <code>BooleanSetting</code> | 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. |
-| from | <code>StringSetting</code> | The directory holding the source, each folder in it becomes a module (TypeDoc) or is scanned recursively (jsdoc). |
+| from | <code>ArrayableSetting</code> | 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. |
 | index | <code>StringSetting</code> | The markdown file used as the front page of the documentation. |
 | logLevel | <code>StringSetting</code> | How much TypeDoc reports: Verbose, Info, Warn, Error or None. Not used by jsdoc. |
 | method | <code>FlagStringSetting</code> | 'typedoc' or 'jsdoc'. False (the default) infers it from typescript.enabled - 'typedoc' when on, 'jsdoc' when off - so an existing TypeScript project's config needs no change to keep working exactly as it already does; set this explicitly to override that inference either way. |

package/dist/build.js

@@ -1,73 +1,73 @@
-"use strict";
-
-require("core-js/modules/esnext.weak-map.delete-all.js");
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.build = void 0;
-var _bundle = require("./bundle.js");
-var _bundleMinify = require("./bundleMinify.js");
-var _partials = require("./partials.js");
-var _compileReadme = require("./compileReadme.js");
-var _typeDocs = require("./typeDocs.js");
-var _jsdocDocs = require("./jsdocDocs.js");
-var _distMinify = require("./distMinify.js");
-var _sourceLint = require("./sourceLint.js");
-var _gulp = require("gulp");
-var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
-var _copyFonts = require("./copyFonts.js");
-var _images = require("./images.js");
-var _resolveDocsMethod = require("./partials/resolveDocsMethod.js");
-var _sass = require("./sass.js");
-var _testFull = require("./testFull.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; }
+"use strict";
+
+require("core-js/modules/esnext.weak-map.delete-all.js");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.build = void 0;
+var _bundle = require("./bundle.js");
+var _bundleMinify = require("./bundleMinify.js");
+var _partials = require("./partials.js");
+var _compileReadme = require("./compileReadme.js");
+var _typeDocs = require("./typeDocs.js");
+var _jsdocDocs = require("./jsdocDocs.js");
+var _distMinify = require("./distMinify.js");
+var _sourceLint = require("./sourceLint.js");
+var _gulp = require("gulp");
+var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
+var _copyFonts = require("./copyFonts.js");
+var _images = require("./images.js");
+var _resolveDocsMethod = require("./partials/resolveDocsMethod.js");
+var _sass = require("./sass.js");
+var _testFull = require("./testFull.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; }
 /**
  * Runs several processes to build and validate the project.
  * Cleans and lints the source, distributes and minifies, bundles and minifies, creates the readme, then runs the
  * tests.
  * @memberOf module:js-build-tools
  * @returns {stream.Stream}
- */
-const build = (done = null) => {
-  const buildActions = [(0, _partials.distSeries)(), _distMinify.distMinify];
-  const generateDocs = gulpConfig.get('docs.enabled');
-  const docsMethod = (0, _resolveDocsMethod.resolveDocsMethod)();
-  if (generateDocs) {
-    // The documentation is generated from the source itself, the readme is written by hand
-    buildActions.push(docsMethod === 'jsdoc' ? _jsdocDocs.jsdocDocs : _typeDocs.typeDocs);
-  } else if (gulpConfig.get('typescript.enabled')) {
-    // For ts usage, we need to run the readme on the dist directly since that is where the .js files are located
-    buildActions.push(_compileReadme.compileReadme);
-  }
-  if (gulpConfig.get('browser.enabled')) {
-    // If not 'nodeOnly' then we also want to bundle for browser after we complete the dist directory
-    buildActions.push(_bundle.bundle);
-    buildActions.push(_bundleMinify.bundleMinify);
-  }
-  const runActions = [(0, _gulp.series)(...buildActions)];
-  if (!generateDocs && !gulpConfig.get('typescript.enabled')) {
-    // Since we didn't run this in series after dist because of typescript, we need to run it now. Potentially faster here.
-    runActions.push(_compileReadme.compileReadme);
-  }
-  runActions.push(_testFull.testFull);
-  if (gulpConfig.get('fonts.enabled')) {
-    // Conditionally add Fonts process
-    runActions.push(_copyFonts.copyFonts);
-  }
-  if (gulpConfig.get('images.enabled')) {
-    // Conditionally add Images process
-    runActions.push(_images.images);
-  }
-  if (gulpConfig.get('sass.enabled')) {
-    // Conditionally add SASS process
-    runActions.push(_sass.sass);
-  }
-  // clean has to finish before anything writes into the output folders - images, fonts and sass all write into
-  // browser/, so running clean in parallel with them races (ENOTEMPTY errors from clean, or output deleted mid-write).
-  // sourceLint fixes the real source in place before anything compiles from it (distSeries, tsFor inside it), so a
-  // build never reads a mix of pre- and post-fix content; clean only touches dist/browser output, so the two can
-  // run alongside each other.
-  return (0, _gulp.series)((0, _gulp.parallel)(_partials.clean, _sourceLint.sourceLint), (0, _gulp.parallel)(...runActions))(done);
-};
+ */
+const build = (done = null) => {
+  const buildActions = [(0, _partials.distSeries)(), _distMinify.distMinify];
+  const generateDocs = gulpConfig.get('docs.enabled');
+  const docsMethod = (0, _resolveDocsMethod.resolveDocsMethod)();
+  if (generateDocs) {
+    // The documentation is generated from the source itself, the readme is written by hand
+    buildActions.push(docsMethod === 'jsdoc' ? _jsdocDocs.jsdocDocs : _typeDocs.typeDocs);
+  } else if (gulpConfig.get('typescript.enabled')) {
+    // For ts usage, we need to run the readme on the dist directly since that is where the .js files are located
+    buildActions.push(_compileReadme.compileReadme);
+  }
+  if (gulpConfig.get('browser.enabled')) {
+    // If not 'nodeOnly' then we also want to bundle for browser after we complete the dist directory
+    buildActions.push(_bundle.bundle);
+    buildActions.push(_bundleMinify.bundleMinify);
+  }
+  const runActions = [(0, _gulp.series)(...buildActions)];
+  if (!generateDocs && !gulpConfig.get('typescript.enabled')) {
+    // Since we didn't run this in series after dist because of typescript, we need to run it now. Potentially faster here.
+    runActions.push(_compileReadme.compileReadme);
+  }
+  runActions.push(_testFull.testFull);
+  if (gulpConfig.get('fonts.enabled')) {
+    // Conditionally add Fonts process
+    runActions.push(_copyFonts.copyFonts);
+  }
+  if (gulpConfig.get('images.enabled')) {
+    // Conditionally add Images process
+    runActions.push(_images.images);
+  }
+  if (gulpConfig.get('sass.enabled')) {
+    // Conditionally add SASS process
+    runActions.push(_sass.sass);
+  }
+  // clean has to finish before anything writes into the output folders - images, fonts and sass all write into
+  // browser/, so running clean in parallel with them races (ENOTEMPTY errors from clean, or output deleted mid-write).
+  // sourceLint fixes the real source in place before anything compiles from it (distSeries, tsFor inside it), so a
+  // build never reads a mix of pre- and post-fix content; clean only touches dist/browser output, so the two can
+  // run alongside each other.
+  return (0, _gulp.series)((0, _gulp.parallel)(_partials.clean, _sourceLint.sourceLint), (0, _gulp.parallel)(...runActions))(done);
+};
 exports.build = build;

package/dist/bundle.js

@@ -25,7 +25,7 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
  *
  * 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/dist/docs.js

@@ -1,12 +1,12 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.docs = void 0;
-var _jsdocDocs = require("./jsdocDocs.js");
-var _resolveDocsMethod = require("./partials/resolveDocsMethod.js");
-var _typeDocs = require("./typeDocs.js");
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.docs = void 0;
+var _jsdocDocs = require("./jsdocDocs.js");
+var _resolveDocsMethod = require("./partials/resolveDocsMethod.js");
+var _typeDocs = require("./typeDocs.js");
 /**
  * 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
@@ -14,6 +14,6 @@ var _typeDocs = require("./typeDocs.js");
  * @memberOf module:js-build-tools
  * @param {Function} [done]
  * @returns {*}
- */
-const docs = (done = null) => ((0, _resolveDocsMethod.resolveDocsMethod)() === 'jsdoc' ? _jsdocDocs.jsdocDocs : _typeDocs.typeDocs)(done);
+ */
+const docs = (done = null) => ((0, _resolveDocsMethod.resolveDocsMethod)() === 'jsdoc' ? _jsdocDocs.jsdocDocs : _typeDocs.typeDocs)(done);
 exports.docs = docs;

package/dist/partials/jsdocDocsFor.js

@@ -21,12 +21,13 @@ 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, 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).
 
 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}`;
 
@@ -78,11 +79,9 @@ const resolveJsdocBin = (projectPath = process.cwd()) => _nodePath.default.join(
 }), '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()]
@@ -95,7 +94,8 @@ const resolveJsdocTheme = (name, projectPath = process.cwd()) => {
     installHint: themeInstallHint(name),
     projectPath
   });
-  return name === 'clean-jsdoc-theme' ? _nodePath.default.join(packageDir, 'dist') : packageDir;
+  const distDir = _nodePath.default.join(packageDir, 'dist');
+  return _nodeFs.default.existsSync(_nodePath.default.join(distDir, 'publish.js')) ? distDir : packageDir;
 };
 
 /**
@@ -105,7 +105,8 @@ 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.
@@ -120,12 +121,13 @@ const jsdocDocsFor = (srcPath = gulpConfig.get('docs.from'), outPath = gulpConfi
       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: [_nodePath.default.resolve(srcPath)]
+          include: [].concat(srcPath).map(includePath => _nodePath.default.resolve(includePath))
         },
         opts: {
           destination: _nodePath.default.resolve(outPath),
@@ -134,6 +136,13 @@ const jsdocDocsFor = (srcPath = gulpConfig.get('docs.from'), outPath = gulpConfi
           // 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)
           } : {})
@@ -144,7 +153,16 @@ const jsdocDocsFor = (srcPath = gulpConfig.get('docs.from'), outPath = gulpConfi
         const configPath = _nodePath.default.join(workDir, 'jsdoc.conf.json');
         _nodeFs.default.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 (0, _removeDirectory.removeDirectory)(workDir);
       }

package/dist/partials/loadPlaywright.js

@@ -0,0 +1,34 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.loadPlaywright = exports.launchBrowser = void 0;
+var _loadPeer = require("./loadPeer.js");
+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.
+ */
+const loadPlaywright = (projectPath = process.cwd()) => (0, _loadPeer.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.
+ */
+exports.loadPlaywright = loadPlaywright;
+const launchBrowser = (load = loadPlaywright, projectPath = process.cwd()) => load(projectPath).chromium.launch();
+exports.launchBrowser = launchBrowser;

package/dist/partials/neostandardLint.js

@@ -21,6 +21,7 @@ const importNeostandard = () => (0, _loadPeer.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 {
@@ -42,7 +43,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,
@@ -75,7 +77,7 @@ const buildEslint = async ({
 /**
  * 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}
  */
@@ -108,7 +110,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}
  */
 const neostandardLint = ({
   fix = true,