js-build-tools 5.1.1 → 5.3.0

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/bundle.mjs

@@ -5,10 +5,26 @@ import source from 'vinyl-source-stream'
 
 /**
  * Starting at the distribution entry point, bundle all the files into a single file and store them in the specified output directory.
+ *
+ * Two escape hatches from browser.config.json keep an unwanted dependency (or a dependency's dependency) out of the
+ * bundle: 'ignore' replaces it with an empty object (safe when your code never actually calls into it - for example
+ * a library's default option value you always override with your own) and 'exclude' leaves it out entirely (your
+ * code must not require it, or provide it another way, such as a separate script tag).
  * @memberOf module:js-build-tools
  * @returns {stream.Stream}
  */
-export const bundle = () => browserify(gulpConfig.get('dist.main'))
-  .bundle()
-  .pipe(source(`${gulpConfig.get('browser.name')}.js`))
-  .pipe(dest(gulpConfig.get('browser.to')))
+export const bundle = () => {
+  const bundler = browserify(gulpConfig.get('dist.main'))
+  const ignore = gulpConfig.get('browser.ignore')
+  const exclude = gulpConfig.get('browser.exclude')
+  if (ignore && ignore.length) {
+    bundler.ignore(ignore)
+  }
+  if (exclude && exclude.length) {
+    bundler.exclude(exclude)
+  }
+  return bundler
+    .bundle()
+    .pipe(source(`${gulpConfig.get('browser.name')}.js`))
+    .pipe(dest(gulpConfig.get('browser.to')))
+}

package/functions/bundle.test.mjs

@@ -67,3 +67,77 @@ describe('bundle', () => {
       })
   })
 })
+
+describe('bundle ignore / exclude', () => {
+  const optionalDepMarker = 'MARKER_FROM_THE_OPTIONAL_DEPENDENCY_CODE'
+
+  beforeEach(() => {
+    const tempDir = gulpConfig.get('rootPath')
+    const depDir = `${tempDir}node_modules/optional-dep`
+    fs.mkdirSync(depDir, { recursive: true })
+    fs.writeFileSync(`${depDir}/package.json`, JSON.stringify({ name: 'optional-dep', main: 'index.js' }))
+    fs.writeFileSync(`${depDir}/index.js`, `module.exports = '${optionalDepMarker}'\n`)
+    const distPath = gulpConfig.get('dist.to')
+    const mainFile = gulpConfig.get('dist.main')
+    fs.mkdirSync(distPath, { recursive: true })
+    // Only reached as a fallback for an option the caller always overrides, the way css-select falls back to its
+    // own default adapter (domutils) unless one is given - exactly the case ignore / exclude exist for.
+    fs.writeFileSync(`${mainFile}.js`, 'const optionalDep = require(\'optional-dep\')\n\nmodule.exports = (given) => given || optionalDep\n')
+  })
+
+  test('without ignore or exclude, the dependency is bundled', done => {
+    const destPath = gulpConfig.get('browser.to')
+    const bundledFile = `${destPath}/${gulpConfig.get('browser.name')}.js`
+    expect.assertions(1)
+    bundle()
+      .on('finish', () => {
+        expect(fs.readFileSync(bundledFile).toString()).toContain(optionalDepMarker)
+        done()
+      })
+      .on('error', error => done(error))
+  })
+
+  test('ignore replaces the dependency with an empty object, but the bundle still finishes', done => {
+    gulpConfig.set('browser.ignore', ['optional-dep'])
+    const destPath = gulpConfig.get('browser.to')
+    const bundledFile = `${destPath}/${gulpConfig.get('browser.name')}.js`
+    expect.assertions(2)
+    bundle()
+      .on('finish', () => {
+        const bundledContents = fs.readFileSync(bundledFile).toString()
+        // The ignored module is still in the bundle (as an empty stub, so requiring it by name still resolves) -
+        // it just no longer has the real code that would have pulled in the marker
+        expect(bundledContents).toContain('optional-dep')
+        expect(bundledContents).not.toContain(optionalDepMarker)
+        done()
+      })
+      .on('error', error => done(error))
+  })
+
+  test('exclude leaves the dependency out of the bundle entirely', done => {
+    gulpConfig.set('browser.exclude', ['optional-dep'])
+    const destPath = gulpConfig.get('browser.to')
+    const bundledFile = `${destPath}/${gulpConfig.get('browser.name')}.js`
+    expect.assertions(1)
+    bundle()
+      .on('finish', () => {
+        expect(fs.readFileSync(bundledFile).toString()).not.toContain(optionalDepMarker)
+        done()
+      })
+      .on('error', error => done(error))
+  })
+
+  test('a single string is accepted the same as a one item array', done => {
+    gulpConfig.set('browser.ignore', 'optional-dep')
+    const destPath = gulpConfig.get('browser.to')
+    const bundledFile = `${destPath}/${gulpConfig.get('browser.name')}.js`
+    expect.assertions(1)
+    bundle()
+      .on('finish', () => {
+        expect(fs.readFileSync(bundledFile).toString()).not.toContain(optionalDepMarker)
+        done()
+      })
+      .on('error', error => done(error))
+  })
+})
+

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()
+  }
+}

package/functions/partials/typeDocsFor.test.mjs

@@ -0,0 +1,183 @@
+import fs from 'fs'
+import path from 'node:path'
+import ts from 'typescript'
+import * as setUp from '../test-helpers/setUp.mjs'
+import { describeExports, loadTypeDoc, typeDocsFor, writeDocEntries } from './typeDocsFor.mjs'
+
+setUp.setDefaults('test-type-docs-for')
+const gulpConfig = setUp.gulpConfig
+
+const write = (file, contents) => {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, contents)
+}
+
+beforeEach(
+  () => setUp.beforeEach().then(() => {
+    const srcPath = gulpConfig.get('srcPath')
+    write(`${srcPath}/main.ts`, "import a from './point/add'\nexport default { a }\n")
+    write(`${srcPath}/point/add.ts`, '/** Add two numbers. */\nconst add = (a: number, b: number): number => a + b\n\nexport default add\n')
+    write(`${srcPath}/point/get-name.ts`, 'export default function getName (): string { return "name" }\n')
+    write(`${srcPath}/point/types.ts`, 'export interface Point { x: number, y: number }\nexport type Axis = keyof Point\n')
+    write(`${srcPath}/point/index.ts`, "import add from './add'\nexport default { add }\n")
+    write(`${srcPath}/point/add.test.ts`, "test('adds', () => {})\n")
+    write(`${srcPath}/point/add.d.ts`, 'export {}\n')
+    write(`${srcPath}/line/length.ts`, 'export const length = 5\nexport default length\n')
+    write(`${srcPath}/empty/README.md`, 'nothing to document\n')
+  })
+)
+
+afterEach(setUp.afterEach)
+
+describe('describeExports', () => {
+  const inSrc = name => `${gulpConfig.get('srcPath')}/${name}`
+
+  test('finds a default export', () => {
+    expect(describeExports(ts, inSrc('point/add.ts'))).toEqual({ hasDefault: true, hasNamed: false })
+  })
+
+  test('finds a default function declaration', () => {
+    expect(describeExports(ts, inSrc('point/get-name.ts'))).toEqual({ hasDefault: true, hasNamed: false })
+  })
+
+  test('finds named exports (types)', () => {
+    expect(describeExports(ts, inSrc('point/types.ts'))).toEqual({ hasDefault: false, hasNamed: true })
+  })
+
+  test('finds both when a file has both', () => {
+    expect(describeExports(ts, inSrc('line/length.ts'))).toEqual({ hasDefault: true, hasNamed: true })
+  })
+
+  test('understands export lists and re-exports', () => {
+    write(inSrc('lists.ts'), "const a = 1\nconst b = 2\nexport { a as default, b }\nexport * from './point/types'\n")
+    expect(describeExports(ts, inSrc('lists.ts'))).toEqual({ hasDefault: true, hasNamed: true })
+  })
+})
+
+describe('writeDocEntries', () => {
+  test('writes one entry file for each folder which has source', () => {
+    const entryDir = `${gulpConfig.get('srcPath')}/../entries`
+    const entries = writeDocEntries(ts, gulpConfig.get('srcPath'), entryDir)
+    expect(entries.map(entry => path.basename(entry)).sort()).toEqual(['line.ts', 'point.ts'])
+  })
+
+  test('re-exports the default of each file by its name and the named exports as they are', () => {
+    const entryDir = `${gulpConfig.get('srcPath')}/../entries`
+    writeDocEntries(ts, gulpConfig.get('srcPath'), entryDir)
+    const absoluteSrc = path.resolve(gulpConfig.get('srcPath')).split(path.sep).join('/')
+    expect(fs.readFileSync(`${entryDir}/point.ts`, 'utf8').trim().split('\n')).toEqual([
+      `export { default as add } from '${absoluteSrc}/point/add'`,
+      `export { default as getName } from '${absoluteSrc}/point/get-name'`,
+      `export * from '${absoluteSrc}/point/types'`
+    ])
+    expect(fs.readFileSync(`${entryDir}/line.ts`, 'utf8').trim().split('\n')).toEqual([
+      `export { default as length } from '${absoluteSrc}/line/length'`,
+      `export * from '${absoluteSrc}/line/length'`
+    ])
+  })
+
+  test('leaves out index files, tests and declaration files', () => {
+    const entryDir = `${gulpConfig.get('srcPath')}/../entries`
+    writeDocEntries(ts, gulpConfig.get('srcPath'), entryDir)
+    const entry = fs.readFileSync(`${entryDir}/point.ts`, 'utf8')
+    expect(entry).not.toMatch(/index|\.test|add\.d/)
+  })
+
+  test('makes one entry called index when the source has no folders', () => {
+    const flat = `${gulpConfig.get('srcPath')}/../flat`
+    write(`${flat}/one.ts`, 'export default 1\n')
+    write(`${flat}/main.ts`, 'export default 2\n')
+    const entries = writeDocEntries(ts, flat, `${flat}/../flat-entries`)
+    expect(entries.map(entry => path.basename(entry))).toEqual(['index.ts'])
+    expect(fs.readFileSync(entries[0], 'utf8')).toMatch(/default as one/)
+    expect(fs.readFileSync(entries[0], 'utf8')).not.toMatch(/main/)
+  })
+})
+
+describe('typeDocsFor', () => {
+  const fakeTypeDoc = calls => () => Promise.resolve({
+    Application: {
+      bootstrap: async options => {
+        calls.options = options
+        calls.entryContents = options.entryPoints.map(entry => fs.readFileSync(entry, 'utf8'))
+        calls.tsconfig = JSON.parse(fs.readFileSync(options.tsconfig, 'utf8'))
+        return {
+          convert: async () => ({ name: 'project' }),
+          generateDocs: async (project, out) => {
+            calls.generated = { project, out }
+            fs.mkdirSync(out, { recursive: true })
+            fs.writeFileSync(`${out}/index.html`, '<html></html>')
+          }
+        }
+      }
+    }
+  })
+
+  test('generates the documentation into the output directory, clearing what was there', done => {
+    gulpConfig.set('docs.enabled', true)
+    const outPath = `${gulpConfig.get('srcPath')}/../docs`
+    write(`${outPath}/stale.html`, 'old')
+    const calls = {}
+    typeDocsFor(gulpConfig.get('srcPath'), outPath, fakeTypeDoc(calls))(() => {
+      expect(fs.existsSync(`${outPath}/stale.html`)).toBe(false)
+      expect(fs.existsSync(`${outPath}/index.html`)).toBe(true)
+      expect(calls.generated.out).toBe(outPath)
+      expect(calls.options.entryPoints.map(entry => path.basename(entry)).sort()).toEqual(['line.ts', 'point.ts'])
+      expect(calls.options.skipErrorChecking).toBe(true)
+      done()
+    })
+  })
+
+  test('uses the front page and the title from the config, and none when the front page is missing', async () => {
+    gulpConfig.set('docs.enabled', true)
+    gulpConfig.set('docs.title', 'my-title')
+    gulpConfig.set('docs.index', `${gulpConfig.get('srcPath')}/../MAIN.md`)
+    write(`${gulpConfig.get('srcPath')}/../MAIN.md`, '# hello\n')
+    const calls = {}
+    await typeDocsFor(gulpConfig.get('srcPath'), `${gulpConfig.get('srcPath')}/../docs`, fakeTypeDoc(calls))()
+    expect(calls.options.name).toBe('my-title')
+    expect(calls.options.readme).toBe(`${gulpConfig.get('srcPath')}/../MAIN.md`)
+    gulpConfig.set('docs.index', 'does-not-exist.md')
+    await typeDocsFor(gulpConfig.get('srcPath'), `${gulpConfig.get('srcPath')}/../docs`, fakeTypeDoc(calls))()
+    expect(calls.options.readme).toBe('none')
+  })
+
+  test('reads the source with the tsconfig of the project, adding the entries to it', async () => {
+    gulpConfig.set('docs.enabled', true)
+    gulpConfig.set('typescript.config', 'tsconfig.json')
+    const calls = {}
+    await typeDocsFor(gulpConfig.get('srcPath'), `${gulpConfig.get('srcPath')}/../docs`, fakeTypeDoc(calls))()
+    expect(calls.tsconfig.extends).toBe(path.resolve('tsconfig.json'))
+    expect(calls.tsconfig.include).toHaveLength(2)
+    expect(calls.tsconfig.exclude[0]).toMatch(/\*\*\/\*\.test\.\*$/)
+    gulpConfig.set('docs.tsconfig', 'other.json')
+    await typeDocsFor(gulpConfig.get('srcPath'), `${gulpConfig.get('srcPath')}/../docs`, fakeTypeDoc(calls))()
+    expect(calls.tsconfig.extends).toBe(path.resolve('other.json'))
+    gulpConfig.set('docs.tsconfig', false)
+    gulpConfig.set('typescript.config', false)
+  })
+
+  test('fails with a clear error when TypeDoc could not read the source', async () => {
+    gulpConfig.set('docs.enabled', true)
+    const failing = () => Promise.resolve({
+      Application: { bootstrap: async () => ({ convert: async () => undefined }) }
+    })
+    await expect(typeDocsFor(gulpConfig.get('srcPath'), `${gulpConfig.get('srcPath')}/../docs`, failing)()).rejects.toThrow(/could not read the TypeScript source/)
+  })
+
+  test('skips if docs.enabled is false', () => {
+    gulpConfig.set('docs.enabled', false)
+    const result = typeDocsFor()
+    expect(result).toBeInstanceOf(Function)
+    expect(result()).toBeUndefined()
+  })
+})
+
+describe('loadTypeDoc', () => {
+  // The real import() of the ESM-only TypeDoc cannot run in this project's CommonJS-transform-based Jest setup (see
+  // tsFor.mjs), so loading it for real is checked by generating the documentation of a project, see the pull request.
+
+  test('explains how to install typedoc when the project does not have it', async () => {
+    await expect(loadTypeDoc('/')).rejects.toThrow(/optional peer dependency typedoc.*npm install --save-dev typedoc/)
+  })
+})

package/functions/partials.mjs

@@ -22,3 +22,4 @@ export { runOnChange } from './partials/runOnChange.mjs'
 export { sassFor } from './partials/sassFor.mjs'
 export { standardLint } from './partials/standardLint.mjs'
 export { tsFor } from './partials/tsFor.mjs'
+export { typeDocsFor } from './partials/typeDocsFor.mjs'

package/functions/partials.test.mjs

@@ -2,6 +2,6 @@ import * as partials from './partials.mjs'
 
 describe('partials', () => {
   test('is object with all partial exports', () => {
-    expect(Object.keys(partials).length).toBe(15)
+    expect(Object.keys(partials).length).toBe(16)
   })
 })

package/functions/typeDocs.mjs

@@ -0,0 +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()

package/functions/typeDocs.test.mjs

@@ -0,0 +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)
+  })
+})