@plugjs/plug 0.0.27 → 0.1.1

package/src/{log.ts → logging.ts}

@@ -1,12 +1,12 @@
 import { currentContext } from './async'
-import { getLogger, type Log } from './log/logger'
-import { setupSpinner } from './log/spinner'
+import { getLogger, type Log } from './logging/logger'
+import { setupSpinner } from './logging/spinner'
 
-export * from './log/colors'
-export * from './log/levels'
-export * from './log/logger'
-export * from './log/options'
-export * from './log/report'
+export * from './logging/colors'
+export * from './logging/levels'
+export * from './logging/logger'
+export * from './logging/options'
+export * from './logging/report'
 
 /* ========================================================================== *
  * INITIALIZATION                                                             *

package/src/paths.ts

@@ -3,7 +3,7 @@ import { createRequire } from 'node:module'
 import { dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
-import { assert } from './assert'
+import { assert } from './asserts'
 
 /** A _branded_ `string` representing an _absolute_ path name */
 export type AbsolutePath = string & { __brand_absolute_path: never }
@@ -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/pipe.ts

@@ -1,13 +1,14 @@
 import { sep } from 'node:path'
 
-import { assert, assertPromises } from './assert'
-import { getLogger } from './log'
+import { assert, assertPromises } from './asserts'
+import { getLogger } from './logging'
 import { getAbsoluteParent, getCurrentWorkingDirectory, resolveAbsolutePath } from './paths'
 
 import type { Files } from './files'
-import type { Logger } from './log'
+import type { Logger } from './logging'
 import type { AbsolutePath } from './paths'
 import type { Result } from './types'
+import type { Pipe } from './index'
 
 /* ========================================================================== *
  * PLUGS                                                                      *
@@ -138,27 +139,19 @@ export class ContextPromises {
   }
 }
 
-/**
- * A class that will be extended by {@link Pipe} where {@link install} will
- * add prototype properties from installed {@link Plug}s
- */
-abstract class PipeProto {
-  abstract plug(plug: Plug<PlugResult>): Pipe | Promise<undefined>
+/** The default implementation of the {@link Pipe} interface. */
+export interface PipeImpl extends Pipe {
+  // used simply for merging types
 }
 
-/**
- * The {@link Pipe} class defines processing pipeline where multiple
- * {@link Plug}s can transform lists of {@link Files}.
- */
-export class Pipe extends PipeProto implements Promise<Files> {
+/** The default implementation of the {@link Pipe} interface. */
+export class PipeImpl implements Pipe {
   readonly [Symbol.toStringTag] = 'Pipe'
 
   constructor(
       private readonly _context: Context,
       private readonly _promise: Promise<Result>,
   ) {
-    super()
-
     // New "Pipe", remember the promise!
     ContextPromises.get(_context).hot(_promise)
   }
@@ -218,7 +211,7 @@ export class Pipe extends PipeProto implements Promise<Files> {
     ContextPromises.get(this._context).cold(this._promise)
 
     // Create and return the new Pipe
-    return new Pipe(this._context, this._promise.then(async (result) => {
+    return new PipeImpl(this._context, this._promise.then(async (result) => {
       assert(result, 'Unable to extend pipe')
       const result2 = await plug.pipe(result, this._context)
       return result2 || undefined
@@ -335,14 +328,14 @@ export function install<
   Ctor extends PlugConstructor<Name>,
 >(name: Name, ctor: Ctor): void {
   /* The function plugging the newly constructed plug in a pipe */
-  function plug(this: PipeProto, ...args: PipeParameters<Name>): Pipe | Promise<undefined> {
+  function plug(this: PipeImpl, ...args: PipeParameters<Name>): Pipe | Promise<undefined> {
     // eslint-disable-next-line new-cap
-    return this.plug(new ctor(...args))
+    return this.plug(new ctor(...args) as any)
   }
 
   /* Setup name so that stack traces look better */
   Object.defineProperty(plug, 'name', { value: name })
 
   /* Inject the create function in the Pipe's prototype */
-  Object.defineProperty(PipeProto.prototype, name, { value: plug })
+  void Object.defineProperty(PipeImpl.prototype, name, { value: plug })
 }

package/src/plugs/copy.ts

@@ -1,9 +1,9 @@
-import { assert } from '../assert'
+import { assert } from '../asserts'
 import { Files } from '../files'
-import { $p } from '../log'
+import { chmod, copyFile, fsConstants, mkdir } from '../fs'
+import { $p } from '../logging'
 import { assertAbsolutePath, getAbsoluteParent, resolveAbsolutePath } from '../paths'
 import { install } from '../pipe'
-import { chmod, copyFile, fsConstants, mkdir } from '../utils/asyncfs'
 
 import type { Context, PipeParameters, Plug } from '../pipe'
 
@@ -19,7 +19,7 @@ export interface CopyOptions {
   rename?: (relative: string) => string
 }
 
-declare module '../pipe' {
+declare module '../index' {
   export interface Pipe {
     /**
      * Copy the curent {@link Files} to a different directory

package/src/plugs/debug.ts

@@ -1,10 +1,10 @@
-import { $gry, $p, $und, $ylw } from '../log'
+import { $gry, $p, $und, $ylw } from '../logging'
 import { install } from '../pipe'
 
 import type { Files } from '../files'
 import type { Context, PipeParameters, Plug } from '../pipe'
 
-declare module '../pipe' {
+declare module '../index' {
   export interface Pipe {
     /** Log some info about the current {@link Files} being passed around. */
     debug(title?: string): Pipe

package/src/plugs/edit.ts

@@ -0,0 +1,34 @@
+import { readFile, writeFile } from '../fs'
+import { install } from '../pipe'
+
+import type { Files } from '../files'
+import type { PipeParameters, Plug } from '../pipe'
+
+declare module '../index' {
+  export interface Pipe {
+    /** Edits the content of all files in a pipeline. */
+    edit(callback: (content: string) => string | void | Promise<string | void>): Pipe
+  }
+}
+
+/* ========================================================================== *
+ * INSTALLATION / IMPLEMENTATION                                              *
+ * ========================================================================== */
+
+/** Edits the content of all files in a pipeline. */
+install('edit', class Edit implements Plug<Files> {
+  private readonly _callback: (content: string) => string | void | Promise<string | void>
+
+  constructor(...args: PipeParameters<'edit'>) {
+    this._callback = args[0]
+  }
+
+  async pipe(files: Files): Promise<Files> {
+    for (const file of files.absolutePaths()) {
+      const data = await readFile(file, 'utf-8')
+      const edited = await this._callback(data)
+      if (edited !== undefined) await writeFile(file, edited, 'utf-8')
+    }
+    return files
+  }
+})

package/src/plugs/esbuild/fix-extensions.ts

@@ -1,7 +1,7 @@
 import path from 'node:path'
 
+import { stat } from '../../fs'
 import { assertAbsolutePath, resolveAbsolutePath, resolveFile } from '../../paths'
-import { stat } from '../../utils/asyncfs'
 
 import type { Plugin } from 'esbuild'
 
@@ -72,7 +72,7 @@ export function fixExtensions(): Plugin {
         const match = args.path.match(/(.*)(\.[mc]?js$)/)
         if (match) {
           const [ , name, ext ] = match
-          const tspath = name + ext.replace('js', 'ts')
+          const tspath = name + ext!.replace('js', 'ts')
           const tsfile = resolveAbsolutePath(resolveDir, tspath)
           if (resolveFile(tsfile)) {
             const newext = ext === '.mjs' ? mjs : ext === '.cjs' ? cjs : js

package/src/plugs/esbuild.ts

@@ -2,25 +2,25 @@ import { basename } from 'node:path'
 
 import { build } from 'esbuild'
 
-import { assert } from '../assert'
+import { assert } from '../asserts'
 import { Files } from '../files'
-import { $p, ERROR, WARN } from '../log'
+import { readFile } from '../fs'
+import { $p, ERROR, WARN } from '../logging'
 import { getAbsoluteParent, resolveAbsolutePath } from '../paths'
 import { install } from '../pipe'
-import { readFile } from '../utils/asyncfs'
 
+import type { BuildFailure, BuildOptions, BuildResult, Format, Message, Metafile } from 'esbuild'
 import type { FilesBuilder } from '../files'
-import type { Logger, ReportLevel, ReportRecord } from '../log'
+import type { Logger, ReportLevel, ReportRecord } from '../logging'
 import type { AbsolutePath } from '../paths'
 import type { Context, PipeParameters, Plug } from '../pipe'
-import type { BuildFailure, BuildOptions, BuildResult, Format, Message, Metafile } from 'esbuild'
 
 export type ESBuildOptions = Omit<BuildOptions, 'absWorkingDir' | 'entryPoints' | 'watch'>
 
 export * from './esbuild/bundle-locals'
 export * from './esbuild/fix-extensions'
 
-declare module '../pipe' {
+declare module '../index' {
   export interface Pipe {
     /**
      * Transpile and bundle with {@link https://esbuild.github.io/ esbuild}.
@@ -68,6 +68,12 @@ install('esbuild', class ESBuild implements Plug<Files> {
       watch: false,
     }
 
+    if (options.format === 'cjs') {
+      options.define = Object.assign({ __fileurl: '__filename' }, options.define)
+    } else if (options.format === 'esm') {
+      options.define = Object.assign({ __fileurl: 'import.meta.url' }, options.define)
+    }
+
     /* Sanity check on output file/directory */
     assert(!(options.outdir && options.outfile), 'Options "outfile" and "outdir" can not coexist')
 
@@ -76,7 +82,7 @@ install('esbuild', class ESBuild implements Plug<Files> {
     if (options.bundle && options.outfile && (entryPoints.length === 1)) {
       builder = Files.builder(absWorkingDir)
       const outputFile = resolveAbsolutePath(absWorkingDir, options.outfile)
-      const entryPoint = resolveAbsolutePath(absWorkingDir, entryPoints[0])
+      const entryPoint = resolveAbsolutePath(absWorkingDir, entryPoints[0]!)
       options.outfile = outputFile
 
       context.log.debug('Bundling', $p(entryPoint), 'into', $p(outputFile))

package/src/plugs/exec.ts

@@ -1,40 +1,27 @@
-import { spawn } from 'node:child_process'
-import path from 'node:path'
-import reaadline from 'node:readline'
-
-import { assert } from '../assert'
-import { requireContext } from '../async'
-import { $p, logOptions } from '../log'
-import { getCurrentWorkingDirectory, resolveDirectory } from '../paths'
 import { install } from '../pipe'
 import { parseOptions } from '../utils/options'
+import { execChild } from '../utils/exec'
 
+import type { ExecChildOptions } from '../utils/exec'
 import type { Files } from '../files'
-import type { AbsolutePath } from '../paths'
 import type { Context, PipeParameters, Plug } from '../pipe'
-import type { SpawnOptions } from 'node:child_process'
 
 /** 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,
+export interface ExecOptions extends ExecChildOptions {
   /**
    * 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}.
+   * Defaults to the current {@link Files.directory | Files' directory}.
    */
   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).
+   * Whether the {@link Files} will be appended to the current arguments as
+   * _relative_ files (default or `true`) or _absolute_ (if `false`).
    */
   relativePaths?: boolean
 }
 
-declare module '../pipe' {
+declare module '../index' {
   export interface Pipe {
     /**
      * Execute a shell command, adding to its _arguments_ the list of files
@@ -114,117 +101,9 @@ install('exec', class Exec implements Plug<Files> {
     if (options.shell) params.forEach((s, i, a) => a[i] = JSON.stringify(s))
 
     // Run our child
-    await spawnChild(this._cmd, [ ...this._args, ...params ], options, context)
+    await execChild(this._cmd, [ ...this._args, ...params ], options, context)
 
     // 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', '/')
- *     // or similarly letting the shell interpret the command
- *     await exec('ls -la /', { shell: true })
- *   },
- * })
- * ```
- *
- * @param cmd The command to execute
- * @param args Any additional argument for the command to execute
- * @param options Extra {@link ExecOptions | options} for process execution
- */
-export function exec(
-    cmd: string,
-    ...args:
-    | [ ...args: string[] ]
-    | [ ...args: string[], options: ExecOptions ]
-): Promise<void> {
-  const { params, options } = parseOptions(args)
-  return spawnChild(cmd, params, options, requireContext())
-}
-
-
-/* ========================================================================== *
- * INTERNALS                                                                  *
- * ========================================================================== */
-
-async function spawnChild(
-    cmd: string,
-    args: readonly string[],
-    options: ExecOptions = {},
-    context: Context,
-): 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 ? context.resolve(cwd) : getCurrentWorkingDirectory()
-  assert(resolveDirectory(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 = context.resolve('@node_modules', '.bin')
-  if (resolveDirectory(baseNodePath)) childPaths.push(baseNodePath)
-
-  // The `.../node_bodules/.bin` path relative to the buildDir */
-  const buildNodePath = context.resolve('./node_modules', '.bin')
-  if (resolveDirectory(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(context.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
-  context.log.info('Executing', [ cmd, ...args ])
-  context.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 ? context.log.notice(line) : context.log.notice('\u00a0'))
-  }
-
-  if (child.stderr) {
-    const err = reaadline.createInterface(child.stderr)
-    err.on('line', (line) => line ? context.log.warn(line) : context.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

@@ -13,7 +13,7 @@ export interface FilterOptions extends MatchOptions {
   directory?: string
 }
 
-declare module '../pipe' {
+declare module '../index' {
   export interface Pipe {
     /**
      * Filter the current {@link Files} using globs.

package/src/plugs/rmf.ts

@@ -1,11 +1,11 @@
-import { $gry, $p } from '../log'
+import { rm } from '../fs'
+import { $gry, $p } from '../logging'
 import { install } from '../pipe'
-import { rm } from '../utils/asyncfs'
 
 import type { Files } from '../files'
 import type { Context, PipeParameters, Plug } from '../pipe'
 
-declare module '../pipe' {
+declare module '../index' {
   export interface Pipe {
     /**
      * Remove all {@link Files} piped in.

package/src/plugs.ts

@@ -1,18 +1,6 @@
-/* ========================================================================== *
- * FORKING PLUGS                                                              *
- * ========================================================================== */
-
-export * from './plugs/eslint'
-export * from './plugs/mocha'
-export * from './plugs/tsc'
-
-/* ========================================================================== *
- * STANDARD IN-PROCESS PLUGS                                                  *
- * ========================================================================== */
-
 export * from './plugs/copy'
-export * from './plugs/coverage'
 export * from './plugs/debug'
+export * from './plugs/edit'
 export * from './plugs/esbuild'
 export * from './plugs/exec'
 export * from './plugs/filter'

package/src/types.ts

@@ -1,6 +1,6 @@
 import type { Files } from './files'
 import type { AbsolutePath } from './paths'
-import type { Pipe } from './pipe'
+import type { Pipe } from './index'
 
 /**
  * A type describing the ultimate result of a {@link Plug}, {@link Pipe} or

package/src/utils/caller.ts

@@ -1,8 +1,8 @@
 import { statSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-import { assert } from '../assert'
-import { $p } from '../log'
+import { assert } from '../asserts'
+import { $p } from '../logging'
 import { assertAbsolutePath } from '../paths'
 
 import type { AbsolutePath } from '../paths'
@@ -12,7 +12,10 @@ export function findCaller(of: (...args: any[]) => any): AbsolutePath {
 
   try {
     Error.prepareStackTrace = (_, stackTraces): AbsolutePath | undefined => {
-      const nullableFileOrUrl = stackTraces[0].getFileName()
+      const [ stackTrace ] = stackTraces
+      if (! stackTrace) return
+
+      const nullableFileOrUrl = stackTrace.getFileName()
       if (! nullableFileOrUrl) return
 
       const file =