js-build-tools 6.4.0 → 6.5.0

package/README.md

@@ -561,6 +561,9 @@ 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",
+    // 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 +585,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/lintSource.js

@@ -8,6 +8,7 @@ exports.lintSource = void 0;
 var gulpConfig = _interopRequireWildcard(require("../../gulp.config.js"));
 var _gulp = require("gulp");
 var _neostandardLint = require("./neostandardLint.js");
+var _nodeStream = require("node:stream");
 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; }
 /**
@@ -30,12 +31,22 @@ const lintSource = ({
   const linter = (0, _neostandardLint.neostandardLint)({
     fix: true,
     ts,
-    rules: gulpConfig.get('lint.rules'),
-    failOnError
+    rules: gulpConfig.get('lint.rules')
   });
-  const written = (0, _gulp.src)(patterns).pipe(linter).pipe((0, _gulp.dest)(srcPath));
-  // pipe() does not forward errors, and gulp only watches the returned stream, so pass the linter's failure along.
-  linter.on('error', error => written.emit('error', error));
+  // Fail only once dest() has written every fixed file: gulp exits as soon as a task fails, so failing from the
+  // linter itself (before dest() finished) could leave a file that dest() had opened, but not yet written, empty.
+  // dest() passes each file on only after writing it, so this last step's flush runs after the final write. Files
+  // are consumed here rather than passed on, so nothing downstream has to read them.
+  const written = new _nodeStream.Transform({
+    objectMode: true,
+    transform: (file, enc, callback) => callback(),
+    flush: callback => failOnError && linter.totals.errors ? callback(new Error(`neostandard found ${linter.totals.errors} lint error(s) that could not be fixed automatically.`)) : callback()
+  });
+  const saved = (0, _gulp.src)(patterns).pipe(linter).pipe((0, _gulp.dest)(srcPath));
+  saved.pipe(written);
+  // pipe() does not forward errors, and gulp only watches the returned stream, so pass any failure along.
+  linter.on('error', error => written.destroy(error));
+  saved.on('error', error => written.destroy(error));
   return written;
 };
 exports.lintSource = lintSource;

package/dist/partials/neostandardLint.js

@@ -113,7 +113,7 @@ const printFileReport = (file, result) => {
  * @param {function(Object): Promise<{lintText: Function}>} [loadEslint] - Resolves an ESLint-shaped linter. Real
  * callers should never need to pass this - it exists so tests can supply a stand-in, since this project's
  * CommonJS-transform-based Jest setup cannot execute a real dynamic import() of neostandard (ESM-only).
- * @returns {stream.Transform}
+ * @returns {stream.Transform} With a `totals` property ({errors, warnings}), complete once the stream ends.
  */
 const neostandardLint = ({
   fix = true,
@@ -126,7 +126,7 @@ const neostandardLint = ({
     warnings: 0
   };
   let eslintPromise = null;
-  return _through.default.obj(function (file, enc, callback) {
+  const linter = _through.default.obj(function (file, enc, callback) {
     if (file.isNull()) {
       callback(null, file);
       return;
@@ -169,5 +169,8 @@ const neostandardLint = ({
     }
     callback();
   });
+  // Read by lintSource, which can only fail once the fixed files have been written, after this stream has ended.
+  linter.totals = totals;
+  return linter;
 };
 exports.neostandardLint = neostandardLint;

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/lintSource.mjs

@@ -1,6 +1,7 @@
 import * as gulpConfig from '../../gulp.config.mjs'
 import { dest, src } from 'gulp'
 import { neostandardLint } from './neostandardLint.mjs'
+import { Transform } from 'node:stream'
 
 /**
  * Lint the project's source (srcPath: .js, .mjs and .cjs, plus .ts when typescript.enabled) with neostandard and
@@ -17,11 +18,24 @@ export const lintSource = ({ failOnError = false } = {}) => {
   if (ts) {
     patterns.push(`${srcPath}/**/*.ts`)
   }
-  const linter = neostandardLint({ fix: true, ts, rules: gulpConfig.get('lint.rules'), failOnError })
-  const written = src(patterns)
+  const linter = neostandardLint({ fix: true, ts, rules: gulpConfig.get('lint.rules') })
+  // Fail only once dest() has written every fixed file: gulp exits as soon as a task fails, so failing from the
+  // linter itself (before dest() finished) could leave a file that dest() had opened, but not yet written, empty.
+  // dest() passes each file on only after writing it, so this last step's flush runs after the final write. Files
+  // are consumed here rather than passed on, so nothing downstream has to read them.
+  const written = new Transform({
+    objectMode: true,
+    transform: (file, enc, callback) => callback(),
+    flush: callback => failOnError && linter.totals.errors
+      ? callback(new Error(`neostandard found ${linter.totals.errors} lint error(s) that could not be fixed automatically.`))
+      : callback()
+  })
+  const saved = src(patterns)
     .pipe(linter)
     .pipe(dest(srcPath))
-  // pipe() does not forward errors, and gulp only watches the returned stream, so pass the linter's failure along.
-  linter.on('error', error => written.emit('error', error))
+  saved.pipe(written)
+  // pipe() does not forward errors, and gulp only watches the returned stream, so pass any failure along.
+  linter.on('error', error => written.destroy(error))
+  saved.on('error', error => written.destroy(error))
   return written
 }

package/functions/partials/neostandardLint.mjs

@@ -87,7 +87,7 @@ const printFileReport = (file, result) => {
  * @param {function(Object): Promise<{lintText: Function}>} [loadEslint] - Resolves an ESLint-shaped linter. Real
  * callers should never need to pass this - it exists so tests can supply a stand-in, since this project's
  * CommonJS-transform-based Jest setup cannot execute a real dynamic import() of neostandard (ESM-only).
- * @returns {stream.Transform}
+ * @returns {stream.Transform} With a `totals` property ({errors, warnings}), complete once the stream ends.
  */
 export const neostandardLint = (
   { fix = true, ts = false, rules = {}, failOnError = false } = {},
@@ -95,7 +95,7 @@ export const neostandardLint = (
 ) => {
   const totals = { errors: 0, warnings: 0 }
   let eslintPromise = null
-  return through.obj(
+  const linter = through.obj(
     function (file, enc, callback) {
       if (file.isNull()) {
         callback(null, file)
@@ -136,4 +136,7 @@ export const neostandardLint = (
       callback()
     }
   )
+  // Read by lintSource, which can only fail once the fixed files have been written, after this stream has ended.
+  linter.totals = totals
+  return linter
 }

package/functions/sourceLint.test.mjs

@@ -143,4 +143,24 @@ describe('lint', () => {
         done(new Error('lint should have failed on the unused variable'))
       })
   }, 20000)
+
+  test('only fails once every fixed file has been written back', done => {
+    // gulp exits as soon as a task fails, so failing while a file is still being written can leave that file empty.
+    const srcPath = gulpConfig.get('srcPath')
+    const fixable = ['a', 'b', 'c'].map(name => `${srcPath}/fixable-${name}.js`)
+    fixable.forEach(file => fs.writeFileSync(file, 'const x = "y";\n\nmodule.exports = x;\n'))
+    fs.writeFileSync(`${srcPath}/unfixable.js`, 'const unused = 1\n')
+    const logSpy = jest.spyOn(console, 'log').mockImplementation(() => {})
+    expect.assertions(fixable.length)
+    lint()
+      .on('error', () => {
+        logSpy.mockRestore()
+        fixable.forEach(file => expect(fs.readFileSync(file).toString()).toEqual('const x = \'y\'\n\nmodule.exports = x\n'))
+        done()
+      })
+      .on('finish', () => {
+        logSpy.mockRestore()
+        done(new Error('lint should have failed on the unused variable'))
+      })
+  }, 30000)
 })

package/gulp.config.mjs

@@ -135,6 +135,9 @@ 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 {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 +219,7 @@ const setDefaults = {
   docs: {
     enabled: false,
     from: 'src',
+    inBuild: true,
     index: 'MAIN.md',
     logLevel: 'Warn',
     method: false,

package/package.json

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