js-build-tools 4.1.0 → 5.0.0

package/functions/partials/removeDirectory.test.mjs

@@ -1,6 +1,26 @@
 import fs from 'fs'
+import { rm } from 'node:fs/promises'
 import { removeDirectory } from './removeDirectory.mjs'
 
+// Wrap rm so tests can simulate something recreating the directory while (or right after) it is deleted.
+jest.mock('node:fs/promises', () => {
+  const actual = jest.requireActual('node:fs/promises')
+  return { ...actual, rm: jest.fn(actual.rm) }
+})
+const { rm: realRm } = jest.requireActual('node:fs/promises')
+
+const dirPath = 'remove-directory'
+const recreateAfterRemoving = async (target, options) => {
+  await realRm(target, options)
+  fs.mkdirSync(target)
+}
+
+afterEach(() => {
+  rm.mockReset()
+  rm.mockImplementation(realRm)
+  fs.rmSync(dirPath, { recursive: true, force: true })
+})
+
 describe('removeDirectory', () => {
   test('able to delete the remove-directory', async () => {
     const dirPath = 'remove-directory'
@@ -25,4 +45,28 @@ describe('removeDirectory', () => {
     expect(fs.existsSync(dirPath)).toBeFalsy()
     expect(await removeDirectory(dirPath)).toBe(dirPath)
   })
+
+  test('removes with force and Node\'s built-in retry-with-back-off for busy or locked directories', async () => {
+    expect.assertions(1)
+    fs.mkdirSync(dirPath)
+    await removeDirectory(dirPath)
+    expect(rm).toHaveBeenCalledWith(dirPath, expect.objectContaining({ recursive: true, force: true, maxRetries: 5 }))
+  })
+
+  test('removes the directory again when something recreates it right after the first removal', async () => {
+    expect.assertions(2)
+    fs.mkdirSync(dirPath)
+    rm.mockImplementationOnce(recreateAfterRemoving)
+    await removeDirectory(dirPath)
+    expect(fs.existsSync(dirPath)).toBeFalsy()
+    expect(rm).toHaveBeenCalledTimes(2)
+  })
+
+  test('fails with a clear error instead of leaving stale output when the directory keeps coming back', async () => {
+    expect.assertions(2)
+    fs.mkdirSync(dirPath)
+    rm.mockImplementation(recreateAfterRemoving)
+    await expect(removeDirectory(dirPath)).rejects.toThrow(/Unable to remove "remove-directory" - it was recreated or is locked/)
+    expect(rm).toHaveBeenCalledTimes(4)
+  })
 })

package/functions/partials/sassFor.mjs

@@ -1,6 +1,8 @@
 import { dest, src } from 'gulp'
 import * as gulpConfig from '../../gulp.config.mjs'
-import cssnano from 'gulp-cssnano'
+import autoprefixer from 'autoprefixer'
+import cssnano from 'cssnano'
+import postcss from 'gulp-postcss'
 import rename from 'gulp-rename'
 import * as sass from 'sass'
 import { default as gulpSass } from 'gulp-sass'
@@ -17,6 +19,7 @@ const runSass = gulpSass(sass)
 export const sassFor = (srcSearch = gulpConfig.get('sass.from'), cssPath = gulpConfig.get('sass.to')) => src(srcSearch)
   .pipe(runSass().on('error', runSass.logError)) // Passes it through a gulp-sass, log errors to console
   .pipe(dest(cssPath))
-  .pipe(cssnano())
+  // add: false - the old gulp-cssnano only ever removed obsolete vendor prefixes, never added any; keep that.
+  .pipe(postcss([autoprefixer({ add: false }), cssnano()]))
   .pipe(rename({ extname: '.min.css' }))
   .pipe(dest(cssPath))

package/functions/partials/sassFor.test.mjs

@@ -27,10 +27,7 @@ const sassContents = 'html\n' +
 
 const sassPath = gulpConfig.get('sass.path')
 
-beforeEach(() => {
-  setUp.beforeEach()
-  return fs.mkdirSync(sassPath, { recursive: true })
-})
+beforeEach(() => setUp.beforeEach().then(() => fs.mkdirSync(sassPath, { recursive: true })))
 
 afterEach(setUp.afterEach)
 
@@ -60,4 +57,25 @@ describe('sassFor', () => {
         done()
       })
   })
+
+  test('also writes a minified .min.css next to the css output', done => {
+    const sassFile = `${sassPath}/sassFor.sass`
+    fs.writeFileSync(sassFile, sassContents)
+    expect.assertions(4)
+    const cssPath = gulpConfig.get('sass.to')
+    sassFor(sassFile)
+      .on('finish', () => {
+        const cssContents = fs.readFileSync(`${cssPath}/sassFor.css`).toString()
+        const minContents = fs.readFileSync(`${cssPath}/sassFor.min.css`).toString()
+        expect(minContents.length).toBeLessThan(cssContents.length)
+        expect(countMatches(minContents.trim(), '\n')).toEqual(0)
+        expect(minContents).toContain('outline:none')
+        expect(minContents).toContain('text-align:center')
+        done()
+      })
+      .on('error', error => {
+        console.error('Encountered error', error)
+        done()
+      })
+  })
 })

package/functions/partials/standardLint.mjs

@@ -0,0 +1,80 @@
+import path from 'node:path'
+import through from 'through2'
+
+// `standard` (17+) ships ESM-only, but this package also publishes a CommonJS build (dist/*.js) whose babel
+// transform would turn even a dynamic import() into a require() that cannot load an ES module. Hiding the import()
+// inside a Function constructor keeps it a genuine dynamic import that works from either build (same escape hatch
+// as tsFor.mjs uses for gulp-ts-compile).
+const importStandard = new Function('return import(\'standard\')')
+
+/**
+ * Print a file's lint messages, if it has any.
+ * @memberOf module:partials
+ * @param {import('vinyl')} file
+ * @param {{messages: Array<{line: number, column: number, message: string}>, errorCount: number, warningCount: number}} result
+ * @returns {undefined}
+ */
+const printFileReport = (file, result) => {
+  if (!result.messages.length) {
+    return
+  }
+  console.log(path.relative(file.cwd, file.path))
+  result.messages.forEach(({ line, column, message }) => console.log(`line ${line}:${column}\t${message}`))
+  console.log(`✖ ${result.errorCount} error\t⚠ ${result.warningCount} warning\n`)
+}
+
+/**
+ * Lint every file streaming through with JavaScript Standard Style 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.
+ *
+ * Project-level Standard configuration (the `standard` field in package.json: ignore, env, globals, ...) is honored
+ * because the file's own path and cwd are handed to Standard.
+ * @memberOf module:partials
+ * @param {Object} [options={}]
+ * @param {boolean} [options.fix=true] - Apply Standard's automatic fixes to the file contents.
+ * @param {function(): Promise<{lintText: Function}>} [loadStandard] - Resolves the `standard` module. 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 an ES module.
+ * @returns {import('stream').Transform}
+ */
+export const standardLint = (
+  { fix = true } = {},
+  loadStandard = () => importStandard().then(({ default: standard }) => standard)
+) => {
+  const totals = { errors: 0, warnings: 0 }
+  return through.obj(
+    function (file, enc, callback) {
+      if (file.isNull()) {
+        callback(null, file)
+        return
+      }
+      if (file.isStream()) {
+        callback(new Error('standardLint: streaming file contents are not supported.'))
+        return
+      }
+      loadStandard()
+        .then(standard => standard.lintText(file.contents.toString(), { filename: file.path, cwd: file.cwd, fix }))
+        .then(results => {
+          // No result at all means the file is ignored by the project's Standard configuration.
+          const [result] = results
+          if (result) {
+            if (typeof result.output === 'string') {
+              file.contents = Buffer.from(result.output)
+            }
+            totals.errors += result.errorCount
+            totals.warnings += result.warningCount
+            printFileReport(file, result)
+          }
+          callback(null, file)
+        }, callback)
+    },
+    function (callback) {
+      console.log('Standard linter results')
+      console.log('======================================')
+      console.log(`✖ Errors total: ${totals.errors}`)
+      console.log(`⚠ Warnings total: ${totals.warnings}\n`)
+      callback()
+    }
+  )
+}

package/functions/partials/standardLint.test.mjs

@@ -0,0 +1,99 @@
+import Vinyl from 'vinyl'
+import { Readable } from 'node:stream'
+import { standardLint } from './standardLint.mjs'
+
+const makeFile = (contents, filePath = '/project/dist/example.js') => new Vinyl({
+  cwd: '/project',
+  base: '/project/dist',
+  path: filePath,
+  contents
+})
+
+const run = (transform, files) => new Promise((resolve, reject) => {
+  const out = []
+  transform.on('data', file => out.push(file)).on('end', () => resolve(out)).on('error', reject)
+  files.forEach(file => transform.write(file))
+  transform.end()
+})
+
+const fakeStandard = (resultFor) => ({
+  lintText: jest.fn((text, options) => Promise.resolve(resultFor(text, options)))
+})
+
+let logSpy
+
+beforeEach(() => {
+  logSpy = jest.spyOn(console, 'log').mockImplementation(() => {})
+})
+
+afterEach(() => {
+  logSpy.mockRestore()
+})
+
+describe('standardLint', () => {
+  test('replaces file contents with the fixed output and hands Standard the file path, cwd and fix option', async () => {
+    expect.assertions(3)
+    const standard = fakeStandard((text) => [{ messages: [], errorCount: 0, warningCount: 0, output: text.replace(/"/g, '\'') }])
+    const [linted] = await run(standardLint({ fix: true }, () => Promise.resolve(standard)), [makeFile(Buffer.from('const a = "b"'))])
+    expect(linted.contents.toString()).toEqual('const a = \'b\'')
+    expect(standard.lintText).toHaveBeenCalledWith('const a = "b"', { filename: '/project/dist/example.js', cwd: '/project', fix: true })
+    expect(linted.path).toEqual('/project/dist/example.js')
+  })
+
+  test('leaves the contents alone when Standard has no fixed output (nothing needed fixing)', async () => {
+    expect.assertions(1)
+    const standard = fakeStandard(() => [{ messages: [], errorCount: 0, warningCount: 0 }])
+    const [linted] = await run(standardLint({}, () => Promise.resolve(standard)), [makeFile(Buffer.from('const a = 1'))])
+    expect(linted.contents.toString()).toEqual('const a = 1')
+  })
+
+  test('passes fix: false through so nothing is rewritten', async () => {
+    expect.assertions(1)
+    const standard = fakeStandard(() => [{ messages: [], errorCount: 0, warningCount: 0 }])
+    await run(standardLint({ fix: false }, () => Promise.resolve(standard)), [makeFile(Buffer.from('x'))])
+    expect(standard.lintText.mock.calls[0][1].fix).toBe(false)
+  })
+
+  test('passes a file through untouched when the project ignores it (Standard returns no results)', async () => {
+    expect.assertions(2)
+    const standard = fakeStandard(() => [])
+    const [linted] = await run(standardLint({}, () => Promise.resolve(standard)), [makeFile(Buffer.from('var x=1'))])
+    expect(linted.contents.toString()).toEqual('var x=1')
+    expect(logSpy).toHaveBeenCalledWith('✖ Errors total: 0')
+  })
+
+  test('skips null-content files without linting them', async () => {
+    expect.assertions(2)
+    const standard = fakeStandard(() => [])
+    const [passed] = await run(standardLint({}, () => Promise.resolve(standard)), [makeFile(null)])
+    expect(passed.isNull()).toBeTruthy()
+    expect(standard.lintText).not.toHaveBeenCalled()
+  })
+
+  test('errors on streaming file contents, which cannot be linted', async () => {
+    expect.assertions(1)
+    const streamFile = makeFile(Readable.from(['x']))
+    await expect(run(standardLint({}, () => Promise.resolve(fakeStandard(() => []))), [streamFile])).rejects.toThrow(/streaming/)
+  })
+
+  test('prints per-file problems and a summary of totals across all files, without failing', async () => {
+    expect.assertions(5)
+    const standard = fakeStandard((text, { filename }) => filename.endsWith('a.js')
+      ? [{ messages: [{ line: 2, column: 7, message: 'unused b' }, { line: 3, column: 1, message: 'bad thing' }], errorCount: 2, warningCount: 0 }]
+      : [{ messages: [{ line: 1, column: 1, message: 'just a warning' }], errorCount: 0, warningCount: 1 }])
+    const out = await run(
+      standardLint({}, () => Promise.resolve(standard)),
+      [makeFile(Buffer.from('a'), '/project/dist/a.js'), makeFile(Buffer.from('b'), '/project/dist/b.js')]
+    )
+    expect(out).toHaveLength(2)
+    expect(logSpy).toHaveBeenCalledWith('dist/a.js')
+    expect(logSpy).toHaveBeenCalledWith('line 2:7\tunused b')
+    expect(logSpy).toHaveBeenCalledWith('✖ Errors total: 2')
+    expect(logSpy).toHaveBeenCalledWith('⚠ Warnings total: 1\n')
+  })
+
+  test('surfaces a failure to load or run Standard as a stream error', async () => {
+    expect.assertions(1)
+    await expect(run(standardLint({}, () => Promise.reject(new Error('cannot load'))), [makeFile(Buffer.from('x'))])).rejects.toThrow('cannot load')
+  })
+})

package/functions/partials/tsFor.mjs

@@ -61,7 +61,14 @@ export const tsFor = (
     return () => {}
   }
   const configPath = gulpConfig.get('typescript.config')
-  const compilerOptions = configPath ? readCompilerOptions(configPath) : { declaration: true }
+  // When no tsconfig.json is configured, target/module are pinned explicitly rather than left for TypeScript's
+  // own compiler defaults - those defaults have already shifted once across a TypeScript version bump in this
+  // project's own history (silently changing whether output keeps `const`/`let` or downlevels to `var`), and
+  // pinning them keeps this task's output stable across future TypeScript upgrades too. ES5/CommonJS matches
+  // what the downstream babel/browserify bundling pipeline has always assumed it receives.
+  const compilerOptions = configPath
+    ? readCompilerOptions(configPath)
+    : { declaration: true, target: ts.ScriptTarget.ES5, module: ts.ModuleKind.CommonJS, esModuleInterop: false }
   // Accepts gulp's own callback-style task convention (an optional `done`, called once finished) rather than
   // just returning a Promise, since callers may invoke the returned function directly with a callback instead
   // of relying on gulp's own runner to observe a returned Promise.

package/functions/partials.mjs

@@ -20,4 +20,5 @@ export { readmeTemplate } from './partials/readmeTemplate.mjs'
 export { removeDirectory } from './partials/removeDirectory.mjs'
 export { runOnChange } from './partials/runOnChange.mjs'
 export { sassFor } from './partials/sassFor.mjs'
+export { standardLint } from './partials/standardLint.mjs'
 export { tsFor } from './partials/tsFor.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(14)
+    expect(Object.keys(partials).length).toBe(15)
   })
 })

package/functions/test-helpers/standardLintWithRealStandard.mjs

@@ -0,0 +1,21 @@
+import { execFileSync } from 'node:child_process'
+
+// Jest's CommonJS transform cannot load `standard` (ESM-only) or run a real dynamic import(), so tests that need
+// genuine Standard behavior run the actual `standard` package in a plain Node subprocess instead of faking it.
+const script = 'import { readFileSync } from \'node:fs\'\n' +
+  'import standard from \'standard\'\n' +
+  'const { text, options } = JSON.parse(readFileSync(0, \'utf8\'))\n' +
+  'process.stdout.write(JSON.stringify(await standard.lintText(text, options)))\n'
+
+export const loadStandardViaSubprocess = () => Promise.resolve({
+  lintText: (text, options) => Promise.resolve().then(() => JSON.parse(execFileSync(
+    process.execPath,
+    ['--input-type=module', '--eval', script],
+    { input: JSON.stringify({ text, options }), encoding: 'utf8', cwd: process.cwd(), maxBuffer: 256 * 1024 * 1024 }
+  )))
+})
+
+const actual = jest.requireActual('../partials/standardLint.mjs')
+
+// Drop-in replacement for the partial module (see jest.mock in the lint/build tests): same API, real Standard.
+export const standardLint = (options) => actual.standardLint(options, loadStandardViaSubprocess)

package/functions/testFull.mjs

@@ -1,5 +1,5 @@
 import * as gulpConfig from '../gulp.config.mjs'
-import { default as jest } from 'jest'
+import { runCLI } from 'jest'
 
 /**
  * Run all tests with jest.
@@ -13,5 +13,5 @@ export const testFull = () => {
     // The testPath must be an array of strings
     testPath = [testPath]
   }
-  return jest.runCLI(gulpConfig.get('test.options'), testPath)
+  return runCLI(gulpConfig.get('test.options'), testPath)
 }

package/functions/testFull.test.mjs

@@ -1,5 +1,5 @@
 import { testHelpers } from './testHelpers.mjs'
-import { default as jestImport } from 'jest'
+import { runCLI } from 'jest'
 import { testFull } from './testFull.mjs'
 
 const gulpConfig = testHelpers.gulpConfig
@@ -12,6 +12,6 @@ describe('testFull', () => {
   test('runs the Jest CLI with the configured options', () => {
     expect.assertions(1)
     testFull()
-    expect(jestImport.runCLI).toHaveBeenCalledWith(gulpConfig.get('test.options'), [gulpConfig.get('test.path')])
+    expect(runCLI).toHaveBeenCalledWith(gulpConfig.get('test.options'), [gulpConfig.get('test.path')])
   })
 })

package/functions/testQuick.mjs

@@ -1,5 +1,5 @@
 import * as gulpConfig from '../gulp.config.mjs'
-import { default as jest } from 'jest'
+import { runCLI } from 'jest'
 
 /**
  * Run the Jest tests for files which have been modified (based on git status).
@@ -13,5 +13,5 @@ export const testQuick = () => {
     // The testPath must be an array of strings
     testPath = [testPath]
   }
-  return jest.runCLI({ onlyChanged: true }, testPath)
+  return runCLI({ onlyChanged: true }, testPath)
 }

package/functions/testQuick.test.mjs

@@ -1,5 +1,5 @@
 import { testHelpers } from './testHelpers.mjs'
-import { default as jestImport } from 'jest'
+import { runCLI } from 'jest'
 import { testQuick } from './testQuick.mjs'
 
 const gulpConfig = testHelpers.gulpConfig
@@ -12,6 +12,6 @@ describe('testQuick', () => {
   test('runs the jest CLI with onlyChanged option', () => {
     expect.assertions(1)
     testQuick()
-    expect(jestImport.runCLI).toHaveBeenCalledWith({ onlyChanged: true }, [gulpConfig.get('test.path')])
+    expect(runCLI).toHaveBeenCalledWith({ onlyChanged: true }, [gulpConfig.get('test.path')])
   })
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-build-tools",
-  "version": "4.1.0",
+  "version": "5.0.0",
   "description": "Standardised build process with gulp.",
   "main": "gulpfile.base.js",
   "exports": {
@@ -50,30 +50,40 @@
     "@babel/plugin-transform-modules-commonjs": "^7.29.7",
     "@babel/preset-env": "^7.29.7",
     "@babel/preset-typescript": "^7.29.7",
-    "@babel/runtime-corejs3": "^7.29.7",
+    "@babel/runtime-corejs3": "^8.0.6",
+    "autoprefixer": "^10.6.1",
     "babel-jest": "^30.4.1",
     "browserify": "^17.0.1",
     "core-js": "^3.49.0",
+    "cssnano": "^6.1.2",
     "glob": "^13.0.6",
     "gulp": "^5.0.1",
     "gulp-babel": "^8.1.0",
     "gulp-cache": "^1.1.3",
-    "gulp-cssnano": "^2.1.3",
-    "gulp-imagemin": "github:jheagle/gulp-imagemin#common-js-compatibility",
+    "gulp-postcss": "^10.0.0",
     "gulp-rename": "^2.1.0",
     "gulp-sass": "^6.0.1",
-    "gulp-standard": "^14.0.0",
     "gulp-ts-compile": "^1.0.0",
     "gulp-uglify-es": "^3.0.0",
-    "jest": "^29.7.0",
+    "jest": "^30.5.2",
     "jest-environment-jsdom": "^30.4.1",
     "jsdoc-to-markdown": "^9.1.3",
+    "postcss": "^8.5.28",
     "regenerator-runtime": "^0.14.1",
     "sass": "^1.101.0",
-    "test-filesystem": "^1.4.0",
+    "standard": "^17.1.2",
+    "test-filesystem": "^1.5.0",
     "through2": "^4.0.2",
     "vinyl-source-stream": "^2.0.0"
   },
+  "peerDependencies": {
+    "gulp-imagemin": ">=9.0.0"
+  },
+  "peerDependenciesMeta": {
+    "gulp-imagemin": {
+      "optional": true
+    }
+  },
   "files": [
     "babel.config.js",
     "dist",
@@ -86,6 +96,7 @@
   ],
   "funding": "https://www.paypal.com/donate/?business=LRYR6SZRWKXVY&no_recurring=0&item_name=Let%27s+build+together+today+to+simplify+our+jobs+tomorrow.&currency_code=CAD",
   "devDependencies": {
-    "typescript": "5.9.2"
+    "gulp-imagemin": "github:jheagle/gulp-imagemin#common-js-compatibility",
+    "typescript": "^6.0.3"
   }
 }