js-build-tools 4.1.1 → 5.0.0

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.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-build-tools",
-  "version": "4.1.1",
+  "version": "5.0.0",
   "description": "Standardised build process with gulp.",
   "main": "gulpfile.base.js",
   "exports": {
@@ -51,29 +51,39 @@
     "@babel/preset-env": "^7.29.7",
     "@babel/preset-typescript": "^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": "^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",
+    "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": {
+    "gulp-imagemin": "github:jheagle/gulp-imagemin#common-js-compatibility",
     "typescript": "^6.0.3"
   }
 }