js-build-tools 6.3.0 → 6.4.0

package/functions/partials/jsdocDocsFor.test.mjs

@@ -92,14 +92,15 @@ describe('jsdocDocsFor', () => {
     expect(['a.test.mjs', 'a.min.js', 'a.min.mjs', 'dir/_private.mjs', 'a.ts'].filter(documented)).toEqual([])
   })
 
-  test('passes docs.title to the theme as a link to the home page of the docs, and leaves it out when unset', async () => {
+  test('passes docs.title to the theme as a link to the home page of the docs and as its page title, and leaves it out when unset', async () => {
     gulpConfig.set('docs.enabled', true)
     const srcPath = gulpConfig.get('srcPath')
     const calls = {}
     gulpConfig.set('docs.title', 'Tom & Jerry <Tools>')
     await jsdocDocsFor(srcPath, `${srcPath}/../docs`, fakeRunJsdoc(calls))()
     expect(calls.config.opts.theme_opts).toEqual({
-      title: '<a href="index.html" class="sidebar-title sidebar-title-anchor">Tom &amp; Jerry &lt;Tools&gt;</a>'
+      title: '<a href="index.html" class="sidebar-title sidebar-title-anchor">Tom &amp; Jerry &lt;Tools&gt;</a>',
+      homepageTitle: 'Tom &amp; Jerry &lt;Tools&gt;'
     })
 
     gulpConfig.set('docs.title', '')
@@ -139,11 +140,13 @@ describe('jsdocDocsFor', () => {
 describe('jsdocDocsFor, end to end with the real jsdoc CLI and clean-jsdoc-theme', () => {
   test('produces a real browsable HTML page from real JSDoc comments', async () => {
     gulpConfig.set('docs.enabled', true)
+    gulpConfig.set('docs.title', 'Tom & Jerry')
     const outPath = `${gulpConfig.get('srcPath')}/../docs`
     await jsdocDocsFor(gulpConfig.get('srcPath'), outPath)()
     // clean-jsdoc-theme nests its real output under its own route folders (global/, source/...), not flat at
     // outPath's own root - confirmed by actually running it, not assumed from the classic jsdoc template shape.
     const files = fs.readdirSync(outPath, { recursive: true })
     expect(files.some(file => file.endsWith('.html'))).toBe(true)
+    expect(fs.readFileSync(`${outPath}/index.html`, 'utf8')).toMatch(/<title>\s*Tom &amp; Jerry\s*<\/title>/)
   }, 30000)
 })

package/functions/partials/lintSource.mjs

@@ -0,0 +1,27 @@
+import * as gulpConfig from '../../gulp.config.mjs'
+import { dest, src } from 'gulp'
+import { neostandardLint } from './neostandardLint.mjs'
+
+/**
+ * Lint the project's source (srcPath: .js, .mjs and .cjs, plus .ts when typescript.enabled) with neostandard and
+ * write the automatic fixes back in place. Shared by the sourceLint (build) and lint (standalone) tasks.
+ * @memberOf module:partials
+ * @param {Object} [options={}]
+ * @param {boolean} [options.failOnError=false] - Fail once linting finishes if any errors could not be fixed.
+ * @returns {stream.Stream}
+ */
+export const lintSource = ({ failOnError = false } = {}) => {
+  const srcPath = gulpConfig.get('srcPath')
+  const ts = gulpConfig.get('typescript.enabled')
+  const patterns = [`${srcPath}/**/*.{js,mjs,cjs}`]
+  if (ts) {
+    patterns.push(`${srcPath}/**/*.ts`)
+  }
+  const linter = neostandardLint({ fix: true, ts, rules: gulpConfig.get('lint.rules'), failOnError })
+  const written = 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))
+  return written
+}

package/functions/partials/loadPeer.mjs

@@ -6,6 +6,7 @@ import { pathToFileURL } from 'node:url'
 // 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.
+// eslint-disable-next-line no-new-func -- deliberate, see above
 const dynamicImport = new Function('specifier', 'return import(specifier)')
 
 /**

package/functions/partials/loadPlaywright.test.mjs

@@ -1,5 +1,4 @@
 import fs from 'fs'
-import path from 'node:path'
 import * as setUp from '../test-helpers/setUp.mjs'
 import { loadPlaywright, launchBrowser } from './loadPlaywright.mjs'
 import { serveStatic } from './serveStatic.mjs'
@@ -61,7 +60,7 @@ describe('a real page, served and loaded end to end', () => {
       const page = await browser.newPage()
       await page.goto(`${url}/index.html`)
       expect(await page.title()).toBe('loaded via a real module script')
-      const backgroundColor = await page.evaluate(() => getComputedStyle(document.body).backgroundColor)
+      const backgroundColor = await page.evaluate(() => globalThis.getComputedStyle(document.body).backgroundColor)
       expect(backgroundColor).toBe('rgb(1, 2, 3)')
     } finally {
       await browser.close()

package/functions/partials/minifyFor.mjs

@@ -2,7 +2,7 @@ import { dest, src } from 'gulp'
 import { default as gulpUglify } from 'gulp-uglify-es'
 import rename from 'gulp-rename'
 
-const uglify = gulpUglify.hasOwnProperty('default') ? gulpUglify.default : gulpUglify
+const uglify = Object.hasOwn(gulpUglify, 'default') ? gulpUglify.default : gulpUglify
 
 /**
  * Minify files and rename the output with '.min' extension.

package/functions/partials/neostandardLint.mjs

@@ -71,7 +71,8 @@ const printFileReport = (file, result) => {
 /**
  * Lint every file streaming through with neostandard and, unless `fix` is false, apply the automatic fixes to the
  * file's contents so a following `dest()` writes the fixed version. Remaining problems are printed along with a
- * summary once the stream ends; they never fail the build.
+ * summary once the stream ends; they only fail the stream when `failOnError` is set (the standalone `lint` task),
+ * never during `build`.
  *
  * One ESLint instance is built from the first file's own cwd and reused for the rest of the stream, since every
  * file in a given lint pass shares the same project (and so the same config).
@@ -81,13 +82,15 @@ const printFileReport = (file, result) => {
  * @param {boolean} [options.ts=false] - Lint `.ts` files too, with type-aware rules (see neostandard's `ts` option).
  * @param {Object<string, *>} [options.rules={}] - ESLint rule overrides layered on top of neostandard's own rules
  * (see gulp.config.mjs's `lint.rules`).
+ * @param {boolean} [options.failOnError=false] - Emit an error once the stream ends if any lint errors remain after
+ * fixing, so a command-line run exits non-zero.
  * @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}
  */
 export const neostandardLint = (
-  { fix = true, ts = false, rules = {} } = {},
+  { fix = true, ts = false, rules = {}, failOnError = false } = {},
   loadEslint = buildEslint
 ) => {
   const totals = { errors: 0, warnings: 0 }
@@ -126,6 +129,10 @@ export const neostandardLint = (
       console.log('======================================')
       console.log(`✖ Errors total: ${totals.errors}`)
       console.log(`⚠ Warnings total: ${totals.warnings}\n`)
+      if (failOnError && totals.errors) {
+        callback(new Error(`neostandard found ${totals.errors} lint error(s) that could not be fixed automatically.`))
+        return
+      }
       callback()
     }
   )

package/functions/partials/neostandardLint.test.mjs

@@ -110,6 +110,20 @@ describe('neostandardLint', () => {
     expect(logSpy).toHaveBeenCalledWith('⚠ Warnings total: 1\n')
   })
 
+  test('with failOnError, fails the stream once it ends if any errors remain', async () => {
+    expect.assertions(2)
+    const eslint = fakeEslint(() => [{ messages: [{ line: 1, column: 1, message: 'bad thing' }], errorCount: 1, warningCount: 0 }])
+    await expect(run(neostandardLint({ failOnError: true }, () => Promise.resolve(eslint)), [makeFile(Buffer.from('a'))]))
+      .rejects.toThrow('neostandard found 1 lint error(s)')
+    expect(logSpy).toHaveBeenCalledWith('✖ Errors total: 1')
+  })
+
+  test('with failOnError, still passes when there are only warnings', async () => {
+    expect.assertions(1)
+    const eslint = fakeEslint(() => [{ messages: [{ line: 1, column: 1, message: 'just a warning' }], errorCount: 0, warningCount: 1 }])
+    await expect(run(neostandardLint({ failOnError: true }, () => Promise.resolve(eslint)), [makeFile(Buffer.from('a'))])).resolves.toHaveLength(1)
+  })
+
   test('surfaces a failure to load or run the linter as a stream error', async () => {
     expect.assertions(1)
     await expect(run(neostandardLint({}, () => Promise.reject(new Error('cannot load'))), [makeFile(Buffer.from('x'))])).rejects.toThrow('cannot load')

package/functions/partials/runOnChange.test.mjs

@@ -1,3 +1,4 @@
+/* eslint-disable no-template-curly-in-string -- fixture source code, the ${...} is meant to stay literal */
 import fs from 'fs'
 import * as setUp from '../test-helpers/setUp.mjs'
 import { bundle } from '../bundle.mjs'
@@ -26,10 +27,10 @@ const srcFile = `${srcPath}/runOnChange.js`
 const srcTsFile = `${srcPath}/runOnChange.ts`
 
 beforeEach(() => {
-    return setUp.beforeEach()
-      .then(() => fs.writeFileSync(srcTsFile, rawContents))
-      .then(() => fs.writeFileSync(srcFile, rawContents))
-  }
+  return setUp.beforeEach()
+    .then(() => fs.writeFileSync(srcTsFile, rawContents))
+    .then(() => fs.writeFileSync(srcFile, rawContents))
+}
 )
 
 afterEach(() => {

package/functions/partials/tsFor.test.mjs

@@ -1,3 +1,4 @@
+/* eslint-disable no-template-curly-in-string -- fixture source code, the ${...} is meant to stay literal */
 import fs from 'fs'
 import { Transform, PassThrough } from 'node:stream'
 import ts from 'typescript'

package/functions/partials.mjs

@@ -18,6 +18,7 @@ export { imagesFor } from './partials/imagesFor.mjs'
 export { importModule, importPeer, requirePeer } from './partials/loadPeer.mjs'
 export { jsdocDocsFor } from './partials/jsdocDocsFor.mjs'
 export { loadPlaywright, launchBrowser } from './partials/loadPlaywright.mjs'
+export { lintSource } from './partials/lintSource.mjs'
 export { minifyFor } from './partials/minifyFor.mjs'
 export { neostandardLint } from './partials/neostandardLint.mjs'
 export { readmeTemplate } from './partials/readmeTemplate.mjs'

package/functions/partials.test.mjs

@@ -2,6 +2,6 @@ import * as partials from './partials.mjs'
 
 describe('partials', () => {
   test('is object with all partial exports', () => {
-    expect(Object.keys(partials).length).toBe(24)
+    expect(Object.keys(partials).length).toBe(25)
   })
 })

package/functions/sourceLint.mjs

@@ -1,24 +1,13 @@
-import * as gulpConfig from '../gulp.config.mjs'
-import { dest, src } from 'gulp'
-import { neostandardLint } from './partials/neostandardLint.mjs'
+import { lintSource } from './partials/lintSource.mjs'
 
 /**
  * Applies neostandard linting (js-build-tools' chosen style) to the real, hand-written source - not the compiled
  * dist/browser output, which is generated and so was never going to pass a hand-authored-code style check (every
  * compiler/bundler emits its own boilerplate - import aliasing, interop headers - that only looks like a style
  * violation). Includes test files: there is no reason to hold tests to a lower style bar than the rest of the
- * source. When typescript.enabled, the real TypeScript source is linted too, with type-aware rules.
+ * source. When typescript.enabled, the real TypeScript source is linted too, with type-aware rules. Runs as part of
+ * `build`, where remaining errors are reported but never fail it.
  * @memberOf module:js-build-tools
  * @returns {*}
  */
-export const sourceLint = () => {
-  const srcPath = gulpConfig.get('srcPath')
-  const ts = gulpConfig.get('typescript.enabled')
-  const patterns = [`${srcPath}/**/*.js`]
-  if (ts) {
-    patterns.push(`${srcPath}/**/*.ts`)
-  }
-  return src(patterns)
-    .pipe(neostandardLint({ fix: true, ts, rules: gulpConfig.get('lint.rules') }))
-    .pipe(dest(srcPath))
-}
+export const sourceLint = () => lintSource()

package/functions/sourceLint.test.mjs

@@ -1,5 +1,7 @@
+/* eslint-disable no-template-curly-in-string -- fixture source code, the ${...} is meant to stay literal */
 import fs from 'fs'
 import * as setUp from './test-helpers/setUp.mjs'
+import { lint } from './lint.mjs'
 import { sourceLint } from './sourceLint.mjs'
 import { countMatches } from 'test-filesystem'
 
@@ -51,6 +53,23 @@ describe('sourceLint', () => {
       })
   }, 20000)
 
+  test('also lints .mjs and .cjs source, not just .js', done => {
+    const srcPath = gulpConfig.get('srcPath')
+    fs.writeFileSync(`${srcPath}/example.mjs`, 'const m = "d";\n\nexport default m;\n')
+    fs.writeFileSync(`${srcPath}/example.cjs`, 'const c = "e";\n\nmodule.exports = c;\n')
+    expect.assertions(2)
+    sourceLint()
+      .on('finish', () => {
+        expect(fs.readFileSync(`${srcPath}/example.mjs`).toString()).toEqual('const m = \'d\'\n\nexport default m\n')
+        expect(fs.readFileSync(`${srcPath}/example.cjs`).toString()).toEqual('const c = \'e\'\n\nmodule.exports = c\n')
+        done()
+      })
+      .on('error', error => {
+        console.error('Encountered error', error)
+        done(error)
+      })
+  }, 20000)
+
   test('lint.rules actually suppresses a real neostandard finding', done => {
     const srcPath = gulpConfig.get('srcPath')
     // A fixture string containing literal ${...} text (simulating real module source, not an accidental
@@ -95,3 +114,33 @@ describe('sourceLint', () => {
       })
   }, 20000)
 })
+
+describe('lint', () => {
+  test('fixes the source and finishes without error when nothing unfixable remains', done => {
+    const srcPath = gulpConfig.get('srcPath')
+    expect.assertions(1)
+    lint()
+      .on('finish', () => {
+        expect(countMatches(fs.readFileSync(`${srcPath}/example.js`).toString(), ';')).toEqual(0)
+        done()
+      })
+      .on('error', error => done(error))
+  }, 20000)
+
+  test('fails when an error remains that neostandard cannot fix', done => {
+    const srcPath = gulpConfig.get('srcPath')
+    fs.writeFileSync(`${srcPath}/unfixable.js`, 'const unused = 1\n')
+    const logSpy = jest.spyOn(console, 'log').mockImplementation(() => {})
+    expect.assertions(1)
+    lint()
+      .on('error', error => {
+        logSpy.mockRestore()
+        expect(error.message).toMatch('neostandard found 1 lint error(s)')
+        done()
+      })
+      .on('finish', () => {
+        logSpy.mockRestore()
+        done(new Error('lint should have failed on the unused variable'))
+      })
+  }, 20000)
+})

package/functions/test-helpers/isolateGulpCache.mjs

@@ -0,0 +1,16 @@
+import cache from 'gulp-cache'
+
+/**
+ * Give this test file its own gulp-cache folder, and return a function that clears only that folder. gulp-cache
+ * otherwise keeps one cache in os.tmpdir() for every process, so a cache.clearAll() in one Jest worker could wipe it
+ * while another worker's images task was still using it, and gulp-cache then silently dropped that worker's
+ * images. Jest loads gulp-cache separately for each test file, so this only changes the copy that file uses.
+ * @memberOf module:testHelpers
+ * @param {string} name - Unique per test file, used in the cache folder name.
+ * @returns {function(): Promise<void>} Clears this test file's cache.
+ */
+export const isolateGulpCache = name => {
+  const fileCache = new cache.Cache({ cacheDirName: `js-build-tools-test-${name}` })
+  cache.defaultOptions.fileCache = fileCache
+  return () => new Promise((resolve, reject) => fileCache.clear(null, error => error ? reject(error) : resolve()))
+}

package/functions/test-helpers/setUp.mjs

@@ -60,41 +60,41 @@ export {
    * @param {boolean} [exists=true]
    * @returns {Promise<*|void>}
    */
-    createTempDir,
+  createTempDir,
   /**
    * In the Jest.beforeEach function call this one to set up the temp directory.
    * @memberOf module:testHelpers
    * @returns {Promise<*|void>}
    */
-    beforeEach,
+  beforeEach,
   /**
    * In the Jest.afterEach function call this one to clean up and remove the temp directory.
    * @memberOf module:testHelpers
    * @returns {Promise<*>}
    */
-    afterEach,
+  afterEach,
   /**
    * Return number of occurrences of substring in another string.
    * @memberOf module:testHelpers
    * @returns {int}
    */
-    countMatches,
+  countMatches,
   /**
    * Returns true if the given file or directory exists, otherwise false.
    * @memberOf module:testHelpers
    * @returns {boolean}
    */
-    fileExists,
+  fileExists,
   /**
    * Console log objects in a readable format, returns the given object.
    * @memberOf module:testHelpers
    * @returns {*}
    */
-    logObject,
+  logObject,
   /**
    * Delete a directory and subcontents.
    * @memberOf module:testHelpers
    * @returns {Promise<*>}
    */
-    removeDirectory,
+  removeDirectory,
 } from 'test-filesystem'

package/functions/testFull.test.mjs

@@ -5,7 +5,7 @@ import { testFull } from './testFull.mjs'
 const gulpConfig = testHelpers.gulpConfig
 
 jest.mock('jest', () => ({
-  'runCLI': jest.fn(() => Promise.resolve(true))
+  runCLI: jest.fn(() => Promise.resolve(true))
 }))
 
 describe('testFull', () => {

package/functions/testQuick.test.mjs

@@ -5,7 +5,7 @@ import { testQuick } from './testQuick.mjs'
 const gulpConfig = testHelpers.gulpConfig
 
 jest.mock('jest', () => ({
-  'runCLI': jest.fn(() => Promise.resolve(true))
+  runCLI: jest.fn(() => Promise.resolve(true))
 }))
 
 describe('testQuick', () => {

package/functions/utilities/convertMjsFilesForDocs.test.mjs

@@ -1,3 +1,4 @@
+/* eslint-disable no-template-curly-in-string -- fixture source code, the ${...} is meant to stay literal */
 import fs from 'fs'
 import * as setUp from '../test-helpers/setUp.mjs'
 import { convertMjsFilesForDocs } from './convertMjsFilesForDocs.mjs'

package/functions/utilities/dotGet.mjs

@@ -11,7 +11,7 @@ import { strBefore } from './strBefore.mjs'
  * @returns {*} The value of the property
  * @private
  */
-export const dotGet = (arrayObject = {}, dotNotation= '', defaultValue = null) => {
+export const dotGet = (arrayObject = {}, dotNotation = '', defaultValue = null) => {
   if (!dotNotation) {
     return arrayObject
   }
@@ -22,7 +22,7 @@ export const dotGet = (arrayObject = {}, dotNotation= '', defaultValue = null) =
   }
   if (key === '*') {
     const result = []
-    for (let wildKey in arrayObject) {
+    for (const wildKey in arrayObject) {
       const wildValue = arrayObject[wildKey]
       if (lastKey) {
         result[wildKey] = wildValue

package/functions/utilities/dotNotate.mjs

@@ -15,7 +15,7 @@ const handleRetainObjects = (retainObjects = []) => {
      */
     return (currentKey, value, results) => false
   }
-  retainObjects = retainObjects.map(key => key.replace('\.', '\\.'))
+  retainObjects = retainObjects.map(key => key.replaceAll('.', '\\.'))
   const retainRegex = new RegExp(`(${retainObjects.join('|')})$`)
   /**
    * Test if a key should be retained as an object.
@@ -44,7 +44,7 @@ const handleRetainObjects = (retainObjects = []) => {
  * @private
  */
 const performDotNotate = (arrayObject, didRetain, prepend = '', results = {}) => {
-  for (let key in arrayObject) {
+  for (const key in arrayObject) {
     const value = arrayObject[key]
     const currentKey = `${prepend}${key}`
     if (didRetain(currentKey, value, results)) {

package/functions/utilities/dotNotate.test.mjs

@@ -31,4 +31,11 @@ describe('dotNotate', () => {
       options: { fix: true }
     })
   })
+
+  test('treats every dot in a retained key literally, not as a regex wildcard', () => {
+    expect(dotNotate({ a: { bXc: { d: 1 }, b: { c: { d: 2 } } } }, ['a.b.c'])).toEqual({
+      'a.bXc.d': 1,
+      'a.b.c': { d: 2 }
+    })
+  })
 })

package/functions/utilities/dotSet.mjs

@@ -18,7 +18,7 @@ export const dotSet = (arrayObject, dotNotation, value = null) => {
     key = dotNotation
   }
   if (key === '*') {
-    for (let wildKey in arrayObject) {
+    for (const wildKey in arrayObject) {
       if (lastKey) {
         arrayObject[wildKey] = value
         continue

package/gulpfile.base.mjs

@@ -16,6 +16,7 @@ export { distMinify } from './functions/distMinify.mjs'
 export * as gulpConfig from './gulp.config.mjs'
 export { images } from './functions/images.mjs'
 export { jsdocDocs } from './functions/jsdocDocs.mjs'
+export { lint } from './functions/lint.mjs'
 export * as partials from './functions/partials.mjs'
 export { sass } from './functions/sass.mjs'
 export { sourceLint } from './functions/sourceLint.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-build-tools",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "description": "Standardised build process with gulp.",
   "main": "gulpfile.base.js",
   "exports": {
@@ -21,6 +21,7 @@
     "build": "gulp build",
     "dev": "gulp",
     "docs": "gulp docs",
+    "lint": "gulp lint",
     "readme": "gulp readme",
     "release": "release-it",
     "release:dry-run": "release-it --dry-run",
@@ -124,12 +125,21 @@
     "clean-jsdoc-theme": "^4.3.3",
     "gulp-imagemin": "github:jheagle/gulp-imagemin#common-js-compatibility",
     "jsdoc": "^4.0.5",
-    "playwright": "~1.62.1",
+    "playwright": "^1.64.1",
     "release-it": "^21.1.1",
     "typedoc": "^0.28.20",
     "typescript": "^6.0.3"
   },
   "engines": {
     "node": ">=22.12.0"
+  },
+  "allowScripts": {
+    "gifsicle@5.3.0": true,
+    "mozjpeg@8.0.0": true,
+    "optipng-bin@7.0.1": true,
+    "core-js": false,
+    "core-js-pure": false,
+    "@parcel/watcher": false,
+    "unrs-resolver": false
   }
 }