js-build-tools 6.6.0 → 6.7.0

package/dist/partials/tsFor.js

@@ -15,21 +15,21 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
 // 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.
- * @memberOf module:partials
- * @param {stream.Stream} stream
- * @returns {Promise<void>}
+/**
+ * Wrap a stream in a promise that resolves once it finishes writing.
+ * @memberOf module:partials
+ * @param {stream.Stream} stream
+ * @returns {Promise<void>}
  */
 const installHint = 'Install it in your project with: npm install --save-dev typescript';
 
-/**
- * Load the project's own copy of TypeScript (an optional peer dependency, only needed when the typescript task is
- * enabled) from the project being built, so projects which do not use TypeScript never need it installed.
- * @memberOf module:partials
- * @param {string} [projectPath=process.cwd()] The folder of the project (which has the package.json) being built.
- * @returns {Object} The TypeScript compiler API module.
- * @throws {Error} With install instructions when typescript is not installed.
+/**
+ * Load the project's own copy of TypeScript (an optional peer dependency, only needed when the typescript task is
+ * enabled) from the project being built, so projects which do not use TypeScript never need it installed.
+ * @memberOf module:partials
+ * @param {string} [projectPath=process.cwd()] The folder of the project (which has the package.json) being built.
+ * @returns {Object} The TypeScript compiler API module.
+ * @throws {Error} With install instructions when typescript is not installed.
  */
 const loadTypescript = (projectPath = process.cwd()) => (0, _loadPeer.requirePeer)('typescript', {
   task: 'typescript',
@@ -42,14 +42,14 @@ const streamToPromise = stream => new Promise((resolve, reject) => {
   stream.on('error', reject);
 });
 
-/**
- * Read a tsconfig.json file into real typescript.CompilerOptions values, using only TypeScript's stable, current,
- * public config-reading API (the same one `tsc --project` itself uses internally) - never
- * `ts.convertCompilerOptionsFromJson`, which is exactly the kind of internal/legacy surface that broke
- * gulp-typescript when a removed API call started throwing under TypeScript 7.
- * @memberOf module:partials
- * @param {string} configPath - Path to a tsconfig.json file.
- * @returns {ts.CompilerOptions} TypeScript's compiler options
+/**
+ * Read a tsconfig.json file into real typescript.CompilerOptions values, using only TypeScript's stable, current,
+ * public config-reading API (the same one `tsc --project` itself uses internally) - never
+ * `ts.convertCompilerOptionsFromJson`, which is exactly the kind of internal/legacy surface that broke
+ * gulp-typescript when a removed API call started throwing under TypeScript 7.
+ * @memberOf module:partials
+ * @param {string} configPath - Path to a tsconfig.json file.
+ * @returns {ts.CompilerOptions} TypeScript's compiler options
  */
 const readCompilerOptions = (ts, configPath) => {
   const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
@@ -57,18 +57,18 @@ const readCompilerOptions = (ts, configPath) => {
   return parsedConfig.options;
 };
 
-/**
- * Starting at the source directory, find all the ts files and convert them into the distribution directory.
- * @memberOf module:partials
- * @param {string|array} [srcPath='']
- * @param {string} [distPath='']
- * @param {function(): Promise<Function>} [loadTsCompile] - Resolves the `gulp-ts-compile` default export. Real
- * callers should never need to pass this - it exists so tests can inject a stand-in compiler, sidestepping the
- * genuine dynamic `import()` above that this project's current CommonJS-transform-based Jest setup cannot
- * execute without a broader (and riskier) migration to Jest's native ESM support. gulp-ts-compile's own test
- * suite already covers real TypeScript-compile correctness - this function's own tests only need to verify its
- * config resolution and stream wiring.
- * @returns {Function}
+/**
+ * Starting at the source directory, find all the ts files and convert them into the distribution directory.
+ * @memberOf module:partials
+ * @param {string|array} [srcPath='']
+ * @param {string} [distPath='']
+ * @param {function(): Promise<Function>} [loadTsCompile] - Resolves the `gulp-ts-compile` default export. Real
+ * callers should never need to pass this - it exists so tests can inject a stand-in compiler, sidestepping the
+ * genuine dynamic `import()` above that this project's current CommonJS-transform-based Jest setup cannot
+ * execute without a broader (and riskier) migration to Jest's native ESM support. gulp-ts-compile's own test
+ * suite already covers real TypeScript-compile correctness - this function's own tests only need to verify its
+ * config resolution and stream wiring.
+ * @returns {Function}
  */
 const tsFor = (srcPath = gulpConfig.get('typescript.from'), distPath = gulpConfig.get('typescript.to'), loadTsCompile = () => importGulpTsCompile().then(({
   default: tsCompile

package/dist/partials/typeDocsFor.js

@@ -1,265 +1,265 @@
-"use strict";
-
-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.describeFile = exports.describeExports = void 0;
-require("core-js/modules/es.array.includes.js");
-require("core-js/modules/es.json.stringify.js");
-require("core-js/modules/esnext.iterator.constructor.js");
-require("core-js/modules/esnext.iterator.filter.js");
-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");
-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 gulpConfig = _interopRequireWildcard(require("../../gulp.config.js"));
-var _loadPeer = require("./loadPeer.js");
-var _tsFor = require("./tsFor.js");
-var _removeDirectory = require("./removeDirectory.js");
-var cache;
-function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-const installHint = 'Install it in your project with: npm install --save-dev typedoc';
-
-/**
- * Find the TypeDoc of the project being built (an optional peer dependency, only needed when the docs task is
- * enabled) and load it, so projects which do not document TypeScript never need it installed.
- * @memberOf module:partials
- * @param {string} [projectPath=process.cwd()] The folder of the project (which has the package.json) being built.
- * @returns {Promise<Object>} The TypeDoc module.
- * @throws {Error} With install instructions when typedoc is not installed.
- */
-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, {
-  withFileTypes: true
-}).filter(entry => entry.isFile() && isSource(entry.name)).map(entry => _nodePath.default.join(dirPath, entry.name));
-
-// Every folder below dirPath (at any depth), named by its path from dirPath, with the source files directly in it
-const listFolders = (dirPath, prefix = '') => _nodeFs.default.readdirSync(dirPath, {
-  withFileTypes: true
-}).filter(entry => entry.isDirectory() && entry.name !== 'node_modules').flatMap(entry => {
-  const folderPath = _nodePath.default.join(dirPath, entry.name);
-  const name = `${prefix}${entry.name}`;
-  return [{
-    name,
-    path: folderPath,
-    files: listSources(folderPath)
-  }, ...listFolders(folderPath, `${name}/`)];
-});
-const toIdentifier = fileName => fileName.replace(/[^\w$]+(\w)?/g, (match, letter) => (letter || '').toUpperCase()).replace(/^(\d)/, '_$1');
-const toModulePath = filePath => filePath.replace(/\.[cm]?tsx?$/, '').split(_nodePath.default.sep).join('/');
-
-/**
- * Describe what a source file exports: whether it has a default export, and whether it has any named exports.
- * @memberOf module:partials
- * @param {Object} ts - The TypeScript compiler API.
- * @param {string} filePath
- * @returns {{hasDefault: boolean, hasNamed: boolean}}
- */
-const describeExports = (ts, filePath) => {
-  const source = ts.createSourceFile(filePath, _nodeFs.default.readFileSync(filePath, 'utf8'), ts.ScriptTarget.Latest);
-  let hasDefault = false;
-  let hasNamed = false;
-  source.statements.forEach(statement => {
-    if (ts.isExportAssignment(statement)) {
-      hasDefault = hasDefault || !statement.isExportEquals;
-      return;
-    }
-    if (ts.isExportDeclaration(statement)) {
-      const names = statement.exportClause && ts.isNamedExports(statement.exportClause) ? statement.exportClause.elements : null;
-      if (names && names.some(element => element.name.text === 'default')) {
-        hasDefault = true;
-      }
-      if (!names || names.some(element => element.name.text !== 'default')) {
-        hasNamed = true;
-      }
-      return;
-    }
-    const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) || [] : [];
-    if (modifiers.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
-      if (modifiers.some(modifier => modifier.kind === ts.SyntaxKind.DefaultKeyword)) {
-        hasDefault = true;
-      } else {
-        hasNamed = true;
-      }
-    }
-  });
-  return {
-    hasDefault,
-    hasNamed
-  };
-};
-
-/**
- * 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. Nested folders are modules of their own, named
- * by their path (utilities/parsers), and a folder's module holds only the files directly in it. The default export of each source file is
- * re-exported under the name of the file (the source files hold one function each), and anything else a file exports
- * is re-exported as it is (that is where the types.ts files go). Index files (the barrels), tests and declaration
- * files are left out, but the first doc comment of a folder's index file becomes the description of its module.
- * A file which sits beside the folders (not an index, main or browser file) is a module of its own, described by its header
- * comment. A source directory with no folders gets a single entry called index.
- * @memberOf module:partials
- * @param {Object} ts - The TypeScript compiler API.
- * @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.describeFile = describeFile;
-const writeDocEntries = (ts, srcDir, entryDir) => {
-  const absoluteSrc = _nodePath.default.resolve(srcDir);
-  _nodeFs.default.mkdirSync(entryDir, {
-    recursive: true
-  });
-  const folders = listFolders(absoluteSrc).filter(folder => folder.files.some(file => !/^index\./.test(_nodePath.default.basename(file))));
-  const rootFiles = listSources(absoluteSrc).filter(file => !/^(index|main|browser)\./.test(_nodePath.default.basename(file)));
-  // Folders make modules, and so do the files which sit beside them (except the barrels: index, main and browser, the
-  // browser bundle's entry). A source directory with no folders gets a single module called index which holds its files.
-  const groups = folders.length ? [...folders, ...rootFiles.map(file => ({
-    name: toIdentifier(_nodePath.default.basename(file).replace(/\.[cm]?tsx?$/, '')),
-    files: [file],
-    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(_nodePath.default.basename(file))).sort().flatMap(file => {
-      const modulePath = toModulePath(file);
-      const {
-        hasDefault,
-        hasNamed
-      } = describeExports(ts, file);
-      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
-    // A nested folder's module is named by its path (utilities/parsers), so it is not mistaken for its parent's
-    const moduleName = group.name.includes('/') ? ` ${group.name}` : '';
-    const moduleComment = description || moduleName ? `/**\n${description ? description.split('\n').map(line => ` * ${line}`.trimEnd()).join('\n') + '\n' : ''} * @module${moduleName}\n */\n\n` : '';
-    const entryPath = _nodePath.default.join(entryDir, `${group.name}.ts`);
-    _nodeFs.default.mkdirSync(_nodePath.default.dirname(entryPath), {
-      recursive: true
-    });
-    _nodeFs.default.writeFileSync(entryPath, moduleComment + lines.join('\n') + '\n');
-    return entryPath;
-  });
-};
-exports.writeDocEntries = writeDocEntries;
-const projectName = () => {
-  try {
-    return JSON.parse(_nodeFs.default.readFileSync(_nodePath.default.join(process.cwd(), 'package.json'), 'utf8')).name;
-  } catch (error) {
-    return _nodePath.default.basename(process.cwd());
-  }
-};
-
-/**
- * Generate the HTML documentation of a TypeScript project with TypeDoc, straight from the TypeScript source, so the
- * types (and the comments on them) are documented from where they are defined. The modules mirror the folders of the
- * source, see {@link writeDocEntries}. Configure this with 'docs.from', 'docs.to', 'docs.index', 'docs.title',
- * 'docs.tsconfig' and 'docs.logLevel'.
- * @memberOf module:partials
- * @param {string} [srcPath=gulpConfig.get('docs.from')] - The directory holding the TypeScript source.
- * @param {string} [outPath=gulpConfig.get('docs.to')] - The directory the documentation is generated into (cleared first).
- * @param {function(string): Promise<Object>} [loadDocs] - Resolves the TypeDoc module, tests can inject a stand-in.
- * @returns {Function} A gulp task, it accepts an optional callback and returns a promise.
- */
-const typeDocsFor = (srcPath = gulpConfig.get('docs.from'), outPath = gulpConfig.get('docs.to'), loadDocs = loadTypeDoc) => {
-  if (gulpConfig.get('docs.enabled') === false) {
-    return () => {};
-  }
-  return done => {
-    const generate = async () => {
-      const ts = (0, _tsFor.loadTypescript)();
-      const {
-        Application
-      } = await loadDocs();
-      const workDir = _nodeFs.default.mkdtempSync(_nodePath.default.join(_nodeOs.default.tmpdir(), 'typedocs-'));
-      try {
-        const entryPoints = writeDocEntries(ts, srcPath, _nodePath.default.join(workDir, 'entries'));
-        // The entry files live outside the project, so the tsconfig which is used for the documentation extends the
-        // one of the project and adds the entries to the files it includes.
-        const projectConfig = gulpConfig.get('docs.tsconfig') || gulpConfig.get('typescript.config');
-        const tsconfig = _nodePath.default.join(workDir, 'tsconfig.json');
-        _nodeFs.default.writeFileSync(tsconfig, JSON.stringify({
-          ...(projectConfig ? {
-            extends: _nodePath.default.resolve(projectConfig)
-          } : {}),
-          include: [_nodePath.default.join(workDir, 'entries', '**', '*.ts').split(_nodePath.default.sep).join('/'), _nodePath.default.resolve(srcPath).split(_nodePath.default.sep).join('/') + '/**/*.ts'],
-          exclude: [_nodePath.default.resolve(srcPath).split(_nodePath.default.sep).join('/') + '/**/*.test.*']
-        }));
-        const indexFile = gulpConfig.get('docs.index');
-        const gitRevision = gulpConfig.get('docs.gitRevision');
-        await (0, _removeDirectory.removeDirectory)(outPath);
-        const app = await Application.bootstrap({
-          entryPoints,
-          tsconfig,
-          name: gulpConfig.get('docs.title') || projectName(),
-          readme: indexFile && _nodeFs.default.existsSync(indexFile) ? indexFile : 'none',
-          logLevel: gulpConfig.get('docs.logLevel') || 'Warn',
-          skipErrorChecking: true,
-          // Left out, TypeDoc links each declaration to its source at the current commit, so every commit changes
-          // every page; a branch name keeps the pages the same until the documentation itself changes.
-          ...(gitRevision ? {
-            gitRevision
-          } : {})
-        });
-        const project = await app.convert();
-        if (!project) {
-          throw new Error('TypeDoc could not read the TypeScript source, see the errors above.');
-        }
-        await app.generateDocs(project, outPath);
-      } finally {
-        await (0, _removeDirectory.removeDirectory)(workDir);
-      }
-    };
-    return typeof done === 'function' ? generate().then(() => done(), done) : generate();
-  };
-};
+"use strict";
+
+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.describeFile = exports.describeExports = void 0;
+require("core-js/modules/es.array.includes.js");
+require("core-js/modules/es.json.stringify.js");
+require("core-js/modules/esnext.iterator.constructor.js");
+require("core-js/modules/esnext.iterator.filter.js");
+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");
+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 gulpConfig = _interopRequireWildcard(require("../../gulp.config.js"));
+var _loadPeer = require("./loadPeer.js");
+var _tsFor = require("./tsFor.js");
+var _removeDirectory = require("./removeDirectory.js");
+var cache;
+function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const installHint = 'Install it in your project with: npm install --save-dev typedoc';
+
+/**
+ * Find the TypeDoc of the project being built (an optional peer dependency, only needed when the docs task is
+ * enabled) and load it, so projects which do not document TypeScript never need it installed.
+ * @memberOf module:partials
+ * @param {string} [projectPath=process.cwd()] The folder of the project (which has the package.json) being built.
+ * @returns {Promise<Object>} The TypeDoc module.
+ * @throws {Error} With install instructions when typedoc is not installed.
+ */
+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, {
+  withFileTypes: true
+}).filter(entry => entry.isFile() && isSource(entry.name)).map(entry => _nodePath.default.join(dirPath, entry.name));
+
+// Every folder below dirPath (at any depth), named by its path from dirPath, with the source files directly in it
+const listFolders = (dirPath, prefix = '') => _nodeFs.default.readdirSync(dirPath, {
+  withFileTypes: true
+}).filter(entry => entry.isDirectory() && entry.name !== 'node_modules').flatMap(entry => {
+  const folderPath = _nodePath.default.join(dirPath, entry.name);
+  const name = `${prefix}${entry.name}`;
+  return [{
+    name,
+    path: folderPath,
+    files: listSources(folderPath)
+  }, ...listFolders(folderPath, `${name}/`)];
+});
+const toIdentifier = fileName => fileName.replace(/[^\w$]+(\w)?/g, (match, letter) => (letter || '').toUpperCase()).replace(/^(\d)/, '_$1');
+const toModulePath = filePath => filePath.replace(/\.[cm]?tsx?$/, '').split(_nodePath.default.sep).join('/');
+
+/**
+ * Describe what a source file exports: whether it has a default export, and whether it has any named exports.
+ * @memberOf module:partials
+ * @param {Object} ts - The TypeScript compiler API.
+ * @param {string} filePath
+ * @returns {{hasDefault: boolean, hasNamed: boolean}}
+ */
+const describeExports = (ts, filePath) => {
+  const source = ts.createSourceFile(filePath, _nodeFs.default.readFileSync(filePath, 'utf8'), ts.ScriptTarget.Latest);
+  let hasDefault = false;
+  let hasNamed = false;
+  source.statements.forEach(statement => {
+    if (ts.isExportAssignment(statement)) {
+      hasDefault = hasDefault || !statement.isExportEquals;
+      return;
+    }
+    if (ts.isExportDeclaration(statement)) {
+      const names = statement.exportClause && ts.isNamedExports(statement.exportClause) ? statement.exportClause.elements : null;
+      if (names && names.some(element => element.name.text === 'default')) {
+        hasDefault = true;
+      }
+      if (!names || names.some(element => element.name.text !== 'default')) {
+        hasNamed = true;
+      }
+      return;
+    }
+    const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) || [] : [];
+    if (modifiers.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
+      if (modifiers.some(modifier => modifier.kind === ts.SyntaxKind.DefaultKeyword)) {
+        hasDefault = true;
+      } else {
+        hasNamed = true;
+      }
+    }
+  });
+  return {
+    hasDefault,
+    hasNamed
+  };
+};
+
+/**
+ * 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. Nested folders are modules of their own, named
+ * by their path (utilities/parsers), and a folder's module holds only the files directly in it. The default export of each source file is
+ * re-exported under the name of the file (the source files hold one function each), and anything else a file exports
+ * is re-exported as it is (that is where the types.ts files go). Index files (the barrels), tests and declaration
+ * files are left out, but the first doc comment of a folder's index file becomes the description of its module.
+ * A file which sits beside the folders (not an index, main or browser file) is a module of its own, described by its header
+ * comment. A source directory with no folders gets a single entry called index.
+ * @memberOf module:partials
+ * @param {Object} ts - The TypeScript compiler API.
+ * @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.describeFile = describeFile;
+const writeDocEntries = (ts, srcDir, entryDir) => {
+  const absoluteSrc = _nodePath.default.resolve(srcDir);
+  _nodeFs.default.mkdirSync(entryDir, {
+    recursive: true
+  });
+  const folders = listFolders(absoluteSrc).filter(folder => folder.files.some(file => !/^index\./.test(_nodePath.default.basename(file))));
+  const rootFiles = listSources(absoluteSrc).filter(file => !/^(index|main|browser)\./.test(_nodePath.default.basename(file)));
+  // Folders make modules, and so do the files which sit beside them (except the barrels: index, main and browser, the
+  // browser bundle's entry). A source directory with no folders gets a single module called index which holds its files.
+  const groups = folders.length ? [...folders, ...rootFiles.map(file => ({
+    name: toIdentifier(_nodePath.default.basename(file).replace(/\.[cm]?tsx?$/, '')),
+    files: [file],
+    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(_nodePath.default.basename(file))).sort().flatMap(file => {
+      const modulePath = toModulePath(file);
+      const {
+        hasDefault,
+        hasNamed
+      } = describeExports(ts, file);
+      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
+    // A nested folder's module is named by its path (utilities/parsers), so it is not mistaken for its parent's
+    const moduleName = group.name.includes('/') ? ` ${group.name}` : '';
+    const moduleComment = description || moduleName ? `/**\n${description ? description.split('\n').map(line => ` * ${line}`.trimEnd()).join('\n') + '\n' : ''} * @module${moduleName}\n */\n\n` : '';
+    const entryPath = _nodePath.default.join(entryDir, `${group.name}.ts`);
+    _nodeFs.default.mkdirSync(_nodePath.default.dirname(entryPath), {
+      recursive: true
+    });
+    _nodeFs.default.writeFileSync(entryPath, moduleComment + lines.join('\n') + '\n');
+    return entryPath;
+  });
+};
+exports.writeDocEntries = writeDocEntries;
+const projectName = () => {
+  try {
+    return JSON.parse(_nodeFs.default.readFileSync(_nodePath.default.join(process.cwd(), 'package.json'), 'utf8')).name;
+  } catch (error) {
+    return _nodePath.default.basename(process.cwd());
+  }
+};
+
+/**
+ * Generate the HTML documentation of a TypeScript project with TypeDoc, straight from the TypeScript source, so the
+ * types (and the comments on them) are documented from where they are defined. The modules mirror the folders of the
+ * source, see {@link writeDocEntries}. Configure this with 'docs.from', 'docs.to', 'docs.index', 'docs.title',
+ * 'docs.tsconfig' and 'docs.logLevel'.
+ * @memberOf module:partials
+ * @param {string} [srcPath=gulpConfig.get('docs.from')] - The directory holding the TypeScript source.
+ * @param {string} [outPath=gulpConfig.get('docs.to')] - The directory the documentation is generated into (cleared first).
+ * @param {function(string): Promise<Object>} [loadDocs] - Resolves the TypeDoc module, tests can inject a stand-in.
+ * @returns {Function} A gulp task, it accepts an optional callback and returns a promise.
+ */
+const typeDocsFor = (srcPath = gulpConfig.get('docs.from'), outPath = gulpConfig.get('docs.to'), loadDocs = loadTypeDoc) => {
+  if (gulpConfig.get('docs.enabled') === false) {
+    return () => {};
+  }
+  return done => {
+    const generate = async () => {
+      const ts = (0, _tsFor.loadTypescript)();
+      const {
+        Application
+      } = await loadDocs();
+      const workDir = _nodeFs.default.mkdtempSync(_nodePath.default.join(_nodeOs.default.tmpdir(), 'typedocs-'));
+      try {
+        const entryPoints = writeDocEntries(ts, srcPath, _nodePath.default.join(workDir, 'entries'));
+        // The entry files live outside the project, so the tsconfig which is used for the documentation extends the
+        // one of the project and adds the entries to the files it includes.
+        const projectConfig = gulpConfig.get('docs.tsconfig') || gulpConfig.get('typescript.config');
+        const tsconfig = _nodePath.default.join(workDir, 'tsconfig.json');
+        _nodeFs.default.writeFileSync(tsconfig, JSON.stringify({
+          ...(projectConfig ? {
+            extends: _nodePath.default.resolve(projectConfig)
+          } : {}),
+          include: [_nodePath.default.join(workDir, 'entries', '**', '*.ts').split(_nodePath.default.sep).join('/'), _nodePath.default.resolve(srcPath).split(_nodePath.default.sep).join('/') + '/**/*.ts'],
+          exclude: [_nodePath.default.resolve(srcPath).split(_nodePath.default.sep).join('/') + '/**/*.test.*']
+        }));
+        const indexFile = gulpConfig.get('docs.index');
+        const gitRevision = gulpConfig.get('docs.gitRevision');
+        await (0, _removeDirectory.removeDirectory)(outPath);
+        const app = await Application.bootstrap({
+          entryPoints,
+          tsconfig,
+          name: gulpConfig.get('docs.title') || projectName(),
+          readme: indexFile && _nodeFs.default.existsSync(indexFile) ? indexFile : 'none',
+          logLevel: gulpConfig.get('docs.logLevel') || 'Warn',
+          skipErrorChecking: true,
+          // Left out, TypeDoc links each declaration to its source at the current commit, so every commit changes
+          // every page; a branch name keeps the pages the same until the documentation itself changes.
+          ...(gitRevision ? {
+            gitRevision
+          } : {})
+        });
+        const project = await app.convert();
+        if (!project) {
+          throw new Error('TypeDoc could not read the TypeScript source, see the errors above.');
+        }
+        await app.generateDocs(project, outPath);
+      } finally {
+        await (0, _removeDirectory.removeDirectory)(workDir);
+      }
+    };
+    return typeof done === 'function' ? generate().then(() => done(), done) : generate();
+  };
+};
 exports.typeDocsFor = typeDocsFor;