js-build-tools 6.2.2 → 6.3.0

package/functions/test-helpers/setUp.mjs

@@ -23,6 +23,12 @@ export const setDefaults = (testDir = 'test-temp') => {
   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)`)

package/functions/utilities/convertMjsFilesForDocs.mjs

@@ -14,6 +14,7 @@ import { esmNamedExportsToCjs } from './esmNamedExportsToCjs.mjs'
  * @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) {

package/functions/utilities/dotGet.mjs

@@ -9,6 +9,7 @@ import { strBefore } from './strBefore.mjs'
  * @param {string} [dotNotation=''] - The path to the property
  * @param {string|null} [defaultValue=null] - The default value to return if the property is not found
  * @returns {*} The value of the property
+ * @private
  */
 export const dotGet = (arrayObject = {}, dotNotation= '', defaultValue = null) => {
   if (!dotNotation) {

package/functions/utilities/dotNotate.mjs

@@ -4,12 +4,14 @@ import { isObject } from './isObject.mjs'
  * Convert an array of keys into a regex, return a function to test if incoming keys match.
  * @param {Array.<string>} [retainObjects=[]] - An array of keys to retain as objects
  * @returns {Function} The dot-notated array
+ * @private
  */
 const handleRetainObjects = (retainObjects = []) => {
   if (!retainObjects.length) {
     /**
      * Bypass the test function if there are no retainObjects.
      * @returns {false}
+     * @private
      */
     return (currentKey, value, results) => false
   }
@@ -21,6 +23,7 @@ const handleRetainObjects = (retainObjects = []) => {
    * @param {*} value - The value of the key
    * @param {Object} results - The result object to add to
    * @returns {boolean}
+   * @private
    */
   return (currentKey, value, results) => {
     if (!currentKey.match(retainRegex)) {
@@ -38,6 +41,7 @@ const handleRetainObjects = (retainObjects = []) => {
  * @param {string} [prepend=''] - The path for the property being processed
  * @param {Object<string, *>} [results={}] - The final notated object to return
  * @returns {Object<string, *>} The dot-notated object
+ * @private
  */
 const performDotNotate = (arrayObject, didRetain, prepend = '', results = {}) => {
   for (let key in arrayObject) {
@@ -64,5 +68,6 @@ const performDotNotate = (arrayObject, didRetain, prepend = '', results = {}) =>
  * @param {Object} arrayObject - The array or object to dot-notate
  * @param {Array.<string>} [retainObjects=[]] - An array of keys to retain as objects
  * @returns {Object<string, *>} The dot-notated object
+ * @private
  */
 export const dotNotate = (arrayObject, retainObjects = []) => performDotNotate(arrayObject, handleRetainObjects(retainObjects))

package/functions/utilities/dotSet.mjs

@@ -9,6 +9,7 @@ import { strBefore } from './strBefore.mjs'
  * @param {string} dotNotation - The path for the property
  * @param {*} value - The default value to return if the property is not found
  * @returns {Object} The modified object
+ * @private
  */
 export const dotSet = (arrayObject, dotNotation, value = null) => {
   let key = strBefore(dotNotation, '.')

package/functions/utilities/esmNamedExportsToCjs.mjs

@@ -12,6 +12,7 @@
  * @memberOf module:utilities
  * @param {string} source - The raw ESM source text (never executed, just rewritten as text).
  * @returns {string} The rewritten text, safe to write out with a `.js` extension for jsdoc-to-markdown to read.
+ * @private
  */
 export const esmNamedExportsToCjs = (source) => {
   const exportedNames = []

package/functions/utilities/getBundleConfigs.mjs

@@ -8,6 +8,7 @@ import * as gulpConfig from '../../gulp.config.mjs'
  * specify what's actually different about it.
  * @memberOf module:utilities
  * @returns {Array<{name: string, main: string, ignore: Array, exclude: Array}>}
+ * @private
  */
 export const getBundleConfigs = () => {
   const primary = {

package/functions/utilities/isObject.mjs

@@ -3,5 +3,6 @@
  * Original source concepts from {@link https://github.com/jheagle/si-funciona/blob/main/src/helpers/objects/isObject.ts Sí, funciona}
  * @param {*} object
  * @returns {boolean}
+ * @private
  */
 export const isObject = (object) => typeof object === 'object' && object !== null

package/functions/utilities/strAfter.mjs

@@ -4,6 +4,7 @@
  * @param {string} str
  * @param {string} search
  * @returns {string}
+ * @private
  */
 export const strAfter = (str, search) => {
   const index = str.indexOf(search)

package/functions/utilities/strBefore.mjs

@@ -4,6 +4,7 @@
  * @param {string} str
  * @param {string} search
  * @returns {string}
+ * @private
  */
 export const strBefore = (str, search) => {
   const index = str.indexOf(search)

package/gulp.config.mjs

@@ -133,8 +133,8 @@ import { fileExists } from 'test-filesystem'
  * @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 {StringSetting} from - The directory holding the source, each folder in it becomes a module (TypeDoc) or
- * is scanned recursively (jsdoc).
+ * @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 {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 -

package/gulpfile.base.mjs

@@ -1,8 +1,6 @@
 /**
- * import these functions to your own project to customize your build pipeline.
- * @file
+ * Import these functions to your own project to customize your build pipeline.
  * @author Joshua Heagle <joshuaheagle@gmail.com>
- * @version 3.0.0
  * @module js-build-tools
  */
 export { build } from './functions/build.mjs'

package/jsdoc.base.js

@@ -1,10 +1,16 @@
+const path = require('path')
 const gulpConfig = require('./gulp.config.js')
 
 module.exports = {
-  plugins: ['plugins/markdown'],
+  plugins: ['plugins/markdown', path.join(__dirname, 'jsdoc.esmExports.js')],
+  // Give markdown headings ids (the README / docs.index front page), so they can be linked to and a theme's
+  // table of contents can follow them
+  markdown: { idInHeadings: true },
   source: {
     include: [gulpConfig.get('dist.to')],
-    includePattern: '.+\\.js(doc|x)?$',
-    excludePattern: '((^|\\/|\\\\)_|.+\\.test\\..*)'
+    // .mjs / .cjs too, so ES module source can be documented as it is, not only its compiled CommonJS
+    includePattern: '.+\\.[cm]?js(doc|x)?$',
+    // Files starting with _, tests, and minified copies (which only repeat what their unminified file documents)
+    excludePattern: '((^|\\/|\\\\)_|.+\\.test\\..*|.+\\.min\\.[cm]?js$)'
   },
 }

package/jsdoc.esmExports.js

@@ -0,0 +1,17 @@
+/**
+ * A jsdoc plugin for ES module source. When a file has no @module tag of its own, jsdoc names each
+ * `export const x` it documents `exports.x`, so with `@memberOf module:name` it becomes `module:name.exports.x`
+ * (shown as "exports.x"). This drops that `exports.` so it is `module:name.x`, the name it is used by.
+ */
+const prefix = 'exports.'
+
+exports.handlers = {
+  newDoclet ({ doclet }) {
+    if (doclet.name && doclet.name.startsWith(prefix)) {
+      doclet.name = doclet.name.slice(prefix.length)
+    }
+    if (doclet.longname && doclet.longname.includes(`.${prefix}`)) {
+      doclet.longname = doclet.longname.replace(`.${prefix}`, '.')
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-build-tools",
-  "version": "6.2.2",
+  "version": "6.3.0",
   "description": "Standardised build process with gulp.",
   "main": "gulpfile.base.js",
   "exports": {
@@ -20,7 +20,7 @@
   "scripts": {
     "build": "gulp build",
     "dev": "gulp",
-    "htmldocs": "jsdoc -R MAIN.md -c ./.jsdoc.conf.js -d docs",
+    "docs": "gulp docs",
     "readme": "gulp readme",
     "release": "release-it",
     "release:dry-run": "release-it --dry-run",
@@ -56,9 +56,9 @@
     "autoprefixer": "^10.6.1",
     "babel-jest": "^30.5.2",
     "browserify": "^17.0.1",
-    "core-js": "^3.50.0",
+    "core-js": "^3.51.0",
     "cssnano": "^6.1.2",
-    "eslint": "^10.12.0",
+    "eslint": "^10.13.0",
     "glob": "^13.0.6",
     "gulp": "^5.0.1",
     "gulp-babel": "^8.1.0",
@@ -66,17 +66,17 @@
     "gulp-postcss": "^10.0.0",
     "gulp-rename": "^2.1.0",
     "gulp-sass": "^6.0.1",
-    "gulp-ts-compile": "^1.0.1",
+    "gulp-ts-compile": "^1.0.2",
     "gulp-uglify-es": "^3.0.0",
     "jest": "^30.5.2",
     "jest-environment-jsdom": "^30.5.2",
     "jsdoc-to-markdown": "^9.1.3",
     "merge-stream": "^2.0.0",
     "neostandard": "^0.14.1",
-    "postcss": "^8.5.30",
+    "postcss": "^8.5.31",
     "regenerator-runtime": "^0.14.1",
-    "sass": "^1.105.1",
-    "test-filesystem": "^2.0.0",
+    "sass": "^1.105.2",
+    "test-filesystem": "^2.0.2",
     "through2": "^4.0.2",
     "vinyl-source-stream": "^2.0.0"
   },
@@ -84,6 +84,7 @@
     "clean-jsdoc-theme": ">=4.0.0",
     "gulp-imagemin": ">=9.0.0",
     "jsdoc": ">=4.0.0",
+    "playwright": ">=1.40.0",
     "typedoc": ">=0.28.0",
     "typescript": ">=5.0.0 <7.0.0"
   },
@@ -97,6 +98,9 @@
     "jsdoc": {
       "optional": true
     },
+    "playwright": {
+      "optional": true
+    },
     "typedoc": {
       "optional": true
     },
@@ -112,13 +116,15 @@
     "gulpfile.base.mjs",
     "gulp.config.js",
     "gulp.config.mjs",
-    "jsdoc.base.js"
+    "jsdoc.base.js",
+    "jsdoc.esmExports.js"
   ],
   "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": {
-    "clean-jsdoc-theme": "^5.2.0",
+    "clean-jsdoc-theme": "^4.3.3",
     "gulp-imagemin": "github:jheagle/gulp-imagemin#common-js-compatibility",
     "jsdoc": "^4.0.5",
+    "playwright": "~1.62.1",
     "release-it": "^21.1.1",
     "typedoc": "^0.28.20",
     "typescript": "^6.0.3"