js-build-tools 6.4.1 → 6.6.0

package/README.md

@@ -90,6 +90,8 @@ provided are the defaults):
     "enabled": false,
     // Path to search for images
     "from": "src/img/**/*.+(png|jpg|jpeg|gif|svg)",
+    // The JPEG quality (0 to 100) to compress to, false keeps mozjpeg's own default (75)
+    "jpegQuality": false,
     // Path to output images
     "to": "browser/img"
   },
@@ -439,6 +441,9 @@ Add the following to the exports in your `build-tools.config.json`:
     "enabled": false,
     // Search pattern to find your images
     "from": "src/img/**/*.+(png|jpg|jpeg|gif|svg)",
+    // The JPEG quality (0 to 100) to compress to. Left false, mozjpeg uses its own default of 75, which can
+    // visibly band smooth gradients in photos; 85 is usually indistinguishable from the original
+    "jpegQuality": false,
     // Output directory for your images files
     "to": "browser/img"
   }
@@ -561,6 +566,13 @@ Add the following to the exports in your `build-tools.config.json`:
     // The directory holding the source, each folder in it becomes a module (TypeDoc) or is scanned recursively (jsdoc).
     // jsdoc also takes a list of directories and files, for example ["functions", "gulpfile.base.mjs"]
     "from": "src",
+    // TypeDoc only: the git revision the "Defined in" source links point to. Left false, TypeDoc uses the current
+    // commit, so every commit changes every page; a branch name such as "main" keeps them the same until the
+    // documentation itself changes
+    "gitRevision": false,
+    // Generate the documentation as part of build (the default). Set it to false to only generate it when you run
+    // the docs task yourself (see below)
+    "inBuild": true,
     // The markdown file used as the front page of the documentation (a short overview of your project)
     "index": "MAIN.md",
     // 'typedoc' or 'jsdoc'. Left out (or false), it's inferred from typescript.enabled - 'typedoc' when your
@@ -582,6 +594,20 @@ While `docs.enabled` is on, `gulp build` generates the documentation instead of
 hand-written (a short overview which links to the documentation). If you also export `docs` from your gulpfile you can
 run it on its own with `gulp docs`, and can then add the script `"docs": "gulp docs"`.
 
+To make generating the documentation a deliberate step instead, set `docs.inBuild` to `false`: `gulp build` then
+generates neither the documentation nor the readme, and `gulp docs` is the only thing that writes to `docs.to`. This
+suits a `docs.to` which points into another repository (a website, say): a build on a work-in-progress branch no
+longer rewrites the published documentation, which you regenerate when you release instead. For example with
+release-it, in `.release-it.json`:
+
+```json
+{
+  "hooks": {
+    "after:bump": "npm run docs"
+  }
+}
+```
+
 ### Browser automation (optional)
 
 Unlike the rest of this file, this isn't a `build-tools.config.json`-driven feature with its own task - it's a pair

package/dist/build.js

@@ -1,73 +1,76 @@
-"use strict";
-
-require("core-js/modules/esnext.weak-map.delete-all.js");
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.build = void 0;
-var _bundle = require("./bundle.js");
-var _bundleMinify = require("./bundleMinify.js");
-var _partials = require("./partials.js");
-var _compileReadme = require("./compileReadme.js");
-var _typeDocs = require("./typeDocs.js");
-var _jsdocDocs = require("./jsdocDocs.js");
-var _distMinify = require("./distMinify.js");
-var _sourceLint = require("./sourceLint.js");
-var _gulp = require("gulp");
-var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
-var _copyFonts = require("./copyFonts.js");
-var _images = require("./images.js");
-var _resolveDocsMethod = require("./partials/resolveDocsMethod.js");
-var _sass = require("./sass.js");
-var _testFull = require("./testFull.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; }
+"use strict";
+
+require("core-js/modules/esnext.weak-map.delete-all.js");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.build = void 0;
+var _bundle = require("./bundle.js");
+var _bundleMinify = require("./bundleMinify.js");
+var _partials = require("./partials.js");
+var _compileReadme = require("./compileReadme.js");
+var _typeDocs = require("./typeDocs.js");
+var _jsdocDocs = require("./jsdocDocs.js");
+var _distMinify = require("./distMinify.js");
+var _sourceLint = require("./sourceLint.js");
+var _gulp = require("gulp");
+var gulpConfig = _interopRequireWildcard(require("../gulp.config.js"));
+var _copyFonts = require("./copyFonts.js");
+var _images = require("./images.js");
+var _resolveDocsMethod = require("./partials/resolveDocsMethod.js");
+var _sass = require("./sass.js");
+var _testFull = require("./testFull.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; }
 /**
  * Runs several processes to build and validate the project.
  * Cleans and lints the source, distributes and minifies, bundles and minifies, creates the readme, then runs the
  * tests.
  * @memberOf module:js-build-tools
  * @returns {stream.Stream}
- */
-const build = (done = null) => {
-  const buildActions = [(0, _partials.distSeries)(), _distMinify.distMinify];
-  const generateDocs = gulpConfig.get('docs.enabled');
-  const docsMethod = (0, _resolveDocsMethod.resolveDocsMethod)();
-  if (generateDocs) {
-    // The documentation is generated from the source itself, the readme is written by hand
-    buildActions.push(docsMethod === 'jsdoc' ? _jsdocDocs.jsdocDocs : _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(_bundleMinify.bundleMinify);
-  }
-  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).
-  // sourceLint fixes the real source in place before anything compiles from it (distSeries, tsFor inside it), so a
-  // build never reads a mix of pre- and post-fix content; clean only touches dist/browser output, so the two can
-  // run alongside each other.
-  return (0, _gulp.series)((0, _gulp.parallel)(_partials.clean, _sourceLint.sourceLint), (0, _gulp.parallel)(...runActions))(done);
-};
+ */
+const build = (done = null) => {
+  const buildActions = [(0, _partials.distSeries)(), _distMinify.distMinify];
+  const generateDocs = gulpConfig.get('docs.enabled');
+  const docsMethod = (0, _resolveDocsMethod.resolveDocsMethod)();
+  if (generateDocs) {
+    // The documentation is generated from the source itself, the readme is written by hand. With docs.inBuild off,
+    // generating it is left to the standalone docs task (gulp docs), so a build never rewrites it.
+    if (gulpConfig.get('docs.inBuild') !== false) {
+      buildActions.push(docsMethod === 'jsdoc' ? _jsdocDocs.jsdocDocs : _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(_bundleMinify.bundleMinify);
+  }
+  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).
+  // sourceLint fixes the real source in place before anything compiles from it (distSeries, tsFor inside it), so a
+  // build never reads a mix of pre- and post-fix content; clean only touches dist/browser output, so the two can
+  // run alongside each other.
+  return (0, _gulp.series)((0, _gulp.parallel)(_partials.clean, _sourceLint.sourceLint), (0, _gulp.parallel)(...runActions))(done);
+};
 exports.build = build;

package/dist/build.min.js

@@ -1 +1 @@
-"use strict";require("core-js/modules/esnext.weak-map.delete-all.js"),Object.defineProperty(exports,"__esModule",{value:!0}),exports.build=void 0;var cache,_bundle=require("./bundle.js"),_bundleMinify=require("./bundleMinify.js"),_partials=require("./partials.js"),_compileReadme=require("./compileReadme.js"),_typeDocs=require("./typeDocs.js"),_jsdocDocs=require("./jsdocDocs.js"),_distMinify=require("./distMinify.js"),_sourceLint=require("./sourceLint.js"),_gulp=require("gulp"),gulpConfig=_interopRequireWildcard(require("../gulp.config.js")),_copyFonts=require("./copyFonts.js"),_images=require("./images.js"),_resolveDocsMethod=require("./partials/resolveDocsMethod.js"),_sass=require("./sass.js"),_testFull=require("./testFull.js");function _interopRequireWildcard(e,s){if(!s&&e&&e.__esModule)return e;var i,r,t=Object.defineProperty,l={__proto__:null,default:e};if(Object(e)!==e)return l;if(cache||"function"!=typeof WeakMap||(cache=new WeakMap),cache){if(cache.has(e))return cache.get(e);cache.set(e,l)}for(r in e)"default"!==r&&{}.hasOwnProperty.call(e,r)&&((i=t&&Object.getOwnPropertyDescriptor(e,r))&&(i.get||i.set)?t(l,r,i):l[r]=e[r]);return l}const build=(e=null)=>{const s=[(0,_partials.distSeries)(),_distMinify.distMinify],i=gulpConfig.get("docs.enabled"),r=(0,_resolveDocsMethod.resolveDocsMethod)();i?s.push("jsdoc"===r?_jsdocDocs.jsdocDocs:_typeDocs.typeDocs):gulpConfig.get("typescript.enabled")&&s.push(_compileReadme.compileReadme),gulpConfig.get("browser.enabled")&&(s.push(_bundle.bundle),s.push(_bundleMinify.bundleMinify));const t=[(0,_gulp.series)(...s)];return i||gulpConfig.get("typescript.enabled")||t.push(_compileReadme.compileReadme),t.push(_testFull.testFull),gulpConfig.get("fonts.enabled")&&t.push(_copyFonts.copyFonts),gulpConfig.get("images.enabled")&&t.push(_images.images),gulpConfig.get("sass.enabled")&&t.push(_sass.sass),(0,_gulp.series)((0,_gulp.parallel)(_partials.clean,_sourceLint.sourceLint),(0,_gulp.parallel)(...t))(e)};exports.build=build;
+"use strict";require("core-js/modules/esnext.weak-map.delete-all.js"),Object.defineProperty(exports,"__esModule",{value:!0}),exports.build=void 0;var cache,_bundle=require("./bundle.js"),_bundleMinify=require("./bundleMinify.js"),_partials=require("./partials.js"),_compileReadme=require("./compileReadme.js"),_typeDocs=require("./typeDocs.js"),_jsdocDocs=require("./jsdocDocs.js"),_distMinify=require("./distMinify.js"),_sourceLint=require("./sourceLint.js"),_gulp=require("gulp"),gulpConfig=_interopRequireWildcard(require("../gulp.config.js")),_copyFonts=require("./copyFonts.js"),_images=require("./images.js"),_resolveDocsMethod=require("./partials/resolveDocsMethod.js"),_sass=require("./sass.js"),_testFull=require("./testFull.js");function _interopRequireWildcard(e,s){if(!s&&e&&e.__esModule)return e;var i,r,t=Object.defineProperty,l={__proto__:null,default:e};if(Object(e)!==e)return l;if(cache||"function"!=typeof WeakMap||(cache=new WeakMap),cache){if(cache.has(e))return cache.get(e);cache.set(e,l)}for(r in e)"default"!==r&&{}.hasOwnProperty.call(e,r)&&((i=t&&Object.getOwnPropertyDescriptor(e,r))&&(i.get||i.set)?t(l,r,i):l[r]=e[r]);return l}const build=(e=null)=>{const s=[(0,_partials.distSeries)(),_distMinify.distMinify],i=gulpConfig.get("docs.enabled"),r=(0,_resolveDocsMethod.resolveDocsMethod)();i?!1!==gulpConfig.get("docs.inBuild")&&s.push("jsdoc"===r?_jsdocDocs.jsdocDocs:_typeDocs.typeDocs):gulpConfig.get("typescript.enabled")&&s.push(_compileReadme.compileReadme),gulpConfig.get("browser.enabled")&&(s.push(_bundle.bundle),s.push(_bundleMinify.bundleMinify));const t=[(0,_gulp.series)(...s)];return i||gulpConfig.get("typescript.enabled")||t.push(_compileReadme.compileReadme),t.push(_testFull.testFull),gulpConfig.get("fonts.enabled")&&t.push(_copyFonts.copyFonts),gulpConfig.get("images.enabled")&&t.push(_images.images),gulpConfig.get("sass.enabled")&&t.push(_sass.sass),(0,_gulp.series)((0,_gulp.parallel)(_partials.clean,_sourceLint.sourceLint),(0,_gulp.parallel)(...t))(e)};exports.build=build;

package/dist/partials/imagesFor.js

@@ -4,7 +4,7 @@ require("core-js/modules/esnext.weak-map.delete-all.js");
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.loadImagemin = exports.imagesFor = void 0;
+exports.loadImageminPlugins = exports.loadImagemin = exports.imagesFor = exports.imageminPlugins = void 0;
 var _gulpCache = _interopRequireDefault(require("gulp-cache"));
 var _loadPeer = require("./loadPeer.js");
 var _gulp = require("gulp");
@@ -33,6 +33,36 @@ const loadImagemin = (projectPath = process.cwd()) => {
   return loaded && (loaded.__esModule || loaded.default) ? loaded.default : loaded;
 };
 
+/**
+ * Load the plugins `gulp-imagemin` exports by name (gifsicle, mozjpeg, optipng and svgo), each a promise of a plugin
+ * factory, for when they need options of their own (see images.jpegQuality). Resolved like {@link loadImagemin}.
+ * @memberOf module:partials
+ * @param {string} [projectPath=process.cwd()] - The project directory to resolve `gulp-imagemin` from.
+ * @returns {Object<string, Promise<Function>>} The plugin factories, by name.
+ */
+exports.loadImagemin = loadImagemin;
+const loadImageminPlugins = (projectPath = process.cwd()) => (0, _loadPeer.requirePeer)('gulp-imagemin', {
+  task: 'images',
+  installHint,
+  esmOnlyMessage: `gulp-imagemin could not be loaded because it is ESM-only. ${installHint}`,
+  projectPath
+});
+
+// The plugins imagemin runs when it isn't given any, in its own order
+exports.loadImageminPlugins = loadImageminPlugins;
+const defaultPluginNames = ['gifsicle', 'mozjpeg', 'optipng', 'svgo'];
+
+/**
+ * The plugins imagemin uses by default, with mozjpeg set to the given JPEG quality instead of its own default (75).
+ * @memberOf module:partials
+ * @param {number} jpegQuality - The mozjpeg quality, 0 to 100.
+ * @param {Object<string, Promise<Function>>} [plugins=loadImageminPlugins()] - The plugin factories, by name.
+ * @returns {Array<Promise<Function>>} The plugins, in imagemin's default order.
+ */
+const imageminPlugins = (jpegQuality, plugins = loadImageminPlugins()) => defaultPluginNames.map(name => Promise.resolve(plugins[name]).then(makePlugin => name === 'mozjpeg' ? makePlugin({
+  quality: jpegQuality
+}) : makePlugin()));
+
 /**
  * Move and optimize images into the browser directory.
  * @memberOf module:partials
@@ -40,18 +70,25 @@ const loadImagemin = (projectPath = process.cwd()) => {
  * @param {string} [imageDest=dest/image/folder]
  * @return {stream.Stream}
  */
-exports.loadImagemin = loadImagemin;
+exports.imageminPlugins = imageminPlugins;
 const imagesFor = (imageSrc = gulpConfig.get('images.from'), imageDest = gulpConfig.get('images.to')) => {
   const imagemin = loadImagemin();
+  const jpegQuality = gulpConfig.get('images.jpegQuality');
+  // Left unset, imagemin runs its default plugins with their own defaults
+  const plugins = jpegQuality ? imageminPlugins(jpegQuality) : undefined;
   // Gulp 5 reads files as utf8 text unless told otherwise, which corrupts binary images (and makes gulp-cache drop them).
   return (0, _gulp.src)(imageSrc, {
     encoding: false
   }).pipe(
   // Caching images that ran through imagemin
-  (0, _gulpCache.default)(imagemin({
+  (0, _gulpCache.default)(imagemin(plugins, {
     interlaced: true,
     silent: true,
     verbose: false
-  }))).pipe((0, _gulp.dest)(imageDest));
+  }),
+  // gulp-cache keys on the file's contents alone, so keep each quality's results apart
+  {
+    name: jpegQuality ? `jpeg-quality-${jpegQuality}` : 'default'
+  })).pipe((0, _gulp.dest)(imageDest));
 };
 exports.imagesFor = imagesFor;

package/dist/partials/typeDocsFor.js

@@ -1,31 +1,31 @@
-"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';
-
+"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.
@@ -33,87 +33,87 @@ 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 {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('/');
-
+ */
+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
-  };
-};
-
+ */
+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) : '';
-};
-
+ */
+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
@@ -121,18 +121,18 @@ const describeFolder = folderPath => {
  * @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();
-};
-
+ */
+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
@@ -147,58 +147,58 @@ const describeFile = filePath => {
  * @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());
-  }
-};
-
+ */
+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
@@ -209,51 +209,57 @@ const projectName = () => {
  * @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');
-        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
-        });
-        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();
-  };
-};
+ */
+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;

package/functions/build.mjs

@@ -26,8 +26,11 @@ export const build = (done = null) => {
   const generateDocs = gulpConfig.get('docs.enabled')
   const docsMethod = resolveDocsMethod()
   if (generateDocs) {
-    // The documentation is generated from the source itself, the readme is written by hand
-    buildActions.push(docsMethod === 'jsdoc' ? jsdocDocs : typeDocs)
+    // The documentation is generated from the source itself, the readme is written by hand. With docs.inBuild off,
+    // generating it is left to the standalone docs task (gulp docs), so a build never rewrites it.
+    if (gulpConfig.get('docs.inBuild') !== false) {
+      buildActions.push(docsMethod === 'jsdoc' ? jsdocDocs : 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)

package/functions/build.test.mjs

@@ -676,6 +676,29 @@ describe('build', () => {
     })
   }, 30000)
 
+  test('with docs.inBuild off, build generates neither the documentation nor the readme', done => {
+    const readmePath = gulpConfig.get('readme.to')
+    const readmeFile = gulpConfig.get('readme.file')
+    fs.rmSync(`${readmePath}/${readmeFile}`, { force: true })
+    typeDocs.mockClear()
+    jsdocDocs.mockClear()
+    gulpConfig.set('browser.enabled', false)
+    gulpConfig.set('typescript.enabled', false)
+    gulpConfig.set('docs.enabled', true)
+    gulpConfig.set('docs.inBuild', false)
+    expect.assertions(4)
+    build(() => {
+      gulpConfig.set('docs.enabled', false)
+      gulpConfig.set('docs.inBuild', true)
+      expect(jsdocDocs).not.toHaveBeenCalled()
+      expect(typeDocs).not.toHaveBeenCalled()
+      // The readme is still written by hand while docs.enabled is on
+      expect(fs.existsSync(`${readmePath}/${readmeFile}`)).toBe(false)
+      expect(testFull).toHaveBeenCalled()
+      done()
+    })
+  }, 30000)
+
   test('docs.method overrides the typescript.enabled inference either way', done => {
     const srcPath = gulpConfig.get('srcPath')
     const rootPath = gulpConfig.get('rootPath')

package/functions/partials/imagesFor.mjs

@@ -25,6 +25,34 @@ export const loadImagemin = (projectPath = process.cwd()) => {
   return loaded && (loaded.__esModule || loaded.default) ? loaded.default : loaded
 }
 
+/**
+ * Load the plugins `gulp-imagemin` exports by name (gifsicle, mozjpeg, optipng and svgo), each a promise of a plugin
+ * factory, for when they need options of their own (see images.jpegQuality). Resolved like {@link loadImagemin}.
+ * @memberOf module:partials
+ * @param {string} [projectPath=process.cwd()] - The project directory to resolve `gulp-imagemin` from.
+ * @returns {Object<string, Promise<Function>>} The plugin factories, by name.
+ */
+export const loadImageminPlugins = (projectPath = process.cwd()) => requirePeer('gulp-imagemin', {
+  task: 'images',
+  installHint,
+  esmOnlyMessage: `gulp-imagemin could not be loaded because it is ESM-only. ${installHint}`,
+  projectPath
+})
+
+// The plugins imagemin runs when it isn't given any, in its own order
+const defaultPluginNames = ['gifsicle', 'mozjpeg', 'optipng', 'svgo']
+
+/**
+ * The plugins imagemin uses by default, with mozjpeg set to the given JPEG quality instead of its own default (75).
+ * @memberOf module:partials
+ * @param {number} jpegQuality - The mozjpeg quality, 0 to 100.
+ * @param {Object<string, Promise<Function>>} [plugins=loadImageminPlugins()] - The plugin factories, by name.
+ * @returns {Array<Promise<Function>>} The plugins, in imagemin's default order.
+ */
+export const imageminPlugins = (jpegQuality, plugins = loadImageminPlugins()) => defaultPluginNames.map(
+  name => Promise.resolve(plugins[name]).then(makePlugin => name === 'mozjpeg' ? makePlugin({ quality: jpegQuality }) : makePlugin())
+)
+
 /**
  * Move and optimize images into the browser directory.
  * @memberOf module:partials
@@ -34,16 +62,21 @@ export const loadImagemin = (projectPath = process.cwd()) => {
  */
 export const imagesFor = (imageSrc = gulpConfig.get('images.from'), imageDest = gulpConfig.get('images.to')) => {
   const imagemin = loadImagemin()
+  const jpegQuality = gulpConfig.get('images.jpegQuality')
+  // Left unset, imagemin runs its default plugins with their own defaults
+  const plugins = jpegQuality ? imageminPlugins(jpegQuality) : undefined
   // Gulp 5 reads files as utf8 text unless told otherwise, which corrupts binary images (and makes gulp-cache drop them).
   return src(imageSrc, { encoding: false })
     .pipe(
       // Caching images that ran through imagemin
       cache(
-        imagemin({
+        imagemin(plugins, {
           interlaced: true,
           silent: true,
           verbose: false,
-        })
+        }),
+        // gulp-cache keys on the file's contents alone, so keep each quality's results apart
+        { name: jpegQuality ? `jpeg-quality-${jpegQuality}` : 'default' }
       )
     )
     .pipe(dest(imageDest))

package/functions/partials/imagesFor.test.mjs

@@ -1,8 +1,10 @@
+import { execFileSync } from 'child_process'
 import fs from 'fs'
 import * as setUp from '../test-helpers/setUp.mjs'
 import os from 'os'
+import path from 'path'
 import zlib from 'zlib'
-import { imagesFor, loadImagemin } from './imagesFor.mjs'
+import { imageminPlugins, imagesFor, loadImagemin } from './imagesFor.mjs'
 import { isolateGulpCache } from '../test-helpers/isolateGulpCache.mjs'
 
 setUp.setDefaults('test-images-for')
@@ -158,6 +160,25 @@ const makePng = (size = 32) => {
   ])
 }
 
+// A JPEG at quality 100, encoded from a generated image by the cjpeg binary the mozjpeg dependency installs
+const makeJpeg = (size = 64) => {
+  const pixels = Buffer.alloc(size * size * 3)
+  for (let i = 0; i < pixels.length; i++) {
+    pixels[i] = (i * 37 + Math.floor(i / (size * 3)) * 91) % 256
+  }
+  const ppm = Buffer.concat([Buffer.from(`P6\n${size} ${size}\n255\n`), pixels])
+  // mozjpeg's exports field hides its files, and Jest runs from the project root
+  const cjpeg = path.resolve('node_modules', 'mozjpeg', 'vendor', 'cjpeg')
+  return execFileSync(cjpeg, ['-quality', '100'], { input: ppm })
+}
+
+// Run imagesFor over one file and resolve with the written output
+const optimize = (file, to) => new Promise((resolve, reject) => {
+  imagesFor(file, to)
+    .on('finish', () => resolve(fs.readFileSync(`${to}/${path.basename(file)}`)))
+    .on('error', reject)
+})
+
 // The cache outlives a run, so clear it or a stale result from an older imagemin can pass
 beforeEach(() => clearImageCache().then(setUp.beforeEach))
 
@@ -210,6 +231,43 @@ describe('imagesFor', () => {
   })
 })
 
+describe('images.jpegQuality', () => {
+  test('compresses JPEGs to the configured quality, never reusing another quality\'s cached result', async () => {
+    expect.assertions(4)
+    const srcPath = gulpConfig.get('srcPath')
+    const jpegFile = `${srcPath}/photo.jpg`
+    fs.writeFileSync(jpegFile, makeJpeg())
+    const browserPath = gulpConfig.get('browser.to')
+    try {
+      const atDefault = await optimize(jpegFile, `${browserPath}/default`)
+      gulpConfig.set('images.jpegQuality', 95)
+      const at95 = await optimize(jpegFile, `${browserPath}/q95`)
+      // Both still JPEGs (start-of-image marker)
+      expect(atDefault.subarray(0, 2).equals(Buffer.from([0xff, 0xd8]))).toBeTruthy()
+      expect(at95.subarray(0, 2).equals(Buffer.from([0xff, 0xd8]))).toBeTruthy()
+      // Same input, so a shared cache entry would make these identical: 95 keeps more detail than mozjpeg's 75
+      expect(at95.equals(atDefault)).toBe(false)
+      expect(at95.length).toBeGreaterThan(atDefault.length)
+    } finally {
+      gulpConfig.set('images.jpegQuality', false)
+    }
+  }, 30000)
+})
+
+describe('imageminPlugins', () => {
+  test('builds imagemin\'s default plugins in order, passing the quality to mozjpeg only', async () => {
+    expect.assertions(2)
+    const calls = []
+    const factory = name => Promise.resolve((...args) => {
+      calls.push([name, ...args])
+      return name
+    })
+    const plugins = { gifsicle: factory('gifsicle'), mozjpeg: factory('mozjpeg'), optipng: factory('optipng'), svgo: factory('svgo') }
+    expect(await Promise.all(imageminPlugins(85, plugins))).toEqual(['gifsicle', 'mozjpeg', 'optipng', 'svgo'])
+    expect(calls).toEqual([['gifsicle'], ['mozjpeg', { quality: 85 }], ['optipng'], ['svgo']])
+  })
+})
+
 describe('loadImagemin', () => {
   test('loads the gulp-imagemin plugin factory from the project directory', () => {
     expect.assertions(1)

package/functions/partials/typeDocsFor.mjs

@@ -204,6 +204,7 @@ export const typeDocsFor = (
           exclude: [path.resolve(srcPath).split(path.sep).join('/') + '/**/*.test.*']
         }))
         const indexFile = gulpConfig.get('docs.index')
+        const gitRevision = gulpConfig.get('docs.gitRevision')
         await removeDirectory(outPath)
         const app = await Application.bootstrap({
           entryPoints,
@@ -211,7 +212,10 @@ export const typeDocsFor = (
           name: gulpConfig.get('docs.title') || projectName(),
           readme: indexFile && fs.existsSync(indexFile) ? indexFile : 'none',
           logLevel: gulpConfig.get('docs.logLevel') || 'Warn',
-          skipErrorChecking: true
+          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) {

package/functions/partials/typeDocsFor.test.mjs

@@ -211,6 +211,17 @@ describe('typeDocsFor', () => {
     expect(calls.options.readme).toBe('none')
   })
 
+  test('passes docs.gitRevision on to TypeDoc, and leaves TypeDoc\'s own default when it is false', async () => {
+    gulpConfig.set('docs.enabled', true)
+    const calls = {}
+    await typeDocsFor(gulpConfig.get('srcPath'), `${gulpConfig.get('srcPath')}/../docs`, fakeTypeDoc(calls))()
+    expect('gitRevision' in calls.options).toBe(false)
+    gulpConfig.set('docs.gitRevision', 'main')
+    await typeDocsFor(gulpConfig.get('srcPath'), `${gulpConfig.get('srcPath')}/../docs`, fakeTypeDoc(calls))()
+    expect(calls.options.gitRevision).toBe('main')
+    gulpConfig.set('docs.gitRevision', false)
+  })
+
   test('reads the source with the tsconfig of the project, adding the entries to it', async () => {
     gulpConfig.set('docs.enabled', true)
     gulpConfig.set('typescript.config', 'tsconfig.json')

package/gulp.config.mjs

@@ -16,6 +16,10 @@ import { fileExists } from 'test-filesystem'
  * A setting that may be true or false.
  * @typedef {boolean} module:gulpConfig~BooleanSetting
  */
+/**
+ * A setting that may be flag 'false' or provide a number
+ * @typedef {false|number} module:gulpConfig~FlagNumberSetting
+ */
 /**
  * A setting that may be flag 'false' or provide a StringSetting
  * @typedef {false|StringSetting} module:gulpConfig~FlagStringSetting
@@ -43,7 +47,7 @@ import { fileExists } from 'test-filesystem'
  */
 /**
  * Any single configuration option is a Setting.
- * @typedef {ArrayableSetting|BooleanSetting|FlagsSetting|StringSetting} Setting
+ * @typedef {ArrayableSetting|BooleanSetting|FlagNumberSetting|FlagsSetting|StringSetting} Setting
  */
 /**
  * One copy-files entry: a glob (or array of globs) to copy, and where to copy it.
@@ -103,6 +107,9 @@ import { fileExists } from 'test-filesystem'
  * @typedef {Object<string, Setting>} module:gulpConfig~ImageConfig
  * @property {BooleanSetting} enabled - Toggle image minify and copy process.
  * @property {StringSetting} from - Path to search for images.
+ * @property {FlagNumberSetting} jpegQuality - The JPEG quality (0 to 100) mozjpeg compresses to. False (the
+ * default) keeps mozjpeg's own default, 75. Raise it (85 is usually indistinguishable from the original) when 75
+ * visibly bands smooth gradients.
  * @property {StringSetting} to - Path to output images.
  */
 /**
@@ -135,6 +142,13 @@ import { fileExists } from 'test-filesystem'
  * build does this instead of generating the readme from the jsdoc comments of the compiled files.
  * @property {ArrayableSetting} from - The directory holding the source, each folder in it becomes a module (TypeDoc) or
  * is scanned recursively (jsdoc). jsdoc also takes a list of directories and files.
+ * @property {FlagStringSetting} gitRevision - The git revision TypeDoc's "Defined in" source links point to (TypeDoc
+ * only). False (the default) is TypeDoc's own: the current commit, which changes every page on every commit. A
+ * branch name such as 'main' keeps the pages unchanged until the documentation itself changes; '{branch}' is the
+ * branch being built.
+ * @property {BooleanSetting} inBuild - Generate the documentation as part of build (the default). Turn it off to only
+ * generate it when you run the docs task yourself (gulp docs), for example when docs.to points into another
+ * repository and you only want to publish the documentation of a release.
  * @property {StringSetting} index - The markdown file used as the front page of the documentation.
  * @property {StringSetting} logLevel - How much TypeDoc reports: Verbose, Info, Warn, Error or None. Not used by jsdoc.
  * @property {FlagStringSetting} method - 'typedoc' or 'jsdoc'. False (the default) infers it from typescript.enabled -
@@ -216,6 +230,8 @@ const setDefaults = {
   docs: {
     enabled: false,
     from: 'src',
+    gitRevision: false,
+    inBuild: true,
     index: 'MAIN.md',
     logLevel: 'Warn',
     method: false,
@@ -232,6 +248,7 @@ const setDefaults = {
   images: {
     enabled: false,
     from: 'src/img/**/*.+(png|jpg|jpeg|gif|svg)',
+    jpegQuality: false,
     to: 'browser/img',
   },
   lint: {

package/package.json

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