js-build-tools 6.0.0 → 6.1.0

package/functions/partials/neostandardLint.mjs

@@ -6,7 +6,7 @@ import { importModule } from './loadPeer.mjs'
 
 // neostandard (js-build-tools' chosen style - a maintained, TypeScript-aware successor to `standard`, see
 // https://github.com/neostandard/neostandard) ships ESM-only, see importModule for how it is imported.
-const importNeostandard = () => importModule('neostandard').then(({ neostandard }) => neostandard)
+const importNeostandard = () => importModule('neostandard')
 
 /**
  * Read the `env` a project already declared for Standard (the `standard` field in its package.json), so a project
@@ -23,20 +23,30 @@ const readEnv = cwd => {
 }
 
 /**
- * Build an ESLint instance configured with neostandard, honoring the project's own package.json `standard.env`.
+ * Build an ESLint instance configured with neostandard, honoring the project's own package.json `standard.env`,
+ * plus an optional layer of rule overrides (see gulp.config.mjs's `lint.rules`) for a rule that is wrong for this
+ * project specifically rather than something to fix in its code - for example a test fixture whose content
+ * neostandard mistakes for a real syntax problem. Scoped to the same files neostandard itself lints (its own
+ * `defaultFilePatterns.all`), per neostandard's own guidance: an unscoped rule-tweak layer would otherwise apply
+ * to every lintable file, including ones from an unrelated plugin this project never defined.
  * @param {Object} options
  * @param {string} options.cwd
  * @param {boolean} options.ts
  * @param {boolean} options.fix
+ * @param {Object<string, *>} [options.rules={}]
  * @returns {Promise<import('eslint').ESLint>}
  */
-const buildEslint = async ({ cwd, ts, fix }) => {
-  const neostandard = await importNeostandard()
+const buildEslint = async ({ cwd, ts, fix, rules = {} }) => {
+  const { neostandard, defaultFilePatterns } = await importNeostandard()
+  const baseConfig = neostandard({ ts, env: readEnv(cwd) })
+  if (Object.keys(rules).length) {
+    baseConfig.push({ files: defaultFilePatterns.all, rules })
+  }
   return new ESLint({
     cwd,
     fix,
     overrideConfigFile: true,
-    baseConfig: neostandard({ ts, env: readEnv(cwd) })
+    baseConfig
   })
 }
 
@@ -67,13 +77,15 @@ const printFileReport = (file, result) => {
  * @param {Object} [options={}]
  * @param {boolean} [options.fix=true] - Apply neostandard's automatic fixes to the file contents.
  * @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 {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 {import('stream').Transform}
  */
 export const neostandardLint = (
-  { fix = true, ts = false } = {},
+  { fix = true, ts = false, rules = {} } = {},
   loadEslint = buildEslint
 ) => {
   const totals = { errors: 0, warnings: 0 }
@@ -89,7 +101,7 @@ export const neostandardLint = (
         return
       }
       if (!eslintPromise) {
-        eslintPromise = loadEslint({ cwd: file.cwd, ts, fix })
+        eslintPromise = loadEslint({ cwd: file.cwd, ts, fix, rules })
       }
       eslintPromise
         .then(eslint => eslint.lintText(file.contents.toString(), { filePath: file.path }))

package/functions/partials/neostandardLint.test.mjs

@@ -61,7 +61,15 @@ describe('neostandardLint', () => {
     expect.assertions(1)
     const loadEslint = jest.fn(() => Promise.resolve(fakeEslint(() => [{ messages: [], errorCount: 0, warningCount: 0 }])))
     await run(neostandardLint({ fix: false, ts: true }, loadEslint), [makeFile(Buffer.from('x'))])
-    expect(loadEslint).toHaveBeenCalledWith({ cwd: '/project', ts: true, fix: false })
+    expect(loadEslint).toHaveBeenCalledWith({ cwd: '/project', ts: true, fix: false, rules: {} })
+  })
+
+  test('passes rule overrides through to the loader', async () => {
+    expect.assertions(1)
+    const loadEslint = jest.fn(() => Promise.resolve(fakeEslint(() => [{ messages: [], errorCount: 0, warningCount: 0 }])))
+    const rules = { 'no-template-curly-in-string': 'off' }
+    await run(neostandardLint({ rules }, loadEslint), [makeFile(Buffer.from('x'))])
+    expect(loadEslint).toHaveBeenCalledWith({ cwd: '/project', ts: false, fix: true, rules })
   })
 
   test('passes a file through untouched when the project ignores it (ESLint returns no results)', async () => {

package/functions/sourceLint.mjs

@@ -19,6 +19,6 @@ export const sourceLint = () => {
     patterns.push(`${srcPath}/**/*.ts`)
   }
   return src(patterns)
-    .pipe(neostandardLint({ fix: true, ts }))
+    .pipe(neostandardLint({ fix: true, ts, rules: gulpConfig.get('lint.rules') }))
     .pipe(dest(srcPath))
 }

package/functions/sourceLint.test.mjs

@@ -51,6 +51,30 @@ describe('sourceLint', () => {
       })
   }, 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
+    // non-template string) - neostandard's no-template-curly-in-string rule flags this as an error by default.
+    const fixtureContents = 'const fixture = \'import(`imagemin-${pluginName}`)\'\n\nmodule.exports = fixture\n'
+    fs.writeFileSync(`${srcPath}/fixture.js`, fixtureContents)
+    gulpConfig.set('lint.rules', { 'no-template-curly-in-string': 'off' })
+    const logSpy = jest.spyOn(console, 'log').mockImplementation(() => {})
+    expect.assertions(1)
+    sourceLint()
+      .on('finish', () => {
+        gulpConfig.set('lint.rules', {})
+        expect(logSpy.mock.calls.flat().join('\n')).not.toMatch(/no-template-curly-in-string|template string expression/)
+        logSpy.mockRestore()
+        done()
+      })
+      .on('error', error => {
+        gulpConfig.set('lint.rules', {})
+        logSpy.mockRestore()
+        console.error('Encountered error', error)
+        done(error)
+      })
+  }, 20000)
+
   test('also lints .ts source when typescript.enabled', done => {
     const srcPath = gulpConfig.get('srcPath')
     gulpConfig.set('typescript.enabled', true)

package/functions/test-helpers/neostandardLintWithRealNeostandard.mjs

@@ -6,9 +6,11 @@ import path from 'node:path'
 // genuine neostandard behavior run the actual package in a plain Node subprocess instead of faking it.
 const script = 'import { readFileSync } from \'node:fs\'\n' +
   'import { ESLint } from \'eslint\'\n' +
-  'import { neostandard } from \'neostandard\'\n' +
-  'const { text, filePath, cwd, fix, ts, env } = JSON.parse(readFileSync(0, \'utf8\'))\n' +
-  'const eslint = new ESLint({ cwd, fix, overrideConfigFile: true, baseConfig: neostandard({ ts, env }) })\n' +
+  'import { neostandard, defaultFilePatterns } from \'neostandard\'\n' +
+  'const { text, filePath, cwd, fix, ts, env, rules } = JSON.parse(readFileSync(0, \'utf8\'))\n' +
+  'const baseConfig = neostandard({ ts, env })\n' +
+  'if (Object.keys(rules).length) { baseConfig.push({ files: defaultFilePatterns.all, rules }) }\n' +
+  'const eslint = new ESLint({ cwd, fix, overrideConfigFile: true, baseConfig })\n' +
   'process.stdout.write(JSON.stringify(await eslint.lintText(text, { filePath })))\n'
 
 const readEnv = cwd => {
@@ -19,12 +21,12 @@ const readEnv = cwd => {
   }
 }
 
-export const loadEslintViaSubprocess = ({ cwd, ts, fix }) => Promise.resolve({
+export const loadEslintViaSubprocess = ({ cwd, ts, fix, rules = {} }) => Promise.resolve({
   lintText: (text, { filePath }) => Promise.resolve().then(() => JSON.parse(execFileSync(
     process.execPath,
     ['--input-type=module', '--eval', script],
     {
-      input: JSON.stringify({ text, filePath, cwd, fix, ts, env: readEnv(cwd) }),
+      input: JSON.stringify({ text, filePath, cwd, fix, ts, env: readEnv(cwd), rules }),
       encoding: 'utf8',
       cwd,
       maxBuffer: 256 * 1024 * 1024

package/functions/utilities/dotNotate.mjs

@@ -46,7 +46,9 @@ const performDotNotate = (arrayObject, didRetain, prepend = '', results = {}) =>
     if (didRetain(currentKey, value, results)) {
       continue
     }
-    if (isObject(value)) {
+    // An empty object/array has no keys to flatten into - recursing into one would silently drop currentKey
+    // from the result entirely, rather than keeping it as the empty value it actually is. Treat it as a leaf.
+    if (isObject(value) && Object.keys(value).length) {
       performDotNotate(value, didRetain, `${currentKey}.`, results)
       continue
     }

package/functions/utilities/dotNotate.test.mjs

@@ -0,0 +1,34 @@
+import { dotNotate } from './dotNotate.mjs'
+
+describe('dotNotate', () => {
+  test('flattens a nested object into dot-notation leaves', () => {
+    expect(dotNotate({ a: { b: 'c', d: { e: 'f' } } })).toEqual({ 'a.b': 'c', 'a.d.e': 'f' })
+  })
+
+  test('flattens a non-empty array into index-numbered leaves, same as a plain object', () => {
+    expect(dotNotate({ a: ['x', 'y'] })).toEqual({ 'a.0': 'x', 'a.1': 'y' })
+  })
+
+  test('keeps a primitive value (including null) as its own leaf, unflattened', () => {
+    expect(dotNotate({ a: 1, b: 'two', c: null })).toEqual({ a: 1, b: 'two', c: null })
+  })
+
+  test('keeps an empty object as a leaf value, rather than silently dropping its key', () => {
+    expect(dotNotate({ a: {}, b: 'c' })).toEqual({ a: {}, b: 'c' })
+  })
+
+  test('keeps an empty array as a leaf value, rather than silently dropping its key', () => {
+    expect(dotNotate({ a: [], b: 'c' })).toEqual({ a: [], b: 'c' })
+  })
+
+  test('keeps an empty object/array as a leaf even nested inside other objects', () => {
+    expect(dotNotate({ a: { b: [], c: {} } })).toEqual({ 'a.b': [], 'a.c': {} })
+  })
+
+  test('retains a matching key as a whole object instead of flattening into it', () => {
+    expect(dotNotate({ a: { b: 'c' }, options: { fix: true } }, ['options'])).toEqual({
+      'a.b': 'c',
+      options: { fix: true }
+    })
+  })
+})

package/functions/utilities/getBundleConfigs.mjs

@@ -16,7 +16,7 @@ export const getBundleConfigs = () => {
     ignore: gulpConfig.get('browser.ignore'),
     exclude: gulpConfig.get('browser.exclude')
   }
-  const additional = gulpConfig.get('browser.bundles') || []
+  const additional = gulpConfig.get('browser.bundles')
   return [
     primary,
     ...additional.map((bundleConfig) => ({

package/gulp.config.mjs

@@ -96,6 +96,16 @@ import { fileExists } from 'test-filesystem'
  * @property {StringSetting} from - Path to search for images.
  * @property {StringSetting} to - Path to output images.
  */
+/**
+ * Configurations for linting (see {@link module:partials.neostandardLint}).
+ * @typedef {Object<string, Setting>} module:gulpConfig~LintConfig
+ * @property {Object<string, *>} rules - ESLint rule overrides layered on top of neostandard's own config, scoped
+ * to the same files neostandard itself lints. For a rule that is wrong for your project specifically (for example
+ * a test fixture that deliberately contains text neostandard mistakes for a real syntax problem), rather than
+ * something to fix in your code. Empty by default: a project that never sets this gets exactly neostandard's own
+ * rules, unchanged. Keyed and valued exactly as ESLint's own `rules` object - see
+ * https://eslint.org/docs/latest/use/configure/rules.
+ */
 /**
  * Configurations to compile and generate the Readme file.
  * @typedef {Object<string, Setting>} module:gulpConfig~ReadmeConfig
@@ -153,6 +163,7 @@ import { fileExists } from 'test-filesystem'
  * @property {DocsConfig} docs - Generate the documentation of a TypeScript project configuration group.
  * @property {FontConfig} fonts - Fonts copy configuration group.
  * @property {ImageConfig} images - Minify and copy the images configuration.
+ * @property {LintConfig} lint - Linting configuration group.
  * @property {ReadmeConfig} readme - Build readme files configuration.
  * @property {StringSetting} rootPath - Base directory of the project.
  * @property {SassConfig} sass - Compile CSS from SASS configuration.
@@ -200,6 +211,9 @@ const setDefaults = {
     from: 'src/img/**/*.+(png|jpg|jpeg|gif|svg)',
     to: 'browser/img',
   },
+  lint: {
+    rules: {},
+  },
   readme: {
     file: 'README.md',
     from: 'src/**/!(*.test).js',

package/package.json

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