js-build-tools 5.3.0 → 5.3.2

package/README.md

@@ -35,6 +35,11 @@ provided are the defaults):
     "name": "my-package",
     // The search pattern used for retrieving compiled distribution files.
     "from": "dist/**/*.js",
+    // Module names or file paths which resolve to an empty object ({}) in the bundle instead of their real contents.
+    "ignore": [],
+    // Module names or file paths left out of the bundle entirely (requiring one at runtime throws, unless something
+    // else provides it, for example a script tag which loads it separately).
+    "exclude": [],
     // The output directory for browser-bundled files.
     "to": "browser"
   },
@@ -290,6 +295,27 @@ const jsDocBase = require('js-build-tools/jsdoc.base')
 module.exports = jsDocBase
 ```
 
+### Configure what the browser bundle leaves out (optional)
+
+A dependency can be reached from your code without being needed in the browser, and bundling it can add a lot of size.
+Two settings in `browser` handle this, both take module names or file paths (see browserify's `b.ignore(file)` and
+`b.exclude(file)`):
+
+```json
+{
+  "browser": {
+    // Resolves to an empty object ({}) in the bundle instead of the real module. This suits a dependency which is only
+    // reached because it is the default value of an option you always override with your own (for example a selector
+    // engine's default DOM adapter). Anything only that module requires is left out too. Your code must never actually
+    // use the real module, so keep overriding that option.
+    "ignore": ["some-default-adapter"],
+    // Left out of the bundle entirely. Requiring it at runtime throws unless something else provides it, for example a
+    // script tag which loads it separately, so this suits a large library which the page already loads.
+    "exclude": ["a-library-the-page-loads"]
+  }
+}
+```
+
 ### Configure move fonts (optional)
 
 Be able to copy a source directory of fonts into the distribution path.
@@ -418,7 +444,9 @@ module.exports = babelConfig
 the readme it generates. Instead, this can generate HTML documentation straight from the TypeScript source with
 [TypeDoc](https://typedoc.org/). Every folder in your source directory becomes a module of the documentation, the default
 export of each file (one function per file) is listed under the name of the file, and everything else a file exports (for
-example the types in a `types.ts`) is listed as it is. Index files, tests and declaration files are left out. The
+example the types in a `types.ts`) is listed as it is. Index files, tests and declaration files are left out. A file
+which sits directly in the source directory, beside the folders, is a module of its own (unless it is `index` or
+`main`). The first comment of a folder's `index.ts` (or the header comment of such a file) describes its module. The
 comments on your code are the documentation, and the types come from the code itself, so `@module`, `@memberOf`,
 `@typedef` and the `{Type}` of `@param` are not needed.
 

package/dist/build.js

@@ -1,68 +1,68 @@
-'use strict'
-
-require('core-js/modules/esnext.weak-map.delete-all.js')
-Object.defineProperty(exports, '__esModule', {
-  value: true
-})
-exports.build = void 0
-const _bundle = require('./bundle.js')
-const _bundleLint = require('./bundleLint.js')
-const _bundleMinify = require('./bundleMinify.js')
-const _partials = require('./partials.js')
-const _compileReadme = require('./compileReadme.js')
-const _typeDocs = require('./typeDocs.js')
-const _distLint = require('./distLint.js')
-const _distMinify = require('./distMinify.js')
-const _gulp = require('gulp')
-const gulpConfig = _interopRequireWildcard(require('../gulp.config.js'))
-const _copyFonts = require('./copyFonts.js')
-const _images = require('./images.js')
-const _sass = require('./sass.js')
-const _testFull = require('./testFull.js')
-function _interopRequireWildcard (e, t) { if (typeof WeakMap === 'function') var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; let o; let i; const f = { __proto__: null, default: e }; if (e === null || typeof e !== 'object' && typeof e !== 'function') return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f) } for (const t in e) t !== 'default' && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f })(e, t) }
+'use strict'
+
+require('core-js/modules/esnext.weak-map.delete-all.js')
+Object.defineProperty(exports, '__esModule', {
+  value: true
+})
+exports.build = void 0
+const _bundle = require('./bundle.js')
+const _bundleLint = require('./bundleLint.js')
+const _bundleMinify = require('./bundleMinify.js')
+const _partials = require('./partials.js')
+const _compileReadme = require('./compileReadme.js')
+const _typeDocs = require('./typeDocs.js')
+const _distLint = require('./distLint.js')
+const _distMinify = require('./distMinify.js')
+const _gulp = require('gulp')
+const gulpConfig = _interopRequireWildcard(require('../gulp.config.js'))
+const _copyFonts = require('./copyFonts.js')
+const _images = require('./images.js')
+const _sass = require('./sass.js')
+const _testFull = require('./testFull.js')
+function _interopRequireWildcard (e, t) { if (typeof WeakMap === 'function') var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; let o; let i; const f = { __proto__: null, default: e }; if (e === null || typeof e !== 'object' && typeof e !== 'function') return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f) } for (const t in e) t !== 'default' && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f })(e, t) }
 /**
  * Runs several processes to build and validate the project.
  * Cleans, distributes (lint and minify), bundles (lint and minify), creates the readme, then runs the tests.
  * @memberOf module:js-build-tools
  * @returns {stream.Stream}
- */
-const build = (done = null) => {
-  const distLintMinify = (0, _gulp.parallel)(_distLint.distLint, _distMinify.distMinify)
-  const bundleLintMinify = (0, _gulp.parallel)(_bundleLint.bundleLint, _bundleMinify.bundleMinify)
-  const buildActions = [(0, _partials.distSeries)(), distLintMinify]
-  const generateDocs = gulpConfig.get('docs.enabled')
-  if (generateDocs) {
-    // The documentation is generated from the TypeScript source itself, the readme is written by hand
-    buildActions.push(_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(bundleLintMinify)
-  }
-  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).
-  return (0, _gulp.series)(_partials.clean, (0, _gulp.parallel)(...runActions))(done)
-}
-exports.build = build
+ */
+const build = (done = null) => {
+  const distLintMinify = (0, _gulp.parallel)(_distLint.distLint, _distMinify.distMinify)
+  const bundleLintMinify = (0, _gulp.parallel)(_bundleLint.bundleLint, _bundleMinify.bundleMinify)
+  const buildActions = [(0, _partials.distSeries)(), distLintMinify]
+  const generateDocs = gulpConfig.get('docs.enabled')
+  if (generateDocs) {
+    // The documentation is generated from the TypeScript source itself, the readme is written by hand
+    buildActions.push(_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(bundleLintMinify)
+  }
+  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).
+  return (0, _gulp.series)(_partials.clean, (0, _gulp.parallel)(...runActions))(done)
+}
+exports.build = build

package/dist/partials/imagesFor.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.loadImagemin = exports.imagesFor = void 0;
 var _gulpCache = _interopRequireDefault(require("gulp-cache"));
-var _nodeModule = require("node:module");
+var _loadPeer = require("./loadPeer.js");
 var _gulp = require("gulp");
 var _nodePath = _interopRequireDefault(require("node:path"));
 var gulpConfig = _interopRequireWildcard(require("../../gulp.config.js"));
@@ -24,18 +24,12 @@ const installHint = 'Add it to your project with: npm install --save-dev github:
  * @throws {Error} With install instructions when gulp-imagemin is missing or is the ESM-only upstream release.
  */
 const loadImagemin = (projectPath = process.cwd()) => {
-  let loaded;
-  try {
-    loaded = (0, _nodeModule.createRequire)(_nodePath.default.join(projectPath, 'package.json'))('gulp-imagemin');
-  } catch (error) {
-    if (error.code === 'MODULE_NOT_FOUND' && /Cannot find module 'gulp-imagemin'/.test(error.message)) {
-      throw new Error(`The images task needs the optional peer dependency gulp-imagemin, which is not installed. ${installHint}`);
-    }
-    if (error.code === 'ERR_REQUIRE_ESM') {
-      throw new Error(`gulp-imagemin could not be loaded because it is ESM-only. ${installHint}`);
-    }
-    throw error;
-  }
+  const loaded = (0, _loadPeer.requirePeer)('gulp-imagemin', {
+    task: 'images',
+    installHint,
+    esmOnlyMessage: `gulp-imagemin could not be loaded because it is ESM-only. ${installHint}`,
+    projectPath
+  });
   return loaded && (loaded.__esModule || loaded.default) ? loaded.default : loaded;
 };
 

package/dist/partials/loadPeer.js

@@ -0,0 +1,99 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.requirePeer = exports.importPeer = exports.importModule = void 0;
+require("core-js/modules/es.array.includes.js");
+var _nodeModule = require("node:module");
+var _nodePath = _interopRequireDefault(require("node:path"));
+var _nodeUrl = require("node:url");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// Several dependencies ship ESM-only (standard, gulp-ts-compile, typedoc), but this package also publishes a CommonJS
+// build (dist/*.js) whose babel transform would turn even a dynamic import() into a require() that cannot load an ES
+// module. Hiding the import() inside a Function constructor keeps it a genuine dynamic import that works from either
+// build, because babel cannot see (and so cannot rewrite) an import expression which only exists as a runtime string.
+const dynamicImport = new Function('specifier', 'return import(specifier)');
+
+/**
+ * Import an ES module (or any module) with a real dynamic import(), whichever build (ESM or CommonJS) this runs from.
+ * @memberOf module:partials
+ * @param {string} specifier - The package name, or the URL of a file.
+ * @returns {Promise<Object>} The module namespace.
+ */
+const importModule = specifier => dynamicImport(specifier);
+exports.importModule = importModule;
+const isMissing = (error, name) => error.code === 'MODULE_NOT_FOUND' && error.message.includes(`'${name}'`);
+const notInstalled = (name, {
+  task,
+  installHint
+}) => new Error(`The ${task} task needs the optional peer dependency ${name}, which is not installed. ${installHint}`);
+
+/**
+ * Load an optional peer dependency (one which is only needed once a task runs, so projects which never use that task
+ * do not have to install it) with require(), from the project being built rather than from this package. When it is
+ * missing the error explains how to install it.
+ * @memberOf module:partials
+ * @param {string} name - The package name.
+ * @param {Object} options
+ * @param {string} options.task - The task which needs the package, for the error message.
+ * @param {string} options.installHint - How to install it, for the error message.
+ * @param {string} [options.esmOnlyMessage] - The error message when the package turns out to be ESM-only (it cannot be require()d).
+ * @param {string} [options.projectPath=process.cwd()] - The folder of the project (which has the package.json) being built.
+ * @returns {*} Whatever the package exports.
+ * @throws {Error} With install instructions when the package is not installed.
+ */
+const requirePeer = (name, {
+  task,
+  installHint,
+  esmOnlyMessage,
+  projectPath = process.cwd()
+}) => {
+  try {
+    return (0, _nodeModule.createRequire)(_nodePath.default.join(projectPath, 'package.json'))(name);
+  } catch (error) {
+    if (isMissing(error, name)) {
+      throw notInstalled(name, {
+        task,
+        installHint
+      });
+    }
+    if (error.code === 'ERR_REQUIRE_ESM' && esmOnlyMessage) {
+      throw new Error(esmOnlyMessage);
+    }
+    throw error;
+  }
+};
+
+/**
+ * Import an optional peer dependency which ships ESM-only, from the project being built. See {@link requirePeer}.
+ * @memberOf module:partials
+ * @param {string} name - The package name.
+ * @param {Object} options
+ * @param {string} options.task - The task which needs the package, for the error message.
+ * @param {string} options.installHint - How to install it, for the error message.
+ * @param {string} [options.projectPath=process.cwd()] - The folder of the project (which has the package.json) being built.
+ * @returns {Promise<Object>} The module namespace.
+ * @throws {Error} With install instructions when the package is not installed.
+ */
+exports.requirePeer = requirePeer;
+const importPeer = async (name, {
+  task,
+  installHint,
+  projectPath = process.cwd()
+}) => {
+  let resolved;
+  try {
+    resolved = (0, _nodeModule.createRequire)(_nodePath.default.join(projectPath, 'package.json')).resolve(name);
+  } catch (error) {
+    if (isMissing(error, name)) {
+      throw notInstalled(name, {
+        task,
+        installHint
+      });
+    }
+    throw error;
+  }
+  return importModule((0, _nodeUrl.pathToFileURL)(resolved).href);
+};
+exports.importPeer = importPeer;

package/dist/partials/standardLint.js

@@ -8,12 +8,10 @@ require("core-js/modules/esnext.iterator.constructor.js");
 require("core-js/modules/esnext.iterator.for-each.js");
 var _nodePath = _interopRequireDefault(require("node:path"));
 var _through = _interopRequireDefault(require("through2"));
+var _loadPeer = require("./loadPeer.js");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-// `standard` (17+) ships ESM-only, but this package also publishes a CommonJS build (dist/*.js) whose babel
-// transform would turn even a dynamic import() into a require() that cannot load an ES module. Hiding the import()
-// inside a Function constructor keeps it a genuine dynamic import that works from either build (same escape hatch
-// as tsFor.mjs uses for gulp-ts-compile).
-const importStandard = new Function('return import(\'standard\')');
+// `standard` (17+) ships ESM-only, see importModule for how it is imported.
+const importStandard = () => (0, _loadPeer.importModule)('standard');
 
 /**
  * Print a file's lint messages, if it has any.

package/dist/partials/tsFor.js

@@ -8,18 +8,11 @@ exports.tsFor = exports.loadTypescript = void 0;
 var _gulp = require("gulp");
 var _nodePath = _interopRequireDefault(require("node:path"));
 var gulpConfig = _interopRequireWildcard(require("../../gulp.config.js"));
-var _nodeModule = require("node:module");
+var _loadPeer = require("./loadPeer.js");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-// gulp-ts-compile ships ESM-only (no CJS build - see its own package.json) since it's meant to be consumed by
-// gulpfiles running under a real ESM loader, same as this project's own gulpfile.mjs does. This project also
-// compiles itself to a CommonJS build (dist/*.js, this file's own compiled counterpart) for consumers using
-// require() though, and even a dynamic `import()` gets downleveled by babel's CommonJS transform into a
-// require() call - which can't load a real ES module. Hiding the import() call inside a Function constructor is
-// the standard escape hatch: babel can't see (and so can't rewrite) an import expression that only exists as a
-// runtime-evaluated string, so it survives as a genuine dynamic import, capable of loading gulp-ts-compile from
-// either build.
-const importGulpTsCompile = new Function('return import(\'gulp-ts-compile\')');
+// gulp-ts-compile ships ESM-only (no CJS build - see its own package.json), see importModule for how it is imported.
+const importGulpTsCompile = () => (0, _loadPeer.importModule)('gulp-ts-compile');
 
 /**
  * Wrap a stream in a promise that resolves once it finishes writing.
@@ -37,16 +30,11 @@ const installHint = 'Install it in your project with: npm install --save-dev typ
  * @returns {Object} The TypeScript compiler API module.
  * @throws {Error} With install instructions when typescript is not installed.
  */
-const loadTypescript = (projectPath = process.cwd()) => {
-  try {
-    return (0, _nodeModule.createRequire)(_nodePath.default.join(projectPath, 'package.json'))('typescript');
-  } catch (error) {
-    if (error.code === 'MODULE_NOT_FOUND' && /Cannot find module 'typescript'/.test(error.message)) {
-      throw new Error(`The typescript task needs the optional peer dependency typescript, which is not installed. ${installHint}`);
-    }
-    throw error;
-  }
-};
+const loadTypescript = (projectPath = process.cwd()) => (0, _loadPeer.requirePeer)('typescript', {
+  task: 'typescript',
+  installHint,
+  projectPath
+});
 exports.loadTypescript = loadTypescript;
 const streamToPromise = stream => new Promise((resolve, reject) => {
   stream.on('finish', resolve);

package/dist/partials/typeDocsFor.js

@@ -4,10 +4,11 @@ require("core-js/modules/esnext.weak-map.delete-all.js");
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.writeDocEntries = exports.typeDocsFor = exports.loadTypeDoc = exports.describeExports = void 0;
+exports.writeDocEntries = exports.typeDocsFor = exports.loadTypeDoc = exports.describeFolder = exports.describeFile = exports.describeExports = void 0;
 require("core-js/modules/es.json.stringify.js");
 require("core-js/modules/esnext.iterator.constructor.js");
 require("core-js/modules/esnext.iterator.filter.js");
+require("core-js/modules/esnext.iterator.find.js");
 require("core-js/modules/esnext.iterator.flat-map.js");
 require("core-js/modules/esnext.iterator.for-each.js");
 require("core-js/modules/esnext.iterator.map.js");
@@ -15,16 +16,12 @@ require("core-js/modules/esnext.iterator.some.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 _nodeUrl = require("node:url");
 var gulpConfig = _interopRequireWildcard(require("../../gulp.config.js"));
+var _loadPeer = require("./loadPeer.js");
 var _tsFor = require("./tsFor.js");
 var _removeDirectory = require("./removeDirectory.js");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-// TypeDoc ships ESM-only, and this project also compiles itself to a CommonJS build (see tsFor.mjs, which hides its
-// own import of gulp-ts-compile the same way), so the import() is hidden from babel's CommonJS transform.
-const importModule = new Function('specifier', 'return import(specifier)');
 const installHint = 'Install it in your project with: npm install --save-dev typedoc';
 
 /**
@@ -35,18 +32,11 @@ const installHint = 'Install it in your project with: npm install --save-dev typ
  * @returns {Promise<Object>} The TypeDoc module.
  * @throws {Error} With install instructions when typedoc is not installed.
  */
-const loadTypeDoc = async (projectPath = process.cwd()) => {
-  let typeDocPath;
-  try {
-    typeDocPath = (0, _nodeModule.createRequire)(_nodePath.default.join(projectPath, 'package.json')).resolve('typedoc');
-  } catch (error) {
-    if (error.code === 'MODULE_NOT_FOUND') {
-      throw new Error(`The docs task needs the optional peer dependency typedoc, which is not installed. ${installHint}`);
-    }
-    throw error;
-  }
-  return importModule((0, _nodeUrl.pathToFileURL)(typeDocPath).href);
-};
+const loadTypeDoc = (projectPath = process.cwd()) => (0, _loadPeer.importPeer)('typedoc', {
+  task: 'docs',
+  installHint,
+  projectPath
+});
 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, {
@@ -102,19 +92,53 @@ const describeExports = (ts, filePath) => {
   };
 };
 
+/**
+ * The description of a folder for its module: the first doc comment of the folder's index file, without its tags
+ * (@module, @file, ...), or an empty string when there is none.
+ * @memberOf module:partials
+ * @param {string} folderPath
+ * @returns {string}
+ */
+exports.describeExports = describeExports;
+const describeFolder = folderPath => {
+  const indexFile = ['index.ts', 'index.tsx', 'index.mts', 'index.cts'].map(name => _nodePath.default.join(folderPath, name)).find(file => _nodeFs.default.existsSync(file));
+  return indexFile ? describeFile(indexFile) : '';
+};
+
+/**
+ * The description of a source file for its module: its first doc comment without the tags (@module, @file, ...), when
+ * that comment is a header (it is followed by an import or export, so it does not document a declaration itself), or
+ * an empty string.
+ * @memberOf module:partials
+ * @param {string} filePath
+ * @returns {string}
+ */
+exports.describeFolder = describeFolder;
+const describeFile = filePath => {
+  const comment = _nodeFs.default.readFileSync(filePath, 'utf8').match(/^\s*\/\*\*([\s\S]*?)\*\/\s*(import\b|export\s+(\*|\{[^}]*\}\s+from)|$)/);
+  if (!comment) {
+    return '';
+  }
+  const lines = comment[1].split('\n').map(line => line.replace(/^\s*\* ?/, '').trimEnd());
+  const tagAt = lines.findIndex(line => /^@\w+/.test(line));
+  return (tagAt === -1 ? lines : lines.slice(0, tagAt)).join('\n').trim();
+};
+
 /**
  * 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
  * 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. A source directory with no folders gets a single entry called index.
+ * 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
+ * comment. A source directory with no folders gets a single entry called index.
  * @memberOf module:partials
  * @param {Object} ts - The TypeScript compiler API.
  * @param {string} srcDir - The directory holding the TypeScript source.
  * @param {string} entryDir - The directory to write the entry files into.
  * @returns {Array<string>} The paths of the entry files.
  */
-exports.describeExports = describeExports;
+exports.describeFile = describeFile;
 const writeDocEntries = (ts, srcDir, entryDir) => {
   const absoluteSrc = _nodePath.default.resolve(srcDir);
   _nodeFs.default.mkdirSync(entryDir, {
@@ -124,11 +148,22 @@ const writeDocEntries = (ts, srcDir, entryDir) => {
     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 groups = folders.length ? folders : [{
+  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 groups = folders.length ? [...folders, ...rootFiles.map(file => ({
+    name: toIdentifier(_nodePath.default.basename(file).replace(/\.[cm]?tsx?$/, '')),
+    files: [file],
+    description: describeFile(file)
+  })).filter(group => !folders.some(folder => folder.name === group.name))] : [{
     name: 'index',
-    files: listSources(absoluteSrc).filter(file => !/^(index|main)\./.test(_nodePath.default.basename(file)))
+    path: absoluteSrc,
+    files: rootFiles
   }];
   return groups.map(group => {
     const lines = group.files.filter(file => !/^index\./.test(_nodePath.default.basename(file))).sort().flatMap(file => {
@@ -140,8 +175,11 @@ const writeDocEntries = (ts, srcDir, entryDir) => {
       const fileName = _nodePath.default.basename(file).replace(/\.[cm]?tsx?$/, '');
       return [...(hasDefault ? [`export { default as ${toIdentifier(fileName)} } from '${modulePath}'`] : []), ...(hasNamed ? [`export * from '${modulePath}'`] : [])];
     });
+    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` : '';
     const entryPath = _nodePath.default.join(entryDir, `${group.name}.ts`);
-    _nodeFs.default.writeFileSync(entryPath, lines.join('\n') + '\n');
+    _nodeFs.default.writeFileSync(entryPath, moduleComment + lines.join('\n') + '\n');
     return entryPath;
   });
 };