@plugjs/plug 0.0.14 → 0.0.15

package/src/fork.ts

@@ -1,11 +1,10 @@
 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, resolveFile, requireFilename } from './paths.js'
-import { install, Plug, PlugName } from './pipe.js'
-import { Run, RunImpl } from './run.js'
+import { assert, failure } from './assert'
+import { runAsync } from './async'
+import { Files } from './files'
+import { $gry, $p, LogOptions, logOptions } from './log'
+import { AbsolutePath, requireFilename, resolveFile } from './paths'
+import { Plug, PlugResult, Context } from './pipe'
 
 /** Fork data, from parent to child process */
 export interface ForkData {
@@ -17,8 +16,6 @@ export interface ForkData {
   taskName: string,
   /** Build file name */
   buildFile: AbsolutePath,
-  /** Build directory */
-  buildDir: AbsolutePath,
   /** Files directory */
   filesDir: AbsolutePath,
   /** All files to pipe */
@@ -37,67 +34,30 @@ export interface ForkResult {
   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> {
+export abstract class ForkingPlug implements Plug<PlugResult> {
   constructor(
       private readonly _scriptFile: AbsolutePath,
       private readonly _arguments: any[],
   ) {}
 
-  pipe(files: Files, run: Run): Promise<Files | undefined> {
+  pipe(files: Files, context: Context): Promise<PlugResult> {
     const message: ForkData = {
       scriptFile: this._scriptFile,
       constructorArgs: this._arguments,
-      taskName: run.taskName,
-      buildFile: run.buildFile,
-      buildDir: run.buildDir,
+      taskName: context.taskName,
+      buildFile: context.buildFile,
       filesDir: files.directory,
       filesList: [ ...files.absolutePaths() ],
-      logOpts: logOptions.fork(run.taskName),
+      logOpts: logOptions.fork(context.taskName),
     }
 
     /* Get _this_ filename to spawn */
     const script = requireFilename(__fileurl)
-    run.log.debug('About to fork plug from', $p(script))
+    context.log.debug('About to fork plug from', $p(script))
 
     /* Environment variables */
     const env = { ...process.env }
@@ -107,8 +67,8 @@ export abstract class ForkingPlug implements Plug<Files | undefined> {
       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))
+          const dir = env.NODE_V8_COVERAGE = context.resolve(this._arguments[i].coverageDir)
+          context.log.debug('Forked process will produce coverage in', $p(dir))
         }
       }
     }
@@ -119,32 +79,32 @@ export abstract class ForkingPlug implements Plug<Files | undefined> {
       env,
     })
 
-    run.log.info('Running', $p(script), $gry(`(pid=${child.pid})`))
+    context.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) => {
+    return new Promise<PlugResult>((resolve, reject) => {
       let result: ForkResult | undefined = undefined
 
       child.on('error', (error) => {
-        run.log.error('Child process error', error)
+        context.log.error('Child process error', error)
         return done || reject(failure())
       })
 
       child.on('message', (message: ForkResult) => {
-        run.log.debug('Message from child process', message)
+        context.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})`))
+          context.log.error(`Child process exited with signal ${signal}`, $gry(`(pid=${child.pid})`))
           return done || reject(failure())
         } else if (code !== 0) {
-          run.log.error(`Child process exited with code ${code}`, $gry(`(pid=${child.pid})`))
+          context.log.error(`Child process exited with code ${code}`, $gry(`(pid=${child.pid})`))
           return done || reject(failure())
         } else if (! result) {
-          run.log.error('Child process exited with no result', $gry(`(pid=${child.pid})`))
+          context.log.error('Child process exited with no result', $gry(`(pid=${child.pid})`))
           return done || reject(failure())
         } else if (result.failed) {
           // definitely logged on the child side
@@ -153,7 +113,7 @@ export abstract class ForkingPlug implements Plug<Files | undefined> {
 
         /* We definitely have a successful result! */
         return done || resolve(message.filesDir && message.filesList ?
-            run.files(message.filesDir).unchecked(...message.filesList).build() :
+            Files.builder(message.filesDir).add(...message.filesList).build() :
             undefined)
       })
 
@@ -161,16 +121,16 @@ export abstract class ForkingPlug implements Plug<Files | undefined> {
       try {
         const result = child.send(message, (error) => {
           if (error) {
-            run.log.error('Error sending message to child process (callback failure)', error)
+            context.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)')
+          context.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)
+        context.log.error('Error sending message to child process (exception caught)', error)
         reject(failure())
       }
     }).finally(() => done = true)
@@ -204,7 +164,6 @@ if ((process.argv[1] === requireFilename(__fileurl)) && (process.send)) {
       constructorArgs,
       taskName,
       buildFile,
-      buildDir,
       filesDir,
       filesList,
       logOpts,
@@ -213,12 +172,12 @@ if ((process.argv[1] === requireFilename(__fileurl)) && (process.send)) {
     /* 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)
+    /* First of all, our plug context */
+    const context = new Context(buildFile, taskName)
+    context.log.debug('Message from parent process', message)
 
     /* Contextualize this run, and go! */
-    const result = runAsync(run, taskName, async () => {
+    const result = runAsync(context, taskName, async () => {
       /* Check that we have a proper script file name */
       assert(resolveFile(scriptFile), `Script file ${$p(scriptFile)} not found`)
       const script = await import(scriptFile)
@@ -232,11 +191,11 @@ if ((process.argv[1] === requireFilename(__fileurl)) && (process.send)) {
           `Script ${$p(scriptFile)} does not export a default constructor`)
 
       /* Create the Plug instance and our Files instance */
-      const plug = new Ctor(...constructorArgs) as Plug<Files | undefined>
-      const files = run.files(filesDir).unchecked(...filesList).build()
+      const plug = new Ctor(...constructorArgs) as Plug<PlugResult>
+      const files = Files.builder(filesDir).add(...filesList).build()
 
       /* Run and return the result */
-      return plug.pipe(files, run)
+      return plug.pipe(files, context)
     })
 
     /* The result promise generates a message back to the parent process */
@@ -248,7 +207,7 @@ if ((process.argv[1] === requireFilename(__fileurl)) && (process.send)) {
         process.send!(message, (err: Error) => err ? reject(err) : resolve())
       })
     }, (error) => {
-      run.log.error(error)
+      context.log.error(error)
       return new Promise<void>((resolve, reject) => {
         process.send!({ failed: true }, (err: Error) => err ? reject(err) : resolve())
       })
@@ -256,10 +215,10 @@ if ((process.argv[1] === requireFilename(__fileurl)) && (process.send)) {
 
     /* The promise generated by `process.send()` simply triggers process exit */
     promise.then(() => {
-      run.log.debug('Forked plug exiting')
+      context.log.debug('Forked plug exiting')
       process.exit(0)
     }, (error) => {
-      run.log.error('Error sending message back to parent process', error)
+      context.log.error('Error sending message back to parent process', error)
       process.exit(1)
     })
   })

package/src/helpers.ts

@@ -1,133 +1,121 @@
-import {
-  AbsolutePath,
-  commonPath,
-  getCurrentWorkingDirectory,
-  resolveDirectory,
-  resolveFile,
-} from './paths.js'
-
-import { assert } from './assert.js'
-import { currentRun } from './async.js'
-import { Files, FilesBuilder } from './files.js'
-import { $p, log, LogLevelString } from './log.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)}`)
+import { assert } from './assert'
+import { requireContext } from './async'
+import { Files } from './files'
+import { $p, log } from './log'
+import { AbsolutePath, commonPath, getCurrentWorkingDirectory, resolveDirectory, resolveFile } from './paths'
+import { Context, Pipe, Plug, PlugFunction, PlugResult } from './pipe'
+import { rm } from './utils/asyncfs'
+import { ParseOptions, parseOptions } from './utils/options'
+import { walk, WalkOptions } from './utils/walk'
+
+class PipeImpl extends Pipe implements Pipe {
+  constructor(private readonly _start: (context: Context) => Promise<Files>) {
+    super()
+  }
 
-  if (! resolveDirectory(dir)) {
-    log.info('Directory', $p(dir), 'not found')
-    return
+  plug(plug: Plug<Files>): Pipe
+  plug(plug: PlugFunction<Files>): Pipe
+  plug(plug: Plug<void | undefined>): Promise<undefined>
+  plug(plug: PlugFunction<void | undefined>): Promise<undefined>
+  plug(arg: Plug<PlugResult> | PlugFunction<PlugResult>): Pipe | Promise<undefined> {
+    const plug = typeof arg === 'function' ? { pipe: arg } : arg
+
+    const parent = this
+    return new PipeImpl(async (context: Context): Promise<Files> => {
+      const files = await parent._start(context)
+      const files2 = await plug.pipe(files, context)
+      assert(files2, 'Unable to extend pipe (part tres)')
+      return files2
+    })
   }
 
-  log.notice('Removing directory', $p(dir), 'recursively')
-  await rm(dir, { recursive: true })
+  async run(): Promise<Files> {
+    return this._start(requireContext())
+  }
 }
 
-/**
- * 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)
+/** The {@link FindOptions} interface defines the options for finding files. */
+export interface FindOptions extends WalkOptions {
+  /** The directory where to start looking for files. */
+  directory?: string
 }
 
-/**
- * Resolve a path into an {@link AbsolutePath}.
- *
- * If the path starts with `@...` it is considered to be relative to the
- * _directory containing the build file where the task was defined_, otherwise
- * it will be relative to the {@link process.cwd | current working directory}.
- */
-export function resolve(...paths: string[]): AbsolutePath {
-  const run = currentRun()
-  assert(run, 'Unable to find files outside a running task')
-  return run.resolve(...paths)
-}
 
+export function find(glob: string): Pipe
+export function find(glob: string, ...globs: string[]): Pipe
+export function find(glob: string, options: FindOptions): Pipe
+export function find(glob: string, ...extra: [...globs: string[], options: FindOptions]): Pipe
 
-/**
- * Create a new {@link Files} instance.
- */
-export function files(files: Files): FilesBuilder
-export function files(directory: string, ...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()
-  }
+export function find(...args: ParseOptions<FindOptions>): Pipe {
+  const { params: globs, options } = parseOptions(args, {})
+
+  return new PipeImpl(async (context: Context): Promise<Files> => {
+    const directory = options.directory ?
+      context.resolve(options.directory) :
+      getCurrentWorkingDirectory()
+
+    const builder = Files.builder(directory)
+    for await (const file of walk(directory, globs, options)) {
+      builder.add(file)
+    }
+
+    return builder.build()
+  })
 }
 
-/**
- * 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')
+export function merge(...pipes: Pipe[]): Pipe {
+  return new PipeImpl(async (): Promise<Files> => {
+    if (pipes.length === 0) return Files.builder(getCurrentWorkingDirectory()).build()
+
+    const results: Files[] = []
 
-  const promise = Promise.resolve().then(async () => {
-    // No arguments, no files... Just convenience!
-    if (args.length === 0) return run.pipe(run.files().build())
+    for (const pipe of pipes) {
+      const result = await pipe.run()
+      assert(result, 'Pipe did not return a Files result')
+      results.push(result)
+    }
 
-    // Resolve all the `Files` instances (might be from other tasks)
-    const instances = await Promise.all(args)
-    const [ first, ...others ] = instances
+    const [ first, ...others ] = results
 
     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 Files.builder(directory).merge(first, ...others).build()
   })
-
-  return run.pipe(promise)
 }
 
 /**
- * Find files according to the globs and {@link FindOptions} specified.
+ * Recursively remove the specified directory _**(use with care)**_.
  */
-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)
-}
+export async function rmrf(directory: string): Promise<void> {
+  const context = requireContext()
+  const dir = context.resolve(directory)
 
-/** 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)
+  assert(dir !== getCurrentWorkingDirectory(),
+      `Cowardly refusing to wipe current working directory ${$p(dir)}`)
+
+  assert(dir !== context.resolve('@'),
+      `Cowardly refusing to wipe build file directory ${$p(dir)}`)
+
+  if (! resolveDirectory(dir)) {
+    log.info('Directory', $p(dir), 'not found')
+    return
+  }
+
+  log.notice('Removing directory', $p(dir), 'recursively')
+  await rm(dir, { recursive: true })
 }
 
 /** Return an absolute path of the file if it exist on disk */
-export function isFile(...paths: string[]): AbsolutePath | undefined {
-  return resolveFile(resolve(...paths))
+export function isFile(...paths: [ string, ...string[] ]): AbsolutePath | undefined {
+  const path = requireContext().resolve(...paths)
+  return resolveFile(path)
 }
 
 /** Return an absolute path of the file if it exist on disk */
-export function isDirectory(...paths: string[]): AbsolutePath | undefined {
-  return resolveDirectory(resolve(...paths))
+export function isDirectory(...paths: [ string, ...string[] ]): AbsolutePath | undefined {
+  const path = requireContext().resolve(...paths)
+  return resolveDirectory(path)
 }

package/src/index.ts

@@ -1,20 +1,15 @@
 /// <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'
+export type { AbsolutePath } from './paths'
+export type { Files, FilesBuilder } from './files'
+export type { Pipe } from './pipe'
 
-// Utility types
-export type { MatchOptions, MatchResult } from './utils/match.js'
-export type { ParseOptions } from './utils/options.js'
-export type { WalkOptions } from './utils/walk.js'
+// Our minimal exports
+export * from './assert'
+export * from './build'
+export * from './helpers'
+export * from './log'
 
 // 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'
+export * from './plugs'
+export * from './types'

package/src/log/colors.ts

@@ -1,6 +1,6 @@
 import { sep } from 'node:path'
-import { AbsolutePath, getCurrentWorkingDirectory, resolveRelativeChildPath } from '../paths.js'
-import { logOptions } from './options.js'
+import { AbsolutePath, getCurrentWorkingDirectory, resolveRelativeChildPath } from '../paths'
+import { logOptions } from './options'
 
 /* ========================================================================== */
 
@@ -49,7 +49,7 @@ export function $t(task: string): string {
 }
 
 /** Colorize milliseconds. */
-export function $ms(millis: number): string {
+export function $ms(millis: number, note?: string): string {
   let string: string
   if (millis >= 60000) {
     // One minute or more: style is Xm Ys
@@ -70,6 +70,7 @@ export function $ms(millis: number): string {
     // Milliseconds: style is 123ms
     string = `${millis}ms`
   }
+  if (note) string = `${note} ${string}`
   return _colors ? `${gry}[${string}]${rst}` : `[${string}]`
 }
 

package/src/log/emit.ts

@@ -1,8 +1,8 @@
 import { formatWithOptions } from 'node:util'
-import { $blu, $grn, $gry, $red, $t, $ylw } from './colors.js'
-import { DEBUG, INFO, LogLevel, NOTICE, TRACE, WARN } from './levels.js'
-import { logOptions } from './options.js'
-import { zapSpinner } from './spinner.js'
+import { $blu, $grn, $gry, $red, $t, $ylw } from './colors'
+import { DEBUG, INFO, LogLevel, NOTICE, TRACE, WARN } from './levels'
+import { logOptions } from './options'
+import { zapSpinner } from './spinner'
 
 /* ========================================================================== */
 

package/src/log/logger.ts

@@ -1,7 +1,8 @@
-import { isBuildError, isBuildFailure } from '../assert.js'
-import { emitColor, emitPlain, LogEmitter } from './emit.js'
-import { DEBUG, ERROR, INFO, LogLevel, NOTICE, TRACE, WARN } from './levels.js'
-import { logOptions } from './options.js'
+import { isBuildError, isBuildFailure } from '../assert'
+import { emitColor, emitPlain, LogEmitter } from './emit'
+import { DEBUG, ERROR, INFO, LogLevel, NOTICE, TRACE, WARN } from './levels'
+import { logOptions } from './options'
+import { Report, ReportImpl } from './report'
 
 /* ========================================================================== */
 
@@ -48,6 +49,8 @@ export interface Logger extends Log {
   leave(): this
   /** Leave a sub-level of logging, decreasing indent */
   leave(level: LogLevel, message: string): this
+  /** Create a {@link Report} associated with this instance */
+  report(title: string): Report
 }
 
 /** Return a {@link Logger} associated with the specified task name. */
@@ -149,6 +152,7 @@ class LoggerImpl implements Logger {
       const [ level, message ] = args
       this._stack.push({ level, message, indent: this._indent })
     }
+
     this._indent ++
     return this
   }
@@ -168,4 +172,8 @@ class LoggerImpl implements Logger {
 
     return this
   }
+
+  report(title: string): Report {
+    return new ReportImpl(title, this._task, this._emitter)
+  }
 }

package/src/log/options.ts

@@ -1,7 +1,7 @@
 import { EventEmitter } from 'node:events'
 import { Writable } from 'node:stream'
 import { InspectOptions } from 'node:util'
-import { getLevelNumber, LogLevel, LogLevelString, NOTICE } from './levels.js'
+import { getLevelNumber, LogLevel, LogLevelString, NOTICE } from './levels'
 
 /* ========================================================================== */
 

package/src/log/report.ts

@@ -1,21 +1,13 @@
-import { fail, failure } from '../assert.js'
-import { AbsolutePath } from '../paths.js'
-import { readFile } from '../utils/asyncfs.js'
-import { $blu, $cyn, $gry, $red, $und, $wht, $ylw } from './colors.js'
-import { emitColor, emitPlain, LogEmitter } from './emit.js'
-import { ERROR, LogLevels, NOTICE, WARN } from './levels.js'
-import { logOptions } from './options.js'
+import { fail, failure } from '../assert'
+import { AbsolutePath } from '../paths'
+import { readFile } from '../utils/asyncfs'
+import { $blu, $cyn, $gry, $red, $und, $wht, $ylw } from './colors'
+import { LogEmitter } from './emit'
+import { ERROR, LogLevels, NOTICE, WARN } from './levels'
+import { logOptions } from './options'
 
 /* ========================================================================== */
 
-/* Track changes for colors */
-let _colors = logOptions.colors
-logOptions.on('changed', ({ colors }) => {
-  _colors = colors
-})
-
-/* ========================================================================== *
-
 /** Levels used in a {@link Report}  */
 export type ReportLevel = LogLevels['NOTICE' | 'WARN' | 'ERROR']
 
@@ -91,12 +83,6 @@ export interface Report {
   done(showSources?: boolean | undefined): void
 }
 
-/** Create a new {@link Report} with the given title */
-export function createReport(title: string, taskName: string): Report {
-  const emitter = _colors ? emitColor : emitPlain
-  return new ReportImpl(title, taskName, emitter)
-}
-
 /* ========================================================================== *
  * REPORT IMPLEMENTATION                                                      *
  * ========================================================================== */
@@ -118,7 +104,7 @@ interface ReportInternalAnnotation {
   readonly note: string
 }
 
-class ReportImpl implements Report {
+export class ReportImpl implements Report {
   private readonly _sources = new Map<AbsolutePath, string[]>()
   private readonly _annotations = new Map<AbsolutePath, ReportInternalAnnotation>()
   private readonly _records = new Map<AbsolutePath | Null, Set<ReportInternalRecord>>()

package/src/log/spinner.ts

@@ -1,6 +1,6 @@
-import { runningTasks } from '../async.js'
-import { $cyn, $gry, $t } from './colors.js'
-import { logOptions } from './options.js'
+import { runningTasks } from '../async'
+import { $cyn, $gry, $t } from './colors'
+import { logOptions } from './options'
 
 /* ========================================================================== */