js-build-tools 6.2.2 → 6.3.1

package/dist/partials/jsdocDocsFor.js

@@ -1,35 +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, 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).
-
-const execFileAsync = (0, _nodeUtil.promisify)(_nodeChild_process.execFile);
-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
@@ -47,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
@@ -70,34 +71,33 @@ 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. 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()]
  * @returns {string}
- */
-exports.resolveJsdocBin = resolveJsdocBin;
-const resolveJsdocTheme = (name, projectPath = process.cwd()) => {
-  const packageDir = resolvePeerDir(name, {
-    task: 'docs',
-    installHint: themeInstallHint(name),
-    projectPath
-  });
-  return name === 'clean-jsdoc-theme' ? _nodePath.default.join(packageDir, 'dist') : 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
@@ -105,51 +105,71 @@ 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.
- */
-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');
-      await (0, _removeDirectory.removeDirectory)(outPath);
-      const config = {
-        ..._jsdocBase.default,
-        source: {
-          ..._jsdocBase.default.source,
-          include: [_nodePath.default.resolve(srcPath)]
-        },
-        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,
-          ...(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();
-        await runJsdoc(bin, ['-c', configPath]);
-      } 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/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,

package/dist/partials/resolveDocsMethod.js

@@ -1,19 +1,19 @@
-"use strict";
-
-require("core-js/modules/esnext.weak-map.delete-all.js");
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.resolveDocsMethod = void 0;
-var gulpConfig = _interopRequireWildcard(require("../../gulp.config.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.resolveDocsMethod = void 0;
+var gulpConfig = _interopRequireWildcard(require("../../gulp.config.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; }
 /**
  * Pick which engine generates the HTML documentation: docs.method picks it explicitly; left unset (false, the
  * default), it's inferred from typescript.enabled - every existing TypeScript project's config, which never
  * sets method, keeps producing TypeDoc output exactly as it always has.
  * @memberOf module:partials
  * @returns {'typedoc'|'jsdoc'}
- */
-const resolveDocsMethod = () => gulpConfig.get('docs.method') || (gulpConfig.get('typescript.enabled') ? 'typedoc' : 'jsdoc');
+ */
+const resolveDocsMethod = () => gulpConfig.get('docs.method') || (gulpConfig.get('typescript.enabled') ? 'typedoc' : 'jsdoc');
 exports.resolveDocsMethod = resolveDocsMethod;

package/dist/partials/serveStatic.js

@@ -0,0 +1,57 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.serveStatic = void 0;
+var _nodeFs = _interopRequireDefault(require("node:fs"));
+var _nodeHttp = _interopRequireDefault(require("node:http"));
+var _nodePath = _interopRequireDefault(require("node:path"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// A real, previously-undiscovered bug fixed here: without a Content-Type header, a browser enforces strict MIME
+// checking on <script type="module"> and refuses to load it at all - exactly the case this partial exists for.
+const contentTypes = {
+  '.css': 'text/css',
+  '.gif': 'image/gif',
+  '.html': 'text/html',
+  '.ico': 'image/x-icon',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.js': 'text/javascript',
+  '.json': 'application/json',
+  '.mjs': 'text/javascript',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2'
+};
+
+/**
+ * Serve a directory's real files over plain HTTP, for anything that needs a page loaded from a real URL rather
+ * than a bare file:// path - most commonly, a page using root-relative asset paths (/browser/...), which a
+ * file:// load resolves against the filesystem root instead of the page's own directory.
+ * @memberOf module:partials
+ * @param {string} rootDir - The directory to serve.
+ * @param {number} [port=0] - The port to listen on; 0 picks any free port.
+ * @returns {Promise<{server: http.Server, url: string}>} The running server, and its base URL - close the
+ * server yourself (server.close()) once done with it.
+ */
+const serveStatic = (rootDir, port = 0) => new Promise((resolve, reject) => {
+  const server = _nodeHttp.default.createServer((req, res) => {
+    const filePath = _nodePath.default.join(rootDir, decodeURIComponent(req.url.split('?')[0]));
+    _nodeFs.default.readFile(filePath, (error, data) => {
+      if (error) {
+        res.statusCode = 404;
+        return res.end(`Not found: ${req.url}`);
+      }
+      res.setHeader('Content-Type', contentTypes[_nodePath.default.extname(filePath)] || 'application/octet-stream');
+      res.end(data);
+    });
+  });
+  server.once('error', reject);
+  server.listen(port, '127.0.0.1', () => resolve({
+    server,
+    url: `http://127.0.0.1:${server.address().port}`
+  }));
+});
+exports.serveStatic = serveStatic;

package/dist/partials/tsFor.js

@@ -18,7 +18,7 @@ const importGulpTsCompile = () => (0, _loadPeer.importModule)('gulp-ts-compile')
 /**
  * Wrap a stream in a promise that resolves once it finishes writing.
  * @memberOf module:partials
- * @param {import('node:stream').Stream} stream
+ * @param {stream.Stream} stream
  * @returns {Promise<void>}
  */
 const installHint = 'Install it in your project with: npm install --save-dev typescript';
@@ -49,7 +49,7 @@ const streamToPromise = stream => new Promise((resolve, reject) => {
  * gulp-typescript when a removed API call started throwing under TypeScript 7.
  * @memberOf module:partials
  * @param {string} configPath - Path to a tsconfig.json file.
- * @returns {import('typescript').CompilerOptions}
+ * @returns {ts.CompilerOptions} TypeScript's compiler options
  */
 const readCompilerOptions = (ts, configPath) => {
   const configFile = ts.readConfigFile(configPath, ts.sys.readFile);

package/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');