js-build-tools 5.6.0 → 5.7.0

package/README.md

@@ -40,6 +40,8 @@ provided are the defaults):
     // 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": [],
+    // Additional bundles to produce alongside the primary one above (see 'Configure additional browser bundles').
+    "bundles": [],
     // The output directory for browser-bundled files.
     "to": "browser"
   },
@@ -100,6 +102,9 @@ provided are the defaults):
     "from": [
       "src/**/!(*.test).js"
     ],
+    // Additional .mjs files to document alongside 'from' (see 'Configure including ESM files in the generated
+    // readme'). Empty by default: a project that never sets this gets exactly the readme it always did.
+    "fromEsm": [],
     // The directory to output the readme file in.
     "to": "./"
   },
@@ -316,6 +321,56 @@ Two settings in `browser` handle this, both take module names or file paths (see
 }
 ```
 
+### Configure additional browser bundles (optional)
+
+By default a project produces exactly one browser bundle, from `dist.main`/`browser.name`/`browser.ignore`/
+`browser.exclude` above. `browser.bundles` adds more bundles alongside it - for example a render-only variant built
+from a different entry point than the full bundle. Each entry only needs to specify what's actually different about
+that bundle; anything left out falls back to the primary bundle's own value:
+
+```json
+{
+  "browser": {
+    "bundles": [
+      {
+        // Required, and must be unique among all of a project's bundles: the name for this bundle's own output file
+        // and standalone export.
+        "name": "render-only",
+        // This bundle's own entry point. Falls back to dist.main when omitted.
+        "main": "dist/renderOnly.js",
+        // This bundle's own ignore list. Falls back to browser.ignore when omitted.
+        "ignore": [],
+        // This bundle's own exclude list. Falls back to browser.exclude when omitted.
+        "exclude": []
+      }
+    ]
+  }
+}
+```
+
+For the `gulpConfig` module's own `get`/`set` functions (read or override a resolved configuration value from your
+own code, by the same dot-notation path a setting has in the JSON above), see the generated reference below.
+
+### Configure including ESM files in the generated readme (optional)
+
+The readme generator (`jsdoc-to-markdown`) only recognizes `.js` files, even though it parses real ESM `import`/
+`export` syntax just fine once it reads one - the file extension is the only thing it filters on, not the content.
+`readme.fromEsm` names `.mjs` files to document anyway: each one is read, rewritten (every top-level `export const`/
+`export function`/`export class` becomes a plain declaration plus a trailing `module.exports = { ... }` - the same
+shape `jsdoc-to-markdown` already documents cleanly, since that rewrite is exactly what this project's own
+`gulp.config.mjs` needs it for) and written to a temp `.js` file outside your project entirely, which is cleaned up
+again once the readme generator has read it. Other export forms (`export default`, re-exports, `export { a, b }`
+lists) are left untouched in whatever way `jsdoc-to-markdown` already handles ESM - restructure a file to use named
+exports if you want it documented this cleanly:
+
+```json
+{
+  "readme": {
+    "fromEsm": ["src/myEsmOnlyModule.mjs"]
+  }
+}
+```
+
 ### Configure move fonts (optional)
 
 Be able to copy a source directory of fonts into the distribution path.
@@ -546,10 +601,12 @@ Modify these configurations to match your project specifications.
         * [~StringSetting](#module_gulpConfig..StringSetting) : <code>string</code>
         * [~Setting](#module_gulpConfig..Setting) : <code>ArrayableSetting</code> \| <code>BooleanSetting</code> \| <code>FlagsSetting</code> \| <code>StringSetting</code>
         * [~BrowserConfig](#module_gulpConfig..BrowserConfig) : <code>Object.&lt;string, Setting&gt;</code>
+        * [~AdditionalBundleConfig](#module_gulpConfig..AdditionalBundleConfig) : <code>Object.&lt;string, Setting&gt;</code>
         * [~DistConfig](#module_gulpConfig..DistConfig) : <code>Object.&lt;string, Setting&gt;</code>
         * [~FontConfig](#module_gulpConfig..FontConfig) : <code>Object.&lt;string, Setting&gt;</code>
         * [~ImageConfig](#module_gulpConfig..ImageConfig) : <code>Object.&lt;string, Setting&gt;</code>
         * [~ReadmeConfig](#module_gulpConfig..ReadmeConfig) : <code>Object.&lt;string, Setting&gt;</code>
+        * [~DocsConfig](#module_gulpConfig..DocsConfig) : <code>Object.&lt;string, Setting&gt;</code>
         * [~SassConfig](#module_gulpConfig..SassConfig) : <code>Object.&lt;string, Setting&gt;</code>
         * [~TestConfig](#module_gulpConfig..TestConfig) : <code>Object.&lt;string, Setting&gt;</code>
         * [~TsConfig](#module_gulpConfig..TsConfig) : <code>Object.&lt;string, Setting&gt;</code>
@@ -646,9 +703,27 @@ Configurations for building the browser files.
 | Name | Type | Description |
 | --- | --- | --- |
 | enabled | <code>BooleanSetting</code> | 'true' to generate browser bundled files; 'false' for node environment only |
-| from | <code>StringSetting</code> | The name to use for the browser-bundled output file (.js will be appended). |
-| name | <code>StringSetting</code> | The search pattern used for retrieving compiled distribution files. |
+| from | <code>StringSetting</code> | The search pattern used for retrieving compiled distribution files. |
+| name | <code>StringSetting</code> | The name to use for the browser-bundled output file (.js will be appended). |
 | to | <code>StringSetting</code> | The output directory for browser-bundled files. |
+| ignore | <code>ArrayableSetting</code> | Module names or file paths which resolve to an empty object ({}) in the bundle instead of their real contents. For a dependency which is only reached because it is the default value of an option you always override (for example a selector engine's default DOM adapter, when you always pass your own), this keeps it (and anything only it requires) out of the bundle, as long as your code never actually reaches the real module by not overriding that option. See browserify's b.ignore(file). |
+| exclude | <code>ArrayableSetting</code> | 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 loading it separately). See browserify's b.exclude(file). |
+| bundles | [<code>Array.&lt;AdditionalBundleConfig&gt;</code>](#module_gulpConfig..AdditionalBundleConfig) | Additional bundles to produce alongside the primary one (name/dist.main/ignore/exclude above) - for example a render-only variant built from a different entry point than the full bundle. Empty by default: a project that never sets this gets exactly the one bundle it always did. |
+
+<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
+
+**Kind**: inner typedef of [<code>gulpConfig</code>](#module_gulpConfig)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| name | <code>StringSetting</code> | The name for this bundle's output file and standalone export - must be unique among all of a project's bundles. |
+| [main] | <code>StringSetting</code> | This bundle's own entry point. Falls back to dist.main when omitted. |
+| [ignore] | <code>ArrayableSetting</code> | This bundle's own ignore list. Falls back to browser.ignore when omitted. |
+| [exclude] | <code>ArrayableSetting</code> | This bundle's own exclude list. Falls back to browser.exclude when omitted. |
 
 <a name="module_gulpConfig..DistConfig"></a>
 
@@ -704,10 +779,29 @@ Configurations to compile and generate the Readme file.
 | --- | --- | --- |
 | file | <code>StringSetting</code> | The name of the output documentation markdown file. |
 | from | <code>StringSetting</code> | Location of files to use for compiling documentation into the readme. |
+| fromEsm | <code>ArrayableSetting</code> | Additional `.mjs` files to document alongside `from`, converted on the fly since the readme generator only recognizes `.js` files - see 'Configure including ESM files in the generated readme'. Empty by default: a project that never sets this gets exactly the readme it always did. |
 | options | <code>ArrayableSetting</code> | Options for formatting the output readme. |
 | template | <code>StringSetting</code> | The file which will be pre-fixed to your README.md output. |
 | to | <code>StringSetting</code> | The directory to output the readme file in. |
 
+<a name="module_gulpConfig..DocsConfig"></a>
+
+### gulpConfig~DocsConfig : <code>Object.&lt;string, Setting&gt;</code>
+Configurations for generating the HTML documentation of a TypeScript project (with TypeDoc, from the source).
+
+**Kind**: inner typedef of [<code>gulpConfig</code>](#module_gulpConfig)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| enabled | <code>BooleanSetting</code> | Toggle generating the documentation from the TypeScript 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 TypeScript source, each folder in it becomes a module. |
+| 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. |
+| title | <code>StringSetting</code> | The name of the documentation, defaults to the name in the package.json. |
+| to | <code>StringSetting</code> | The directory to generate the documentation in (it is cleared first). |
+| tsconfig | <code>FlagStringSetting</code> | The tsconfig file to read the source with, defaults to the one of typescript.config. |
+
 <a name="module_gulpConfig..SassConfig"></a>
 
 ### gulpConfig~SassConfig : <code>Object.&lt;string, Setting&gt;</code>
@@ -765,6 +859,7 @@ A set of Configurations options defined by Settings.
 | browser | <code>BrowserConfig</code> | Browser bundling configuration group. |
 | cleanPaths | <code>ArrayableSetting</code> | The paths for directories to delete before build. |
 | dist | <code>DistConfig</code> | Distribution file generation configuration group. |
+| docs | <code>DocsConfig</code> | Generate the documentation of a TypeScript project configuration group. |
 | fonts | <code>FontConfig</code> | Fonts copy configuration group. |
 | images | <code>ImageConfig</code> | Minify and copy the images configuration. |
 | readme | <code>ReadmeConfig</code> | Build readme files configuration. |

package/dist/partials/addToReadme.js

@@ -1,23 +1,34 @@
-"use strict";
-
-require("core-js/modules/esnext.weak-map.delete-all.js");
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.addToReadme = void 0;
-var _fs = _interopRequireDefault(require("fs"));
-var gulpConfig = _interopRequireWildcard(require("../../gulp.config.js"));
-var _jsdocToMarkdown = _interopRequireDefault(require("jsdoc-to-markdown"));
-var _glob = require("glob");
-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 }; }
+"use strict";
+
+require("core-js/modules/esnext.weak-map.delete-all.js");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.addToReadme = void 0;
+var _fs = _interopRequireDefault(require("fs"));
+var gulpConfig = _interopRequireWildcard(require("../../gulp.config.js"));
+var _jsdocToMarkdown = _interopRequireDefault(require("jsdoc-to-markdown"));
+var _glob = require("glob");
+var _convertMjsFilesForDocs = require("../utilities/convertMjsFilesForDocs.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 }; }
 /**
  * Appends all the jsdoc comments to the readme file. Assumes empty or templated file.
  * Configure this with 'readmeSearch', 'readmePath', 'readmeFile', and 'readmeOptions'.
+ *
+ * jsdoc-to-markdown only recognizes `.js` files, even though it parses real ESM syntax just fine once it reads
+ * one - `readme.fromEsm` (empty by default) names `.mjs` files to include anyway, converted on the fly (see
+ * {@link convertMjsFilesForDocs}) and cleaned up again once this has read them, win or lose.
  * @memberOf module:partials
  * @returns {string|Uint8Array}
- */
-const addToReadme = () => _jsdocToMarkdown.default.render({
-  files: (0, _glob.globSync)(gulpConfig.get('readme.from'))
-}).then(readme => _fs.default.appendFileSync(gulpConfig.get('readme.to') + gulpConfig.get('readme.file'), readme, gulpConfig.get('readmeOptions')));
+ */
+const addToReadme = () => {
+  const {
+    filePaths: esmFilePaths,
+    cleanUp
+  } = (0, _convertMjsFilesForDocs.convertMjsFilesForDocs)((0, _glob.globSync)(gulpConfig.get('readme.fromEsm') || []));
+  return _jsdocToMarkdown.default.render({
+    files: [...(0, _glob.globSync)(gulpConfig.get('readme.from')), ...esmFilePaths]
+  }).finally(cleanUp).then(readme => _fs.default.appendFileSync(gulpConfig.get('readme.to') + gulpConfig.get('readme.file'), readme, gulpConfig.get('readmeOptions')));
+};
 exports.addToReadme = addToReadme;

package/dist/test-helpers/setUp.js

@@ -1,94 +1,99 @@
-"use strict";
-
-require("core-js/modules/esnext.weak-map.delete-all.js");
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "afterEach", {
-  enumerable: true,
-  get: function () {
-    return _testFilesystem.afterEach;
-  }
-});
-Object.defineProperty(exports, "beforeEach", {
-  enumerable: true,
-  get: function () {
-    return _testFilesystem.beforeEach;
-  }
-});
-Object.defineProperty(exports, "countMatches", {
-  enumerable: true,
-  get: function () {
-    return _testFilesystem.countMatches;
-  }
-});
-Object.defineProperty(exports, "createTempDir", {
-  enumerable: true,
-  get: function () {
-    return _testFilesystem.createTempDir;
-  }
-});
-Object.defineProperty(exports, "fileExists", {
-  enumerable: true,
-  get: function () {
-    return _testFilesystem.fileExists;
-  }
-});
-exports.gulpConfig = void 0;
-Object.defineProperty(exports, "logObject", {
-  enumerable: true,
-  get: function () {
-    return _testFilesystem.logObject;
-  }
-});
-Object.defineProperty(exports, "removeDirectory", {
-  enumerable: true,
-  get: function () {
-    return _testFilesystem.removeDirectory;
-  }
-});
-exports.setDefaults = void 0;
-var gulpConfig = _interopRequireWildcard(require("../../gulp.config.js"));
-exports.gulpConfig = gulpConfig;
-var _testFilesystem = require("test-filesystem");
-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); }
-// Import the configurations and override some of them to direct to the temp directory.
-
-let tempDir = 'test-temp/';
-let srcPath = `${tempDir}src`;
-
+"use strict";
+
+require("core-js/modules/esnext.weak-map.delete-all.js");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "afterEach", {
+  enumerable: true,
+  get: function () {
+    return _testFilesystem.afterEach;
+  }
+});
+Object.defineProperty(exports, "beforeEach", {
+  enumerable: true,
+  get: function () {
+    return _testFilesystem.beforeEach;
+  }
+});
+Object.defineProperty(exports, "countMatches", {
+  enumerable: true,
+  get: function () {
+    return _testFilesystem.countMatches;
+  }
+});
+Object.defineProperty(exports, "createTempDir", {
+  enumerable: true,
+  get: function () {
+    return _testFilesystem.createTempDir;
+  }
+});
+Object.defineProperty(exports, "fileExists", {
+  enumerable: true,
+  get: function () {
+    return _testFilesystem.fileExists;
+  }
+});
+exports.gulpConfig = void 0;
+Object.defineProperty(exports, "logObject", {
+  enumerable: true,
+  get: function () {
+    return _testFilesystem.logObject;
+  }
+});
+Object.defineProperty(exports, "removeDirectory", {
+  enumerable: true,
+  get: function () {
+    return _testFilesystem.removeDirectory;
+  }
+});
+exports.setDefaults = void 0;
+var gulpConfig = _interopRequireWildcard(require("../../gulp.config.js"));
+exports.gulpConfig = gulpConfig;
+var _testFilesystem = require("test-filesystem");
+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); }
+// Import the configurations and override some of them to direct to the temp directory.
+
+let tempDir = 'test-temp/';
+let srcPath = `${tempDir}src`;
+
 /**
  * Update the gulp configurations with the test data. Set the test directory where temp files will be created for testing.
  * @memberOf module:testHelpers
  * @param {string} testDir
- */
-const setDefaults = (testDir = 'test-temp') => {
-  tempDir = `${testDir}/`;
-  srcPath = `${tempDir}src`;
-  _testFilesystem.setUp.setDefaults(tempDir);
-  const distPath = `${tempDir}dist`;
-  const browserPath = `${tempDir}browser`;
-  const sassPath = `${tempDir}sass`;
-  gulpConfig.set('browser.from', `${distPath}/**/*.js`);
-  gulpConfig.set('browser.to', browserPath);
-  gulpConfig.set('cleanPaths', [distPath, browserPath]);
-  gulpConfig.set('dist.from', `${srcPath}/**/!(*.test).js`);
-  gulpConfig.set('dist.main', `${distPath}/main`);
-  gulpConfig.set('dist.to', distPath);
-  gulpConfig.set('fonts.from', `${srcPath}/fonts/**/*`);
-  gulpConfig.set('fonts.to', `${browserPath}/fonts`);
-  gulpConfig.set('images.from', `${srcPath}/img/**/*.+(png|jpg|jpeg|gif|svg)`);
-  gulpConfig.set('images.to', `${browserPath}/img`);
-  gulpConfig.set('readme.template', `${tempDir}MAIN.md`);
-  gulpConfig.set('readme.to', tempDir);
-  gulpConfig.set('readme.from', `${srcPath}/**/!(*.test).js`);
-  gulpConfig.set('rootPath', tempDir);
-  gulpConfig.set('sass.from', `${sassPath}/**/*.+(scss|sass)`);
-  gulpConfig.set('sass.path', sassPath);
-  gulpConfig.set('sass.to', `${browserPath}/css`);
-  gulpConfig.set('srcPath', srcPath);
-  gulpConfig.set('typescript.from', `${srcPath}/**/*.ts`);
-  gulpConfig.set('typescript.to', distPath);
-  gulpConfig.set('test.watch', `${srcPath}/**/*.js`);
-};
+ */
+const setDefaults = (testDir = 'test-temp') => {
+  tempDir = `${testDir}/`;
+  srcPath = `${tempDir}src`;
+  _testFilesystem.setUp.setDefaults(tempDir);
+  const distPath = `${tempDir}dist`;
+  const browserPath = `${tempDir}browser`;
+  const sassPath = `${tempDir}sass`;
+  gulpConfig.set('browser.from', `${distPath}/**/*.js`);
+  gulpConfig.set('browser.to', browserPath);
+  gulpConfig.set('cleanPaths', [distPath, browserPath]);
+  gulpConfig.set('dist.from', `${srcPath}/**/!(*.test).js`);
+  gulpConfig.set('dist.main', `${distPath}/main`);
+  gulpConfig.set('dist.to', distPath);
+  gulpConfig.set('fonts.from', `${srcPath}/fonts/**/*`);
+  gulpConfig.set('fonts.to', `${browserPath}/fonts`);
+  gulpConfig.set('images.from', `${srcPath}/img/**/*.+(png|jpg|jpeg|gif|svg)`);
+  gulpConfig.set('images.to', `${browserPath}/img`);
+  gulpConfig.set('readme.template', `${tempDir}MAIN.md`);
+  gulpConfig.set('readme.to', tempDir);
+  gulpConfig.set('readme.from', `${srcPath}/**/!(*.test).js`);
+  // Reset explicitly: gulpConfig is a process-wide singleton seeded once from this real project's own
+  // build-tools.config.json, so without this, this project's own real readme.fromEsm value (gulp.config.mjs)
+  // would leak into every test that exercises addToReadme/compileReadme but never sets this path itself -
+  // doing real file I/O and a real jsdoc-to-markdown parse of this project's own, much larger, config file.
+  gulpConfig.set('readme.fromEsm', []);
+  gulpConfig.set('rootPath', tempDir);
+  gulpConfig.set('sass.from', `${sassPath}/**/*.+(scss|sass)`);
+  gulpConfig.set('sass.path', sassPath);
+  gulpConfig.set('sass.to', `${browserPath}/css`);
+  gulpConfig.set('srcPath', srcPath);
+  gulpConfig.set('typescript.from', `${srcPath}/**/*.ts`);
+  gulpConfig.set('typescript.to', distPath);
+  gulpConfig.set('test.watch', `${srcPath}/**/*.js`);
+};
 exports.setDefaults = setDefaults;

package/dist/utilities/convertMjsFilesForDocs.js

@@ -0,0 +1,48 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.convertMjsFilesForDocs = void 0;
+require("core-js/modules/esnext.iterator.constructor.js");
+require("core-js/modules/esnext.iterator.map.js");
+var _fs = _interopRequireDefault(require("fs"));
+var _os = _interopRequireDefault(require("os"));
+var _path = _interopRequireDefault(require("path"));
+var _esmNamedExportsToCjs = require("./esmNamedExportsToCjs.js");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Writes a rewritten (see {@link esmNamedExportsToCjs}) copy of each given `.mjs` file into a fresh, unique
+ * directory under the OS temp directory, with a `.js` extension - jsdoc-to-markdown only recognizes `.js` as a
+ * documentable file, regardless of whether its contents are actually CommonJS or ESM (it parses the real ESM
+ * syntax of the rest of a file fine; the extension is the only thing it filters on). Writing outside the project
+ * tree means there is nothing to gitignore and nothing left behind in the project - call the returned `cleanUp`
+ * once done (for example, right after jsdoc-to-markdown has read the files) to remove the temp directory.
+ * @memberOf module:utilities
+ * @param {Array<string>} mjsFilePaths - Real `.mjs` files to convert. An empty array is a safe, cheap no-op.
+ * @returns {{filePaths: Array<string>, cleanUp: function(): void}} The temp `.js` file paths to pass to
+ * jsdoc-to-markdown instead of the real `.mjs` ones, and a function to remove the temp directory afterward.
+ */
+const convertMjsFilesForDocs = (mjsFilePaths = []) => {
+  if (mjsFilePaths.length === 0) {
+    return {
+      filePaths: [],
+      cleanUp: () => {}
+    };
+  }
+  const tempDir = _fs.default.mkdtempSync(_path.default.join(_os.default.tmpdir(), 'js-build-tools-docs-'));
+  const filePaths = mjsFilePaths.map(mjsFilePath => {
+    const tempFilePath = _path.default.join(tempDir, _path.default.basename(mjsFilePath, '.js') + '.js');
+    const source = _fs.default.readFileSync(mjsFilePath, 'utf8');
+    _fs.default.writeFileSync(tempFilePath, (0, _esmNamedExportsToCjs.esmNamedExportsToCjs)(source));
+    return tempFilePath;
+  });
+  return {
+    filePaths,
+    cleanUp: () => _fs.default.rmSync(tempDir, {
+      recursive: true,
+      force: true
+    })
+  };
+};
+exports.convertMjsFilesForDocs = convertMjsFilesForDocs;

package/dist/utilities/esmNamedExportsToCjs.js

@@ -0,0 +1,33 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.esmNamedExportsToCjs = void 0;
+/**
+ * Rewrites named `export const`/`export function`/`export class` declarations to plain declarations plus a
+ * trailing `module.exports = { ... }` - the same shape jsdoc-to-markdown already documents cleanly (a plain
+ * declaration with its own `@memberOf` tag, exported all at once at the bottom), rather than the "exports.name"
+ * longname jsdoc-to-markdown's own ESM-compat layer produces for an inline `export const name = ...`.
+ *
+ * This is a narrow, text-level rewrite for documentation purposes only - it does not execute the module, so it
+ * only has to look enough like the real thing for jsdoc-to-markdown's parser. It handles the common named-export
+ * forms (`export const`, `export function`, `export class`) and leaves everything else (including `export
+ * default`, re-exports, and `export { a, b }` lists) untouched in place - a file using one of those keeps its
+ * own export line as-is, which jsdoc-to-markdown will document however it already does for ESM.
+ * @memberOf module:utilities
+ * @param {string} source - The raw ESM source text (never executed, just rewritten as text).
+ * @returns {string} The rewritten text, safe to write out with a `.js` extension for jsdoc-to-markdown to read.
+ */
+const esmNamedExportsToCjs = source => {
+  const exportedNames = [];
+  const rewritten = source.replace(/^export (const|function|class) (\w+)/gm, (match, keyword, name) => {
+    exportedNames.push(name);
+    return `${keyword} ${name}`;
+  });
+  if (exportedNames.length === 0) {
+    return rewritten;
+  }
+  return `${rewritten}\n\nmodule.exports = { ${exportedNames.join(', ')} }\n`;
+};
+exports.esmNamedExportsToCjs = esmNamedExportsToCjs;

package/functions/partials/addToReadme.mjs

@@ -2,15 +2,24 @@ import fs from 'fs'
 import * as gulpConfig from '../../gulp.config.mjs'
 import jsdoc2md from 'jsdoc-to-markdown'
 import { globSync } from 'glob'
+import { convertMjsFilesForDocs } from '../utilities/convertMjsFilesForDocs.mjs'
 
 /**
  * Appends all the jsdoc comments to the readme file. Assumes empty or templated file.
  * Configure this with 'readmeSearch', 'readmePath', 'readmeFile', and 'readmeOptions'.
+ *
+ * jsdoc-to-markdown only recognizes `.js` files, even though it parses real ESM syntax just fine once it reads
+ * one - `readme.fromEsm` (empty by default) names `.mjs` files to include anyway, converted on the fly (see
+ * {@link convertMjsFilesForDocs}) and cleaned up again once this has read them, win or lose.
  * @memberOf module:partials
  * @returns {string|Uint8Array}
  */
-export const addToReadme = () => jsdoc2md
-  .render({ files: globSync(gulpConfig.get('readme.from')) })
-  .then(
-    readme => fs.appendFileSync(gulpConfig.get('readme.to') + gulpConfig.get('readme.file'), readme, gulpConfig.get('readmeOptions'))
-  )
+export const addToReadme = () => {
+  const { filePaths: esmFilePaths, cleanUp } = convertMjsFilesForDocs(globSync(gulpConfig.get('readme.fromEsm') || []))
+  return jsdoc2md
+    .render({ files: [...globSync(gulpConfig.get('readme.from')), ...esmFilePaths] })
+    .finally(cleanUp)
+    .then(
+      readme => fs.appendFileSync(gulpConfig.get('readme.to') + gulpConfig.get('readme.file'), readme, gulpConfig.get('readmeOptions'))
+    )
+}

package/functions/test-helpers/setUp.mjs

@@ -30,6 +30,11 @@ export const setDefaults = (testDir = 'test-temp') => {
   gulpConfig.set('readme.template', `${tempDir}MAIN.md`)
   gulpConfig.set('readme.to', tempDir)
   gulpConfig.set('readme.from', `${srcPath}/**/!(*.test).js`)
+  // Reset explicitly: gulpConfig is a process-wide singleton seeded once from this real project's own
+  // build-tools.config.json, so without this, this project's own real readme.fromEsm value (gulp.config.mjs)
+  // would leak into every test that exercises addToReadme/compileReadme but never sets this path itself -
+  // doing real file I/O and a real jsdoc-to-markdown parse of this project's own, much larger, config file.
+  gulpConfig.set('readme.fromEsm', [])
   gulpConfig.set('rootPath', tempDir)
   gulpConfig.set('sass.from', `${sassPath}/**/*.+(scss|sass)`)
   gulpConfig.set('sass.path', sassPath)

package/functions/utilities/convertMjsFilesForDocs.mjs

@@ -0,0 +1,33 @@
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import { esmNamedExportsToCjs } from './esmNamedExportsToCjs.mjs'
+
+/**
+ * Writes a rewritten (see {@link esmNamedExportsToCjs}) copy of each given `.mjs` file into a fresh, unique
+ * directory under the OS temp directory, with a `.js` extension - jsdoc-to-markdown only recognizes `.js` as a
+ * documentable file, regardless of whether its contents are actually CommonJS or ESM (it parses the real ESM
+ * syntax of the rest of a file fine; the extension is the only thing it filters on). Writing outside the project
+ * tree means there is nothing to gitignore and nothing left behind in the project - call the returned `cleanUp`
+ * once done (for example, right after jsdoc-to-markdown has read the files) to remove the temp directory.
+ * @memberOf module:utilities
+ * @param {Array<string>} mjsFilePaths - Real `.mjs` files to convert. An empty array is a safe, cheap no-op.
+ * @returns {{filePaths: Array<string>, cleanUp: function(): void}} The temp `.js` file paths to pass to
+ * jsdoc-to-markdown instead of the real `.mjs` ones, and a function to remove the temp directory afterward.
+ */
+export const convertMjsFilesForDocs = (mjsFilePaths = []) => {
+  if (mjsFilePaths.length === 0) {
+    return { filePaths: [], cleanUp: () => {} }
+  }
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'js-build-tools-docs-'))
+  const filePaths = mjsFilePaths.map((mjsFilePath) => {
+    const tempFilePath = path.join(tempDir, path.basename(mjsFilePath, '.mjs') + '.js')
+    const source = fs.readFileSync(mjsFilePath, 'utf8')
+    fs.writeFileSync(tempFilePath, esmNamedExportsToCjs(source))
+    return tempFilePath
+  })
+  return {
+    filePaths,
+    cleanUp: () => fs.rmSync(tempDir, { recursive: true, force: true })
+  }
+}

package/functions/utilities/convertMjsFilesForDocs.test.mjs

@@ -0,0 +1,57 @@
+import fs from 'fs'
+import * as setUp from '../test-helpers/setUp.mjs'
+import { convertMjsFilesForDocs } from './convertMjsFilesForDocs.mjs'
+
+setUp.setDefaults('test-temp-convert-mjs-for-docs')
+const gulpConfig = setUp.gulpConfig
+
+const rawContents = '/**\n' +
+  ' * Say hello with a given name.\n' +
+  ' * @memberOf module:greet\n' +
+  ' * @param {string} name\n' +
+  ' * @returns {string}\n' +
+  ' */\n' +
+  'export const sayHello = name => `Hello from ${name}`\n'
+
+beforeEach(() => setUp.beforeEach()
+  .then(() => fs.writeFileSync(gulpConfig.get('srcPath') + '/greet.mjs', rawContents)))
+
+afterEach(setUp.afterEach)
+
+describe('convertMjsFilesForDocs', () => {
+  test('returns an empty result, with a safe no-op cleanUp, for an empty list', () => {
+    const { filePaths, cleanUp } = convertMjsFilesForDocs([])
+    expect(filePaths).toEqual([])
+    expect(() => cleanUp()).not.toThrow()
+  })
+
+  test('writes a rewritten, doc-parseable .js copy outside the project tree', () => {
+    const mjsFilePath = gulpConfig.get('srcPath') + '/greet.mjs'
+    const { filePaths, cleanUp } = convertMjsFilesForDocs([mjsFilePath])
+
+    expect(filePaths).toHaveLength(1)
+    expect(filePaths[0]).toMatch(/greet\.js$/)
+    expect(filePaths[0]).not.toContain(process.cwd())
+
+    const converted = fs.readFileSync(filePaths[0], 'utf8')
+    expect(converted).toContain('const sayHello = name => `Hello from ${name}`')
+    expect(converted).toContain('module.exports = { sayHello }')
+
+    cleanUp()
+    expect(fs.existsSync(filePaths[0])).toBe(false)
+  })
+
+  test('converts several files into the same temp directory', () => {
+    fs.writeFileSync(gulpConfig.get('srcPath') + '/greetAgain.mjs', rawContents.replace('sayHello', 'sayHelloAgain'))
+    const { filePaths, cleanUp } = convertMjsFilesForDocs([
+      gulpConfig.get('srcPath') + '/greet.mjs',
+      gulpConfig.get('srcPath') + '/greetAgain.mjs'
+    ])
+
+    expect(filePaths).toHaveLength(2)
+    filePaths.forEach(filePath => expect(fs.existsSync(filePath)).toBe(true))
+
+    cleanUp()
+    filePaths.forEach(filePath => expect(fs.existsSync(filePath)).toBe(false))
+  })
+})

package/functions/utilities/esmNamedExportsToCjs.mjs

@@ -0,0 +1,29 @@
+/**
+ * Rewrites named `export const`/`export function`/`export class` declarations to plain declarations plus a
+ * trailing `module.exports = { ... }` - the same shape jsdoc-to-markdown already documents cleanly (a plain
+ * declaration with its own `@memberOf` tag, exported all at once at the bottom), rather than the "exports.name"
+ * longname jsdoc-to-markdown's own ESM-compat layer produces for an inline `export const name = ...`.
+ *
+ * This is a narrow, text-level rewrite for documentation purposes only - it does not execute the module, so it
+ * only has to look enough like the real thing for jsdoc-to-markdown's parser. It handles the common named-export
+ * forms (`export const`, `export function`, `export class`) and leaves everything else (including `export
+ * default`, re-exports, and `export { a, b }` lists) untouched in place - a file using one of those keeps its
+ * own export line as-is, which jsdoc-to-markdown will document however it already does for ESM.
+ * @memberOf module:utilities
+ * @param {string} source - The raw ESM source text (never executed, just rewritten as text).
+ * @returns {string} The rewritten text, safe to write out with a `.js` extension for jsdoc-to-markdown to read.
+ */
+export const esmNamedExportsToCjs = (source) => {
+  const exportedNames = []
+  const rewritten = source.replace(
+    /^export (const|function|class) (\w+)/gm,
+    (match, keyword, name) => {
+      exportedNames.push(name)
+      return `${keyword} ${name}`
+    }
+  )
+  if (exportedNames.length === 0) {
+    return rewritten
+  }
+  return `${rewritten}\n\nmodule.exports = { ${exportedNames.join(', ')} }\n`
+}

package/functions/utilities/esmNamedExportsToCjs.test.mjs

@@ -0,0 +1,47 @@
+import { esmNamedExportsToCjs } from './esmNamedExportsToCjs.mjs'
+
+describe('esmNamedExportsToCjs', () => {
+  test('rewrites a single export const to a plain declaration plus a trailing module.exports', () => {
+    const source = 'export const get = (path) => path\n'
+    const result = esmNamedExportsToCjs(source)
+    expect(result).toContain('const get = (path) => path')
+    expect(result).toContain('module.exports = { get }')
+    expect(result).not.toContain('export const')
+  })
+
+  test('rewrites multiple export const declarations into one module.exports with all the names', () => {
+    const source = 'export const get = () => {}\nexport const set = () => {}\n'
+    const result = esmNamedExportsToCjs(source)
+    expect(result).toContain('const get = () => {}')
+    expect(result).toContain('const set = () => {}')
+    expect(result).toContain('module.exports = { get, set }')
+  })
+
+  test('rewrites export function and export class the same way', () => {
+    const source = 'export function doThing() {}\nexport class Thing {}\n'
+    const result = esmNamedExportsToCjs(source)
+    expect(result).toContain('function doThing() {}')
+    expect(result).toContain('class Thing {}')
+    expect(result).toContain('module.exports = { doThing, Thing }')
+  })
+
+  test('leaves non-export lines and JSDoc comments untouched', () => {
+    const source = '/**\n * A function.\n * @memberOf module:gulpConfig\n */\nexport const get = () => {}\n'
+    const result = esmNamedExportsToCjs(source)
+    expect(result).toContain('/**\n * A function.\n * @memberOf module:gulpConfig\n */\nconst get = () => {}')
+  })
+
+  test('does not add a module.exports block when there is nothing to export', () => {
+    const source = 'import { thing } from \'./thing.mjs\'\nconst local = 1\n'
+    const result = esmNamedExportsToCjs(source)
+    expect(result).toBe(source)
+    expect(result).not.toContain('module.exports')
+  })
+
+  test('leaves export default and other export forms untouched', () => {
+    const source = 'const value = 1\nexport default value\n'
+    const result = esmNamedExportsToCjs(source)
+    expect(result).toContain('export default value')
+    expect(result).not.toContain('module.exports')
+  })
+})

package/gulp.config.mjs

@@ -101,6 +101,9 @@ import { fileExists } from 'test-filesystem'
  * @typedef {Object<string, Setting>} module:gulpConfig~ReadmeConfig
  * @property {StringSetting} file - The name of the output documentation markdown file.
  * @property {StringSetting} from - Location of files to use for compiling documentation into the readme.
+ * @property {ArrayableSetting} fromEsm - Additional `.mjs` files to document alongside `from`, converted on the
+ * fly since the readme generator only recognizes `.js` files - see 'Configure including ESM files in the
+ * generated readme'. Empty by default: a project that never sets this gets exactly the readme it always did.
  * @property {ArrayableSetting} options - Options for formatting the output readme.
  * @property {StringSetting} template - The file which will be pre-fixed to your README.md output.
  * @property {StringSetting} to - The directory to output the readme file in.
@@ -200,6 +203,7 @@ const setDefaults = {
   readme: {
     file: 'README.md',
     from: 'src/**/!(*.test).js',
+    fromEsm: [],
     options: 'utf8',
     template: 'MAIN.md',
     to: './'

package/package.json

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