js-build-tools 5.2.0 → 5.3.0

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

package/gulp.config.mjs

@@ -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.0",
   "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"
   }
 }