functions/partials/tsFor.mjsjavascript
import { dest, src } from 'gulp'
import path from 'node:path'
import * as gulpConfig from '../../gulp.config.mjs'
import { importModule, requirePeer } from './loadPeer.mjs'

// gulp-ts-compile ships ESM-only (no CJS build - see its own package.json), see importModule for how it is imported.
const importGulpTsCompile = () => importModule('gulp-ts-compile')

/**
 * Wrap a stream in a promise that resolves once it finishes writing.
 * @memberOf module:partials
 * @param {stream.Stream} stream
 * @returns {Promise<void>}
 */
const installHint = 'Install it in your project with: npm install --save-dev typescript'

/**
 * Load the project's own copy of TypeScript (an optional peer dependency, only needed when the typescript task is
 * enabled) from the project being built, so projects which do not use TypeScript never need it installed.
 * @memberOf module:partials
 * @param {string} [projectPath=process.cwd()] The folder of the project (which has the package.json) being built.
 * @returns {Object} The TypeScript compiler API module.
 * @throws {Error} With install instructions when typescript is not installed.
 */
export const loadTypescript = (projectPath = process.cwd()) => requirePeer('typescript', { task: 'typescript', installHint, projectPath })

const streamToPromise = (stream) => new Promise((resolve, reject) => {
  stream.on('finish', resolve)
  stream.on('error', reject)
})

/**
 * Read a tsconfig.json file into real typescript.CompilerOptions values, using only TypeScript's stable, current,
 * public config-reading API (the same one `tsc --project` itself uses internally) - never
 * `ts.convertCompilerOptionsFromJson`, which is exactly the kind of internal/legacy surface that broke
 * gulp-typescript when a removed API call started throwing under TypeScript 7.
 * @memberOf module:partials
 * @param {string} configPath - Path to a tsconfig.json file.
 * @returns {ts.CompilerOptions} TypeScript's compiler options
 */
const readCompilerOptions = (ts, configPath) => {
  const configFile = ts.readConfigFile(configPath, ts.sys.readFile)
  const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path.dirname(configPath))
  return parsedConfig.options
}

/**
 * Starting at the source directory, find all the ts files and convert them into the distribution directory.
 * @memberOf module:partials
 * @param {string|array} [srcPath='']
 * @param {string} [distPath='']
 * @param {function(): Promise<Function>} [loadTsCompile] - Resolves the `gulp-ts-compile` default export. Real
 * callers should never need to pass this - it exists so tests can inject a stand-in compiler, sidestepping the
 * genuine dynamic `import()` above that this project's current CommonJS-transform-based Jest setup cannot
 * execute without a broader (and riskier) migration to Jest's native ESM support. gulp-ts-compile's own test
 * suite already covers real TypeScript-compile correctness - this function's own tests only need to verify its
 * config resolution and stream wiring.
 * @returns {Function}
 */
export const tsFor = (
  srcPath = gulpConfig.get('typescript.from'),
  distPath = gulpConfig.get('typescript.to'),
  loadTsCompile = () => importGulpTsCompile().then(({ default: tsCompile }) => tsCompile)
) => {
  if (gulpConfig.get('typescript.enabled') === false) {
    return () => {}
  }
  const ts = loadTypescript()
  const configPath = gulpConfig.get('typescript.config')
  // When no tsconfig.json is configured, target/module are pinned explicitly rather than left for TypeScript's
  // own compiler defaults - those defaults have already shifted once across a TypeScript version bump in this
  // project's own history (silently changing whether output keeps `const`/`let` or downlevels to `var`), and
  // pinning them keeps this task's output stable across future TypeScript upgrades too. ES5/CommonJS matches
  // what the downstream babel/browserify bundling pipeline has always assumed it receives.
  const compilerOptions = configPath
    ? readCompilerOptions(ts, configPath)
    : { declaration: true, target: ts.ScriptTarget.ES5, module: ts.ModuleKind.CommonJS, esModuleInterop: false }
  // Accepts gulp's own callback-style task convention (an optional `done`, called once finished) rather than
  // just returning a Promise, since callers may invoke the returned function directly with a callback instead
  // of relying on gulp's own runner to observe a returned Promise.
  return (done) => {
    const compile = async () => {
      const tsCompile = await loadTsCompile()
      const tsResult = src(srcPath).pipe(tsCompile(compilerOptions))
      await Promise.all([
        streamToPromise(tsResult.dts.pipe(dest(distPath))),
        streamToPromise(tsResult.js.pipe(dest(distPath)))
      ])
    }
    return typeof done === 'function' ? compile().then(() => done(), done) : compile()
  }
}