js-build-tools 5.3.0 → 5.3.1

package/functions/partials/typeDocsFor.mjs

@@ -1,16 +1,11 @@
 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 { importPeer } from './loadPeer.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'
 
 /**
@@ -21,18 +16,7 @@ const installHint = 'Install it in your project with: npm install --save-dev typ
  * @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)
-}
+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)
 
@@ -86,12 +70,30 @@ export const describeExports = (ts, filePath) => {
   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. A source directory with no folders gets a single entry called index.
+ * 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.
@@ -103,11 +105,11 @@ export const writeDocEntries = (ts, srcDir, entryDir) => {
   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)) }))
+    .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', files: listSources(absoluteSrc).filter(file => !/^(index|main)\./.test(path.basename(file))) }]
+    : [{ 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)))
@@ -121,8 +123,11 @@ export const writeDocEntries = (ts, srcDir, entryDir) => {
           ...(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, lines.join('\n') + '\n')
+    fs.writeFileSync(entryPath, moduleComment + lines.join('\n') + '\n')
     return entryPath
   })
 }

package/functions/partials/typeDocsFor.test.mjs

@@ -2,7 +2,7 @@ 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'
+import { describeExports, describeFolder, loadTypeDoc, typeDocsFor, writeDocEntries } from './typeDocsFor.mjs'
 
 setUp.setDefaults('test-type-docs-for')
 const gulpConfig = setUp.gulpConfig
@@ -19,7 +19,7 @@ beforeEach(
     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/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')
@@ -54,6 +54,18 @@ describe('describeExports', () => {
   })
 })
 
+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`
@@ -65,12 +77,13 @@ describe('writeDocEntries', () => {
     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([
+    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(fs.readFileSync(`${entryDir}/line.ts`, 'utf8').trim().split('\n')).toEqual([
+    expect(exportLines(`${entryDir}/line.ts`)).toEqual([
       `export { default as length } from '${absoluteSrc}/line/length'`,
       `export * from '${absoluteSrc}/line/length'`
     ])
@@ -80,7 +93,15 @@ describe('writeDocEntries', () => {
     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/)
+    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', () => {

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'

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(16)
+    expect(Object.keys(partials).length).toBe(19)
   })
 })

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-build-tools",
-  "version": "5.3.0",
+  "version": "5.3.1",
   "description": "Standardised build process with gulp.",
   "main": "gulpfile.base.js",
   "exports": {