js-build-tools 5.2.0 → 5.3.1

package/functions/partials/typeDocsFor.mjs

@@ -0,0 +1,199 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import * as gulpConfig from '../../gulp.config.mjs'
+import { importPeer } from './loadPeer.mjs'
+import { loadTypescript } from './tsFor.mjs'
+import { removeDirectory } from './removeDirectory.mjs'
+
+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 = (projectPath = process.cwd()) => importPeer('typedoc', { task: 'docs', installHint, projectPath })
+
+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 }
+}
+
+/**
+ * The description of a folder for its module: the first doc comment of the folder's index file, without its tags
+ * (@module, @file, ...), or an empty string when there is none.
+ * @memberOf module:partials
+ * @param {string} folderPath
+ * @returns {string}
+ */
+export const describeFolder = folderPath => {
+  const indexFile = ['index.ts', 'index.tsx', 'index.mts', 'index.cts'].map(name => path.join(folderPath, name)).find(file => fs.existsSync(file))
+  const comment = indexFile && fs.readFileSync(indexFile, 'utf8').match(/^\s*\/\*\*([\s\S]*?)\*\//)
+  if (!comment) {
+    return ''
+  }
+  const lines = comment[1].split('\n').map(line => line.replace(/^\s*\* ?/, '').trimEnd())
+  const tagAt = lines.findIndex(line => /^@\w+/.test(line))
+  return (tagAt === -1 ? lines : lines.slice(0, tagAt)).join('\n').trim()
+}
+
+/**
+ * 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, but the first doc comment of a folder's index file becomes the description of its module. 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, path: path.join(absoluteSrc, entry.name), files: listSources(path.join(absoluteSrc, entry.name)) }))
+    .filter(folder => folder.files.length)
+  const groups = folders.length
+    ? folders
+    : [{ name: 'index', path: absoluteSrc, 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 description = group.path ? describeFolder(group.path) : ''
+    // TypeDoc takes the first comment of an entry file which has the @module tag as the description of the module
+    const moduleComment = description ? `/**\n${description.split('\n').map(line => ` * ${line}`.trimEnd()).join('\n')}\n * @module\n */\n\n` : ''
+    const entryPath = path.join(entryDir, `${group.name}.ts`)
+    fs.writeFileSync(entryPath, moduleComment + 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,204 @@
+import fs from 'fs'
+import path from 'node:path'
+import ts from 'typescript'
+import * as setUp from '../test-helpers/setUp.mjs'
+import { describeExports, describeFolder, 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`, "/**\n * Points of a matrix and the maths on them.\n * A second line.\n * @file Not part of the description\n * @module point\n */\nimport 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('describeFolder', () => {
+  test('is the text of the first comment of the index file, without its tags', () => {
+    expect(describeFolder(`${gulpConfig.get('srcPath')}/point`)).toBe('Points of a matrix and the maths on them.\nA second line.')
+  })
+
+  test('is empty without an index file, or a comment in it', () => {
+    expect(describeFolder(`${gulpConfig.get('srcPath')}/line`)).toBe('')
+    write(`${gulpConfig.get('srcPath')}/bare/index.ts`, "import a from './a'\nexport default { a }\n")
+    expect(describeFolder(`${gulpConfig.get('srcPath')}/bare`)).toBe('')
+  })
+})
+
+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('/')
+    const exportLines = file => fs.readFileSync(file, 'utf8').trim().split('\n').filter(line => line.startsWith('export'))
+    expect(exportLines(`${entryDir}/point.ts`)).toEqual([
+      `export { default as add } from '${absoluteSrc}/point/add'`,
+      `export { default as getName } from '${absoluteSrc}/point/get-name'`,
+      `export * from '${absoluteSrc}/point/types'`
+    ])
+    expect(exportLines(`${entryDir}/line.ts`)).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(/from '.*(index|\.test|add\.d)/)
+  })
+
+  test('describes the module with the first comment of the index file of the folder', () => {
+    const entryDir = `${gulpConfig.get('srcPath')}/../entries`
+    writeDocEntries(ts, gulpConfig.get('srcPath'), entryDir)
+    expect(fs.readFileSync(`${entryDir}/point.ts`, 'utf8')).toMatch(/^\/\*\*\n \* Points of a matrix and the maths on them\.\n \* A second line\.\n \* @module\n \*\/\n\nexport/)
+    // A folder without an index file has no comment
+    expect(fs.readFileSync(`${entryDir}/line.ts`, 'utf8').startsWith('export')).toBe(true)
+  })
+
+  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

@@ -15,6 +15,7 @@ export { distFor } from './partials/distFor.mjs'
 export { distForSrc } from './partials/distForSrc.mjs'
 export { distSeries } from './partials/distSeries.mjs'
 export { imagesFor } from './partials/imagesFor.mjs'
+export { importModule, importPeer, requirePeer } from './partials/loadPeer.mjs'
 export { minifyFor } from './partials/minifyFor.mjs'
 export { readmeTemplate } from './partials/readmeTemplate.mjs'
 export { removeDirectory } from './partials/removeDirectory.mjs'
@@ -22,3 +23,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(19)
   })
 })

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

package/gulp.config.mjs

@@ -49,8 +49,8 @@ import { fileExists } from 'test-filesystem'
  * 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 name to use for the browser-bundled output file (.js will be appended).
- * @property {StringSetting} name - The search pattern used for retrieving compiled distribution files.
+ * @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
@@ -91,6 +91,18 @@ import { fileExists } from 'test-filesystem'
  * @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 TypeScript project (with TypeDoc, from the source).
+ * @typedef {Object<string, Setting>} module:gulpConfig~DocsConfig
+ * @property {BooleanSetting} enabled - Toggle generating the documentation from the TypeScript 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 TypeScript source, each folder in it becomes a module.
+ * @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.
+ * @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, defaults to the one of typescript.config.
+ */
 /**
  * Configurations to compile and copy the sass files into css.
  * @typedef {Object<string, Setting>} module:gulpConfig~SassConfig
@@ -121,6 +133,7 @@ import { fileExists } from 'test-filesystem'
  * @property {BrowserConfig} browser - Browser bundling configuration group.
  * @property {ArrayableSetting} cleanPaths - The paths for directories to delete before build.
  * @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 {ReadmeConfig} readme - Build readme files configuration.
@@ -150,6 +163,15 @@ const setDefaults = {
     main: 'dist/main',
     to: 'dist',
   },
+  docs: {
+    enabled: false,
+    from: 'src',
+    index: 'MAIN.md',
+    logLevel: 'Warn',
+    title: '',
+    to: 'docs',
+    tsconfig: false,
+  },
   fonts: {
     enabled: false,
     from: 'src/fonts/**/*',

package/gulpfile.base.js

@@ -23,6 +23,7 @@ const sass = require('./dist/sass.js')
 const testFull = require('./dist/testFull.js')
 const testHelpers = require('./dist/testHelpers.js')
 const testQuick = require('./dist/testQuick.js')
+const typeDocs = require('./dist/typeDocs.js')
 const typescript = require('./dist/typeScript')
 const watchFull = require('./dist/watchFull.js')
 const watchTest = require('./dist/watchTest.js')
@@ -34,6 +35,7 @@ module.exports = {
   bundleMinify,
   copyFonts,
   defaultCmd,
+  docs: typeDocs,
   dist,
   distLint,
   distMinify,

package/gulpfile.base.mjs

@@ -22,6 +22,7 @@ export { sass } from './functions/sass.mjs'
 export { testFull } from './functions/testFull.mjs'
 export * as testHelpers from './functions/testHelpers.mjs'
 export { testQuick } from './functions/testQuick.mjs'
+export { typeDocs as docs } from './functions/typeDocs.mjs'
 export { typeScript as typescript } from './functions/typeScript.mjs'
 export { watchFull } from './functions/watchFull.mjs'
 export { watchTest } from './functions/watchTest.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-build-tools",
-  "version": "5.2.0",
+  "version": "5.3.1",
   "description": "Standardised build process with gulp.",
   "main": "gulpfile.base.js",
   "exports": {
@@ -52,9 +52,9 @@
     "@babel/preset-typescript": "^7.29.7",
     "@babel/runtime-corejs3": "^8.0.6",
     "autoprefixer": "^10.6.1",
-    "babel-jest": "^30.4.1",
+    "babel-jest": "^30.5.2",
     "browserify": "^17.0.1",
-    "core-js": "^3.49.0",
+    "core-js": "^3.50.0",
     "cssnano": "^6.1.2",
     "glob": "^13.0.6",
     "gulp": "^5.0.1",
@@ -63,27 +63,31 @@
     "gulp-postcss": "^10.0.0",
     "gulp-rename": "^2.1.0",
     "gulp-sass": "^6.0.1",
-    "gulp-ts-compile": "^1.0.0",
+    "gulp-ts-compile": "^1.0.1",
     "gulp-uglify-es": "^3.0.0",
     "jest": "^30.5.2",
-    "jest-environment-jsdom": "^30.4.1",
+    "jest-environment-jsdom": "^30.5.2",
     "jsdoc-to-markdown": "^9.1.3",
     "postcss": "^8.5.28",
     "regenerator-runtime": "^0.14.1",
-    "sass": "^1.101.0",
+    "sass": "^1.105.0",
     "standard": "^17.1.2",
-    "test-filesystem": "^1.5.0",
+    "test-filesystem": "^1.5.1",
     "through2": "^4.0.2",
     "vinyl-source-stream": "^2.0.0"
   },
   "peerDependencies": {
     "gulp-imagemin": ">=9.0.0",
+    "typedoc": ">=0.28.0",
     "typescript": ">=5.0.0 <7.0.0"
   },
   "peerDependenciesMeta": {
     "gulp-imagemin": {
       "optional": true
     },
+    "typedoc": {
+      "optional": true
+    },
     "typescript": {
       "optional": true
     }
@@ -101,6 +105,7 @@
   "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": {
     "gulp-imagemin": "github:jheagle/gulp-imagemin#common-js-compatibility",
+    "typedoc": "^0.28.20",
     "typescript": "^6.0.3"
   }
 }