js-build-tools 6.5.0 → 6.7.0

package/functions/partials/typeDocsFor.test.mjs

@@ -1,252 +1,263 @@
-import fs from 'fs'
-import path from 'node:path'
-import ts from 'typescript'
-import * as setUp from '../test-helpers/setUp.mjs'
-import { describeExports, describeFile, 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('describeFile', () => {
-  test('is the header comment of a file, without its tags', () => {
-    write(`${gulpConfig.get('srcPath')}/header.ts`, "/**\n * Simulate what a user does.\n * @module simulate\n */\nimport a from './a'\nexport default a\n")
-    expect(describeFile(`${gulpConfig.get('srcPath')}/header.ts`)).toBe('Simulate what a user does.')
-  })
-
-  test('is empty when the first comment documents a declaration', () => {
-    write(`${gulpConfig.get('srcPath')}/declaration.ts`, '/**\n * Add two numbers.\n */\nconst add = (a: number, b: number) => a + b\nexport default add\n')
-    expect(describeFile(`${gulpConfig.get('srcPath')}/declaration.ts`)).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 a module of a file which sits beside the folders, but not of the barrel files', () => {
-    const srcPath = gulpConfig.get('srcPath')
-    write(`${srcPath}/simulate.ts`, "/**\n * Simulate what a user does.\n */\nimport add from './point/add'\nexport const click = () => add(1, 2)\nexport default { click }\n")
-    write(`${srcPath}/simulate.test.ts`, "test('x', () => {})\n")
-    write(`${srcPath}/browser.ts`, "export * from './main'\n")
-    const entryDir = `${srcPath}/../entries`
-    const entries = writeDocEntries(ts, srcPath, entryDir)
-    expect(entries.map(entry => path.basename(entry)).sort()).toEqual(['line.ts', 'point.ts', 'simulate.ts'])
-    const absoluteSrc = path.resolve(srcPath).split(path.sep).join('/')
-    expect(fs.readFileSync(`${entryDir}/simulate.ts`, 'utf8')).toBe(
-      `/**\n * Simulate what a user does.\n * @module\n */\n\nexport { default as simulate } from '${absoluteSrc}/simulate'\nexport * from '${absoluteSrc}/simulate'\n`
-    )
-  })
-
-  test('makes a module of each nested folder, named by its path, holding only the files directly in it', () => {
-    const srcPath = gulpConfig.get('srcPath')
-    write(`${srcPath}/point/polar/to-polar.ts`, 'export default (x: number): number => x\n')
-    write(`${srcPath}/point/polar/index.ts`, "/**\n * Polar coordinates.\n */\nexport * from './to-polar'\n")
-    write(`${srcPath}/point/deep/index.ts`, "export * from './deeper/far'\n")
-    write(`${srcPath}/point/deep/deeper/far.ts`, 'export const far = 1\n')
-    const entryDir = `${srcPath}/../entries`
-    const entries = writeDocEntries(ts, srcPath, entryDir)
-    const absoluteEntries = path.resolve(entryDir)
-    expect(entries.map(entry => path.relative(absoluteEntries, entry).split(path.sep).join('/')).sort())
-      .toEqual(['line.ts', 'point.ts', 'point/deep/deeper.ts', 'point/polar.ts'])
-    const absoluteSrc = path.resolve(srcPath).split(path.sep).join('/')
-    expect(fs.readFileSync(`${entryDir}/point.ts`, 'utf8')).not.toMatch(/polar|deep/)
-    expect(fs.readFileSync(`${entryDir}/point/polar.ts`, 'utf8')).toBe(
-      `/**\n * Polar coordinates.\n * @module point/polar\n */\n\nexport { default as toPolar } from '${absoluteSrc}/point/polar/to-polar'\n`
-    )
-    // A folder with only an index file (point/deep) has no module, and one without a description is still named
-    expect(fs.readFileSync(`${entryDir}/point/deep/deeper.ts`, 'utf8')).toBe(
-      `/**\n * @module point/deep/deeper\n */\n\nexport * from '${absoluteSrc}/point/deep/deeper/far'\n`
-    )
-  })
-
-  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/)
-  })
-})
+import fs from 'fs'
+import path from 'node:path'
+import ts from 'typescript'
+import * as setUp from '../test-helpers/setUp.mjs'
+import { describeExports, describeFile, 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('describeFile', () => {
+  test('is the header comment of a file, without its tags', () => {
+    write(`${gulpConfig.get('srcPath')}/header.ts`, "/**\n * Simulate what a user does.\n * @module simulate\n */\nimport a from './a'\nexport default a\n")
+    expect(describeFile(`${gulpConfig.get('srcPath')}/header.ts`)).toBe('Simulate what a user does.')
+  })
+
+  test('is empty when the first comment documents a declaration', () => {
+    write(`${gulpConfig.get('srcPath')}/declaration.ts`, '/**\n * Add two numbers.\n */\nconst add = (a: number, b: number) => a + b\nexport default add\n')
+    expect(describeFile(`${gulpConfig.get('srcPath')}/declaration.ts`)).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 a module of a file which sits beside the folders, but not of the barrel files', () => {
+    const srcPath = gulpConfig.get('srcPath')
+    write(`${srcPath}/simulate.ts`, "/**\n * Simulate what a user does.\n */\nimport add from './point/add'\nexport const click = () => add(1, 2)\nexport default { click }\n")
+    write(`${srcPath}/simulate.test.ts`, "test('x', () => {})\n")
+    write(`${srcPath}/browser.ts`, "export * from './main'\n")
+    const entryDir = `${srcPath}/../entries`
+    const entries = writeDocEntries(ts, srcPath, entryDir)
+    expect(entries.map(entry => path.basename(entry)).sort()).toEqual(['line.ts', 'point.ts', 'simulate.ts'])
+    const absoluteSrc = path.resolve(srcPath).split(path.sep).join('/')
+    expect(fs.readFileSync(`${entryDir}/simulate.ts`, 'utf8')).toBe(
+      `/**\n * Simulate what a user does.\n * @module\n */\n\nexport { default as simulate } from '${absoluteSrc}/simulate'\nexport * from '${absoluteSrc}/simulate'\n`
+    )
+  })
+
+  test('makes a module of each nested folder, named by its path, holding only the files directly in it', () => {
+    const srcPath = gulpConfig.get('srcPath')
+    write(`${srcPath}/point/polar/to-polar.ts`, 'export default (x: number): number => x\n')
+    write(`${srcPath}/point/polar/index.ts`, "/**\n * Polar coordinates.\n */\nexport * from './to-polar'\n")
+    write(`${srcPath}/point/deep/index.ts`, "export * from './deeper/far'\n")
+    write(`${srcPath}/point/deep/deeper/far.ts`, 'export const far = 1\n')
+    const entryDir = `${srcPath}/../entries`
+    const entries = writeDocEntries(ts, srcPath, entryDir)
+    const absoluteEntries = path.resolve(entryDir)
+    expect(entries.map(entry => path.relative(absoluteEntries, entry).split(path.sep).join('/')).sort())
+      .toEqual(['line.ts', 'point.ts', 'point/deep/deeper.ts', 'point/polar.ts'])
+    const absoluteSrc = path.resolve(srcPath).split(path.sep).join('/')
+    expect(fs.readFileSync(`${entryDir}/point.ts`, 'utf8')).not.toMatch(/polar|deep/)
+    expect(fs.readFileSync(`${entryDir}/point/polar.ts`, 'utf8')).toBe(
+      `/**\n * Polar coordinates.\n * @module point/polar\n */\n\nexport { default as toPolar } from '${absoluteSrc}/point/polar/to-polar'\n`
+    )
+    // A folder with only an index file (point/deep) has no module, and one without a description is still named
+    expect(fs.readFileSync(`${entryDir}/point/deep/deeper.ts`, 'utf8')).toBe(
+      `/**\n * @module point/deep/deeper\n */\n\nexport * from '${absoluteSrc}/point/deep/deeper/far'\n`
+    )
+  })
+
+  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('passes docs.gitRevision on to TypeDoc, and leaves TypeDoc\'s own default when it is false', async () => {
+    gulpConfig.set('docs.enabled', true)
+    const calls = {}
+    await typeDocsFor(gulpConfig.get('srcPath'), `${gulpConfig.get('srcPath')}/../docs`, fakeTypeDoc(calls))()
+    expect('gitRevision' in calls.options).toBe(false)
+    gulpConfig.set('docs.gitRevision', 'main')
+    await typeDocsFor(gulpConfig.get('srcPath'), `${gulpConfig.get('srcPath')}/../docs`, fakeTypeDoc(calls))()
+    expect(calls.options.gitRevision).toBe('main')
+    gulpConfig.set('docs.gitRevision', false)
+  })
+
+  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

@@ -1,31 +1,31 @@
-/**
- * Micro-functions used as components for the main gulp functions.
- * @file
- * @author Joshua Heagle <joshuaheagle@gmail.com>
- * @version 3.0.0
- * @module partials
- * @memberOf module:js-build-tools
- */
-
-export { addToReadme } from './partials/addToReadme.mjs'
-export { beginWatcher } from './partials/beginWatcher.mjs'
-export { clean } from './partials/clean.mjs'
-export { copyFor } from './partials/copyFor.mjs'
-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 { jsdocDocsFor } from './partials/jsdocDocsFor.mjs'
-export { loadPlaywright, launchBrowser } from './partials/loadPlaywright.mjs'
-export { lintSource } from './partials/lintSource.mjs'
-export { minifyFor } from './partials/minifyFor.mjs'
-export { neostandardLint } from './partials/neostandardLint.mjs'
-export { readmeTemplate } from './partials/readmeTemplate.mjs'
-export { removeDirectory } from './partials/removeDirectory.mjs'
-export { resolveDocsMethod } from './partials/resolveDocsMethod.mjs'
-export { runOnChange } from './partials/runOnChange.mjs'
-export { sassFor } from './partials/sassFor.mjs'
-export { serveStatic } from './partials/serveStatic.mjs'
-export { tsFor } from './partials/tsFor.mjs'
-export { typeDocsFor } from './partials/typeDocsFor.mjs'
+/**
+ * Micro-functions used as components for the main gulp functions.
+ * @file
+ * @author Joshua Heagle <joshuaheagle@gmail.com>
+ * @version 3.0.0
+ * @module partials
+ * @memberOf module:js-build-tools
+ */
+
+export { addToReadme } from './partials/addToReadme.mjs'
+export { beginWatcher } from './partials/beginWatcher.mjs'
+export { clean } from './partials/clean.mjs'
+export { copyFor } from './partials/copyFor.mjs'
+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 { jsdocDocsFor } from './partials/jsdocDocsFor.mjs'
+export { loadPlaywright, launchBrowser } from './partials/loadPlaywright.mjs'
+export { lintSource } from './partials/lintSource.mjs'
+export { minifyFor } from './partials/minifyFor.mjs'
+export { neostandardLint } from './partials/neostandardLint.mjs'
+export { readmeTemplate } from './partials/readmeTemplate.mjs'
+export { removeDirectory } from './partials/removeDirectory.mjs'
+export { resolveDocsMethod } from './partials/resolveDocsMethod.mjs'
+export { runOnChange } from './partials/runOnChange.mjs'
+export { sassFor } from './partials/sassFor.mjs'
+export { serveStatic } from './partials/serveStatic.mjs'
+export { tsFor } from './partials/tsFor.mjs'
+export { typeDocsFor } from './partials/typeDocsFor.mjs'

package/functions/partials.test.mjs

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

package/functions/sass.mjs

@@ -1,4 +1,4 @@
-import { sassFor } from './partials/sassFor.mjs'
-
-// Compile sass into CSS & auto-inject into browsers
-export const sass = () => sassFor()
+import { sassFor } from './partials/sassFor.mjs'
+
+// Compile sass into CSS & auto-inject into browsers
+export const sass = () => sassFor()