js-build-tools 6.5.0 → 6.7.0

package/functions/test-helpers/setUp.mjs

@@ -1,100 +1,100 @@
-// Import the configurations and override some of them to direct to the temp directory.
-import * as gulpConfig from '../../gulp.config.mjs'
-import { setUp } from 'test-filesystem'
-
-let tempDir = 'test-temp/'
-let srcPath = `${tempDir}src`
-
-/**
- * Update the gulp configurations with the test data. Set the test directory where temp files will be created for testing.
- * @memberOf module:testHelpers
- * @param {string} testDir
- */
-export const setDefaults = (testDir = 'test-temp') => {
-  tempDir = `${testDir}/`
-  srcPath = `${tempDir}src`
-  setUp.setDefaults(tempDir)
-  const distPath = `${tempDir}dist`
-  const browserPath = `${tempDir}browser`
-  const sassPath = `${tempDir}sass`
-  gulpConfig.set('browser.from', `${distPath}/**/*.js`)
-  gulpConfig.set('browser.to', browserPath)
-  gulpConfig.set('cleanPaths', [distPath, browserPath])
-  gulpConfig.set('dist.from', `${srcPath}/**/!(*.test).js`)
-  gulpConfig.set('dist.main', `${distPath}/main`)
-  gulpConfig.set('dist.to', distPath)
-  // Reset explicitly, for the same reason as readme.fromEsm below: this project's own build-tools.config.json turns
-  // docs on and points them at the website checkout, which would leak into every test that never sets these itself.
-  gulpConfig.set('docs.enabled', false)
-  gulpConfig.set('docs.from', srcPath)
-  gulpConfig.set('docs.to', `${tempDir}docs`)
-  gulpConfig.set('docs.title', '')
-  gulpConfig.set('fonts.from', `${srcPath}/fonts/**/*`)
-  gulpConfig.set('fonts.to', `${browserPath}/fonts`)
-  gulpConfig.set('images.from', `${srcPath}/img/**/*.+(png|jpg|jpeg|gif|svg)`)
-  gulpConfig.set('images.to', `${browserPath}/img`)
-  gulpConfig.set('readme.template', `${tempDir}MAIN.md`)
-  gulpConfig.set('readme.to', tempDir)
-  gulpConfig.set('readme.from', `${srcPath}/**/!(*.test).js`)
-  // Reset explicitly: gulpConfig is a process-wide singleton seeded once from this real project's own
-  // build-tools.config.json, so without this, this project's own real readme.fromEsm value (gulp.config.mjs)
-  // would leak into every test that exercises addToReadme/compileReadme but never sets this path itself -
-  // doing real file I/O and a real jsdoc-to-markdown parse of this project's own, much larger, config file.
-  gulpConfig.set('readme.fromEsm', [])
-  gulpConfig.set('rootPath', tempDir)
-  gulpConfig.set('sass.from', `${sassPath}/**/*.+(scss|sass)`)
-  gulpConfig.set('sass.path', sassPath)
-  gulpConfig.set('sass.to', `${browserPath}/css`)
-  gulpConfig.set('srcPath', srcPath)
-  gulpConfig.set('typescript.from', `${srcPath}/**/*.ts`)
-  gulpConfig.set('typescript.to', distPath)
-  gulpConfig.set('test.watch', `${srcPath}/**/*.js`)
-}
-
-export { gulpConfig }
-
-export {
-  /**
-   * Ensure that the del has completed, recursively attempt to delete and recreate
-   * @memberOf module:testHelpers
-   * @param {boolean} [exists=true]
-   * @returns {Promise<*|void>}
-   */
-  createTempDir,
-  /**
-   * In the Jest.beforeEach function call this one to set up the temp directory.
-   * @memberOf module:testHelpers
-   * @returns {Promise<*|void>}
-   */
-  beforeEach,
-  /**
-   * In the Jest.afterEach function call this one to clean up and remove the temp directory.
-   * @memberOf module:testHelpers
-   * @returns {Promise<*>}
-   */
-  afterEach,
-  /**
-   * Return number of occurrences of substring in another string.
-   * @memberOf module:testHelpers
-   * @returns {int}
-   */
-  countMatches,
-  /**
-   * Returns true if the given file or directory exists, otherwise false.
-   * @memberOf module:testHelpers
-   * @returns {boolean}
-   */
-  fileExists,
-  /**
-   * Console log objects in a readable format, returns the given object.
-   * @memberOf module:testHelpers
-   * @returns {*}
-   */
-  logObject,
-  /**
-   * Delete a directory and subcontents.
-   * @memberOf module:testHelpers
-   * @returns {Promise<*>}
-   */
-  removeDirectory,
-} from 'test-filesystem'
+// Import the configurations and override some of them to direct to the temp directory.
+import * as gulpConfig from '../../gulp.config.mjs'
+import { setUp } from 'test-filesystem'
+
+let tempDir = 'test-temp/'
+let srcPath = `${tempDir}src`
+
+/**
+ * Update the gulp configurations with the test data. Set the test directory where temp files will be created for testing.
+ * @memberOf module:testHelpers
+ * @param {string} testDir
+ */
+export const setDefaults = (testDir = 'test-temp') => {
+  tempDir = `${testDir}/`
+  srcPath = `${tempDir}src`
+  setUp.setDefaults(tempDir)
+  const distPath = `${tempDir}dist`
+  const browserPath = `${tempDir}browser`
+  const sassPath = `${tempDir}sass`
+  gulpConfig.set('browser.from', `${distPath}/**/*.js`)
+  gulpConfig.set('browser.to', browserPath)
+  gulpConfig.set('cleanPaths', [distPath, browserPath])
+  gulpConfig.set('dist.from', `${srcPath}/**/!(*.test).js`)
+  gulpConfig.set('dist.main', `${distPath}/main`)
+  gulpConfig.set('dist.to', distPath)
+  // Reset explicitly, for the same reason as readme.fromEsm below: this project's own build-tools.config.json turns
+  // docs on and points them at the website checkout, which would leak into every test that never sets these itself.
+  gulpConfig.set('docs.enabled', false)
+  gulpConfig.set('docs.from', srcPath)
+  gulpConfig.set('docs.to', `${tempDir}docs`)
+  gulpConfig.set('docs.title', '')
+  gulpConfig.set('fonts.from', `${srcPath}/fonts/**/*`)
+  gulpConfig.set('fonts.to', `${browserPath}/fonts`)
+  gulpConfig.set('images.from', `${srcPath}/img/**/*.+(png|jpg|jpeg|gif|svg)`)
+  gulpConfig.set('images.to', `${browserPath}/img`)
+  gulpConfig.set('readme.template', `${tempDir}MAIN.md`)
+  gulpConfig.set('readme.to', tempDir)
+  gulpConfig.set('readme.from', `${srcPath}/**/!(*.test).js`)
+  // Reset explicitly: gulpConfig is a process-wide singleton seeded once from this real project's own
+  // build-tools.config.json, so without this, this project's own real readme.fromEsm value (gulp.config.mjs)
+  // would leak into every test that exercises addToReadme/compileReadme but never sets this path itself -
+  // doing real file I/O and a real jsdoc-to-markdown parse of this project's own, much larger, config file.
+  gulpConfig.set('readme.fromEsm', [])
+  gulpConfig.set('rootPath', tempDir)
+  gulpConfig.set('sass.from', `${sassPath}/**/*.+(scss|sass)`)
+  gulpConfig.set('sass.path', sassPath)
+  gulpConfig.set('sass.to', `${browserPath}/css`)
+  gulpConfig.set('srcPath', srcPath)
+  gulpConfig.set('typescript.from', `${srcPath}/**/*.ts`)
+  gulpConfig.set('typescript.to', distPath)
+  gulpConfig.set('test.watch', `${srcPath}/**/*.js`)
+}
+
+export { gulpConfig }
+
+export {
+  /**
+   * Ensure that the del has completed, recursively attempt to delete and recreate
+   * @memberOf module:testHelpers
+   * @param {boolean} [exists=true]
+   * @returns {Promise<*|void>}
+   */
+  createTempDir,
+  /**
+   * In the Jest.beforeEach function call this one to set up the temp directory.
+   * @memberOf module:testHelpers
+   * @returns {Promise<*|void>}
+   */
+  beforeEach,
+  /**
+   * In the Jest.afterEach function call this one to clean up and remove the temp directory.
+   * @memberOf module:testHelpers
+   * @returns {Promise<*>}
+   */
+  afterEach,
+  /**
+   * Return number of occurrences of substring in another string.
+   * @memberOf module:testHelpers
+   * @returns {int}
+   */
+  countMatches,
+  /**
+   * Returns true if the given file or directory exists, otherwise false.
+   * @memberOf module:testHelpers
+   * @returns {boolean}
+   */
+  fileExists,
+  /**
+   * Console log objects in a readable format, returns the given object.
+   * @memberOf module:testHelpers
+   * @returns {*}
+   */
+  logObject,
+  /**
+   * Delete a directory and subcontents.
+   * @memberOf module:testHelpers
+   * @returns {Promise<*>}
+   */
+  removeDirectory,
+} from 'test-filesystem'

package/functions/test-helpers/setUp.test.mjs

@@ -1,19 +1,19 @@
-import { afterEach, createTempDir, gulpConfig, setDefaults } from './setUp.mjs'
-import fs from 'fs'
-
-setDefaults()
-
-describe('setUp', () => {
-  test('able to create the test-temp/src directory', async () => {
-    const srcPath = gulpConfig.get('srcPath')
-    expect(fs.existsSync(srcPath)).toBeFalsy()
-    await createTempDir()
-    expect(fs.existsSync(srcPath)).toBeTruthy()
-  })
-
-  test('able to delete the test-temp/src directory', async () => {
-    expect(fs.existsSync(gulpConfig.get('srcPath'))).toBeTruthy()
-    await afterEach()
-    expect(fs.existsSync(gulpConfig.get('srcPath'))).toBeFalsy()
-  })
-})
+import { afterEach, createTempDir, gulpConfig, setDefaults } from './setUp.mjs'
+import fs from 'fs'
+
+setDefaults()
+
+describe('setUp', () => {
+  test('able to create the test-temp/src directory', async () => {
+    const srcPath = gulpConfig.get('srcPath')
+    expect(fs.existsSync(srcPath)).toBeFalsy()
+    await createTempDir()
+    expect(fs.existsSync(srcPath)).toBeTruthy()
+  })
+
+  test('able to delete the test-temp/src directory', async () => {
+    expect(fs.existsSync(gulpConfig.get('srcPath'))).toBeTruthy()
+    await afterEach()
+    expect(fs.existsSync(gulpConfig.get('srcPath'))).toBeFalsy()
+  })
+})

package/functions/testFull.mjs

@@ -1,17 +1,17 @@
-import * as gulpConfig from '../gulp.config.mjs'
-import { runCLI } from 'jest'
-
-/**
- * Run all tests with jest.
- * Configure where tests are located by using 'testPath'.
- * @memberOf module:js-build-tools
- * @returns {Promise<*>}
- */
-export const testFull = () => {
-  let testPath = gulpConfig.get('test.path')
-  if (!Array.isArray(testPath)) {
-    // The testPath must be an array of strings
-    testPath = [testPath]
-  }
-  return runCLI(gulpConfig.get('test.options'), testPath)
-}
+import * as gulpConfig from '../gulp.config.mjs'
+import { runCLI } from 'jest'
+
+/**
+ * Run all tests with jest.
+ * Configure where tests are located by using 'testPath'.
+ * @memberOf module:js-build-tools
+ * @returns {Promise<*>}
+ */
+export const testFull = () => {
+  let testPath = gulpConfig.get('test.path')
+  if (!Array.isArray(testPath)) {
+    // The testPath must be an array of strings
+    testPath = [testPath]
+  }
+  return runCLI(gulpConfig.get('test.options'), testPath)
+}

package/functions/testFull.test.mjs

@@ -1,17 +1,17 @@
-import { testHelpers } from './testHelpers.mjs'
-import { runCLI } from 'jest'
-import { testFull } from './testFull.mjs'
-
-const gulpConfig = testHelpers.gulpConfig
-
-jest.mock('jest', () => ({
-  runCLI: jest.fn(() => Promise.resolve(true))
-}))
-
-describe('testFull', () => {
-  test('runs the Jest CLI with the configured options', () => {
-    expect.assertions(1)
-    testFull()
-    expect(runCLI).toHaveBeenCalledWith(gulpConfig.get('test.options'), [gulpConfig.get('test.path')])
-  })
-})
+import { testHelpers } from './testHelpers.mjs'
+import { runCLI } from 'jest'
+import { testFull } from './testFull.mjs'
+
+const gulpConfig = testHelpers.gulpConfig
+
+jest.mock('jest', () => ({
+  runCLI: jest.fn(() => Promise.resolve(true))
+}))
+
+describe('testFull', () => {
+  test('runs the Jest CLI with the configured options', () => {
+    expect.assertions(1)
+    testFull()
+    expect(runCLI).toHaveBeenCalledWith(gulpConfig.get('test.options'), [gulpConfig.get('test.path')])
+  })
+})

package/functions/testHelpers.mjs

@@ -1,10 +1,10 @@
-/**
- * Export the setUp helper.
- * @file
- * @author Joshua Heagle <joshuaheagle@gmail.com>
- * @version 3.0.0
- * @module testHelpers
- * @memberOf module:js-build-tools
- */
-
-export * as testHelpers from './test-helpers/setUp.mjs'
+/**
+ * Export the setUp helper.
+ * @file
+ * @author Joshua Heagle <joshuaheagle@gmail.com>
+ * @version 3.0.0
+ * @module testHelpers
+ * @memberOf module:js-build-tools
+ */
+
+export * as testHelpers from './test-helpers/setUp.mjs'

package/functions/testHelpers.test.mjs

@@ -1,7 +1,7 @@
-import { testHelpers } from './testHelpers.mjs'
-
-describe('testHelpers', () => {
-  test('is object with all helper exports', () => {
-    expect(Object.keys(testHelpers).length).toBe(9)
-  })
-})
+import { testHelpers } from './testHelpers.mjs'
+
+describe('testHelpers', () => {
+  test('is object with all helper exports', () => {
+    expect(Object.keys(testHelpers).length).toBe(9)
+  })
+})

package/functions/testQuick.mjs

@@ -1,17 +1,17 @@
-import * as gulpConfig from '../gulp.config.mjs'
-import { runCLI } from 'jest'
-
-/**
- * Run the Jest tests for files which have been modified (based on git status).
- * Configure where tests are located by using 'testPath'.
- * @memberOf module:js-build-tools
- * @returns {Promise<*>}
- */
-export const testQuick = () => {
-  let testPath = gulpConfig.get('test.path')
-  if (!Array.isArray(testPath)) {
-    // The testPath must be an array of strings
-    testPath = [testPath]
-  }
-  return runCLI({ onlyChanged: true }, testPath)
-}
+import * as gulpConfig from '../gulp.config.mjs'
+import { runCLI } from 'jest'
+
+/**
+ * Run the Jest tests for files which have been modified (based on git status).
+ * Configure where tests are located by using 'testPath'.
+ * @memberOf module:js-build-tools
+ * @returns {Promise<*>}
+ */
+export const testQuick = () => {
+  let testPath = gulpConfig.get('test.path')
+  if (!Array.isArray(testPath)) {
+    // The testPath must be an array of strings
+    testPath = [testPath]
+  }
+  return runCLI({ onlyChanged: true }, testPath)
+}

package/functions/testQuick.test.mjs

@@ -1,17 +1,17 @@
-import { testHelpers } from './testHelpers.mjs'
-import { runCLI } from 'jest'
-import { testQuick } from './testQuick.mjs'
-
-const gulpConfig = testHelpers.gulpConfig
-
-jest.mock('jest', () => ({
-  runCLI: jest.fn(() => Promise.resolve(true))
-}))
-
-describe('testQuick', () => {
-  test('runs the jest CLI with onlyChanged option', () => {
-    expect.assertions(1)
-    testQuick()
-    expect(runCLI).toHaveBeenCalledWith({ onlyChanged: true }, [gulpConfig.get('test.path')])
-  })
-})
+import { testHelpers } from './testHelpers.mjs'
+import { runCLI } from 'jest'
+import { testQuick } from './testQuick.mjs'
+
+const gulpConfig = testHelpers.gulpConfig
+
+jest.mock('jest', () => ({
+  runCLI: jest.fn(() => Promise.resolve(true))
+}))
+
+describe('testQuick', () => {
+  test('runs the jest CLI with onlyChanged option', () => {
+    expect.assertions(1)
+    testQuick()
+    expect(runCLI).toHaveBeenCalledWith({ onlyChanged: true }, [gulpConfig.get('test.path')])
+  })
+})

package/functions/typeDocs.mjs

@@ -1,9 +1,9 @@
-import { typeDocsFor } from './partials/typeDocsFor.mjs'
-
-/**
- * Generate the HTML documentation of a TypeScript project from its source, with the modules mirroring the source
- * folders. Turn it on with docs.enabled, see {@link module:partials.typeDocsFor}.
- * @memberOf module:js-build-tools
- * @returns {Function}
- */
-export const typeDocs = typeDocsFor()
+import { typeDocsFor } from './partials/typeDocsFor.mjs'
+
+/**
+ * Generate the HTML documentation of a TypeScript project from its source, with the modules mirroring the source
+ * folders. Turn it on with docs.enabled, see {@link module:partials.typeDocsFor}.
+ * @memberOf module:js-build-tools
+ * @returns {Function}
+ */
+export const typeDocs = typeDocsFor()

package/functions/typeDocs.test.mjs

@@ -1,11 +1,11 @@
-import { typeDocs } from './typeDocs.mjs'
-import { typeDocsFor } from './partials/typeDocsFor.mjs'
-
-jest.mock('./partials/typeDocsFor.mjs', () => ({ typeDocsFor: jest.fn(() => () => null) }))
-
-describe('typeDocs', () => {
-  test('is the task made by typeDocsFor with no parameters', () => {
-    expect(typeDocsFor).toHaveBeenCalledWith()
-    expect(typeDocs).toBeInstanceOf(Function)
-  })
-})
+import { typeDocs } from './typeDocs.mjs'
+import { typeDocsFor } from './partials/typeDocsFor.mjs'
+
+jest.mock('./partials/typeDocsFor.mjs', () => ({ typeDocsFor: jest.fn(() => () => null) }))
+
+describe('typeDocs', () => {
+  test('is the task made by typeDocsFor with no parameters', () => {
+    expect(typeDocsFor).toHaveBeenCalledWith()
+    expect(typeDocs).toBeInstanceOf(Function)
+  })
+})

package/functions/typeScript.mjs

@@ -1,8 +1,8 @@
-import { tsFor } from './partials/tsFor.mjs'
-
-/**
- * Simplified typescript task using tsFor.
- * @memberOf module:js-build-tools
- * @returns {Function}
- */
-export const typeScript = tsFor()
+import { tsFor } from './partials/tsFor.mjs'
+
+/**
+ * Simplified typescript task using tsFor.
+ * @memberOf module:js-build-tools
+ * @returns {Function}
+ */
+export const typeScript = tsFor()

package/functions/typeScript.test.mjs

@@ -1,11 +1,11 @@
-import { typeScript } from './typeScript.mjs'
-import { tsFor } from './partials/tsFor.mjs'
-
-jest.mock('./partials/tsFor.mjs', () => ({ tsFor: jest.fn(() => () => null) }))
-
-describe('typeScript', () => {
-  test('calls tsFor with no parameters', () => {
-    typeScript()
-    expect(tsFor).toHaveBeenCalled()
-  })
-})
+import { typeScript } from './typeScript.mjs'
+import { tsFor } from './partials/tsFor.mjs'
+
+jest.mock('./partials/tsFor.mjs', () => ({ tsFor: jest.fn(() => () => null) }))
+
+describe('typeScript', () => {
+  test('calls tsFor with no parameters', () => {
+    typeScript()
+    expect(tsFor).toHaveBeenCalled()
+  })
+})

package/functions/utilities/convertMjsFilesForDocs.mjs

@@ -1,34 +1,34 @@
-import fs from 'fs'
-import os from 'os'
-import path from 'path'
-import { esmNamedExportsToCjs } from './esmNamedExportsToCjs.mjs'
-
-/**
- * Writes a rewritten (see {@link esmNamedExportsToCjs}) copy of each given `.mjs` file into a fresh, unique
- * directory under the OS temp directory, with a `.js` extension - jsdoc-to-markdown only recognizes `.js` as a
- * documentable file, regardless of whether its contents are actually CommonJS or ESM (it parses the real ESM
- * syntax of the rest of a file fine; the extension is the only thing it filters on). Writing outside the project
- * tree means there is nothing to gitignore and nothing left behind in the project - call the returned `cleanUp`
- * once done (for example, right after jsdoc-to-markdown has read the files) to remove the temp directory.
- * @memberOf module:utilities
- * @param {Array<string>} mjsFilePaths - Real `.mjs` files to convert. An empty array is a safe, cheap no-op.
- * @returns {{filePaths: Array<string>, cleanUp: function(): void}} The temp `.js` file paths to pass to
- * jsdoc-to-markdown instead of the real `.mjs` ones, and a function to remove the temp directory afterward.
- * @private
- */
-export const convertMjsFilesForDocs = (mjsFilePaths = []) => {
-  if (mjsFilePaths.length === 0) {
-    return { filePaths: [], cleanUp: () => {} }
-  }
-  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'js-build-tools-docs-'))
-  const filePaths = mjsFilePaths.map((mjsFilePath) => {
-    const tempFilePath = path.join(tempDir, path.basename(mjsFilePath, '.mjs') + '.js')
-    const source = fs.readFileSync(mjsFilePath, 'utf8')
-    fs.writeFileSync(tempFilePath, esmNamedExportsToCjs(source))
-    return tempFilePath
-  })
-  return {
-    filePaths,
-    cleanUp: () => fs.rmSync(tempDir, { recursive: true, force: true })
-  }
-}
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import { esmNamedExportsToCjs } from './esmNamedExportsToCjs.mjs'
+
+/**
+ * Writes a rewritten (see {@link esmNamedExportsToCjs}) copy of each given `.mjs` file into a fresh, unique
+ * directory under the OS temp directory, with a `.js` extension - jsdoc-to-markdown only recognizes `.js` as a
+ * documentable file, regardless of whether its contents are actually CommonJS or ESM (it parses the real ESM
+ * syntax of the rest of a file fine; the extension is the only thing it filters on). Writing outside the project
+ * tree means there is nothing to gitignore and nothing left behind in the project - call the returned `cleanUp`
+ * once done (for example, right after jsdoc-to-markdown has read the files) to remove the temp directory.
+ * @memberOf module:utilities
+ * @param {Array<string>} mjsFilePaths - Real `.mjs` files to convert. An empty array is a safe, cheap no-op.
+ * @returns {{filePaths: Array<string>, cleanUp: function(): void}} The temp `.js` file paths to pass to
+ * jsdoc-to-markdown instead of the real `.mjs` ones, and a function to remove the temp directory afterward.
+ * @private
+ */
+export const convertMjsFilesForDocs = (mjsFilePaths = []) => {
+  if (mjsFilePaths.length === 0) {
+    return { filePaths: [], cleanUp: () => {} }
+  }
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'js-build-tools-docs-'))
+  const filePaths = mjsFilePaths.map((mjsFilePath) => {
+    const tempFilePath = path.join(tempDir, path.basename(mjsFilePath, '.mjs') + '.js')
+    const source = fs.readFileSync(mjsFilePath, 'utf8')
+    fs.writeFileSync(tempFilePath, esmNamedExportsToCjs(source))
+    return tempFilePath
+  })
+  return {
+    filePaths,
+    cleanUp: () => fs.rmSync(tempDir, { recursive: true, force: true })
+  }
+}