@plugjs/plug 0.0.1

package/src/async.ts

@@ -0,0 +1,50 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { Run } from './run.js'
+
+/* ========================================================================== *
+ * EXPORTED                                                                   *
+ * ========================================================================== */
+
+/**
+ * Run the specified `callback` associating the specified {@link Run} and task
+ * name with the current asynchronous invocation context.
+ */
+export function runAsync<T>(run: Run, task: string, callback: () => Promise<T>): Promise<T> {
+  return storage.run({ run, task }, () => {
+    tasks.push(task)
+    return callback().finally(() => {
+      const index = tasks.lastIndexOf(task)
+      if (index >= 0) tasks.splice(index, 1)
+    })
+  })
+}
+
+/**
+ * Returns the _task name_ associated with the current asynchronous invocation
+ * context or `undefined`.
+ */
+export function currentTask(): string | undefined {
+  return storage.getStore()?.task
+}
+
+/**
+ * Returns the {@link Run} associated with the current asynchronous invocation
+ * context or `undefined`.
+ */
+export function currentRun(): Run | undefined {
+  return storage.getStore()?.run
+}
+
+/**
+ * Return an array of all _task names_ currently running
+ */
+export function runningTasks(): string[] {
+  return [ ...tasks ].sort()
+}
+
+/* ========================================================================== *
+ * INTERNALS                                                                  *
+ * ========================================================================== */
+
+const storage = new AsyncLocalStorage<{ run: Run, task: string }>()
+const tasks: string[] = []

package/src/files.ts

@@ -0,0 +1,129 @@
+import { inspect } from 'node:util'
+import { AbsolutePath, assertRelativeChildPath, getAbsoluteParent, resolveAbsolutePath } from './paths.js'
+import { mkdir, writeFile } from './utils/asyncfs.js'
+
+/** The {@link FilesBuilder} interface defines a builder for {@link Files}. */
+export interface FilesBuilder {
+  /** The (resolved) directory the {@link Files} will be associated with */
+  readonly directory: AbsolutePath
+  /** Push files into the {@link Files} instance being built */
+  add(...files: string[]): this
+  /** Merge orther {@link Files} instance to the {@link Files} being built */
+  merge(...files: Files[]): this
+  /** Write a file and add it to the {@link Files} instance being built */
+  write(file: string, content: string | Buffer): Promise<AbsolutePath>
+  /** Build and return a {@link Files} instance */
+  build(): Files
+}
+
+/**
+ * The {@link Files} class represents a collection of relative path names
+ * identifying some _files_ rooted in a given _directory_.
+ */
+export class Files {
+  readonly _directory: AbsolutePath
+  readonly _files: string[]
+
+  /**
+   * Create a new {@link Files} instance rooted in the specified `directory`
+   * relative to the specified {@link Run}'s directory.
+   */
+  constructor(directory: AbsolutePath) {
+    this._directory = directory
+    this._files = []
+  }
+
+  /** Return the _directory_ where this {@link Files} is rooted */
+  get directory(): AbsolutePath {
+    return this._directory
+  }
+
+  /** Return the number of files tracked by this instance. */
+  get length(): number {
+    return this._files.length
+  }
+
+  /** Return an iterator over all _relative_ files of this instance */
+  * [Symbol.iterator](): Generator<string> {
+    for (const file of this._files) yield file
+  }
+
+  /** Return an iterator over all _absolute_ files of this instance */
+  * absolutePaths(): Generator<AbsolutePath> {
+    for (const file of this) yield resolveAbsolutePath(this._directory, file)
+  }
+
+  /** Return an iterator over all _relative_ to _absolute_ mappings */
+  * pathMappings(): Generator<[ relative: string, absolute: AbsolutePath ]> {
+    for (const file of this) yield [ file, resolveAbsolutePath(this._directory, file) ]
+  }
+
+  /* Nicety for logging */
+  [inspect.custom](): any {
+    const self = this
+    return new class Files {
+      directory = self._directory
+      files = [ ...self._files ]
+    }
+  }
+
+  /** Create a new {@link FilesBuilder} creating {@link Files} instances. */
+  static builder(files: Files): FilesBuilder
+  static builder(directory: AbsolutePath): FilesBuilder
+  static builder(arg: Files | AbsolutePath): FilesBuilder {
+    const directory = typeof arg === 'string' ? arg : arg.directory
+    const set = typeof arg === 'string' ? new Set<string>() : new Set(arg._files)
+
+    const instance = new Files(directory)
+    let built = false
+
+    return {
+      directory: instance.directory,
+
+      add(...files: string[]): FilesBuilder {
+        if (built) throw new Error('FileBuilder "build()" already called')
+
+        if (typeof files === 'string') files = [ files ]
+        for (const file of files) {
+          const relative = assertRelativeChildPath(instance.directory, file)
+          set.add(relative)
+        }
+
+        return this
+      },
+
+      merge(...args: Files[]): FilesBuilder {
+        if (built) throw new Error('FileBuilder "build()" already called')
+
+        for (const files of args) {
+          for (const file of files.absolutePaths()) {
+            this.add(file)
+          }
+        }
+
+        return this
+      },
+
+      async write(file: string, content: string | Buffer): Promise<AbsolutePath> {
+        const relative = assertRelativeChildPath(instance.directory, file)
+        const absolute = resolveAbsolutePath(instance.directory, relative)
+        const directory = getAbsoluteParent(absolute)
+
+        await mkdir(directory, { recursive: true })
+        await writeFile(absolute, content)
+        this.add(absolute)
+
+        return absolute
+      },
+
+      build(): Files {
+        if (built) throw new Error('FileBuilder "build()" already called')
+
+        built = true
+        instance._files.push(...set)
+        instance._files.sort()
+        return instance
+      },
+    }
+  }
+}

package/src/fork.ts

@@ -0,0 +1,263 @@
+import { fork } from 'node:child_process'
+import { assert, failure } from './assert.js'
+import { runAsync } from './async.js'
+import { Files } from './files.js'
+import { $gry, $p, LogOptions, logOptions } from './log.js'
+import { AbsolutePath, isFile, requireFilename } from './paths.js'
+import { install, Plug, PlugName } from './pipe.js'
+import { Run, RunImpl } from './run.js'
+
+/** Fork data, from parent to child process */
+export interface ForkData {
+  /** Script name for the Plug to execute */
+  scriptFile: AbsolutePath,
+  /** Plug constructor arguments */
+  constructorArgs: any[],
+  /** Task name (for logs) */
+  taskName: string,
+  /** Build file name */
+  buildFile: AbsolutePath,
+  /** Build directory */
+  buildDir: AbsolutePath,
+  /** Files directory */
+  filesDir: AbsolutePath,
+  /** All files to pipe */
+  filesList: AbsolutePath[],
+  /** Options for our logger in the child process */
+  logOpts: Partial<LogOptions>,
+}
+
+/** Fork result, from child to parent process */
+export interface ForkResult {
+  /** If this is `true` we _might_ have `filesDir` and `filesList` */
+  failed: boolean,
+  /** Files directory of the result */
+  filesDir?: AbsolutePath | undefined,
+  /** All files returned by the plug */
+  filesList?: AbsolutePath[] | undefined,
+}
+
+/* ========================================================================== *
+ * PIPE INSTALLATION                                                          *
+ * ========================================================================== */
+
+/**
+ * Install a _forking_ {@link Plug} in the {@link Pipe}, in other words
+ * execute the plug in a separate process.
+ *
+ * As a contract, if the _last non-null_ parameter of the constructor is an
+ * object and contains the key `coverageDir`, the process will be forked with
+ * the approptiately resolved `NODE_V8_COVERAGE` environment variable.
+ *
+ * Also, forking plugs require some special attention:
+ *
+ * * plug functions are not supported, only classes implementing the
+ *   {@link Plug} interface can be used with this.
+ *
+ * * the class itself _MUST_ be exported as the _default_ export for the
+ *   `scriptFile` specified below. This is to simplify interoperability between
+ *   CommonJS and ESM modules as we use dynamic `import(...)` statements.
+ */
+export function installForking(
+    plugName: PlugName,
+    scriptFile: AbsolutePath,
+): void {
+  /** Extend out our ForkingPlug below */
+  const ctor = class extends ForkingPlug {
+    constructor(...args: any[]) {
+      super(scriptFile, args)
+    }
+  }
+
+  /** Install the plug in  */
+  install(plugName, ctor)
+}
+
+/* ========================================================================== *
+ * PARENT PROCESS SIDE OF THE FORKING PLUG IMPLEMENTATION                     *
+ * ========================================================================== */
+
+export abstract class ForkingPlug implements Plug<Files | undefined> {
+  constructor(
+      private readonly _scriptFile: AbsolutePath,
+      private readonly _arguments: any[],
+  ) {}
+
+  pipe(files: Files, run: Run): Promise<Files | undefined> {
+    const message: ForkData = {
+      scriptFile: this._scriptFile,
+      constructorArgs: this._arguments,
+      taskName: run.taskName,
+      buildFile: run.buildFile,
+      buildDir: run.buildDir,
+      filesDir: files.directory,
+      filesList: [ ...files.absolutePaths() ],
+      logOpts: logOptions.fork(run.taskName),
+    }
+
+    /* Get _this_ filename to spawn */
+    const script = requireFilename(__fileurl)
+    run.log.debug('About to fork plug from', $p(script))
+
+    /* Environment variables */
+    const env = { ...process.env }
+
+    /* Check our args (reversed) to see if the last specifies `coverageDir` */
+    for (let i = this._arguments.length - 1; i >= 0; i --) {
+      if (this._arguments[i] == null) continue // null or undefined... optionals
+      if (typeof this._arguments[i] === 'object') {
+        if (typeof this._arguments[i].coverageDir === 'string') {
+          const dir = env.NODE_V8_COVERAGE = run.resolve(this._arguments[i].coverageDir)
+          run.log.debug('Forked process will produce coverage in', $p(dir))
+        }
+      }
+    }
+
+    /* Run our script in a _separate_ process */
+    const child = fork(script, {
+      stdio: [ 'ignore', 'inherit', 'inherit', 'ipc' ],
+      env,
+    })
+
+    run.log.info('Running', $p(script), $gry(`(pid=${child.pid})`))
+
+    /* Return a promise from the child process events */
+    let done = false // this will be fixed up in "finally" below
+    return new Promise<Files | undefined>((resolve, reject) => {
+      let result: ForkResult | undefined = undefined
+
+      child.on('error', (error) => {
+        run.log.error('Child process error', error)
+        return done ? reject(failure()) : void 0
+      })
+
+      child.on('message', (message: ForkResult) => {
+        run.log.debug('Message from child process', message)
+        result = message
+      })
+
+      child.on('exit', (code, signal) => {
+        if (signal) {
+          run.log.error(`Child process exited with signal ${signal}`, $gry(`(pid=${child.pid})`))
+          return done ? reject(failure()) : void 0
+        } else if (code !== 0) {
+          run.log.error(`Child process exited with code ${code}`, $gry(`(pid=${child.pid})`))
+          return done ? reject(failure()) : void 0
+        } else if (! result) {
+          run.log.error('Child process exited with no result', $gry(`(pid=${child.pid})`))
+          return done ? reject(failure()) : void 0
+        } else if (result.failed) {
+          // definitely logged on the child side
+          return done ? reject(failure()) : void 0
+        }
+
+        /* We definitely have a successful result! */
+        return resolve(message.filesDir && message.filesList ?
+            run.files(message.filesDir).add(...message.filesList).build() :
+            undefined)
+      })
+
+      /* After the handlers have been setup, send the message */
+      try {
+        const result = child.send(message, (error) => {
+          if (error) {
+            run.log.error('Error sending message to child process (callback failure)', error)
+            reject(failure())
+          }
+        })
+        if (! result) {
+          run.log.error('Error sending message to child process (send returned false)')
+          reject(failure())
+        }
+      } catch (error) {
+        run.log.error('Error sending message to child process (exception caught)', error)
+        reject(failure())
+      }
+    }).finally(() => done = true)
+  }
+}
+
+
+/* ========================================================================== *
+ * CHILD PROCESS SIDE OF THE FORKING PLUG IMPLEMENTATION                      *
+ * ========================================================================== */
+
+/*
+ * If we were started as ourselves (fork.js) and we have an IPC channel to the
+ * parent process, we can safely assume we need to run our plug... So we wait
+ * for the message and respond once the plug returns _something_!
+ */
+if ((process.argv[1] === requireFilename(__fileurl)) && (process.send)) {
+  /* If we haven't processed our message in 5 seconds, fail _badly_ */
+  const timeout = setTimeout(() => {
+    // eslint-disable-next-line no-console
+    console.error('Mocha not initialized in 5 seconds')
+    process.exit(2)
+  }, 5000)
+
+  /* Await our message to initialize and run the plug */
+  process.on('message', (message: ForkData) => {
+    clearTimeout(timeout)
+
+    const {
+      scriptFile,
+      constructorArgs,
+      taskName,
+      buildFile,
+      buildDir,
+      filesDir,
+      filesList,
+      logOpts,
+    } = message
+
+    /* Restore logging options first */
+    Object.assign(logOptions, logOpts)
+
+    /* First of all, our Run */
+    const run = new RunImpl({ buildDir, buildFile, taskName })
+    run.log.debug('Message from parent process', message)
+
+    /* Contextualize this run, and go! */
+    const result = runAsync(run, taskName, async () => {
+      /* Check that we have a proper script file name */
+      assert(isFile(scriptFile), `Script file ${$p(scriptFile)} not found`)
+      const script = await import(scriptFile)
+
+      /* Check that we have a proper constructor */
+      assert(typeof script.default === 'function',
+          `Script ${$p(scriptFile)} does not export a default constructor`)
+
+      /* Create the Plug instance and our Files instance */
+      const Ctor = script.default as new (...args: any[]) => Plug<Files | undefined>
+      const plug = new Ctor(...constructorArgs)
+      const files = run.files(filesDir).add(...filesList).build()
+
+      /* Run and return the result */
+      return plug.pipe(files, run)
+    })
+
+    /* The result promise generates a message back to the parent process */
+    const promise = result.then((result) => {
+      const message: ForkResult = result ?
+        { failed: false, filesDir: result.directory, filesList: [ ...result.absolutePaths() ] } :
+        { failed: false }
+      return new Promise<void>((resolve, reject) => {
+        process.send!(message, (err: Error) => err ? reject(err) : resolve())
+      })
+    }, (error) => {
+      run.log.error(error)
+      return new Promise<void>((resolve, reject) => {
+        process.send!({ failed: true }, (err: Error) => err ? reject(err) : resolve())
+      })
+    })
+
+    /* The promise generated by `process.send()` simply triggers process exit */
+    promise.then(() => {
+      run.log.debug('Forked plug exiting')
+      process.exit(0)
+    }, (error) => {
+      run.log.error('Error sending message back to parent process', error)
+      process.exit(1)
+    })
+  })
+}

package/src/helpers.ts

@@ -0,0 +1,145 @@
+import { assert } from './assert.js'
+import { currentRun } from './async.js'
+import { Files, FilesBuilder } from './files.js'
+import { $p, log, LogLevelString } from './log.js'
+import { AbsolutePath, commonPath, getCurrentWorkingDirectory, isDirectory } from './paths.js'
+import { Pipe } from './pipe.js'
+import { FindOptions } from './run.js'
+import { rm } from './utils/asyncfs.js'
+import { ParseOptions } from './utils/options.js'
+
+/**
+ * Recursively remove the specified directory _**(use with care)**_.
+ */
+export async function rmrf(directory: string): Promise<void> {
+  const run = currentRun()
+  assert(run, 'Unable to find files outside a running task')
+  const dir = run.resolve(directory)
+
+  assert(dir !== getCurrentWorkingDirectory(),
+      `Cowardly refusing to wipe current working directory ${$p(dir)}`)
+
+  assert(dir !== run.buildDir,
+      `Cowardly refusing to wipe build file directory ${$p(dir)}`)
+
+  if (! isDirectory(dir)) {
+    log.info('Directory', $p(dir), 'not found')
+    return
+  }
+
+  log.info('Removing', $p(dir))
+  await rm(dir, { recursive: true })
+}
+
+/**
+ * Set the current _log level_.
+ *
+ * The _level_ will be applied _only_ within the execution of the current task.
+ */
+export function setLogLevel(level: LogLevelString): void {
+  const run = currentRun()
+  assert(run, 'Unable to find files outside a running task')
+  return run.setLogLevel(level)
+}
+
+/**
+ * Resolve a path into an {@link AbsolutePath}.
+ *
+ * If the path starts with `@...` it is considered to be relative to the
+ * {@link process.cwd | current working directory}, otherwise it will be
+ * resolved against the build file where the task was originally defined in.
+ */
+export function resolve(...paths: string[]): AbsolutePath {
+  const run = currentRun()
+  assert(run, 'Unable to find files outside a running task')
+  return run.resolve(...paths)
+}
+
+
+/**
+ * Create a new {@link Files} instance.
+ */
+export function files(files: Files): FilesBuilder
+export function files(...paths: string[]): FilesBuilder
+export function files(first: Files | string | undefined, ...paths: string[]): FilesBuilder {
+  const run = currentRun()
+  assert(run, 'Unable to create files builder outside a running task')
+  if (typeof first === 'string') {
+    return run.files(first, ...paths)
+  } else if (first) {
+    return run.files(first)
+  } else {
+    return run.files()
+  }
+}
+
+/**
+ * Merge multiple {@link Files} instance.
+ */
+export function merge(args: (Files | Promise<Files>)[]): Promise<Files> & Pipe {
+  const run = currentRun()
+  assert(run, 'Unable to create files builder outside a running task')
+
+  const promise = Promise.resolve().then(async () => {
+    // No arguments, no files... Just convenience!
+    if (args.length === 0) return run.pipe(run.files().build())
+
+    // Resolve all the `Files` instances (might be from other tasks)
+    const instances = await Promise.all(args)
+    const [ first, ...others ] = instances
+
+    const firstDir = first.directory
+    const otherDirs = others.map((f) => f.directory)
+
+    const directory = commonPath(firstDir, ...otherDirs)
+
+    return run.files(directory).merge(first, ...others).build()
+  })
+
+  return run.pipe(promise)
+}
+
+/**
+ * Find files according to the globs and {@link FindOptions} specified.
+ */
+export function find(glob: string, ...args: ParseOptions<FindOptions>): Pipe & Promise<Files> {
+  const run = currentRun()
+  assert(run, 'Unable to find files outside a running task')
+  return run.find(glob, ...args)
+}
+
+/** Create a {@link Pipe} from a {@link Files} instance. */
+export function pipe(files: Files | Promise<Files>): Pipe & Promise<Files> {
+  const run = currentRun()
+  assert(run, 'Unable to create pipes outside a running task')
+  return run.pipe(files)
+}
+
+/** Await for the settlement of all the promises, then return their results. */
+export async function parallel<P extends readonly any[]>(promises: P): Promise<ParallelResult<P>> {
+  const settlements = await Promise.allSettled(promises)
+  const results: any[] = []
+
+  let errors = 0
+  for (const settlement of settlements) {
+    if (settlement.status === 'fulfilled') {
+      results.push(settlement.value)
+      continue
+    }
+
+    log.error(settlement.reason)
+    errors ++
+  }
+
+  assert(! errors, `Parallel execution failed for ${errors} tasks`)
+  return results as ParallelResult<P>
+}
+
+type ParallelResult<T extends readonly any[]> =
+  T extends readonly [ infer First, ...infer Rest ] ?
+    [ Awaited<First>, ...ParallelResult<Rest> ] :
+  T extends readonly [ infer Only ] ?
+    [ Awaited<Only> ] :
+  T extends readonly [] ?
+    [] :
+  never

package/src/index.ts

@@ -0,0 +1,20 @@
+/// <reference path="../extra/webassembly.d.ts" />
+
+// Our minimal exports
+export * from './assert.js'
+export * from './build.js'
+export * from './plugs.js'
+export * from './log.js'
+export * from './helpers.js'
+
+// Utility types
+export type { MatchOptions, MatchResult } from './utils/match.js'
+export type { ParseOptions } from './utils/options.js'
+export type { WalkOptions } from './utils/walk.js'
+
+// PlugJS types
+export type { AbsolutePath } from './paths.js'
+export type { Files, FilesBuilder } from './files.js'
+export type { FindOptions, Run } from './run.js'
+export type { Pipe, Plug, PlugFunction } from './pipe.js'
+export type { Task } from './task.js'