@plugjs/plug 0.0.1

package/src/plugs/exec.ts

@@ -0,0 +1,215 @@
+import path from 'node:path'
+import reaadline from 'node:readline'
+
+import { spawn, SpawnOptions } from 'node:child_process'
+import { assert } from '../assert.js'
+import { currentRun } from '../async.js'
+import { Files } from '../files.js'
+import { $p, logOptions } from '../log.js'
+import { AbsolutePath, getCurrentWorkingDirectory, isDirectory } from '../paths.js'
+import { install, Plug } from '../pipe.js'
+import { Run } from '../run.js'
+import { parseOptions, ParseOptions } from '../utils/options.js'
+
+/** Options for executing scripts */
+export interface ExecOptions {
+  /** Extra environment variables, or overrides for existing ones */
+  env?: Record<string, any>,
+  /** Whether to run in the context of a _shell_ or not */
+  shell?: string | boolean,
+  /**
+   * The current working directory of the process to execute.
+   *
+   * Defaults to the current {@link Files.directory | Files' directory} when
+   * used as a {@link Plug} or `process.cwd()` when used from {@link exec}.
+   */
+  cwd?: string
+  /**
+   * When used as a {@link Plug}, the {@link Files} will be appended to the
+   * current arguments as _relative_ files (default) or _absolute_ (if false).
+   */
+  relativePaths?: boolean
+}
+
+/**
+ * Execute a shell command, adding to its _arguments_ the list of files from
+ * the current pipe (much like `xargs` does on Unix systems).
+ *
+ * This {@link Plug} returns the same {@link Files} it was given, so that
+ * executing a shell command doesn't interrupt a {@link Pipe}.
+ *
+ * For example:
+ *
+ * ```
+ * import { find, exec } from '@plugjs/plugjs'
+ *
+ * export default build({
+ *   async runme() {
+ *     find('*.ts', { directory: 'src' })
+ *       .plug(new Exec('chmod', '755' }))
+ *       .plug(new Exec('chown root:root', { shell: true }))
+ *   },
+ * })
+ * ```
+ */
+export class Exec implements Plug<Files> {
+  private readonly _cmd: string
+  private readonly _args: readonly string[]
+  private readonly _options: ExecOptions
+
+  constructor(cmd: string, ...args: ParseOptions<ExecOptions>) {
+    const { params, options } = parseOptions(args, {})
+    this._cmd = cmd
+    this._args = params
+    this._options = options
+  }
+
+  async pipe(files: Files, run: Run): Promise<Files> {
+    const { relativePaths = true, ...options } = this._options
+
+    if (! options.cwd) options.cwd = files.directory
+
+    // What to use as extra arguments? Relative or absolute paths?
+    const params = [ ...(relativePaths ? files : files.absolutePaths() ) ]
+
+    // In case of shell usage, each extra parameter (file) gets quoted!
+    if (options.shell) params.forEach((s, i, a) => a[i] = JSON.stringify(s))
+
+    // Run our child
+    await spawnChild(this._cmd, [ ...this._args, ...params ], options, run)
+
+    // Return our files
+    return files
+  }
+}
+
+/**
+ * Execute a command and await for its result from within a task.
+ *
+ * For example:
+ *
+ * ```
+ * import { exec } from '@plugjs/plugjs'
+ *
+ * export default build({
+ *   async runme() {
+ *     await exec('ls', '-la', '/')
+ *   },
+ * })
+ * ```
+ */
+
+export function exec(cmd: string, ...args: ParseOptions<ExecOptions>): Promise<void> {
+  const run = currentRun()
+  assert(run, 'Unable to execute commands outside a running task')
+
+  const { params, options } = parseOptions(args, {})
+  return spawnChild(cmd, params, options, run)
+}
+
+
+/* ========================================================================== *
+ * INSTALLATION                                                               *
+ * ========================================================================== */
+
+install('exec', Exec)
+
+declare module '../pipe.js' {
+  export interface Pipe {
+    /**
+     * Execute a shell command, adding to its _arguments_ the list of files
+     * from the current pipe (much like `xargs` does on Unix systems).
+     *
+     * For example:
+     *
+     * ```
+     * import { find, exec } from '@plugjs/plugjs'
+     *
+     * export default build({
+     *   async runme() {
+     *     find('*.ts', { directory: 'src' })
+     *       .exec('chmod', '755' })
+     *       .exec('chown root:root', { shell: true })
+     *   },
+     * })
+     * ```
+     */
+    exec: PipeExtension<typeof Exec>
+  }
+}
+
+/* ========================================================================== *
+ * INTERNALS                                                                  *
+ * ========================================================================== */
+
+async function spawnChild(
+    cmd: string,
+    args: readonly string[],
+    options: ExecOptions = {},
+    run: Run,
+): Promise<void> {
+  const {
+    env = {}, // default empty environment
+    shell = false, // by default do not use a shell
+    cwd = undefined, // by default use "process.cwd()"
+    ...extraOptions
+  } = options
+
+  const childCwd = cwd ? run.resolve(cwd) : getCurrentWorkingDirectory()
+  assert(isDirectory(childCwd), `Current working directory ${$p(childCwd)} does not exist`)
+
+  // Figure out the PATH environment variable
+  const childPaths: AbsolutePath[] = []
+
+  // The `.../node_modules/.bin` path relative to the current working dir */
+  const baseNodePath = run.resolve('@node_modules', '.bin')
+  if (isDirectory(baseNodePath)) childPaths.push(baseNodePath)
+
+  // The `.../node_bodules/.bin` path relative to the buildDir */
+  const buildNodePath = run.resolve('./node_modules', '.bin')
+  if (isDirectory(buildNodePath)) childPaths.push(buildNodePath)
+
+  // Any other paths either from `process.env` or `env` (which overrides it)
+  const extraPath = env.PATH || process.env.PATH
+  if (extraPath) childPaths.push(extraPath)
+
+  // Build our environment variables record
+  const PATH = childPaths.join(path.delimiter)
+  const __LOG_OPTIONS = JSON.stringify(logOptions.fork(run.taskName))
+  const childEnv = { ...process.env, ...env, PATH, __LOG_OPTIONS }
+
+  // Prepare the options for calling `spawn`
+  const childOptions: SpawnOptions = {
+    ...extraOptions,
+    stdio: [ 'ignore', 'pipe', 'pipe' ],
+    cwd: childCwd,
+    env: childEnv,
+    shell,
+  }
+
+  // Spawn our subprocess and monitor its stdout/stderr
+  run.log.info('Executing', [ cmd, ...args ])
+  run.log.info('Execution options', childOptions)
+  const child = spawn(cmd, args, childOptions)
+
+  if (child.stdout) {
+    const out = reaadline.createInterface(child.stdout)
+    out.on('line', (line) => line ? run.log.notice(line) : run.log.notice('\u00a0'))
+  }
+
+  if (child.stderr) {
+    const err = reaadline.createInterface(child.stderr)
+    err.on('line', (line) => line ? run.log.warn(line) : run.log.warn('\u00a0'))
+  }
+
+  // Return our promise from the spawn events
+  return new Promise<void>((resolve, reject) => {
+    child.on('error', (error) => reject(error))
+    child.on('exit', (code, signal) => {
+      if (code === 0) return resolve()
+      if (signal) return reject(new Error(`Child process exited with signal ${signal}`))
+      if (code) return reject(new Error(`Child process exited with code ${code}`))
+      reject(new Error('Child process failed for an unknown reason'))
+    })
+  })
+}

package/src/plugs/filter.ts

@@ -0,0 +1,56 @@
+import { Files } from '../files.js'
+import { log } from '../log.js'
+import { resolveRelativeChildPath } from '../paths.js'
+import { install, Plug } from '../pipe.js'
+import { Run } from '../run.js'
+import { match, MatchOptions } from '../utils/match.js'
+import { ParseOptions, parseOptions } from '../utils/options.js'
+
+/** Options for filtering {@link Files}. */
+export interface FilterOptions extends MatchOptions {
+  /** The base directory for filtering, and relativising the resulting files. */
+  directory?: string
+}
+
+/** Filter the current {@link Files} using globs. */
+export class Filter implements Plug<Files> {
+  private readonly _globs: readonly [ string, ...readonly string[] ]
+  private readonly _options: FilterOptions
+
+  constructor(glob: string, ...args: ParseOptions<FilterOptions>) {
+    const { params, options } = parseOptions(args, {})
+    this._globs = [ glob, ...params ]
+    this._options = options
+  }
+
+  pipe(files: Files, run: Run): Files {
+    const { directory, ...options } = this._options
+
+    const builder = run.files(directory || files.directory)
+    const matcher = match(this._globs, options)
+
+    for (const file of files.absolutePaths()) {
+      const relative = resolveRelativeChildPath(builder.directory, file)
+      if (relative && matcher(relative)) builder.add(relative)
+    }
+
+    const result = builder.build()
+    const discarded = files.length - result.length
+    log.debug('Filtered', result.length, 'files (discarded', discarded, 'files)')
+
+    return result
+  }
+}
+
+/* ========================================================================== *
+ * INSTALLATION                                                               *
+ * ========================================================================== */
+
+install('filter', Filter)
+
+declare module '../pipe.js' {
+  export interface Pipe {
+    /** Filter the current {@link Files} using globs. */
+    filter: PipeExtension<typeof Filter>
+  }
+}

package/src/plugs/mocha/reporter.ts

@@ -0,0 +1,152 @@
+import RealMocha from 'mocha' // Mocha types pollute the global scope!
+
+import { AssertionError } from 'assert'
+import { diffJson } from 'diff'
+import { $blu, $grn, $gry, $ms, $red, $wht, $ylw, ERROR, Logger, NOTICE, WARN } from '../../log.js'
+
+const _pending = '\u22EF' // middle ellipsis
+const _success = '\u2714' // heavy check mark
+const _failure = '\u2718' // heavy ballot x
+const _details = '\u21B3' // downwards arrow with tip rightwards
+
+/* ========================================================================== *
+ * LOGGER / REPORTER                                                          *
+ * ========================================================================== */
+
+/** Symbol to inject `Logger` in reporter options */
+export const logSymbol = Symbol()
+/** Symbol to inject `Run` in reporter options */
+export const runSymbol = Symbol()
+
+export class PlugReporter extends RealMocha.reporters.Base {
+  constructor(runner: RealMocha.Runner, options: RealMocha.MochaOptions) {
+    super(runner, options)
+
+    const showDiff = !! options.diff
+    const log = options.reporterOptions[logSymbol] as Logger
+    const failures: RealMocha.Test[] = []
+    const rootSuite = runner.suite
+
+    // Enter a suite (increase indent)
+    runner.on('suite', (suite) => {
+      if (suite === rootSuite) return
+      log.notice('')
+      log.enter(NOTICE, `${$wht(suite.title)}`)
+    })
+
+    // Leave a suite (decrease indent)
+    runner.on('suite end', () => {
+      log.leave()
+    })
+
+    // Enter a test (increase indent)
+    runner.on('test', (test) => {
+      log.enter(NOTICE, `${$blu(_pending)} ${test.title}`)
+    })
+
+    // Leave a test (handle warning/failures and decrease indent)
+    runner.on('test end', (test) => {
+      // TODO: slow!!!
+      if (test.isPassed()) {
+        log.leave(NOTICE, `${$grn(_success)} ${test.title}`)
+      } else if (test.isPending()) {
+        const tag = $gry('[') + $ylw('skipped') + $gry(']')
+        log.leave(WARN, `${$ylw(_pending)} ${test.title} ${tag}`)
+      } else if (test.isFailed()) {
+        const number = failures.push(test)
+        const tag = $gry('[') + $red('failed') + $gry('] [') + $red(number) + $gry(']')
+        log.leave(ERROR, `${$red(_failure)} ${test.title} ${tag}`)
+      }
+    })
+
+    // Mocha finished running, dump our report
+    runner.once('end', () => {
+      try {
+        // Each failure gets dumped individually
+        for (let i = 0; i < failures.length; i ++) {
+          log.notice('')
+          const failure = failures[i]
+
+          // The titles (from the suite, up to the test)
+          const titles = [ failure.title ]
+          for (let parent = failure.parent; parent; parent = parent?.parent) {
+            if (parent.parent) titles.unshift(parent.title)
+          }
+
+          // Log out our titles (one per line, indented)
+          log.error(`${$gry('Failure [')}${$red(i + 1)}${$gry(']')}`)
+          titles.forEach((title, indent) => {
+            log.error(`  ${''.padStart(indent * 4)}${$gry(_details)} ${$wht(title)}`)
+          })
+
+          // If we have an error, luckily this is an `Error` instance
+          if (failure.err) {
+            const message = `${failure.err}` // this is the message, can be multiple lines
+            const messageOrStack = failure.err.stack || `${failure.err}` // maybe a stack?
+            const messageIndex = messageOrStack.indexOf(message)
+
+            // Subtrack the message from the stack
+            const stack =
+              messageOrStack === message ? '' :
+              messageIndex < 0 ? messageOrStack :
+              messageOrStack.substring(messageIndex + message.length)
+
+            // Split and clean up stack lines
+            const stackLines = stack.split('\n')
+                .map((line) => line.trim())
+                .filter((line) => !! line)
+
+            // Output the message
+            log.enter(ERROR, '')
+            log.error($red(message))
+
+            // Should we diff?
+            if (showDiff && ('actual' in failure.err) && ('expected' in failure.err)) {
+              const err = failure.err as AssertionError
+              const actual =
+                err.actual === undefined ? '[undefined]' :
+                err.actual === null ? '[null]' :
+                err.actual
+
+              const expected =
+                err.expected === undefined ? '[undefined]' :
+                err.expected === null ? '[null]' :
+                err.expected
+
+              const changes = diffJson(actual as any, expected as any)
+
+              const diff = changes.map((change): string => {
+                if (change.removed) return $red(change.value)
+                if (change.added) return $grn(change.value)
+                return $gry(change.value)
+              }).join('')
+
+              log.enter(ERROR, `${$gry('diff')} ${$grn('expected')}  ${$gry('/')} ${$red('actual')}`)
+              log.error(diff)
+              log.leave()
+            }
+
+            // Dump our stack trace and leave
+            stackLines.forEach((line) => log.error(line))
+            log.leave()
+          }
+        }
+
+        // If we have some statistics, then let's dump them out in pretty colors
+        if (runner.stats) {
+          log.notice('')
+          const { passes, pending, failures, duration = 0 } = runner.stats
+          const fmt = (n: number): string => n === 1 ? `${n} test` : `${n} tests`
+          if (passes) log.notice($grn(fmt(passes)), 'passing', $ms(duration))
+          if (pending) log.warn($ylw(fmt(pending)), 'pending')
+          if (failures) log.error($red(fmt(failures)), 'pending')
+        }
+
+        // Done...
+        log.notice('')
+      } catch (error) {
+        log.error('Error rendering Mocha report', error)
+      }
+    })
+  }
+}

package/src/plugs/mocha/runner.ts

@@ -0,0 +1,77 @@
+import RealMocha from 'mocha' // Mocha types pollute the global scope!
+
+import { failure } from '../../assert.js'
+import { Files } from '../../files.js'
+import { $wht, NOTICE } from '../../log.js'
+import { Plug } from '../../pipe.js'
+import { Run } from '../../run.js'
+import { logSymbol, PlugReporter, runSymbol } from './reporter.js'
+
+/** Options to construct our {@link Mocha} plug. */
+export interface MochaOptions {
+  /** Specify the directory where coverage data will be saved */
+  coverageDir?: string,
+  /** Bail after first test failure? */
+  bail?: boolean,
+  /** Show diff on failure? */
+  diff?: boolean,
+  /** Report tests without running them? */
+  dryRun?: boolean,
+  /** Tests marked `only` fail the suite? */
+  forbidOnly?: boolean,
+  /** Pending tests fail the suite? */
+  forbidPending?: false,
+  /** Reporter name. */
+  reporter?: string
+  /** Options for the reporter */
+  reporterOptions?: Record<string, any>,
+  /** Number of times to retry failed tests. */
+  retries?: number,
+  /** Slow threshold value. */
+  slow?: number,
+  /** Timeout threshold value. */
+  timeout?: number,
+}
+
+/** Writes some info about the current {@link Files} being passed around. */
+export default class Mocha implements Plug<undefined> {
+  constructor(private readonly _options: MochaOptions = {}) {}
+
+  async pipe(files: Files, run: Run): Promise<undefined> {
+    // Enter log here, so that log messages called when loading files get
+    // properly indented by our logger
+    run.log.notice('') // empty line
+    run.log.enter(NOTICE, $wht('Starting Mocha'))
+
+    // Create the mocha runner
+    const mocha = new RealMocha({
+      diff: true, // by defaut enable diffs
+      reporter: PlugReporter, // default to our reporter
+      ...this._options, // override defaults with all other options
+      reporterOptions: {
+        ...this._options.reporterOptions,
+        [logSymbol]: run.log, // always force a log
+        [runSymbol]: run, // always force a run
+      },
+      allowUncaught: false, // never allow uncaught exceptions
+      delay: false, // never delay running
+    })
+
+    // Tell mocha about all our files
+    for (const file of files.absolutePaths()) mocha.addFile(file)
+
+    await mocha.loadFilesAsync()
+
+    // Run mocha!
+    return new Promise((resolve, reject) => {
+      try {
+        mocha.run((failures) => {
+          if (failures) reject(failure())
+          resolve(undefined)
+        })
+      } catch (error) {
+        reject(error)
+      }
+    })
+  }
+}

package/src/plugs/tsc/compiler.ts

@@ -0,0 +1,66 @@
+import ts from 'typescript' // TypeScript does NOT support ESM modules
+
+import { AbsolutePath, resolveAbsolutePath } from '../../paths.js'
+
+export class TypeScriptHost
+implements ts.CompilerHost {
+  constructor(directory: AbsolutePath)
+  constructor(private readonly _directory: AbsolutePath) {}
+
+  /* ======================================================================== */
+
+  /** Get a source file parsing one of our virtual files */
+  getSourceFile(
+      fileName: string,
+      languageVersion: ts.ScriptTarget,
+  ): ts.SourceFile | undefined {
+    const code = this.readFile(fileName)
+    return code ? ts.createSourceFile(fileName, code, languageVersion) : void 0
+  }
+
+  /** Never write any files */
+  writeFile(fileName: string): void {
+    throw new Error(`Cowardly refusing to write "${fileName}"`)
+  }
+
+  /** Get the default library associated with the given options */
+  getDefaultLibFileName(options: ts.CompilerOptions): string {
+    return ts.getDefaultLibFilePath(options)
+  }
+
+  /** Check for filesystem case sensitivity */
+  useCaseSensitiveFileNames(): boolean {
+    return ts.sys.useCaseSensitiveFileNames
+  }
+
+  /** Check for the existence of a given file */
+  fileExists(fileName: string): boolean {
+    return ts.sys.fileExists(resolveAbsolutePath(this.getCurrentDirectory(), fileName))
+  }
+
+  /** Read the file if it exists, otherwise return undefined */
+  readFile(fileName: string): string | undefined {
+    return ts.sys.readFile(resolveAbsolutePath(this.getCurrentDirectory(), fileName))
+  }
+
+  /** Return the current working directory */
+  getCurrentDirectory(): AbsolutePath {
+    return this._directory
+  }
+
+  /** Return the canonical name for the specified file */
+  getCanonicalFileName(fileName: string): string {
+    if (ts.sys.useCaseSensitiveFileNames) return fileName
+
+    // Lifted from TypeScript sources
+    const fileNameLowerCaseRegExp = /[^\u0130\u0131\u00DFa-z0-9\\/:\-_. ]+/g
+    return fileNameLowerCaseRegExp.test(fileName) ?
+      fileName.replace(fileNameLowerCaseRegExp, (s) => s.toLowerCase()) :
+      fileName
+  }
+
+  /** Return the new line sequence used by this platform */
+  getNewLine(): string {
+    return ts.sys.newLine
+  }
+}

package/src/plugs/tsc/options.ts

@@ -0,0 +1,97 @@
+import ts from 'typescript' // TypeScript does NOT support ESM modules
+
+import { AbsolutePath, getAbsoluteParent, resolveAbsolutePath } from '../../paths.js'
+import { readFile } from '../../utils/asyncfs.js'
+
+/* ========================================================================== */
+
+export type CompilerOptionsAndDiagnostics = {
+  options: ts.CompilerOptions,
+  errors: readonly ts.Diagnostic[],
+}
+
+/* ========================================================================== */
+
+function mergeResults(
+    base: CompilerOptionsAndDiagnostics,
+    override: CompilerOptionsAndDiagnostics,
+): CompilerOptionsAndDiagnostics {
+  return {
+    options: { ...base.options, ...override.options },
+    errors: [ ...base.errors, ...override.errors ],
+  }
+}
+
+/* ========================================================================== */
+
+async function loadOptions(
+    file: AbsolutePath,
+    stack: AbsolutePath[] = [ file ],
+): Promise<CompilerOptionsAndDiagnostics> {
+  const dir = getAbsoluteParent(file)
+
+  // Load up our config file and convert is wicked JSON
+  const data = await readFile(file, 'utf-8')
+  const { config, error } = ts.parseConfigFileTextToJson(file, data)
+  if (error) return { options: {}, errors: [ error ] }
+
+  // Parse up the configuration file as options
+  const { compilerOptions = {}, extends: extendsPath } = config
+  const result = ts.convertCompilerOptionsFromJson(compilerOptions, dir, file)
+  if (result.errors.length) return result
+
+  // If we don't extend, we can return our result
+  if (!extendsPath) return result
+
+  // Resolve the name of the file this config extends
+  const ext = resolveAbsolutePath(dir, extendsPath)
+
+  // Triple check that we are not recursively importing this file
+  if (stack.includes(ext)) {
+    return { options: {}, errors: [ {
+      messageText: `Circularity detected extending from "${ext}"`,
+      category: ts.DiagnosticCategory.Error,
+      code: 18000, // copied from typescript internals...
+      file: ts.createSourceFile(file, data, ts.ScriptTarget.JSON, false, ts.ScriptKind.JSON),
+      start: undefined,
+      length: undefined,
+    } ] }
+  }
+
+  // Push our file in the stack and load recursively
+  return mergeResults(await loadOptions(ext, [ ...stack, ext ]), result)
+}
+
+/* ========================================================================== */
+
+export async function getCompilerOptions(
+  file?: AbsolutePath,
+): Promise<CompilerOptionsAndDiagnostics>
+
+export async function getCompilerOptions(
+  file: AbsolutePath | undefined,
+  overrides: ts.CompilerOptions,
+  overridesFile: AbsolutePath,
+): Promise<CompilerOptionsAndDiagnostics>
+
+/** Load compiler options from a JSON file, and merge in the overrides */
+export async function getCompilerOptions(
+    file?: AbsolutePath,
+    ...override: [ ts.CompilerOptions, AbsolutePath ] | []
+): Promise<CompilerOptionsAndDiagnostics> {
+  let result: CompilerOptionsAndDiagnostics = { options: ts.getDefaultCompilerOptions(), errors: [] }
+
+  // If we have a file to parse, load it, otherwise try "tsconfig.json"
+  if (file) result = mergeResults(result, await loadOptions(file))
+
+  // If we have overrides, merge them
+  if (override.length) {
+    const [ overrides, overridesFile ] = override
+    const overridesDir = getAbsoluteParent(overridesFile)
+    const options = ts.convertCompilerOptionsFromJson(overrides, overridesDir, overridesFile)
+    result = mergeResults(result, options)
+  }
+
+  // Return all we have
+  return result
+}