js-build-tools 5.2.0 → 5.3.0

package/dist/utilities/dotSet.js

@@ -1,12 +1,12 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.dotSet = void 0;
-var _isObject = require("./isObject.js");
-var _strAfter = require("./strAfter.js");
-var _strBefore = require("./strBefore.js");
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.dotSet = void 0;
+var _isObject = require("./isObject.js");
+var _strAfter = require("./strAfter.js");
+var _strBefore = require("./strBefore.js");
 /**
  * Set a nested property value an object.
  * Original source concepts from {@link https://github.com/jheagle/si-funciona/blob/main/src/helpers/objects/dotSet.ts Sí, funciona}
@@ -14,32 +14,32 @@ var _strBefore = require("./strBefore.js");
  * @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
- */
-const dotSet = (arrayObject, dotNotation, value = null) => {
-  let key = (0, _strBefore.strBefore)(dotNotation, '.');
-  const lastKey = !key;
-  if (lastKey) {
-    key = dotNotation;
-  }
-  if (key === '*') {
-    for (let wildKey in arrayObject) {
-      if (lastKey) {
-        arrayObject[wildKey] = value;
-        continue;
-      }
-      if (!(0, _isObject.isObject)(arrayObject[wildKey])) {
-        continue;
-      }
-      dotSet(arrayObject[wildKey], (0, _strAfter.strAfter)(dotNotation, '.'), value);
-    }
-    return arrayObject;
-  }
-  if (lastKey) {
-    arrayObject[dotNotation] = value;
-    return arrayObject;
-  }
-  const next = arrayObject[key] ?? [];
-  arrayObject[key] = dotSet(next, (0, _strAfter.strAfter)(dotNotation, '.'), value);
-  return arrayObject;
-};
+ */
+const dotSet = (arrayObject, dotNotation, value = null) => {
+  let key = (0, _strBefore.strBefore)(dotNotation, '.');
+  const lastKey = !key;
+  if (lastKey) {
+    key = dotNotation;
+  }
+  if (key === '*') {
+    for (let wildKey in arrayObject) {
+      if (lastKey) {
+        arrayObject[wildKey] = value;
+        continue;
+      }
+      if (!(0, _isObject.isObject)(arrayObject[wildKey])) {
+        continue;
+      }
+      dotSet(arrayObject[wildKey], (0, _strAfter.strAfter)(dotNotation, '.'), value);
+    }
+    return arrayObject;
+  }
+  if (lastKey) {
+    arrayObject[dotNotation] = value;
+    return arrayObject;
+  }
+  const next = arrayObject[key] ?? [];
+  arrayObject[key] = dotSet(next, (0, _strAfter.strAfter)(dotNotation, '.'), value);
+  return arrayObject;
+};
 exports.dotSet = dotSet;

package/dist/utilities/isObject.js

@@ -1,14 +1,14 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.isObject = void 0;
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.isObject = void 0;
 /**
  * Check if the provided thing is an object / array.
  * Original source concepts from {@link https://github.com/jheagle/si-funciona/blob/main/src/helpers/objects/isObject.ts Sí, funciona}
  * @param {*} object
  * @returns {boolean}
- */
-const isObject = object => typeof object === 'object' && object !== null;
+ */
+const isObject = object => typeof object === 'object' && object !== null;
 exports.isObject = isObject;

package/dist/utilities/strAfter.js

@@ -1,18 +1,18 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.strAfter = void 0;
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.strAfter = void 0;
 /**
  * Retrieve the string part after the search match.
  * Original source from {@link https://github.com/jheagle/si-funciona/blob/main/src/helpers/strings/strAfter.ts Sí, funciona}
  * @param {string} str
  * @param {string} search
  * @returns {string}
- */
-const strAfter = (str, search) => {
-  const index = str.indexOf(search);
-  return index === -1 ? '' : str.substring(index + search.length);
-};
+ */
+const strAfter = (str, search) => {
+  const index = str.indexOf(search);
+  return index === -1 ? '' : str.substring(index + search.length);
+};
 exports.strAfter = strAfter;

package/dist/utilities/strBefore.js

@@ -1,18 +1,18 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.strBefore = void 0;
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.strBefore = void 0;
 /**
  * Retrieve the string part before the search match.
  * Original source from {@link https://github.com/jheagle/si-funciona/blob/main/src/helpers/strings/strBefore.ts Sí, funciona}
  * @param {string} str
  * @param {string} search
  * @returns {string}
- */
-const strBefore = (str, search) => {
-  const index = str.indexOf(search);
-  return index === -1 ? '' : str.slice(0, index);
-};
+ */
+const strBefore = (str, search) => {
+  const index = str.indexOf(search);
+  return index === -1 ? '' : str.slice(0, index);
+};
 exports.strBefore = strBefore;

package/dist/watchFull.js

@@ -1,14 +1,14 @@
-'use strict'
-
-Object.defineProperty(exports, '__esModule', {
-  value: true
-})
-exports.watchFull = void 0
-const _partials = require('./partials.js')
+'use strict'
+
+Object.defineProperty(exports, '__esModule', {
+  value: true
+})
+exports.watchFull = void 0
+const _partials = require('./partials.js')
 /**
  * Watch for changes and run the distribution for the changed files, then bundle and test the changed files.
  * @memberOf module:js-build-tools
  * @returns {FSWatcher}
- */
-const watchFull = () => (0, _partials.beginWatcher)().on('change', _partials.runOnChange)
-exports.watchFull = watchFull
+ */
+const watchFull = () => (0, _partials.beginWatcher)().on('change', _partials.runOnChange)
+exports.watchFull = watchFull

package/dist/watchTest.js

@@ -1,20 +1,20 @@
-'use strict'
-
-require('core-js/modules/esnext.weak-map.delete-all.js')
-Object.defineProperty(exports, '__esModule', {
-  value: true
-})
-exports.watchTest = void 0
-const gulpConfig = _interopRequireWildcard(require('../gulp.config.js'))
-const _gulp = require('gulp')
-const _testQuick = require('./testQuick.js')
-function _interopRequireWildcard (e, t) { if (typeof WeakMap === 'function') var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; let o; let i; const f = { __proto__: null, default: e }; if (e === null || typeof e !== 'object' && typeof e !== 'function') return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f) } for (const t in e) t !== 'default' && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f })(e, t) }
+'use strict'
+
+require('core-js/modules/esnext.weak-map.delete-all.js')
+Object.defineProperty(exports, '__esModule', {
+  value: true
+})
+exports.watchTest = void 0
+const gulpConfig = _interopRequireWildcard(require('../gulp.config.js'))
+const _gulp = require('gulp')
+const _testQuick = require('./testQuick.js')
+function _interopRequireWildcard (e, t) { if (typeof WeakMap === 'function') var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; let o; let i; const f = { __proto__: null, default: e }; if (e === null || typeof e !== 'object' && typeof e !== 'function') return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f) } for (const t in e) t !== 'default' && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f })(e, t) }
 /**
  * Watch for changes and run the tests.
  * @memberOf module:js-build-tools
  * @returns {*}
- */
-const watchTest = () => (0, _gulp.watch)(gulpConfig.get('test.watch'), {
-  ignoreInitial: false
-}, _testQuick.testQuick)
-exports.watchTest = watchTest
+ */
+const watchTest = () => (0, _gulp.watch)(gulpConfig.get('test.watch'), {
+  ignoreInitial: false
+}, _testQuick.testQuick)
+exports.watchTest = watchTest

package/functions/build.mjs

@@ -3,6 +3,7 @@ import { bundleLint } from './bundleLint.mjs'
 import { bundleMinify } from './bundleMinify.mjs'
 import { clean, distSeries } from './partials.mjs'
 import { compileReadme } from './compileReadme.mjs'
+import { typeDocs } from './typeDocs.mjs'
 import { distLint } from './distLint.mjs'
 import { distMinify } from './distMinify.mjs'
 import { parallel, series } from 'gulp'
@@ -22,7 +23,11 @@ export const build = (done = null) => {
   const distLintMinify = parallel(distLint, distMinify)
   const bundleLintMinify = parallel(bundleLint, bundleMinify)
   const buildActions = [distSeries(), distLintMinify]
-  if (gulpConfig.get('typescript.enabled')) {
+  const generateDocs = gulpConfig.get('docs.enabled')
+  if (generateDocs) {
+    // The documentation is generated from the TypeScript source itself, the readme is written by hand
+    buildActions.push(typeDocs)
+  } else if (gulpConfig.get('typescript.enabled')) {
     // For ts usage, we need to run the readme on the dist directly since that is where the .js files are located
     buildActions.push(compileReadme)
   }
@@ -34,7 +39,7 @@ export const build = (done = null) => {
   const runActions = [
     series(...buildActions),
   ]
-  if (!gulpConfig.get('typescript.enabled')) {
+  if (!generateDocs && !gulpConfig.get('typescript.enabled')) {
     // Since we didn't run this in series after dist because of typescript, we need to run it now. Potentially faster here.
     runActions.push(compileReadme)
   }

package/functions/build.test.mjs

@@ -3,6 +3,7 @@ import * as setUp from './test-helpers/setUp.mjs'
 import { build } from './build.mjs'
 import { clean } from './partials/clean.mjs'
 import { testFull } from './testFull.mjs'
+import { typeDocs } from './typeDocs.mjs'
 import { countMatches } from 'test-filesystem'
 
 // Run the real Standard (in a subprocess) - Jest's CommonJS transform can't load the ESM-only package itself.
@@ -15,6 +16,8 @@ const genericFunction = () => Promise.resolve(true)
 
 jest.mock('./partials/clean.mjs', () => ({ clean: jest.fn(genericFunction) }))
 jest.mock('./testFull.mjs', () => ({ testFull: jest.fn(genericFunction) }))
+// The documentation is generated by TypeDoc, whose own tests cover that (see typeDocsFor.test.mjs)
+jest.mock('./typeDocs.mjs', () => ({ typeDocs: jest.fn(genericFunction) }))
 // tsFor's real implementation loads gulp-ts-compile (a genuine ESM-only package) via a dynamic import() hidden
 // from babel's static analysis - necessary for production correctness (see tsFor.mjs's own comments), but this
 // project's current CommonJS-transform-based Jest setup can't execute a real dynamic import at all: it doesn't
@@ -625,6 +628,31 @@ describe('build', () => {
     })
   }, 30000)
 
+  test('when docs.enabled is set: generates the documentation from the TypeScript source instead of the readme', done => {
+    const srcPath = gulpConfig.get('srcPath')
+    const rootPath = gulpConfig.get('rootPath')
+    const tsConfig = `${rootPath}/tsconfig.json`
+    const readmePath = gulpConfig.get('readme.to')
+    const readmeFile = gulpConfig.get('readme.file')
+    fs.writeFileSync(`${srcPath}/main.ts`, mainTypescript)
+    fs.writeFileSync(tsConfig, tsConfigContents)
+    fs.rmSync(`${readmePath}/${readmeFile}`, { force: true })
+    typeDocs.mockClear()
+    gulpConfig.set('browser.enabled', false)
+    gulpConfig.set('typescript.config', tsConfig)
+    gulpConfig.set('typescript.enabled', true)
+    gulpConfig.set('docs.enabled', true)
+    expect.assertions(3)
+    build(() => {
+      gulpConfig.set('docs.enabled', false)
+      expect(typeDocs).toHaveBeenCalledTimes(1)
+      // The readme is not generated, it is written by hand
+      expect(fs.existsSync(`${readmePath}/${readmeFile}`)).toBe(false)
+      expect(testFull).toHaveBeenCalled()
+      done()
+    })
+  }, 30000)
+
   test('finishes clean before starting the tasks that write into the output folders', done => {
     const srcPath = gulpConfig.get('srcPath')
     const sourcesPath = `${srcPath}/sources`
@@ -647,6 +675,7 @@ describe('build', () => {
     gulpConfig.set('images.enabled', false)
     gulpConfig.set('sass.enabled', false)
     gulpConfig.set('typescript.enabled', false)
+    gulpConfig.set('docs.enabled', false)
     build(() => {
       expect(events).toEqual(['clean finished', 'testFull started'])
       done()

package/functions/partials/typeDocsFor.mjs

@@ -0,0 +1,194 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
+import * as gulpConfig from '../../gulp.config.mjs'
+import { loadTypescript } from './tsFor.mjs'
+import { removeDirectory } from './removeDirectory.mjs'
+
+// TypeDoc ships ESM-only, and this project also compiles itself to a CommonJS build (see tsFor.mjs, which hides its
+// own import of gulp-ts-compile the same way), so the import() is hidden from babel's CommonJS transform.
+const importModule = new Function('specifier', 'return import(specifier)')
+
+const installHint = 'Install it in your project with: npm install --save-dev typedoc'
+
+/**
+ * Find the TypeDoc of the project being built (an optional peer dependency, only needed when the docs task is
+ * enabled) and load it, so projects which do not document TypeScript never need it installed.
+ * @memberOf module:partials
+ * @param {string} [projectPath=process.cwd()] The folder of the project (which has the package.json) being built.
+ * @returns {Promise<Object>} The TypeDoc module.
+ * @throws {Error} With install instructions when typedoc is not installed.
+ */
+export const loadTypeDoc = async (projectPath = process.cwd()) => {
+  let typeDocPath
+  try {
+    typeDocPath = createRequire(path.join(projectPath, 'package.json')).resolve('typedoc')
+  } catch (error) {
+    if (error.code === 'MODULE_NOT_FOUND') {
+      throw new Error(`The docs task needs the optional peer dependency typedoc, which is not installed. ${installHint}`)
+    }
+    throw error
+  }
+  return importModule(pathToFileURL(typeDocPath).href)
+}
+
+const isSource = fileName => /\.(ts|tsx|mts|cts)$/.test(fileName) && !/\.d\.[cm]?ts$/.test(fileName) && !/\.(test|spec)\./.test(fileName)
+
+const listSources = dirPath => fs.readdirSync(dirPath, { withFileTypes: true }).flatMap(entry => {
+  const entryPath = path.join(dirPath, entry.name)
+  if (entry.isDirectory()) {
+    return entry.name === 'node_modules' ? [] : listSources(entryPath)
+  }
+  return isSource(entry.name) ? [entryPath] : []
+})
+
+const toIdentifier = fileName => fileName.replace(/[^\w$]+(\w)?/g, (match, letter) => (letter || '').toUpperCase()).replace(/^(\d)/, '_$1')
+
+const toModulePath = filePath => filePath.replace(/\.[cm]?tsx?$/, '').split(path.sep).join('/')
+
+/**
+ * Describe what a source file exports: whether it has a default export, and whether it has any named exports.
+ * @memberOf module:partials
+ * @param {Object} ts - The TypeScript compiler API.
+ * @param {string} filePath
+ * @returns {{hasDefault: boolean, hasNamed: boolean}}
+ */
+export const describeExports = (ts, filePath) => {
+  const source = ts.createSourceFile(filePath, fs.readFileSync(filePath, 'utf8'), ts.ScriptTarget.Latest)
+  let hasDefault = false
+  let hasNamed = false
+  source.statements.forEach(statement => {
+    if (ts.isExportAssignment(statement)) {
+      hasDefault = hasDefault || !statement.isExportEquals
+      return
+    }
+    if (ts.isExportDeclaration(statement)) {
+      const names = statement.exportClause && ts.isNamedExports(statement.exportClause) ? statement.exportClause.elements : null
+      if (names && names.some(element => element.name.text === 'default')) {
+        hasDefault = true
+      }
+      if (!names || names.some(element => element.name.text !== 'default')) {
+        hasNamed = true
+      }
+      return
+    }
+    const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) || [] : []
+    if (modifiers.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
+      if (modifiers.some(modifier => modifier.kind === ts.SyntaxKind.DefaultKeyword)) {
+        hasDefault = true
+      } else {
+        hasNamed = true
+      }
+    }
+  })
+  return { hasDefault, hasNamed }
+}
+
+/**
+ * Write one entry file per folder of the source directory into the entry directory. TypeDoc makes a module of every
+ * entry file, so the modules of the documentation mirror the folders. The default export of each source file is
+ * re-exported under the name of the file (the source files hold one function each), and anything else a file exports
+ * is re-exported as it is (that is where the types.ts files go). Index files (the barrels), tests and declaration
+ * files are left out. A source directory with no folders gets a single entry called index.
+ * @memberOf module:partials
+ * @param {Object} ts - The TypeScript compiler API.
+ * @param {string} srcDir - The directory holding the TypeScript source.
+ * @param {string} entryDir - The directory to write the entry files into.
+ * @returns {Array<string>} The paths of the entry files.
+ */
+export const writeDocEntries = (ts, srcDir, entryDir) => {
+  const absoluteSrc = path.resolve(srcDir)
+  fs.mkdirSync(entryDir, { recursive: true })
+  const folders = fs.readdirSync(absoluteSrc, { withFileTypes: true })
+    .filter(entry => entry.isDirectory() && entry.name !== 'node_modules')
+    .map(entry => ({ name: entry.name, files: listSources(path.join(absoluteSrc, entry.name)) }))
+    .filter(folder => folder.files.length)
+  const groups = folders.length
+    ? folders
+    : [{ name: 'index', files: listSources(absoluteSrc).filter(file => !/^(index|main)\./.test(path.basename(file))) }]
+  return groups.map(group => {
+    const lines = group.files
+      .filter(file => !/^index\./.test(path.basename(file)))
+      .sort()
+      .flatMap(file => {
+        const modulePath = toModulePath(file)
+        const { hasDefault, hasNamed } = describeExports(ts, file)
+        const fileName = path.basename(file).replace(/\.[cm]?tsx?$/, '')
+        return [
+          ...(hasDefault ? [`export { default as ${toIdentifier(fileName)} } from '${modulePath}'`] : []),
+          ...(hasNamed ? [`export * from '${modulePath}'`] : [])
+        ]
+      })
+    const entryPath = path.join(entryDir, `${group.name}.ts`)
+    fs.writeFileSync(entryPath, lines.join('\n') + '\n')
+    return entryPath
+  })
+}
+
+const projectName = () => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8')).name
+  } catch (error) {
+    return path.basename(process.cwd())
+  }
+}
+
+/**
+ * Generate the HTML documentation of a TypeScript project with TypeDoc, straight from the TypeScript source, so the
+ * types (and the comments on them) are documented from where they are defined. The modules mirror the folders of the
+ * source, see {@link writeDocEntries}. Configure this with 'docs.from', 'docs.to', 'docs.index', 'docs.title',
+ * 'docs.tsconfig' and 'docs.logLevel'.
+ * @memberOf module:partials
+ * @param {string} [srcPath=gulpConfig.get('docs.from')] - The directory holding the TypeScript source.
+ * @param {string} [outPath=gulpConfig.get('docs.to')] - The directory the documentation is generated into (cleared first).
+ * @param {function(string): Promise<Object>} [loadDocs] - Resolves the TypeDoc module, tests can inject a stand-in.
+ * @returns {Function} A gulp task, it accepts an optional callback and returns a promise.
+ */
+export const typeDocsFor = (
+  srcPath = gulpConfig.get('docs.from'),
+  outPath = gulpConfig.get('docs.to'),
+  loadDocs = loadTypeDoc
+) => {
+  if (gulpConfig.get('docs.enabled') === false) {
+    return () => {}
+  }
+  return (done) => {
+    const generate = async () => {
+      const ts = loadTypescript()
+      const { Application } = await loadDocs()
+      const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'typedocs-'))
+      try {
+        const entryPoints = writeDocEntries(ts, srcPath, path.join(workDir, 'entries'))
+        // The entry files live outside the project, so the tsconfig which is used for the documentation extends the
+        // one of the project and adds the entries to the files it includes.
+        const projectConfig = gulpConfig.get('docs.tsconfig') || gulpConfig.get('typescript.config')
+        const tsconfig = path.join(workDir, 'tsconfig.json')
+        fs.writeFileSync(tsconfig, JSON.stringify({
+          ...(projectConfig ? { extends: path.resolve(projectConfig) } : {}),
+          include: [path.join(workDir, 'entries', '*.ts').split(path.sep).join('/'), path.resolve(srcPath).split(path.sep).join('/') + '/**/*.ts'],
+          exclude: [path.resolve(srcPath).split(path.sep).join('/') + '/**/*.test.*']
+        }))
+        const indexFile = gulpConfig.get('docs.index')
+        await removeDirectory(outPath)
+        const app = await Application.bootstrap({
+          entryPoints,
+          tsconfig,
+          name: gulpConfig.get('docs.title') || projectName(),
+          readme: indexFile && fs.existsSync(indexFile) ? indexFile : 'none',
+          logLevel: gulpConfig.get('docs.logLevel') || 'Warn',
+          skipErrorChecking: true
+        })
+        const project = await app.convert()
+        if (!project) {
+          throw new Error('TypeDoc could not read the TypeScript source, see the errors above.')
+        }
+        await app.generateDocs(project, outPath)
+      } finally {
+        await removeDirectory(workDir)
+      }
+    }
+    return typeof done === 'function' ? generate().then(() => done(), done) : generate()
+  }
+}