js-build-tools 5.3.1 → 5.4.0

package/README.md

@@ -444,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/bundle.js

@@ -1,36 +1,43 @@
-'use strict'
-
-require('core-js/modules/esnext.weak-map.delete-all.js')
-Object.defineProperty(exports, '__esModule', {
-  value: true
-})
-exports.bundle = void 0
-const _browserify = _interopRequireDefault(require('browserify'))
-const _gulp = require('gulp')
-const gulpConfig = _interopRequireWildcard(require('../gulp.config.js'))
-const _vinylSourceStream = _interopRequireDefault(require('vinyl-source-stream'))
-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) }
-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.bundle = void 0
+const _browserify = _interopRequireDefault(require('browserify'))
+const _gulp = require('gulp')
+const gulpConfig = _interopRequireWildcard(require('../gulp.config.js'))
+const _vinylSourceStream = _interopRequireDefault(require('vinyl-source-stream'))
+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) }
+function _interopRequireDefault (e) { return e && e.__esModule ? e : { default: e } }
 /**
  * Starting at the distribution entry point, bundle all the files into a single file and store them in the specified output directory.
  *
+ * browser.name does double duty: it names the output file (browser.name.js) and, via browserify's `standalone`
+ * option, is also the name the bundle's exports are exposed under - as a global when loaded with a bare <script>
+ * tag, or as the module when required via CommonJS/AMD. Without this, a bundle built from a real entry point (one
+ * that actually exports something) builds successfully but exposes nothing a consumer can reach.
+ *
  * Two escape hatches from browser.config.json keep an unwanted dependency (or a dependency's dependency) out of the
  * bundle: 'ignore' replaces it with an empty object (safe when your code never actually calls into it - for example
  * a library's default option value you always override with your own) and 'exclude' leaves it out entirely (your
  * code must not require it, or provide it another way, such as a separate script tag).
  * @memberOf module:js-build-tools
  * @returns {stream.Stream}
- */
-const bundle = () => {
-  const bundler = (0, _browserify.default)(gulpConfig.get('dist.main'))
-  const ignore = gulpConfig.get('browser.ignore')
-  const exclude = gulpConfig.get('browser.exclude')
-  if (ignore && ignore.length) {
-    bundler.ignore(ignore)
-  }
-  if (exclude && exclude.length) {
-    bundler.exclude(exclude)
-  }
-  return bundler.bundle().pipe((0, _vinylSourceStream.default)(`${gulpConfig.get('browser.name')}.js`)).pipe((0, _gulp.dest)(gulpConfig.get('browser.to')))
-}
-exports.bundle = bundle
+ */
+const bundle = () => {
+  const bundler = (0, _browserify.default)(gulpConfig.get('dist.main'), {
+    standalone: gulpConfig.get('browser.name')
+  })
+  const ignore = gulpConfig.get('browser.ignore')
+  const exclude = gulpConfig.get('browser.exclude')
+  if (ignore && ignore.length) {
+    bundler.ignore(ignore)
+  }
+  if (exclude && exclude.length) {
+    bundler.exclude(exclude)
+  }
+  return bundler.bundle().pipe((0, _vinylSourceStream.default)(`${gulpConfig.get('browser.name')}.js`)).pipe((0, _gulp.dest)(gulpConfig.get('browser.to')))
+}
+exports.bundle = bundle

package/dist/bundle.min.js

@@ -1 +1 @@
-"use strict";require("core-js/modules/esnext.weak-map.delete-all.js"),Object.defineProperty(exports,"__esModule",{value:!0}),exports.bundle=void 0;var _browserify=_interopRequireDefault(require("browserify")),_gulp=require("gulp"),gulpConfig=_interopRequireWildcard(require("../gulp.config.js")),_vinylSourceStream=_interopRequireDefault(require("vinyl-source-stream"));function _interopRequireWildcard(e,r){if("function"==typeof WeakMap)var t=new WeakMap,u=new WeakMap;return(_interopRequireWildcard=function(e,r){if(!r&&e&&e.__esModule)return e;var n,i,o={__proto__:null,default:e};if(null===e||"object"!=typeof e&&"function"!=typeof e)return o;if(n=r?u:t){if(n.has(e))return n.get(e);n.set(e,o)}for(const r in e)"default"!==r&&{}.hasOwnProperty.call(e,r)&&((i=(n=Object.defineProperty)&&Object.getOwnPropertyDescriptor(e,r))&&(i.get||i.set)?n(o,r,i):o[r]=e[r]);return o})(e,r)}function _interopRequireDefault(e){return e&&e.__esModule?e:{default:e}}const bundle=()=>{const e=(0,_browserify.default)(gulpConfig.get("dist.main")),r=gulpConfig.get("browser.ignore"),t=gulpConfig.get("browser.exclude");return r&&r.length&&e.ignore(r),t&&t.length&&e.exclude(t),e.bundle().pipe((0,_vinylSourceStream.default)(`${gulpConfig.get("browser.name")}.js`)).pipe((0,_gulp.dest)(gulpConfig.get("browser.to")))};exports.bundle=bundle;
+"use strict";require("core-js/modules/esnext.weak-map.delete-all.js"),Object.defineProperty(exports,"__esModule",{value:!0}),exports.bundle=void 0;var _browserify=_interopRequireDefault(require("browserify")),_gulp=require("gulp"),gulpConfig=_interopRequireWildcard(require("../gulp.config.js")),_vinylSourceStream=_interopRequireDefault(require("vinyl-source-stream"));function _interopRequireWildcard(e,r){if("function"==typeof WeakMap)var t=new WeakMap,n=new WeakMap;return(_interopRequireWildcard=function(e,r){if(!r&&e&&e.__esModule)return e;var u,o,i={__proto__:null,default:e};if(null===e||"object"!=typeof e&&"function"!=typeof e)return i;if(u=r?n:t){if(u.has(e))return u.get(e);u.set(e,i)}for(const r in e)"default"!==r&&{}.hasOwnProperty.call(e,r)&&((o=(u=Object.defineProperty)&&Object.getOwnPropertyDescriptor(e,r))&&(o.get||o.set)?u(i,r,o):i[r]=e[r]);return i})(e,r)}function _interopRequireDefault(e){return e&&e.__esModule?e:{default:e}}const bundle=()=>{const e=(0,_browserify.default)(gulpConfig.get("dist.main"),{standalone:gulpConfig.get("browser.name")}),r=gulpConfig.get("browser.ignore"),t=gulpConfig.get("browser.exclude");return r&&r.length&&e.ignore(r),t&&t.length&&e.exclude(t),e.bundle().pipe((0,_vinylSourceStream.default)(`${gulpConfig.get("browser.name")}.js`)).pipe((0,_gulp.dest)(gulpConfig.get("browser.to")))};exports.bundle=bundle;

package/dist/partials/typeDocsFor.js

@@ -4,7 +4,7 @@ require("core-js/modules/esnext.weak-map.delete-all.js");
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.writeDocEntries = exports.typeDocsFor = exports.loadTypeDoc = exports.describeFolder = 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");
@@ -102,7 +102,20 @@ const describeExports = (ts, filePath) => {
 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));
-  const comment = indexFile && _nodeFs.default.readFileSync(indexFile, 'utf8').match(/^\s*\/\*\*([\s\S]*?)\*\//);
+  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 '';
   }
@@ -116,14 +129,16 @@ const describeFolder = folderPath => {
  * 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, but the first doc comment of a folder's index file becomes the description of its module. 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.describeFolder = describeFolder;
+exports.describeFile = describeFile;
 const writeDocEntries = (ts, srcDir, entryDir) => {
   const absoluteSrc = _nodePath.default.resolve(srcDir);
   _nodeFs.default.mkdirSync(entryDir, {
@@ -136,10 +151,19 @@ const writeDocEntries = (ts, srcDir, entryDir) => {
     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',
     path: absoluteSrc,
-    files: listSources(absoluteSrc).filter(file => !/^(index|main)\./.test(_nodePath.default.basename(file)))
+    files: rootFiles
   }];
   return groups.map(group => {
     const lines = group.files.filter(file => !/^index\./.test(_nodePath.default.basename(file))).sort().flatMap(file => {
@@ -151,7 +175,7 @@ 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.path ? describeFolder(group.path) : '';
+    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`);

package/dist/typeDocs.js

@@ -1,14 +1,14 @@
-'use strict'
-
-Object.defineProperty(exports, '__esModule', {
-  value: true
-})
-exports.typeDocs = void 0
-const _typeDocsFor = require('./partials/typeDocsFor.js')
+'use strict'
+
+Object.defineProperty(exports, '__esModule', {
+  value: true
+})
+exports.typeDocs = void 0
+const _typeDocsFor = require('./partials/typeDocsFor.js')
 /**
  * Generate the HTML documentation of a TypeScript project from its source, with the modules mirroring the source
  * folders. Turn it on with docs.enabled, see {@link module:partials.typeDocsFor}.
  * @memberOf module:js-build-tools
  * @returns {Function}
- */
-const typeDocs = exports.typeDocs = (0, _typeDocsFor.typeDocsFor)()
+ */
+const typeDocs = exports.typeDocs = (0, _typeDocsFor.typeDocsFor)()

package/functions/bundle.mjs

@@ -6,6 +6,11 @@ import source from 'vinyl-source-stream'
 /**
  * Starting at the distribution entry point, bundle all the files into a single file and store them in the specified output directory.
  *
+ * browser.name does double duty: it names the output file (browser.name.js) and, via browserify's `standalone`
+ * option, is also the name the bundle's exports are exposed under - as a global when loaded with a bare <script>
+ * tag, or as the module when required via CommonJS/AMD. Without this, a bundle built from a real entry point (one
+ * that actually exports something) builds successfully but exposes nothing a consumer can reach.
+ *
  * Two escape hatches from browser.config.json keep an unwanted dependency (or a dependency's dependency) out of the
  * bundle: 'ignore' replaces it with an empty object (safe when your code never actually calls into it - for example
  * a library's default option value you always override with your own) and 'exclude' leaves it out entirely (your
@@ -14,7 +19,7 @@ import source from 'vinyl-source-stream'
  * @returns {stream.Stream}
  */
 export const bundle = () => {
-  const bundler = browserify(gulpConfig.get('dist.main'))
+  const bundler = browserify(gulpConfig.get('dist.main'), { standalone: gulpConfig.get('browser.name') })
   const ignore = gulpConfig.get('browser.ignore')
   const exclude = gulpConfig.get('browser.exclude')
   if (ignore && ignore.length) {

package/functions/bundle.test.mjs

@@ -1,4 +1,5 @@
 import fs from 'fs'
+import path from 'path'
 import * as setUp from './test-helpers/setUp.mjs'
 import { bundle } from './bundle.mjs'
 import { countMatches } from 'test-filesystem'
@@ -66,6 +67,25 @@ describe('bundle', () => {
         done()
       })
   })
+
+  test('exposes browser.name as the standalone export, reachable by a real consumer', done => {
+    const destPath = gulpConfig.get('browser.to')
+    const bundledFile = `${destPath}/${gulpConfig.get('browser.name')}.js`
+    expect.assertions(2)
+    bundle()
+      .on('finish', () => {
+        // A UMD bundle (browserify's `standalone` option) resolves to its CommonJS branch when
+        // required like this, and to a `window.<browser.name>` global when loaded via a bare
+        // <script> tag in a real browser - both paths hit the same exported value.
+        const resolved = path.resolve(bundledFile)
+        delete require.cache[resolved]
+        const loaded = require(resolved)
+        expect(typeof loaded.file1).toBe('function')
+        expect(typeof loaded.file2).toBe('function')
+        done()
+      })
+      .on('error', error => done(error))
+  })
 })
 
 describe('bundle ignore / exclude', () => {

package/functions/partials/typeDocsFor.mjs

@@ -79,7 +79,19 @@ export const describeExports = (ts, filePath) => {
  */
 export const describeFolder = folderPath => {
   const indexFile = ['index.ts', 'index.tsx', 'index.mts', 'index.cts'].map(name => path.join(folderPath, name)).find(file => fs.existsSync(file))
-  const comment = indexFile && fs.readFileSync(indexFile, 'utf8').match(/^\s*\/\*\*([\s\S]*?)\*\//)
+  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}
+ */
+export const describeFile = filePath => {
+  const comment = fs.readFileSync(filePath, 'utf8').match(/^\s*\/\*\*([\s\S]*?)\*\/\s*(import\b|export\s+(\*|\{[^}]*\}\s+from)|$)/)
   if (!comment) {
     return ''
   }
@@ -93,7 +105,9 @@ export const describeFolder = folderPath => {
  * 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, but the first doc comment of a folder's index file becomes the description of its module. 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.
@@ -107,9 +121,19 @@ export const writeDocEntries = (ts, srcDir, entryDir) => {
     .filter(entry => entry.isDirectory() && entry.name !== 'node_modules')
     .map(entry => ({ name: entry.name, path: path.join(absoluteSrc, entry.name), files: listSources(path.join(absoluteSrc, entry.name)) }))
     .filter(folder => folder.files.length)
+  const rootFiles = fs.readdirSync(absoluteSrc, { withFileTypes: true })
+    .filter(entry => entry.isFile() && isSource(entry.name) && !/^(index|main)\./.test(entry.name))
+    .map(entry => path.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
-    : [{ name: 'index', path: absoluteSrc, files: listSources(absoluteSrc).filter(file => !/^(index|main)\./.test(path.basename(file))) }]
+    ? [
+        ...folders,
+        ...rootFiles
+          .map(file => ({ name: toIdentifier(path.basename(file).replace(/\.[cm]?tsx?$/, '')), files: [file], description: describeFile(file) }))
+          .filter(group => !folders.some(folder => folder.name === group.name))
+      ]
+    : [{ name: 'index', path: absoluteSrc, files: rootFiles }]
   return groups.map(group => {
     const lines = group.files
       .filter(file => !/^index\./.test(path.basename(file)))
@@ -123,7 +147,7 @@ export const writeDocEntries = (ts, srcDir, entryDir) => {
           ...(hasNamed ? [`export * from '${modulePath}'`] : [])
         ]
       })
-    const description = group.path ? describeFolder(group.path) : ''
+    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 = path.join(entryDir, `${group.name}.ts`)

package/functions/partials/typeDocsFor.test.mjs

@@ -2,7 +2,7 @@ import fs from 'fs'
 import path from 'node:path'
 import ts from 'typescript'
 import * as setUp from '../test-helpers/setUp.mjs'
-import { describeExports, describeFolder, loadTypeDoc, typeDocsFor, writeDocEntries } from './typeDocsFor.mjs'
+import { describeExports, describeFile, describeFolder, loadTypeDoc, typeDocsFor, writeDocEntries } from './typeDocsFor.mjs'
 
 setUp.setDefaults('test-type-docs-for')
 const gulpConfig = setUp.gulpConfig
@@ -66,6 +66,18 @@ describe('describeFolder', () => {
   })
 })
 
+describe('describeFile', () => {
+  test('is the header comment of a file, without its tags', () => {
+    write(`${gulpConfig.get('srcPath')}/header.ts`, "/**\n * Simulate what a user does.\n * @module simulate\n */\nimport a from './a'\nexport default a\n")
+    expect(describeFile(`${gulpConfig.get('srcPath')}/header.ts`)).toBe('Simulate what a user does.')
+  })
+
+  test('is empty when the first comment documents a declaration', () => {
+    write(`${gulpConfig.get('srcPath')}/declaration.ts`, '/**\n * Add two numbers.\n */\nconst add = (a: number, b: number) => a + b\nexport default add\n')
+    expect(describeFile(`${gulpConfig.get('srcPath')}/declaration.ts`)).toBe('')
+  })
+})
+
 describe('writeDocEntries', () => {
   test('writes one entry file for each folder which has source', () => {
     const entryDir = `${gulpConfig.get('srcPath')}/../entries`
@@ -104,6 +116,19 @@ describe('writeDocEntries', () => {
     expect(fs.readFileSync(`${entryDir}/line.ts`, 'utf8').startsWith('export')).toBe(true)
   })
 
+  test('makes a module of a file which sits beside the folders, but not of the barrel files', () => {
+    const srcPath = gulpConfig.get('srcPath')
+    write(`${srcPath}/simulate.ts`, "/**\n * Simulate what a user does.\n */\nimport add from './point/add'\nexport const click = () => add(1, 2)\nexport default { click }\n")
+    write(`${srcPath}/simulate.test.ts`, "test('x', () => {})\n")
+    const entryDir = `${srcPath}/../entries`
+    const entries = writeDocEntries(ts, srcPath, entryDir)
+    expect(entries.map(entry => path.basename(entry)).sort()).toEqual(['line.ts', 'point.ts', 'simulate.ts'])
+    const absoluteSrc = path.resolve(srcPath).split(path.sep).join('/')
+    expect(fs.readFileSync(`${entryDir}/simulate.ts`, 'utf8')).toBe(
+      `/**\n * Simulate what a user does.\n * @module\n */\n\nexport { default as simulate } from '${absoluteSrc}/simulate'\nexport * from '${absoluteSrc}/simulate'\n`
+    )
+  })
+
   test('makes one entry called index when the source has no folders', () => {
     const flat = `${gulpConfig.get('srcPath')}/../flat`
     write(`${flat}/one.ts`, 'export default 1\n')

package/package.json

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