functions/utilities/convertMjsFilesForDocs.mjsjavascript
import fs from 'fs'
import os from 'os'
import path from 'path'
import { esmNamedExportsToCjs } from './esmNamedExportsToCjs.mjs'

/**
 * Writes a rewritten (see {@link esmNamedExportsToCjs}) copy of each given `.mjs` file into a fresh, unique
 * directory under the OS temp directory, with a `.js` extension - jsdoc-to-markdown only recognizes `.js` as a
 * documentable file, regardless of whether its contents are actually CommonJS or ESM (it parses the real ESM
 * syntax of the rest of a file fine; the extension is the only thing it filters on). Writing outside the project
 * tree means there is nothing to gitignore and nothing left behind in the project - call the returned `cleanUp`
 * once done (for example, right after jsdoc-to-markdown has read the files) to remove the temp directory.
 * @memberOf module:utilities
 * @param {Array<string>} mjsFilePaths - Real `.mjs` files to convert. An empty array is a safe, cheap no-op.
 * @returns {{filePaths: Array<string>, cleanUp: function(): void}} The temp `.js` file paths to pass to
 * jsdoc-to-markdown instead of the real `.mjs` ones, and a function to remove the temp directory afterward.
 * @private
 */
export const convertMjsFilesForDocs = (mjsFilePaths = []) => {
  if (mjsFilePaths.length === 0) {
    return { filePaths: [], cleanUp: () => {} }
  }
  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'js-build-tools-docs-'))
  const filePaths = mjsFilePaths.map((mjsFilePath) => {
    const tempFilePath = path.join(tempDir, path.basename(mjsFilePath, '.mjs') + '.js')
    const source = fs.readFileSync(mjsFilePath, 'utf8')
    fs.writeFileSync(tempFilePath, esmNamedExportsToCjs(source))
    return tempFilePath
  })
  return {
    filePaths,
    cleanUp: () => fs.rmSync(tempDir, { recursive: true, force: true })
  }
}