js-build-tools 5.3.0 → 5.3.2

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, describeFile, 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,30 @@ 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('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`
@@ -65,12 +89,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 +105,28 @@ 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 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")
+    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 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.2",
   "description": "Standardised build process with gulp.",
   "main": "gulpfile.base.js",
   "exports": {