js-build-tools 5.3.0 → 5.3.1

package/dist/partials/tsFor.js

@@ -1,34 +1,27 @@
-"use strict";
-
-require("core-js/modules/esnext.weak-map.delete-all.js");
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.tsFor = exports.loadTypescript = void 0;
-var _gulp = require("gulp");
-var _nodePath = _interopRequireDefault(require("node:path"));
-var gulpConfig = _interopRequireWildcard(require("../../gulp.config.js"));
-var _nodeModule = require("node:module");
-function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-// gulp-ts-compile ships ESM-only (no CJS build - see its own package.json) since it's meant to be consumed by
-// gulpfiles running under a real ESM loader, same as this project's own gulpfile.mjs does. This project also
-// compiles itself to a CommonJS build (dist/*.js, this file's own compiled counterpart) for consumers using
-// require() though, and even a dynamic `import()` gets downleveled by babel's CommonJS transform into a
-// require() call - which can't load a real ES module. Hiding the import() call inside a Function constructor is
-// the standard escape hatch: babel can't see (and so can't rewrite) an import expression that only exists as a
-// runtime-evaluated string, so it survives as a genuine dynamic import, capable of loading gulp-ts-compile from
-// either build.
-const importGulpTsCompile = new Function('return import(\'gulp-ts-compile\')');
-
+"use strict";
+
+require("core-js/modules/esnext.weak-map.delete-all.js");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.tsFor = exports.loadTypescript = void 0;
+var _gulp = require("gulp");
+var _nodePath = _interopRequireDefault(require("node:path"));
+var gulpConfig = _interopRequireWildcard(require("../../gulp.config.js"));
+var _loadPeer = require("./loadPeer.js");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// gulp-ts-compile ships ESM-only (no CJS build - see its own package.json), 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 {import('node:stream').Stream} stream
  * @returns {Promise<void>}
- */
-const installHint = 'Install it in your project with: npm install --save-dev typescript';
-
+ */
+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.
@@ -36,23 +29,18 @@ const installHint = 'Install it in your project with: npm install --save-dev typ
  * @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()) => {
-  try {
-    return (0, _nodeModule.createRequire)(_nodePath.default.join(projectPath, 'package.json'))('typescript');
-  } catch (error) {
-    if (error.code === 'MODULE_NOT_FOUND' && /Cannot find module 'typescript'/.test(error.message)) {
-      throw new Error(`The typescript task needs the optional peer dependency typescript, which is not installed. ${installHint}`);
-    }
-    throw error;
-  }
-};
-exports.loadTypescript = loadTypescript;
-const streamToPromise = stream => new Promise((resolve, reject) => {
-  stream.on('finish', resolve);
-  stream.on('error', reject);
-});
-
+ */
+const loadTypescript = (projectPath = process.cwd()) => (0, _loadPeer.requirePeer)('typescript', {
+  task: 'typescript',
+  installHint,
+  projectPath
+});
+exports.loadTypescript = loadTypescript;
+const streamToPromise = stream => new Promise((resolve, reject) => {
+  stream.on('finish', resolve);
+  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
@@ -61,13 +49,13 @@ const streamToPromise = stream => new Promise((resolve, reject) => {
  * @memberOf module:partials
  * @param {string} configPath - Path to a tsconfig.json file.
  * @returns {import('typescript').CompilerOptions}
- */
-const readCompilerOptions = (ts, configPath) => {
-  const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
-  const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, _nodePath.default.dirname(configPath));
-  return parsedConfig.options;
-};
-
+ */
+const readCompilerOptions = (ts, configPath) => {
+  const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+  const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, _nodePath.default.dirname(configPath));
+  return parsedConfig.options;
+};
+
 /**
  * Starting at the source directory, find all the ts files and convert them into the distribution directory.
  * @memberOf module:partials
@@ -80,36 +68,36 @@ const readCompilerOptions = (ts, configPath) => {
  * 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
-}) => tsCompile)) => {
-  if (gulpConfig.get('typescript.enabled') === false) {
-    return () => {};
-  }
-  const ts = loadTypescript();
-  const configPath = gulpConfig.get('typescript.config');
-  // When no tsconfig.json is configured, target/module are pinned explicitly rather than left for TypeScript's
-  // own compiler defaults - those defaults have already shifted once across a TypeScript version bump in this
-  // project's own history (silently changing whether output keeps `const`/`let` or downlevels to `var`), and
-  // pinning them keeps this task's output stable across future TypeScript upgrades too. ES5/CommonJS matches
-  // what the downstream babel/browserify bundling pipeline has always assumed it receives.
-  const compilerOptions = configPath ? readCompilerOptions(ts, configPath) : {
-    declaration: true,
-    target: ts.ScriptTarget.ES5,
-    module: ts.ModuleKind.CommonJS,
-    esModuleInterop: false
-  };
-  // Accepts gulp's own callback-style task convention (an optional `done`, called once finished) rather than
-  // just returning a Promise, since callers may invoke the returned function directly with a callback instead
-  // of relying on gulp's own runner to observe a returned Promise.
-  return done => {
-    const compile = async () => {
-      const tsCompile = await loadTsCompile();
-      const tsResult = (0, _gulp.src)(srcPath).pipe(tsCompile(compilerOptions));
-      await Promise.all([streamToPromise(tsResult.dts.pipe((0, _gulp.dest)(distPath))), streamToPromise(tsResult.js.pipe((0, _gulp.dest)(distPath)))]);
-    };
-    return typeof done === 'function' ? compile().then(() => done(), done) : compile();
-  };
-};
+ */
+const tsFor = (srcPath = gulpConfig.get('typescript.from'), distPath = gulpConfig.get('typescript.to'), loadTsCompile = () => importGulpTsCompile().then(({
+  default: tsCompile
+}) => tsCompile)) => {
+  if (gulpConfig.get('typescript.enabled') === false) {
+    return () => {};
+  }
+  const ts = loadTypescript();
+  const configPath = gulpConfig.get('typescript.config');
+  // When no tsconfig.json is configured, target/module are pinned explicitly rather than left for TypeScript's
+  // own compiler defaults - those defaults have already shifted once across a TypeScript version bump in this
+  // project's own history (silently changing whether output keeps `const`/`let` or downlevels to `var`), and
+  // pinning them keeps this task's output stable across future TypeScript upgrades too. ES5/CommonJS matches
+  // what the downstream babel/browserify bundling pipeline has always assumed it receives.
+  const compilerOptions = configPath ? readCompilerOptions(ts, configPath) : {
+    declaration: true,
+    target: ts.ScriptTarget.ES5,
+    module: ts.ModuleKind.CommonJS,
+    esModuleInterop: false
+  };
+  // Accepts gulp's own callback-style task convention (an optional `done`, called once finished) rather than
+  // just returning a Promise, since callers may invoke the returned function directly with a callback instead
+  // of relying on gulp's own runner to observe a returned Promise.
+  return done => {
+    const compile = async () => {
+      const tsCompile = await loadTsCompile();
+      const tsResult = (0, _gulp.src)(srcPath).pipe(tsCompile(compilerOptions));
+      await Promise.all([streamToPromise(tsResult.dts.pipe((0, _gulp.dest)(distPath))), streamToPromise(tsResult.js.pipe((0, _gulp.dest)(distPath)))]);
+    };
+    return typeof done === 'function' ? compile().then(() => done(), done) : compile();
+  };
+};
 exports.tsFor = tsFor;

package/dist/partials/typeDocsFor.js

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

package/dist/partials.js

@@ -51,6 +51,18 @@ Object.defineProperty(exports, 'imagesFor', {
     return _imagesFor.imagesFor
   }
 })
+Object.defineProperty(exports, 'importModule', {
+  enumerable: true,
+  get: function () {
+    return _loadPeer.importModule
+  }
+})
+Object.defineProperty(exports, 'importPeer', {
+  enumerable: true,
+  get: function () {
+    return _loadPeer.importPeer
+  }
+})
 Object.defineProperty(exports, 'minifyFor', {
   enumerable: true,
   get: function () {
@@ -69,6 +81,12 @@ Object.defineProperty(exports, 'removeDirectory', {
     return _removeDirectory.removeDirectory
   }
 })
+Object.defineProperty(exports, 'requirePeer', {
+  enumerable: true,
+  get: function () {
+    return _loadPeer.requirePeer
+  }
+})
 Object.defineProperty(exports, 'runOnChange', {
   enumerable: true,
   get: function () {
@@ -107,6 +125,7 @@ var _distFor = require('./partials/distFor.js')
 var _distForSrc = require('./partials/distForSrc.js')
 var _distSeries = require('./partials/distSeries.js')
 var _imagesFor = require('./partials/imagesFor.js')
+var _loadPeer = require('./partials/loadPeer.js')
 var _minifyFor = require('./partials/minifyFor.js')
 var _readmeTemplate = require('./partials/readmeTemplate.js')
 var _removeDirectory = require('./partials/removeDirectory.js')

package/dist/partials.min.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),Object.defineProperty(exports,"addToReadme",{enumerable:!0,get:function(){return _addToReadme.addToReadme}}),Object.defineProperty(exports,"beginWatcher",{enumerable:!0,get:function(){return _beginWatcher.beginWatcher}}),Object.defineProperty(exports,"clean",{enumerable:!0,get:function(){return _clean.clean}}),Object.defineProperty(exports,"copyFor",{enumerable:!0,get:function(){return _copyFor.copyFor}}),Object.defineProperty(exports,"distFor",{enumerable:!0,get:function(){return _distFor.distFor}}),Object.defineProperty(exports,"distForSrc",{enumerable:!0,get:function(){return _distForSrc.distForSrc}}),Object.defineProperty(exports,"distSeries",{enumerable:!0,get:function(){return _distSeries.distSeries}}),Object.defineProperty(exports,"imagesFor",{enumerable:!0,get:function(){return _imagesFor.imagesFor}}),Object.defineProperty(exports,"minifyFor",{enumerable:!0,get:function(){return _minifyFor.minifyFor}}),Object.defineProperty(exports,"readmeTemplate",{enumerable:!0,get:function(){return _readmeTemplate.readmeTemplate}}),Object.defineProperty(exports,"removeDirectory",{enumerable:!0,get:function(){return _removeDirectory.removeDirectory}}),Object.defineProperty(exports,"runOnChange",{enumerable:!0,get:function(){return _runOnChange.runOnChange}}),Object.defineProperty(exports,"sassFor",{enumerable:!0,get:function(){return _sassFor.sassFor}}),Object.defineProperty(exports,"standardLint",{enumerable:!0,get:function(){return _standardLint.standardLint}}),Object.defineProperty(exports,"tsFor",{enumerable:!0,get:function(){return _tsFor.tsFor}}),Object.defineProperty(exports,"typeDocsFor",{enumerable:!0,get:function(){return _typeDocsFor.typeDocsFor}});var _addToReadme=require("./partials/addToReadme.js"),_beginWatcher=require("./partials/beginWatcher.js"),_clean=require("./partials/clean.js"),_copyFor=require("./partials/copyFor.js"),_distFor=require("./partials/distFor.js"),_distForSrc=require("./partials/distForSrc.js"),_distSeries=require("./partials/distSeries.js"),_imagesFor=require("./partials/imagesFor.js"),_minifyFor=require("./partials/minifyFor.js"),_readmeTemplate=require("./partials/readmeTemplate.js"),_removeDirectory=require("./partials/removeDirectory.js"),_runOnChange=require("./partials/runOnChange.js"),_sassFor=require("./partials/sassFor.js"),_standardLint=require("./partials/standardLint.js"),_tsFor=require("./partials/tsFor.js"),_typeDocsFor=require("./partials/typeDocsFor.js");
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),Object.defineProperty(exports,"addToReadme",{enumerable:!0,get:function(){return _addToReadme.addToReadme}}),Object.defineProperty(exports,"beginWatcher",{enumerable:!0,get:function(){return _beginWatcher.beginWatcher}}),Object.defineProperty(exports,"clean",{enumerable:!0,get:function(){return _clean.clean}}),Object.defineProperty(exports,"copyFor",{enumerable:!0,get:function(){return _copyFor.copyFor}}),Object.defineProperty(exports,"distFor",{enumerable:!0,get:function(){return _distFor.distFor}}),Object.defineProperty(exports,"distForSrc",{enumerable:!0,get:function(){return _distForSrc.distForSrc}}),Object.defineProperty(exports,"distSeries",{enumerable:!0,get:function(){return _distSeries.distSeries}}),Object.defineProperty(exports,"imagesFor",{enumerable:!0,get:function(){return _imagesFor.imagesFor}}),Object.defineProperty(exports,"importModule",{enumerable:!0,get:function(){return _loadPeer.importModule}}),Object.defineProperty(exports,"importPeer",{enumerable:!0,get:function(){return _loadPeer.importPeer}}),Object.defineProperty(exports,"minifyFor",{enumerable:!0,get:function(){return _minifyFor.minifyFor}}),Object.defineProperty(exports,"readmeTemplate",{enumerable:!0,get:function(){return _readmeTemplate.readmeTemplate}}),Object.defineProperty(exports,"removeDirectory",{enumerable:!0,get:function(){return _removeDirectory.removeDirectory}}),Object.defineProperty(exports,"requirePeer",{enumerable:!0,get:function(){return _loadPeer.requirePeer}}),Object.defineProperty(exports,"runOnChange",{enumerable:!0,get:function(){return _runOnChange.runOnChange}}),Object.defineProperty(exports,"sassFor",{enumerable:!0,get:function(){return _sassFor.sassFor}}),Object.defineProperty(exports,"standardLint",{enumerable:!0,get:function(){return _standardLint.standardLint}}),Object.defineProperty(exports,"tsFor",{enumerable:!0,get:function(){return _tsFor.tsFor}}),Object.defineProperty(exports,"typeDocsFor",{enumerable:!0,get:function(){return _typeDocsFor.typeDocsFor}});var _addToReadme=require("./partials/addToReadme.js"),_beginWatcher=require("./partials/beginWatcher.js"),_clean=require("./partials/clean.js"),_copyFor=require("./partials/copyFor.js"),_distFor=require("./partials/distFor.js"),_distForSrc=require("./partials/distForSrc.js"),_distSeries=require("./partials/distSeries.js"),_imagesFor=require("./partials/imagesFor.js"),_loadPeer=require("./partials/loadPeer.js"),_minifyFor=require("./partials/minifyFor.js"),_readmeTemplate=require("./partials/readmeTemplate.js"),_removeDirectory=require("./partials/removeDirectory.js"),_runOnChange=require("./partials/runOnChange.js"),_sassFor=require("./partials/sassFor.js"),_standardLint=require("./partials/standardLint.js"),_tsFor=require("./partials/tsFor.js"),_typeDocsFor=require("./partials/typeDocsFor.js");

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/partials/imagesFor.mjs

@@ -1,5 +1,5 @@
 import cache from 'gulp-cache'
-import { createRequire } from 'node:module'
+import { requirePeer } from './loadPeer.mjs'
 import { dest, src } from 'gulp'
 import path from 'node:path'
 import * as gulpConfig from '../../gulp.config.mjs'
@@ -17,18 +17,12 @@ const installHint = 'Add it to your project with: npm install --save-dev github:
  * @throws {Error} With install instructions when gulp-imagemin is missing or is the ESM-only upstream release.
  */
 export const loadImagemin = (projectPath = process.cwd()) => {
-  let loaded
-  try {
-    loaded = createRequire(path.join(projectPath, 'package.json'))('gulp-imagemin')
-  } catch (error) {
-    if (error.code === 'MODULE_NOT_FOUND' && /Cannot find module 'gulp-imagemin'/.test(error.message)) {
-      throw new Error(`The images task needs the optional peer dependency gulp-imagemin, which is not installed. ${installHint}`)
-    }
-    if (error.code === 'ERR_REQUIRE_ESM') {
-      throw new Error(`gulp-imagemin could not be loaded because it is ESM-only. ${installHint}`)
-    }
-    throw error
-  }
+  const loaded = requirePeer('gulp-imagemin', {
+    task: 'images',
+    installHint,
+    esmOnlyMessage: `gulp-imagemin could not be loaded because it is ESM-only. ${installHint}`,
+    projectPath
+  })
   return loaded && (loaded.__esModule || loaded.default) ? loaded.default : loaded
 }
 

package/functions/partials/loadPeer.mjs

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

package/functions/partials/loadPeer.test.mjs

@@ -0,0 +1,58 @@
+import fs from 'fs'
+import path from 'node:path'
+import * as setUp from '../test-helpers/setUp.mjs'
+import { importModule, importPeer, requirePeer } from './loadPeer.mjs'
+
+setUp.setDefaults('test-load-peer')
+
+const options = { task: 'example', installHint: 'Install it with: npm install --save-dev fake-peer' }
+
+// A project with its own node_modules, so the packages are found from the project rather than from this package
+const projectWith = (name, files) => {
+  const project = path.resolve('test-load-peer/project')
+  fs.mkdirSync(`${project}/node_modules/${name}`, { recursive: true })
+  fs.writeFileSync(`${project}/package.json`, '{}')
+  Object.entries(files).forEach(([file, contents]) => fs.writeFileSync(`${project}/node_modules/${name}/${file}`, contents))
+  return project
+}
+
+beforeEach(setUp.beforeEach)
+afterEach(setUp.afterEach)
+
+describe('requirePeer', () => {
+  test('loads the package from the project being built', () => {
+    const project = projectWith('fake-peer', { 'package.json': '{"name":"fake-peer","main":"index.js"}', 'index.js': 'module.exports = { found: true }' })
+    expect(requirePeer('fake-peer', { ...options, projectPath: project })).toEqual({ found: true })
+  })
+
+  test('explains how to install the package when the project does not have it', () => {
+    expect(() => requirePeer('fake-peer', { ...options, projectPath: '/' })).toThrow(
+      'The example task needs the optional peer dependency fake-peer, which is not installed. Install it with: npm install --save-dev fake-peer'
+    )
+  })
+
+  test('does not hide other errors, and explains a package which is ESM-only when it has a message for that', () => {
+    const project = projectWith('broken-peer', { 'package.json': '{"name":"broken-peer","main":"index.js"}', 'index.js': 'throw new Error("boom")' })
+    expect(() => requirePeer('broken-peer', { ...options, projectPath: project })).toThrow('boom')
+    // A missing dependency of the peer is not the peer being missing
+    const inner = projectWith('inner-peer', { 'package.json': '{"name":"inner-peer","main":"index.js"}', 'index.js': 'require("something-else-missing")' })
+    expect(() => requirePeer('inner-peer', { ...options, projectPath: inner })).toThrow(/something-else-missing/)
+    expect(() => requirePeer('inner-peer', { ...options, projectPath: inner })).not.toThrow(/optional peer dependency/)
+  })
+})
+
+describe('importPeer', () => {
+  test('explains how to install the package when the project does not have it', async () => {
+    await expect(importPeer('fake-peer', { ...options, projectPath: '/' })).rejects.toThrow(
+      /needs the optional peer dependency fake-peer, which is not installed. Install it with/
+    )
+  })
+})
+
+describe('importModule', () => {
+  // The real import() cannot run under this project's CommonJS-transform-based Jest setup (see tsFor.mjs), so the
+  // loaders are checked by running the tasks for real, see the pull request.
+  test('is a function', () => {
+    expect(importModule).toBeInstanceOf(Function)
+  })
+})

package/functions/partials/standardLint.mjs

@@ -1,11 +1,9 @@
 import path from 'node:path'
 import through from 'through2'
+import { importModule } from './loadPeer.mjs'
 
-// `standard` (17+) ships ESM-only, but this package also publishes a CommonJS build (dist/*.js) whose babel
-// transform would turn even a dynamic import() into a require() that cannot load an ES module. Hiding the import()
-// inside a Function constructor keeps it a genuine dynamic import that works from either build (same escape hatch
-// as tsFor.mjs uses for gulp-ts-compile).
-const importStandard = new Function('return import(\'standard\')')
+// `standard` (17+) ships ESM-only, see importModule for how it is imported.
+const importStandard = () => importModule('standard')
 
 /**
  * Print a file's lint messages, if it has any.

package/functions/partials/tsFor.mjs

@@ -1,17 +1,10 @@
 import { dest, src } from 'gulp'
 import path from 'node:path'
 import * as gulpConfig from '../../gulp.config.mjs'
-import { createRequire } from 'node:module'
+import { importModule, requirePeer } from './loadPeer.mjs'
 
-// gulp-ts-compile ships ESM-only (no CJS build - see its own package.json) since it's meant to be consumed by
-// gulpfiles running under a real ESM loader, same as this project's own gulpfile.mjs does. This project also
-// compiles itself to a CommonJS build (dist/*.js, this file's own compiled counterpart) for consumers using
-// require() though, and even a dynamic `import()` gets downleveled by babel's CommonJS transform into a
-// require() call - which can't load a real ES module. Hiding the import() call inside a Function constructor is
-// the standard escape hatch: babel can't see (and so can't rewrite) an import expression that only exists as a
-// runtime-evaluated string, so it survives as a genuine dynamic import, capable of loading gulp-ts-compile from
-// either build.
-const importGulpTsCompile = new Function('return import(\'gulp-ts-compile\')')
+// gulp-ts-compile ships ESM-only (no CJS build - see its own package.json), see importModule for how it is imported.
+const importGulpTsCompile = () => importModule('gulp-ts-compile')
 
 /**
  * Wrap a stream in a promise that resolves once it finishes writing.
@@ -29,16 +22,7 @@ const installHint = 'Install it in your project with: npm install --save-dev typ
  * @returns {Object} The TypeScript compiler API module.
  * @throws {Error} With install instructions when typescript is not installed.
  */
-export const loadTypescript = (projectPath = process.cwd()) => {
-  try {
-    return createRequire(path.join(projectPath, 'package.json'))('typescript')
-  } catch (error) {
-    if (error.code === 'MODULE_NOT_FOUND' && /Cannot find module 'typescript'/.test(error.message)) {
-      throw new Error(`The typescript task needs the optional peer dependency typescript, which is not installed. ${installHint}`)
-    }
-    throw error
-  }
-}
+export const loadTypescript = (projectPath = process.cwd()) => requirePeer('typescript', { task: 'typescript', installHint, projectPath })
 
 const streamToPromise = (stream) => new Promise((resolve, reject) => {
   stream.on('finish', resolve)