js-build-tools 6.6.0 → 6.7.0

package/gulp.config.mjs

@@ -1,340 +1,344 @@
-/**
- * Modify these configurations to match your project specifications.
- * @file
- * @author Joshua Heagle <joshuaheagle@gmail.com>
- * @version 3.0.0
- * @module gulpConfig
- * @memberOf module:js-build-tools
- */
-import { fileExists } from 'test-filesystem'
-
-/**
- * A setting that may be an array of strings or a string only.
- * @typedef {Array<string>|string} module:gulpConfig~ArrayableSetting
- */
-/**
- * A setting that may be true or false.
- * @typedef {boolean} module:gulpConfig~BooleanSetting
- */
-/**
- * A setting that may be flag 'false' or provide a number
- * @typedef {false|number} module:gulpConfig~FlagNumberSetting
- */
-/**
- * A setting that may be flag 'false' or provide a StringSetting
- * @typedef {false|StringSetting} module:gulpConfig~FlagStringSetting
- */
-/**
- * An object of boolean settings used as flags.
- * @typedef {Object<string, BooleanSetting>} module:gulpConfig~FlagsSetting
- */
-/**
- * Configure cli options for running Jest.
- * @typedef {FlagsSetting} module:gulpConfig~JestTestFlags
- * @property {BooleanSetting} clearCache
- * @property {BooleanSetting} debug
- * @property {BooleanSetting} ignoreProjects:
- * @property {BooleanSetting} json
- * @property {BooleanSetting} selectProjects
- * @property {BooleanSetting} showConfig
- * @property {BooleanSetting} useStderr
- * @property {BooleanSetting} watch
- * @property {BooleanSetting} watchAll
- */
-/**
- * A setting that may only be a string.
- * @typedef {string} module:gulpConfig~StringSetting
- */
-/**
- * Any single configuration option is a Setting.
- * @typedef {ArrayableSetting|BooleanSetting|FlagNumberSetting|FlagsSetting|StringSetting} Setting
- */
-/**
- * One copy-files entry: a glob (or array of globs) to copy, and where to copy it.
- * @typedef {Object} module:gulpConfig~CopyFilesEntry
- * @property {ArrayableSetting} from - The glob pattern(s) of files to copy.
- * @property {StringSetting} to - The directory to copy them into.
- * @property {FlagStringSetting} base - Optional base for gulp's own src(pattern, {base}), to preserve a glob's
- * own subdirectory structure in the destination instead of flattening it. false (the default) uses gulp's own
- * default base behaviour.
- */
-/**
- * Configurations for building the browser files.
- * @typedef {Object<string, Setting>} module:gulpConfig~BrowserConfig
- * @property {BooleanSetting} enabled - 'true' to generate browser bundled files; 'false' for node environment only
- * @property {StringSetting} from - The search pattern used for retrieving compiled distribution files.
- * @property {StringSetting} name - The name to use for the browser-bundled output file (.js will be appended).
- * @property {StringSetting} to - The output directory for browser-bundled files.
- * @property {ArrayableSetting} ignore - Module names or file paths which resolve to an empty object ({}) in the
- * bundle instead of their real contents. For a dependency which is only reached because it is the default value of
- * an option you always override (for example a selector engine's default DOM adapter, when you always pass your
- * own), this keeps it (and anything only it requires) out of the bundle, as long as your code never actually reaches
- * the real module by not overriding that option. See browserify's b.ignore(file).
- * @property {ArrayableSetting} exclude - Module names or file paths left out of the bundle entirely; requiring one at
- * runtime throws unless something else provides it (for example a script tag loading it separately). See
- * browserify's b.exclude(file).
- * @property {Array<module:gulpConfig~AdditionalBundleConfig>} bundles - Additional bundles to produce alongside the
- * primary one (name/dist.main/ignore/exclude above) - for example a render-only variant built from a different
- * entry point than the full bundle. Empty by default: a project that never sets this gets exactly the one bundle it
- * always did.
- */
-/**
- * One additional bundle - everything but `name` falls back to the primary bundle's own value when omitted, so an
- * additional bundle only has to specify what's actually different about it.
- * @typedef {Object<string, Setting>} module:gulpConfig~AdditionalBundleConfig
- * @property {StringSetting} name - The name for this bundle's output file and standalone export - must be unique
- * among all of a project's bundles.
- * @property {StringSetting} [main] - This bundle's own entry point. Falls back to dist.main when omitted.
- * @property {ArrayableSetting} [ignore] - This bundle's own ignore list. Falls back to browser.ignore when omitted.
- * @property {ArrayableSetting} [exclude] - This bundle's own exclude list. Falls back to browser.exclude when omitted.
- */
-/**
- * Configurations for building the node distribution files.
- * @typedef {Object<string, Setting>} module:gulpConfig~DistConfig
- * @property {StringSetting} from - The search pattern used for gathering source files for distribution.
- * @property {StringSetting} main - Name of the entry the distribution file.
- * @property {StringSetting} to - The output directory for the distribution files.
- */
-/**
- * Configurations for copying the font files.
- * @typedef {Object<string, Setting>} module:gulpConfig~FontConfig
- * @property {BooleanSetting} enabled - Toggle copy directory of fonts on.
- * @property {StringSetting} from - Path to search for fonts.
- * @property {StringSetting} to - Path to output fonts.
- */
-/**
- * Configurations to minify and copy the images.
- * @typedef {Object<string, Setting>} module:gulpConfig~ImageConfig
- * @property {BooleanSetting} enabled - Toggle image minify and copy process.
- * @property {StringSetting} from - Path to search for images.
- * @property {FlagNumberSetting} jpegQuality - The JPEG quality (0 to 100) mozjpeg compresses to. False (the
- * default) keeps mozjpeg's own default, 75. Raise it (85 is usually indistinguishable from the original) when 75
- * visibly bands smooth gradients.
- * @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
- * @property {StringSetting} file - The name of the output documentation markdown file.
- * @property {StringSetting} from - Location of files to use for compiling documentation into the readme.
- * @property {ArrayableSetting} fromEsm - Additional `.mjs` files to document alongside `from`, converted on the
- * fly since the readme generator only recognizes `.js` files - see 'Configure including ESM files in the
- * generated readme'. Empty by default: a project that never sets this gets exactly the readme it always did.
- * @property {ArrayableSetting} options - Options for formatting the output readme.
- * @property {StringSetting} template - The file which will be pre-fixed to your README.md output.
- * @property {StringSetting} to - The directory to output the readme file in.
- */
-/**
- * Configurations for generating the HTML documentation of a project's own source, with either TypeDoc (real
- * TypeScript types) or jsdoc (a modern theme over jsdoc's own classic default) - see docs.method.
- * @typedef {Object<string, Setting>} module:gulpConfig~DocsConfig
- * @property {BooleanSetting} enabled - Toggle generating the documentation from the source. When it is on the
- * build does this instead of generating the readme from the jsdoc comments of the compiled files.
- * @property {ArrayableSetting} from - The directory holding the source, each folder in it becomes a module (TypeDoc) or
- * is scanned recursively (jsdoc). jsdoc also takes a list of directories and files.
- * @property {FlagStringSetting} gitRevision - The git revision TypeDoc's "Defined in" source links point to (TypeDoc
- * only). False (the default) is TypeDoc's own: the current commit, which changes every page on every commit. A
- * branch name such as 'main' keeps the pages unchanged until the documentation itself changes; '{branch}' is the
- * branch being built.
- * @property {BooleanSetting} inBuild - Generate the documentation as part of build (the default). Turn it off to only
- * generate it when you run the docs task yourself (gulp docs), for example when docs.to points into another
- * repository and you only want to publish the documentation of a release.
- * @property {StringSetting} index - The markdown file used as the front page of the documentation.
- * @property {StringSetting} logLevel - How much TypeDoc reports: Verbose, Info, Warn, Error or None. Not used by jsdoc.
- * @property {FlagStringSetting} method - 'typedoc' or 'jsdoc'. False (the default) infers it from typescript.enabled -
- * 'typedoc' when on, 'jsdoc' when off - so an existing TypeScript project's config needs no change to keep working
- * exactly as it already does; set this explicitly to override that inference either way.
- * @property {StringSetting} theme - The jsdoc theme package to use (only meaningful when method is 'jsdoc' - TypeDoc
- * keeps its own default regardless). Defaults to 'clean-jsdoc-theme'.
- * @property {StringSetting} title - The name of the documentation, defaults to the name in the package.json.
- * @property {StringSetting} to - The directory to generate the documentation in (it is cleared first).
- * @property {FlagStringSetting} tsconfig - The tsconfig file to read the source with (TypeDoc only), defaults to the
- * one of typescript.config.
- */
-/**
- * Configurations to compile and copy the sass files into css.
- * @typedef {Object<string, Setting>} module:gulpConfig~SassConfig
- * @property {BooleanSetting} enabled - Toggle SASS to CSS process on.
- * @property {StringSetting} from - The pattern for finding all sass files.
- * @property {StringSetting} path - The directory were sass files will be stored.
- * @property {StringSetting} to - The destination path for where generated CSS (from SASS files) should go.
- */
-/**
- * Configurations for running the test suite.
- * @typedef {Object<string, Setting>} module:gulpConfig~TestConfig
- * @property {JestTestFlags} options - Additional flags for programmatically running Jest Cli.
- * @property {ArrayableSetting} path - The directory where Jest test files are stored.
- * By default, stored as *.test.js adjacent to the files they are testing.
- * @property {ArrayableSetting} watch - The search pattern for watching files for changes.
- */
-/**
- * Configurations for compiling typescript into JS files.
- * @typedef {Object<string, Setting>} module:gulpConfig~TsConfig
- * @property {FlagStringSetting} config - The path the tsconfig file for running typescript or false if no ts file given.
- * @property {BooleanSetting} enabled - Toggle usage of typescript parsing.
- * @property {StringSetting} from - Pattern for finding the TypeScript files.
- * @property {StringSetting} to - Directory where parsed typescript files go.
- */
-/**
- * A set of Configurations options defined by Settings.
- * @typedef {Object<string, Setting>} module:gulpConfig~Configurations
- * @property {BrowserConfig} browser - Browser bundling configuration group.
- * @property {ArrayableSetting} cleanPaths - The paths for directories to delete before build.
- * @property {Array<CopyFilesEntry>} copyFiles - Files to copy elsewhere, run via the copyFiles task - never
- * automatically as part of build, since what this copies is often the live, publicly-reachable version of
- * something (e.g. a bundle), and publishing it should be a deliberate step.
- * @property {DistConfig} dist - Distribution file generation configuration group.
- * @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.
- * @property {StringSetting} srcPath - The directory where your source files are stored (the files you manually created).
- * @property {TestConfig} test - Run test suite configuration.
- * @property {TsConfig} typescript - Compile from typescript configuration.
- */
-import { dotGet } from './functions/utilities/dotGet.mjs'
-import { dotSet } from './functions/utilities/dotSet.mjs'
-import { dotNotate } from './functions/utilities/dotNotate.mjs'
-import { readFileSync } from 'fs'
-
-const setDefaults = {
-  browser: {
-    bundles: [],
-    enabled: true,
-    exclude: [],
-    from: 'dist/**/*.js',
-    ignore: [],
-    name: 'default',
-    to: 'browser',
-  },
-  cleanPaths: ['dist', 'browser'],
-  copyFiles: [],
-  dist: {
-    from: 'src/**/!(*.test).js',
-    main: 'dist/main',
-    to: 'dist',
-  },
-  docs: {
-    enabled: false,
-    from: 'src',
-    gitRevision: false,
-    inBuild: true,
-    index: 'MAIN.md',
-    logLevel: 'Warn',
-    method: false,
-    theme: 'clean-jsdoc-theme',
-    title: '',
-    to: 'docs',
-    tsconfig: false,
-  },
-  fonts: {
-    enabled: false,
-    from: 'src/fonts/**/*',
-    to: 'browser/fonts',
-  },
-  images: {
-    enabled: false,
-    from: 'src/img/**/*.+(png|jpg|jpeg|gif|svg)',
-    jpegQuality: false,
-    to: 'browser/img',
-  },
-  lint: {
-    rules: {},
-  },
-  readme: {
-    file: 'README.md',
-    from: 'src/**/!(*.test).js',
-    fromEsm: [],
-    options: 'utf8',
-    template: 'MAIN.md',
-    to: './'
-  },
-  rootPath: './',
-  sass: {
-    enabled: false,
-    from: 'sass/**/*.+(scss|sass)',
-    path: 'sass',
-    to: 'browser/css',
-  },
-  srcPath: 'src',
-  test: {
-    options: {
-      clearCache: false,
-      debug: false,
-      ignoreProjects: false,
-      json: false,
-      selectProjects: false,
-      showConfig: false,
-      useStderr: false,
-      watch: false,
-      watchAll: false,
-    },
-    path: ['src'],
-    watch: 'src/**/*.js'
-  },
-  typescript: {
-    config: false,
-    enabled: false,
-    from: 'src/**/*.ts',
-    to: 'dist',
-  },
-}
-
-/**
- * All the available configuration setting options for running the build.
- * @memberOf module:gulpConfig` `
- * @type {Configurations}
- */
-let gulpConfigurations = null
-if (fileExists(process.cwd() + '/build-tools.config.json')) {
-  gulpConfigurations = JSON.parse(readFileSync(process.cwd() + '/build-tools.config.json').toString())
-} else {
-  if (fileExists('./build-tools.config.json')) {
-    gulpConfigurations = JSON.parse(readFileSync('./build-tools.config.json').toString())
-  } else {
-    console.warn('Missing config path, ensure you have a build-tools.config.js file in you project root')
-  }
-}
-
-const notation = dotNotate(setDefaults)
-for (let notationKey in notation) {
-  const arrayEnding = /(\.\d+)$/
-  if (arrayEnding.test(notationKey)) {
-    // ends in number a key then it must be an array; use the entire array
-    notationKey = notationKey.replace(arrayEnding, '')
-  }
-  const defaultValue = dotGet(setDefaults, notationKey)
-  const existingConfig = dotGet(gulpConfigurations, notationKey, defaultValue)
-  dotSet(gulpConfigurations, notationKey, existingConfig)
-}
-
-/**
- * Retrieve a value from the configurations, default may be returned.
- * @memberOf module:gulpConfig
- * @param {string|null} path
- * @param {*} defaultValue
- * @returns {*|null}
- */
-export const get = (path = null, defaultValue = null) => dotGet(gulpConfigurations, path, defaultValue)
-
-/**
- * Specify a value for the configurations to use.
- * @memberOf module:gulpConfig
- * @param path
- * @param value
- * @returns {*}
- */
-export const set = (path, value) => dotSet(gulpConfigurations, path, value)
+/**
+ * Modify these configurations to match your project specifications.
+ * @file
+ * @author Joshua Heagle <joshuaheagle@gmail.com>
+ * @version 3.0.0
+ * @module gulpConfig
+ * @memberOf module:js-build-tools
+ */
+import { fileExists } from 'test-filesystem'
+
+/**
+ * A setting that may be an array of strings or a string only.
+ * @typedef {Array<string>|string} module:gulpConfig~ArrayableSetting
+ */
+/**
+ * A setting that may be true or false.
+ * @typedef {boolean} module:gulpConfig~BooleanSetting
+ */
+/**
+ * A setting that may be flag 'false' or provide a number
+ * @typedef {false|number} module:gulpConfig~FlagNumberSetting
+ */
+/**
+ * A setting that may be flag 'false' or provide a StringSetting
+ * @typedef {false|StringSetting} module:gulpConfig~FlagStringSetting
+ */
+/**
+ * An object of boolean settings used as flags.
+ * @typedef {Object<string, BooleanSetting>} module:gulpConfig~FlagsSetting
+ */
+/**
+ * Configure cli options for running Jest.
+ * @typedef {FlagsSetting} module:gulpConfig~JestTestFlags
+ * @property {BooleanSetting} clearCache
+ * @property {BooleanSetting} debug
+ * @property {BooleanSetting} ignoreProjects:
+ * @property {BooleanSetting} json
+ * @property {BooleanSetting} selectProjects
+ * @property {BooleanSetting} showConfig
+ * @property {BooleanSetting} useStderr
+ * @property {BooleanSetting} watch
+ * @property {BooleanSetting} watchAll
+ */
+/**
+ * A setting that may only be a string.
+ * @typedef {string} module:gulpConfig~StringSetting
+ */
+/**
+ * Any single configuration option is a Setting.
+ * @typedef {ArrayableSetting|BooleanSetting|FlagNumberSetting|FlagsSetting|StringSetting} Setting
+ */
+/**
+ * One copy-files entry: a glob (or array of globs) to copy, and where to copy it.
+ * @typedef {Object} module:gulpConfig~CopyFilesEntry
+ * @property {ArrayableSetting} from - The glob pattern(s) of files to copy.
+ * @property {StringSetting} to - The directory to copy them into.
+ * @property {FlagStringSetting} base - Optional base for gulp's own src(pattern, {base}), to preserve a glob's
+ * own subdirectory structure in the destination instead of flattening it. false (the default) uses gulp's own
+ * default base behaviour.
+ */
+/**
+ * Configurations for building the browser files.
+ * @typedef {Object<string, Setting>} module:gulpConfig~BrowserConfig
+ * @property {BooleanSetting} enabled - 'true' to generate browser bundled files; 'false' for node environment only
+ * @property {StringSetting} from - The search pattern used for retrieving compiled distribution files.
+ * @property {StringSetting} name - The name to use for the browser-bundled output file (.js will be appended).
+ * @property {StringSetting} to - The output directory for browser-bundled files.
+ * @property {ArrayableSetting} ignore - Module names or file paths which resolve to an empty object ({}) in the
+ * bundle instead of their real contents. For a dependency which is only reached because it is the default value of
+ * an option you always override (for example a selector engine's default DOM adapter, when you always pass your
+ * own), this keeps it (and anything only it requires) out of the bundle, as long as your code never actually reaches
+ * the real module by not overriding that option. See browserify's b.ignore(file).
+ * @property {ArrayableSetting} exclude - Module names or file paths left out of the bundle entirely; requiring one at
+ * runtime throws unless something else provides it (for example a script tag loading it separately). See
+ * browserify's b.exclude(file).
+ * @property {Array<module:gulpConfig~AdditionalBundleConfig>} bundles - Additional bundles to produce alongside the
+ * primary one (name/dist.main/ignore/exclude above) - for example a render-only variant built from a different
+ * entry point than the full bundle. Empty by default: a project that never sets this gets exactly the one bundle it
+ * always did.
+ */
+/**
+ * One additional bundle - everything but `name` falls back to the primary bundle's own value when omitted, so an
+ * additional bundle only has to specify what's actually different about it.
+ * @typedef {Object<string, Setting>} module:gulpConfig~AdditionalBundleConfig
+ * @property {StringSetting} name - The name for this bundle's output file and standalone export - must be unique
+ * among all of a project's bundles.
+ * @property {StringSetting} [main] - This bundle's own entry point. Falls back to dist.main when omitted.
+ * @property {ArrayableSetting} [ignore] - This bundle's own ignore list. Falls back to browser.ignore when omitted.
+ * @property {ArrayableSetting} [exclude] - This bundle's own exclude list. Falls back to browser.exclude when omitted.
+ */
+/**
+ * Configurations for building the node distribution files.
+ * @typedef {Object<string, Setting>} module:gulpConfig~DistConfig
+ * @property {StringSetting} from - The search pattern used for gathering source files for distribution.
+ * @property {StringSetting} main - Name of the entry the distribution file.
+ * @property {StringSetting} to - The output directory for the distribution files.
+ */
+/**
+ * Configurations for copying the font files.
+ * @typedef {Object<string, Setting>} module:gulpConfig~FontConfig
+ * @property {BooleanSetting} enabled - Toggle copy directory of fonts on.
+ * @property {StringSetting} from - Path to search for fonts.
+ * @property {StringSetting} to - Path to output fonts.
+ */
+/**
+ * Configurations to minify and copy the images.
+ * @typedef {Object<string, Setting>} module:gulpConfig~ImageConfig
+ * @property {BooleanSetting} enabled - Toggle image minify and copy process.
+ * @property {StringSetting} from - Path to search for images.
+ * @property {FlagNumberSetting} jpegQuality - The JPEG quality (0 to 100) mozjpeg compresses to. False (the
+ * default) keeps mozjpeg's own default, 75. Raise it (85 is usually indistinguishable from the original) when 75
+ * visibly bands smooth gradients.
+ * @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
+ * @property {StringSetting} file - The name of the output documentation markdown file.
+ * @property {StringSetting} from - Location of files to use for compiling documentation into the readme.
+ * @property {ArrayableSetting} fromEsm - Additional `.mjs` files to document alongside `from`, converted on the
+ * fly since the readme generator only recognizes `.js` files - see 'Configure including ESM files in the
+ * generated readme'. Empty by default: a project that never sets this gets exactly the readme it always did.
+ * @property {ArrayableSetting} options - Options for formatting the output readme.
+ * @property {StringSetting} template - The file which will be pre-fixed to your README.md output.
+ * @property {StringSetting} to - The directory to output the readme file in.
+ */
+/**
+ * Configurations for generating the HTML documentation of a project's own source, with either TypeDoc (real
+ * TypeScript types) or jsdoc (a modern theme over jsdoc's own classic default) - see docs.method.
+ * @typedef {Object<string, Setting>} module:gulpConfig~DocsConfig
+ * @property {FlagStringSetting} basePath - The path the documentation is served from, such as '/projects/my-lib/docs/'
+ * (jsdoc with clean-jsdoc-theme 5.x only). The theme's links start at the site root, so documentation served below it
+ * needs this. False (the default) serves it from the site root.
+ * @property {BooleanSetting} enabled - Toggle generating the documentation from the source. When it is on the
+ * build does this instead of generating the readme from the jsdoc comments of the compiled files.
+ * @property {ArrayableSetting} from - The directory holding the source, each folder in it becomes a module (TypeDoc) or
+ * is scanned recursively (jsdoc). jsdoc also takes a list of directories and files.
+ * @property {FlagStringSetting} gitRevision - The git revision TypeDoc's "Defined in" source links point to (TypeDoc
+ * only). False (the default) is TypeDoc's own: the current commit, which changes every page on every commit. A
+ * branch name such as 'main' keeps the pages unchanged until the documentation itself changes; '{branch}' is the
+ * branch being built.
+ * @property {BooleanSetting} inBuild - Generate the documentation as part of build (the default). Turn it off to only
+ * generate it when you run the docs task yourself (gulp docs), for example when docs.to points into another
+ * repository and you only want to publish the documentation of a release.
+ * @property {StringSetting} index - The markdown file used as the front page of the documentation.
+ * @property {StringSetting} logLevel - How much TypeDoc reports: Verbose, Info, Warn, Error or None. Not used by jsdoc.
+ * @property {FlagStringSetting} method - 'typedoc' or 'jsdoc'. False (the default) infers it from typescript.enabled -
+ * 'typedoc' when on, 'jsdoc' when off - so an existing TypeScript project's config needs no change to keep working
+ * exactly as it already does; set this explicitly to override that inference either way.
+ * @property {StringSetting} theme - The jsdoc theme package to use (only meaningful when method is 'jsdoc' - TypeDoc
+ * keeps its own default regardless). Defaults to 'clean-jsdoc-theme'.
+ * @property {StringSetting} title - The name of the documentation, defaults to the name in the package.json.
+ * @property {StringSetting} to - The directory to generate the documentation in (it is cleared first).
+ * @property {FlagStringSetting} tsconfig - The tsconfig file to read the source with (TypeDoc only), defaults to the
+ * one of typescript.config.
+ */
+/**
+ * Configurations to compile and copy the sass files into css.
+ * @typedef {Object<string, Setting>} module:gulpConfig~SassConfig
+ * @property {BooleanSetting} enabled - Toggle SASS to CSS process on.
+ * @property {StringSetting} from - The pattern for finding all sass files.
+ * @property {StringSetting} path - The directory were sass files will be stored.
+ * @property {StringSetting} to - The destination path for where generated CSS (from SASS files) should go.
+ */
+/**
+ * Configurations for running the test suite.
+ * @typedef {Object<string, Setting>} module:gulpConfig~TestConfig
+ * @property {JestTestFlags} options - Additional flags for programmatically running Jest Cli.
+ * @property {ArrayableSetting} path - The directory where Jest test files are stored.
+ * By default, stored as *.test.js adjacent to the files they are testing.
+ * @property {ArrayableSetting} watch - The search pattern for watching files for changes.
+ */
+/**
+ * Configurations for compiling typescript into JS files.
+ * @typedef {Object<string, Setting>} module:gulpConfig~TsConfig
+ * @property {FlagStringSetting} config - The path the tsconfig file for running typescript or false if no ts file given.
+ * @property {BooleanSetting} enabled - Toggle usage of typescript parsing.
+ * @property {StringSetting} from - Pattern for finding the TypeScript files.
+ * @property {StringSetting} to - Directory where parsed typescript files go.
+ */
+/**
+ * A set of Configurations options defined by Settings.
+ * @typedef {Object<string, Setting>} module:gulpConfig~Configurations
+ * @property {BrowserConfig} browser - Browser bundling configuration group.
+ * @property {ArrayableSetting} cleanPaths - The paths for directories to delete before build.
+ * @property {Array<CopyFilesEntry>} copyFiles - Files to copy elsewhere, run via the copyFiles task - never
+ * automatically as part of build, since what this copies is often the live, publicly-reachable version of
+ * something (e.g. a bundle), and publishing it should be a deliberate step.
+ * @property {DistConfig} dist - Distribution file generation configuration group.
+ * @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.
+ * @property {StringSetting} srcPath - The directory where your source files are stored (the files you manually created).
+ * @property {TestConfig} test - Run test suite configuration.
+ * @property {TsConfig} typescript - Compile from typescript configuration.
+ */
+import { dotGet } from './functions/utilities/dotGet.mjs'
+import { dotSet } from './functions/utilities/dotSet.mjs'
+import { dotNotate } from './functions/utilities/dotNotate.mjs'
+import { readFileSync } from 'fs'
+
+const setDefaults = {
+  browser: {
+    bundles: [],
+    enabled: true,
+    exclude: [],
+    from: 'dist/**/*.js',
+    ignore: [],
+    name: 'default',
+    to: 'browser',
+  },
+  cleanPaths: ['dist', 'browser'],
+  copyFiles: [],
+  dist: {
+    from: 'src/**/!(*.test).js',
+    main: 'dist/main',
+    to: 'dist',
+  },
+  docs: {
+    basePath: false,
+    enabled: false,
+    from: 'src',
+    gitRevision: false,
+    inBuild: true,
+    index: 'MAIN.md',
+    logLevel: 'Warn',
+    method: false,
+    theme: 'clean-jsdoc-theme',
+    title: '',
+    to: 'docs',
+    tsconfig: false,
+  },
+  fonts: {
+    enabled: false,
+    from: 'src/fonts/**/*',
+    to: 'browser/fonts',
+  },
+  images: {
+    enabled: false,
+    from: 'src/img/**/*.+(png|jpg|jpeg|gif|svg)',
+    jpegQuality: false,
+    to: 'browser/img',
+  },
+  lint: {
+    rules: {},
+  },
+  readme: {
+    file: 'README.md',
+    from: 'src/**/!(*.test).js',
+    fromEsm: [],
+    options: 'utf8',
+    template: 'MAIN.md',
+    to: './'
+  },
+  rootPath: './',
+  sass: {
+    enabled: false,
+    from: 'sass/**/*.+(scss|sass)',
+    path: 'sass',
+    to: 'browser/css',
+  },
+  srcPath: 'src',
+  test: {
+    options: {
+      clearCache: false,
+      debug: false,
+      ignoreProjects: false,
+      json: false,
+      selectProjects: false,
+      showConfig: false,
+      useStderr: false,
+      watch: false,
+      watchAll: false,
+    },
+    path: ['src'],
+    watch: 'src/**/*.js'
+  },
+  typescript: {
+    config: false,
+    enabled: false,
+    from: 'src/**/*.ts',
+    to: 'dist',
+  },
+}
+
+/**
+ * All the available configuration setting options for running the build.
+ * @memberOf module:gulpConfig` `
+ * @type {Configurations}
+ */
+let gulpConfigurations = null
+if (fileExists(process.cwd() + '/build-tools.config.json')) {
+  gulpConfigurations = JSON.parse(readFileSync(process.cwd() + '/build-tools.config.json').toString())
+} else {
+  if (fileExists('./build-tools.config.json')) {
+    gulpConfigurations = JSON.parse(readFileSync('./build-tools.config.json').toString())
+  } else {
+    console.warn('Missing config path, ensure you have a build-tools.config.js file in you project root')
+  }
+}
+
+const notation = dotNotate(setDefaults)
+for (let notationKey in notation) {
+  const arrayEnding = /(\.\d+)$/
+  if (arrayEnding.test(notationKey)) {
+    // ends in number a key then it must be an array; use the entire array
+    notationKey = notationKey.replace(arrayEnding, '')
+  }
+  const defaultValue = dotGet(setDefaults, notationKey)
+  const existingConfig = dotGet(gulpConfigurations, notationKey, defaultValue)
+  dotSet(gulpConfigurations, notationKey, existingConfig)
+}
+
+/**
+ * Retrieve a value from the configurations, default may be returned.
+ * @memberOf module:gulpConfig
+ * @param {string|null} path
+ * @param {*} defaultValue
+ * @returns {*|null}
+ */
+export const get = (path = null, defaultValue = null) => dotGet(gulpConfigurations, path, defaultValue)
+
+/**
+ * Specify a value for the configurations to use.
+ * @memberOf module:gulpConfig
+ * @param path
+ * @param value
+ * @returns {*}
+ */
+export const set = (path, value) => dotSet(gulpConfigurations, path, value)