@plugjs/plug 0.1.0 → 0.1.2

package/src/build.ts

@@ -0,0 +1,179 @@
+import { assert } from './asserts'
+import { runAsync } from './async'
+import { $ms, $p, $t, getLogger, log, logOptions } from './logging'
+import { Context, ContextPromises, PipeImpl } from './pipe'
+import { findCaller } from './utils/caller'
+import { parseOptions } from './utils/options'
+
+import type { Pipe } from './index'
+import type { AbsolutePath } from './paths'
+import type {
+  Build,
+  BuildDef,
+  Props,
+  Result,
+  State,
+  Task,
+  TaskDef,
+  Tasks,
+  ThisBuild,
+} from './types'
+
+/* ========================================================================== *
+ * TASK                                                                       *
+ * ========================================================================== */
+
+class TaskImpl implements Task {
+  constructor(
+      public readonly buildFile: AbsolutePath,
+      public readonly tasks: Tasks,
+      public readonly props: Props,
+      private readonly _def: TaskDef,
+  ) {}
+
+  invoke(state: State, taskName: string): Promise<Result> {
+    assert(! state.stack.includes(this), `Recursion detected calling ${$t(taskName)}`)
+
+    /* Check cache */
+    const cached = state.cache.get(this)
+    if (cached) return cached
+
+    /* Create new substate merging sibling tasks/props and adding this to the stack */
+    const props: Record<string, string> = Object.assign({}, this.props, state.props)
+    const tasks: Record<string, Task> = Object.assign({}, this.tasks, state.tasks)
+    const stack = [ ...state.stack, this ]
+    const cache = state.cache
+
+    /* Create run context and build */
+    const context = new Context(this.buildFile, taskName)
+
+    const build = new Proxy({}, {
+      get(_: any, name: string): void | string | (() => Pipe) {
+        // Tasks first, props might come also from environment
+        if (name in tasks) {
+          return (): Pipe => {
+            const state = { stack, cache, tasks, props }
+            const promise = tasks[name]!.invoke(state, name)
+            return new PipeImpl(context, promise)
+          }
+        } else if (name in props) {
+          return props[name]
+        }
+      },
+    })
+
+    /* Some logging */
+    context.log.info('Running...')
+    const now = Date.now()
+
+    /* Run asynchronously in an asynchronous context */
+    const promise = runAsync(context, taskName, async () => {
+      return await this._def.call(build) || undefined
+    }).then((result) => {
+      context.log.notice(`Success ${$ms(Date.now() - now)}`)
+      return result
+    }).catch((error) => {
+      throw context.log.fail(`Failure ${$ms(Date.now() - now)}`, error)
+    }).finally(() => ContextPromises.wait(context))
+
+    /* Cache the resulting promise and return it */
+    cache.set(this, promise)
+    return promise
+  }
+}
+
+/* ========================================================================== *
+ * BUILD COMPILER                                                             *
+ * ========================================================================== */
+
+/** Symbol indicating that an object is a {@link Build} */
+const buildMarker = Symbol.for('plugjs:isBuild')
+
+/** Compile a {@link BuildDef | build definition} into a {@link Build} */
+export function build<
+  D extends BuildDef, B extends ThisBuild<D>
+>(def: D & ThisType<B>): Build<D> {
+  const buildFile = findCaller(build)
+  const tasks: Record<string, Task> = {}
+  const props: Record<string, string> = {}
+
+  /* Iterate through all definition extracting properties and tasks */
+  for (const [ key, val ] of Object.entries(def)) {
+    let len = 0
+    if (typeof val === 'string') {
+      props[key] = val
+    } else if (typeof val === 'function') {
+      tasks[key] = new TaskImpl(buildFile, tasks, props, val)
+      len = key.length
+    } else if (val instanceof TaskImpl) {
+      tasks[key] = val
+      len = key.length
+    }
+
+    /* Update the logger's own "taskLength" for nice printing */
+    /* coverage ignore if */
+    if (len > logOptions.taskLength) logOptions.taskLength = len
+  }
+
+  /* Create the "call" function for this build */
+  const invoke: InvokeBuild = async function invoke(
+      taskNames: string[],
+      overrideProps: Record<string, string | undefined> = {},
+  ): Promise<void> {
+    /* Our "root" logger and initial (empty) state */
+    const logger = getLogger()
+    const state = {
+      cache: new Map<Task, Promise<Result>>(),
+      stack: [] as Task[],
+      props: Object.assign({}, props, overrideProps),
+      tasks: tasks,
+    }
+
+    /* Let's go down to business */
+    logger.notice('Starting...')
+    const now = Date.now()
+
+    try {
+      /* Run tasks _serially_ */
+      for (const name of taskNames) {
+        const task = tasks[name]
+        assert(task, `Task ${$t(name)} not found in build ${$p(buildFile)}`)
+        await task.invoke(state, name)
+      }
+      logger.notice(`Build successful ${$ms(Date.now() - now)}`)
+    } catch (error) {
+      throw logger.fail(`Build failed ${$ms(Date.now() - now)}`, error)
+    }
+  }
+
+  /* Create our build, the collection of all props and tasks */
+  const compiled = Object.assign({}, props, tasks) as Build<D>
+
+  /* Sneak our "call" function in the build, for the CLI and "call" below */
+  Object.defineProperty(compiled, buildMarker, { value: invoke })
+
+  /* All done! */
+  return compiled
+}
+
+/** Internal type describing the build invocation function */
+type InvokeBuild = (tasks: string[], props?: Record<string, string | undefined>) => Promise<void>
+
+/** Serially invoke tasks in a {@link Build} optionally overriding properties */
+export async function invoke(
+    build: Build,
+    ...args:
+    | [ ...taskNames: [ string, ...string[] ] ]
+    | [ ...taskNames: [ string, ...string[] ], options: Record<string, string | undefined> ]
+): Promise<void> {
+  const { params: tasks, options: props } = parseOptions(args, {})
+
+  /* Get the calling function from the sneaked-in property in build */
+  const invoke: InvokeBuild = (build as any)[buildMarker]
+
+  /* Triple check that we actually _have_ a function (no asserts here, log!) */
+  if (typeof invoke !== 'function') log.fail('Unknown build type')
+
+  /* Call everyhin that needs to be called */
+  return await invoke(tasks, props)
+}

package/src/files.ts

@@ -1,3 +1,4 @@
+import { assert } from './asserts'
 import { mkdir, writeFile } from './fs'
 import { assertRelativeChildPath, getAbsoluteParent, resolveAbsolutePath } from './paths'
 
@@ -88,9 +89,8 @@ export class Files {
       directory: instance.directory,
 
       add(...files: string[]): FilesBuilder {
-        if (built) throw new Error('FileBuilder "build()" already called')
+        assert(! built, 'FileBuilder "build()" already called')
 
-        if (typeof files === 'string') files = [ files ]
         for (const file of files) {
           const relative = assertRelativeChildPath(instance.directory, file)
           set.add(relative)
@@ -100,7 +100,7 @@ export class Files {
       },
 
       merge(...args: Files[]): FilesBuilder {
-        if (built) throw new Error('FileBuilder "build()" already called')
+        assert(! built, 'FileBuilder "build()" already called')
 
         for (const files of args) {
           for (const file of files.absolutePaths()) {
@@ -124,7 +124,7 @@ export class Files {
       },
 
       build(): Files {
-        if (built) throw new Error('FileBuilder "build()" already called')
+        assert(! built, 'FileBuilder "build()" already called')
 
         built = true
         instance._files.push(...set)

package/src/fs.ts

@@ -30,11 +30,12 @@ const fs = Object.entries(fsp as any).reduce((fs, [ key, val ]) => {
     /* If the value is a function, wrap it! */
     const f = function(...args: any[]): any {
       /* Call the function, and _catch_ any error */
-      return val.apply(fsp, args).catch((error: any) => {
-        /* For any error caught, we fill in the stack trace */
-        Error.captureStackTrace(error)
-        throw error
-      })
+      return val.apply(fsp, args)
+          .catch(/* coverage ignore next*/ (error: any) => {
+            /* For any error caught, we fill in the stack trace */
+            Error.captureStackTrace(error)
+            throw error
+          })
     }
 
     /* Make sure that the functions are called correctly */

package/src/helpers.ts

@@ -1,3 +1,7 @@
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { mkdtempSync } from 'node:fs'
+
 import { assert, assertPromises } from './asserts'
 import { requireContext } from './async'
 import { Files } from './files'
@@ -65,6 +69,7 @@ export async function rmrf(directory: string): Promise<void> {
   assert(dir !== context.resolve('@'),
       `Cowardly refusing to wipe build file directory ${$p(dir)}`)
 
+  /* coverage ignore if */
   if (! resolveDirectory(dir)) {
     log.info('Directory', $p(dir), 'not found')
     return
@@ -159,6 +164,17 @@ export function isDirectory(...paths: [ string, ...string[] ]): AbsolutePath | u
   return resolveDirectory(path)
 }
 
+/**
+ * Create a temporary directory and return its {@link AbsolutePath}.
+ *
+ * The directory will be rooted in `/tmp` or wherever `os.tmpdir()` decides.
+ */
+export function mkdtemp(): AbsolutePath {
+  const prefix = join(tmpdir(), 'plugjs-')
+  const path = mkdtempSync(prefix)
+  return resolve(path)
+}
+
 /**
  * Execute a command and await for its result from within a task.
  *

package/src/index.ts

@@ -30,8 +30,8 @@ export * as pipe from './pipe'
 export * as utils from './utils'
 
 // Individual utilities
-export { log } from './logging'
-export { assert } from './asserts'
+export { log, $ms, $p, $t, $blu, $cyn, $grn, $gry, $mgt, $red, $und, $wht, $ylw } from './logging'
+export { assert, fail } from './asserts'
 
 // Our minimal exports
 export * from './build'

package/src/logging/logger.ts

@@ -27,17 +27,17 @@ logOptions.on('changed', ({ defaultTaskName, colors, level }) => {
 /** The basic interface giving access to log facilities. */
 export interface Log {
   /** Log a `TRACE` message */
-  trace(...args: [ any, ...any ]): this
+  trace(...args: [ any, ...any ]): void
   /** Log a `DEBUG` message */
-  debug(...args: [ any, ...any ]): this
+  debug(...args: [ any, ...any ]): void
   /** Log an `INFO` message */
-  info(...args: [ any, ...any ]): this
+  info(...args: [ any, ...any ]): void
   /** Log a `NOTICE` message */
-  notice(...args: [ any, ...any ]): this
+  notice(...args: [ any, ...any ]): void
   /** Log a `WARNING` message */
-  warn(...args: [ any, ...any ]): this
+  warn(...args: [ any, ...any ]): void
   /** Log an `ERROR` message */
-  error(...args: [ any, ...any ]): this
+  error(...args: [ any, ...any ]): void
   /** Log an `ERROR` message and fail the build */
   fail(...args: [ any, ...any ]): never
 }
@@ -48,13 +48,13 @@ export interface Logger extends Log {
   level: LogLevel,
 
   /** Enter a sub-level of logging, increasing indent */
-  enter(): this
+  enter(): void
   /** Enter a sub-level of logging, increasing indent */
-  enter(evel: LogLevel, message: string): this
+  enter(evel: LogLevel, message: string): void
   /** Leave a sub-level of logging, decreasing indent */
-  leave(): this
+  leave(): void
   /** Leave a sub-level of logging, decreasing indent */
-  leave(level: LogLevel, message: string): this
+  leave(level: LogLevel, message: string): void
   /** Create a {@link Report} associated with this instance */
   report(title: string): Report
 }
@@ -88,8 +88,8 @@ class LoggerImpl implements Logger {
       private readonly _emitter: LogEmitter,
   ) {}
 
-  private _emit(level: LogLevel, args: [ any, ...any ]): this {
-    if (this._level > level) return this
+  private _emit(level: LogLevel, args: [ any, ...any ]): void {
+    if (this._level > level) return
 
     // The `BuildFailure` is a bit special case
     const params = args.filter((arg) => {
@@ -116,7 +116,7 @@ class LoggerImpl implements Logger {
     })
 
     // If there's nothing left to log, then we're done
-    if (params.length === 0) return this
+    if (params.length === 0) return
 
     // Prepare our options for logging
     const options = { level, taskName: this._task, indent: this._indent }
@@ -131,7 +131,6 @@ class LoggerImpl implements Logger {
 
     // Emit our log lines and return
     this._emitter(options, params)
-    return this
   }
 
   get level(): LogLevel {
@@ -142,28 +141,28 @@ class LoggerImpl implements Logger {
     this._level = level
   }
 
-  trace(...args: [ any, ...any ]): this {
-    return this._emit(TRACE, args)
+  trace(...args: [ any, ...any ]): void {
+    this._emit(TRACE, args)
   }
 
-  debug(...args: [ any, ...any ]): this {
-    return this._emit(DEBUG, args)
+  debug(...args: [ any, ...any ]): void {
+    this._emit(DEBUG, args)
   }
 
-  info(...args: [ any, ...any ]): this {
-    return this._emit(INFO, args)
+  info(...args: [ any, ...any ]): void {
+    this._emit(INFO, args)
   }
 
-  notice(...args: [ any, ...any ]): this {
-    return this._emit(NOTICE, args)
+  notice(...args: [ any, ...any ]): void {
+    this._emit(NOTICE, args)
   }
 
-  warn(...args: [ any, ...any ]): this {
-    return this._emit(WARN, args)
+  warn(...args: [ any, ...any ]): void {
+    this._emit(WARN, args)
   }
 
-  error(...args: [ any, ...any ]): this {
-    return this._emit(ERROR, args)
+  error(...args: [ any, ...any ]): void {
+    this._emit(ERROR, args)
   }
 
   fail(...args: [ any, ...any ]): never {
@@ -171,21 +170,20 @@ class LoggerImpl implements Logger {
     throw BuildFailure.fail()
   }
 
-  enter(): this
-  enter(level: LogLevel, message: string): this
-  enter(...args: [] | [ level: LogLevel, message: string ]): this {
+  enter(): void
+  enter(level: LogLevel, message: string): void
+  enter(...args: [] | [ level: LogLevel, message: string ]): void {
     if (args.length) {
       const [ level, message ] = args
       this._stack.push({ level, message, indent: this._indent })
     }
 
     this._indent ++
-    return this
   }
 
-  leave(): this
-  leave(level: LogLevel, message: string): this
-  leave(...args: [] | [ level: LogLevel, message: string ]): this {
+  leave(): void
+  leave(level: LogLevel, message: string): void
+  leave(...args: [] | [ level: LogLevel, message: string ]): void {
     this._stack.pop()
     this._indent --
 
@@ -195,8 +193,6 @@ class LoggerImpl implements Logger {
       const [ level, message ] = args
       this._emit(level, [ message ])
     }
-
-    return this
   }
 
   report(title: string): Report {

package/src/logging.ts

@@ -29,38 +29,32 @@ export const log: LogFunction = ((): LogFunction => {
 
   /* Create a Logger wrapping the current logger */
   const wrapper: Log = {
-    trace(...args: [ any, ...any ]): Log {
+    trace(...args: [ any, ...any ]): void {
       logger().trace(...args)
-      return wrapper
     },
 
-    debug(...args: [ any, ...any ]): Log {
+    debug(...args: [ any, ...any ]): void {
       logger().debug(...args)
-      return wrapper
     },
 
-    info(...args: [ any, ...any ]): Log {
+    info(...args: [ any, ...any ]): void {
       logger().info(...args)
-      return wrapper
     },
 
-    notice(...args: [ any, ...any ]): Log {
+    notice(...args: [ any, ...any ]): void {
       logger().notice(...args)
-      return wrapper
     },
 
-    warn(...args: [ any, ...any ]): Log {
+    warn(...args: [ any, ...any ]): void {
       logger().warn(...args)
-      return wrapper
     },
 
-    error(...args: [ any, ...any ]): Log {
+    error(...args: [ any, ...any ]): void {
       logger().error(...args)
-      return wrapper
     },
 
     fail(...args: [ any, ...any ]): never {
-      throw logger().fail(...args) // fail() returns never but ?!?!?!?!?
+      return logger().fail(...args)
     },
   }
 

package/src/paths.ts

@@ -14,9 +14,8 @@ export type AbsolutePath = string & { __brand_absolute_path: never }
 
 /** Resolve a path into an {@link AbsolutePath} */
 export function resolveAbsolutePath(directory: AbsolutePath, ...paths: string[]): AbsolutePath {
-  const resolved = resolve(directory, ...paths) as AbsolutePath
-  assert(isAbsolute(resolved), `Path "${join(...paths)}" resolved in "${directory}" is not absolute`)
-  return resolved
+  assertAbsolutePath(directory)
+  return resolve(directory, ...paths) as AbsolutePath
 }
 
 /**
@@ -32,8 +31,6 @@ export function resolveAbsolutePath(directory: AbsolutePath, ...paths: string[])
  * ```
  */
 export function resolveRelativeChildPath(directory: AbsolutePath, ...paths: string[]): string | undefined {
-  assertAbsolutePath(directory)
-
   const abs = resolveAbsolutePath(directory, ...paths)
   const rel = relative(directory, abs)
   return (isAbsolute(rel) || (rel === '..') || rel.startsWith(`..${sep}`)) ? undefined : rel
@@ -43,7 +40,6 @@ export function resolveRelativeChildPath(directory: AbsolutePath, ...paths: stri
  * Asserts that a path is a relative path to the directory specified, failing
  * the build if it's not (see also {@link resolveRelativeChildPath}).
  */
-
 export function assertRelativeChildPath(directory: AbsolutePath, ...paths: string[]): string {
   const relative = resolveRelativeChildPath(directory, ...paths)
   assert(relative, `Path "${join(...paths)}" not relative to "${directory}"`)
@@ -76,6 +72,38 @@ export function getCurrentWorkingDirectory(): AbsolutePath {
   return cwd
 }
 
+/**
+ * Return the _common_ path amongst all specified paths.
+ *
+ * While the first `path` _must_ be an {@link AbsolutePath}, all other `paths`
+ * can be _relative_ and will be resolved against the first `path`.
+ */
+export function commonPath(path: AbsolutePath, ...paths: string[]): AbsolutePath {
+  assertAbsolutePath(path)
+
+  // Here the first path will be split into its components
+  // on win => [ 'C:', 'Windows', 'System32' ]
+  // on unx => [ '', 'usr'
+  const components = normalize(path).split(sep)
+
+  let length = components.length
+  for (const current of paths) {
+    const absolute = resolveAbsolutePath(path, current)
+    const parts = absolute.split(sep)
+    for (let i = 0; i < length; i++) {
+      if (components[i] !== parts[i]) {
+        length = i
+        break
+      }
+    }
+
+    assert(length, 'No common ancestors amongst paths')
+  }
+
+  const common = components.slice(0, length).join(sep)
+  assertAbsolutePath(common)
+  return common
+}
 
 /* ========================================================================== *
  * MODULE RESOLUTION FUNCTIONS                                                *
@@ -130,7 +158,7 @@ export function requireResolve(__fileurl: string, module: string): AbsolutePath
     // ... then delegate to the standard "require.resolve(...)"
     const url = pathToFileURL(file)
     const ext = extname(file)
-    const checks = ext ? [ `${module}`, `${module}${ext}`, `${module}/index${ext}` ] : [ module ]
+    const checks = [ `${module}`, `${module}${ext}`, `${module}/index${ext}` ]
 
     for (const check of checks) {
       const resolved = fileURLToPath(new URL(check, url)) as AbsolutePath
@@ -147,39 +175,6 @@ export function requireResolve(__fileurl: string, module: string): AbsolutePath
   return required
 }
 
-/**
- * Return the _common_ path amongst all specified paths.
- *
- * While the first `path` _must_ be an {@link AbsolutePath}, all other `paths`
- * can be _relative_ and will be resolved against the first `path`.
- */
-export function commonPath(path: AbsolutePath, ...paths: string[]): AbsolutePath {
-  assertAbsolutePath(path)
-
-  // Here the first path will be split into its components
-  // on win => [ 'C:', 'Windows', 'System32' ]
-  // on unx => [ '', 'usr'
-  const components = normalize(path).split(sep)
-
-  let length = components.length
-  for (const current of paths) {
-    const absolute = resolveAbsolutePath(path, current)
-    const parts = absolute.split(sep)
-    for (let i = 0; i < length; i++) {
-      if (components[i] !== parts[i]) {
-        length = i
-        break
-      }
-    }
-
-    assert(length, 'No common ancestors amongst paths')
-  }
-
-  const common = components.slice(0, length).join(sep)
-  assertAbsolutePath(common)
-  return common
-}
-
 /* ========================================================================== *
  * FILE CHECKING FUNCTIONS                                                    *
  * ========================================================================== */

package/src/plugs/copy.ts

@@ -9,8 +9,8 @@ import type { Context, PipeParameters, Plug } from '../pipe'
 
 /** Options for copying files */
 export interface CopyOptions {
-  /** Whether to allow overwriting or not (default `false`). */
-  overwrite?: boolean,
+  /** Whether to allow overwriting or not (default `fail`). */
+  overwrite?: 'overwrite' | 'fail' | 'skip',
   /** If specified, use this `mode` (octal string) when creating files. */
   mode?: string | number,
   /** If specified, use this `mode` (octal string) when creating directories. */
@@ -51,8 +51,8 @@ install('copy', class Copy implements Plug<Files> {
 
   async pipe(files: Files, context: Context): Promise<Files> {
     /* Destructure our options with some defaults and compute write flags */
-    const { mode, dirMode, overwrite, rename = (s): string => s } = this._options
-    const flags = overwrite ? fsConstants.COPYFILE_EXCL : 0
+    const { mode, dirMode, overwrite = 'fail', rename = (s): string => s } = this._options
+    const flags = overwrite === 'overwrite' ? 0 : fsConstants.COPYFILE_EXCL
     const dmode = parseMode(dirMode)
     const fmode = parseMode(mode)
 
@@ -88,7 +88,15 @@ install('copy', class Copy implements Plug<Files> {
 
       /* Actually _copy_ the file */
       context.log.trace(`Copying "${$p(absolute)}" to "${$p(target)}"`)
-      await copyFile(absolute, target, flags)
+      try {
+        await copyFile(absolute, target, flags)
+      } catch (error: any) {
+        if ((error.code === 'EEXIST') && (overwrite === 'skip')) {
+          context.log.warn(`Not overwriting existing file ${$p(target)}`)
+        } else {
+          throw error
+        }
+      }
 
       /* Set the mode, if we need to */
       if (fmode !== undefined) {