@plugjs/plug 0.1.3 → 0.2.0

package/extra/utils.ts

@@ -0,0 +1,168 @@
+/* eslint-disable no-console */
+import _childProcess from 'node:child_process'
+import _fs from 'node:fs'
+import _path from 'node:path'
+import _url from 'node:url'
+import _util from 'node:util'
+
+/* ========================================================================== *
+ * PRETTY COLORS                                                              *
+ * ========================================================================== */
+
+export const $rst = process.stdout.isTTY ? '\u001b[0m' : '' // reset all colors to default
+export const $und = process.stdout.isTTY ? '\u001b[4m' : '' // underline on
+export const $gry = process.stdout.isTTY ? '\u001b[38;5;240m' : '' // somewhat gray
+export const $blu = process.stdout.isTTY ? '\u001b[38;5;69m' : '' // brighter blue
+export const $wht = process.stdout.isTTY ? '\u001b[1;38;5;255m' : '' // full-bright white
+export const $tsk = process.stdout.isTTY ? '\u001b[38;5;141m' : '' // the color for tasks (purple)
+
+
+/* ========================================================================== *
+ * PACKAGE VERSION                                                            *
+ * ========================================================================== */
+
+export function version(): string {
+  const debug = _util.debuglog('plug:cli')
+
+  try {
+    const thisFile = _url.fileURLToPath(import.meta.url)
+    const packageFile = _path.resolve(thisFile, '..', '..', 'package.json')
+    const packageData = _fs.readFileSync(packageFile, 'utf-8')
+    return JSON.parse(packageData).version || '(unknown)'
+  } catch (error) {
+    debug('Error parsing version:', error)
+    return '(error)'
+  }
+}
+
+/* ========================================================================== *
+ * TS LOADER FORCE TYPE                                                       *
+ * ========================================================================== */
+
+function forceType(type: 'commonjs' | 'module'): void {
+  const debug = _util.debuglog('plug:cli')
+
+  const tsLoaderMarker = Symbol.for('plugjs:tsLoader')
+
+  if (!(tsLoaderMarker in globalThis)) {
+    throw new Error('TypeScript Loader not available')
+  }
+  debug(`Forcing type to "${type}"`)
+  ;(globalThis as any)[tsLoaderMarker] = type
+}
+
+
+/* ========================================================================== *
+ * FILES UTILITIES                                                            *
+ * ========================================================================== */
+
+/* Returns a boolean indicating whether the specified file exists or not */
+export function isFile(path: string): boolean {
+  try {
+    return _fs.statSync(path).isFile()
+  } catch (error) {
+    return false
+  }
+}
+
+/* Returns a boolean indicating whether the specified directory exists or not */
+export function isDirectory(path: string): boolean {
+  try {
+    return _fs.statSync(path).isDirectory()
+  } catch (error) {
+    return false
+  }
+}
+
+
+/* ========================================================================== *
+ * MAIN ENTRY POINT                                                           *
+ * ========================================================================== */
+export function main(callback: (args: string[]) => void | Promise<void>): void {
+  const debug = _util.debuglog('plug:cli')
+
+  /* Check for source maps and typescript support */
+  const sourceMapsEnabled = process.execArgv.indexOf('--enable-source-maps') >= 0
+
+  /* Check if our `ts-loader` loader is enabled */
+  const tsLoaderMarker = Symbol.for('plugjs:tsLoader')
+  const typeScriptEnabled = (globalThis as any)[tsLoaderMarker]
+
+  /* Some debugging if needed */
+  debug('SourceMaps enabled =', sourceMapsEnabled)
+  debug('TypeScript enabled =', typeScriptEnabled || false)
+
+  /* If both source maps and typescript are on, run! */
+  if (sourceMapsEnabled && typeScriptEnabled) {
+    const args = process.argv.slice(2).filter((arg: string): string | void => {
+      if (arg === '--force-esm') {
+        return forceType('module')
+      } else if (arg === '--force-cjs') {
+        return forceType('commonjs')
+      } else {
+        return arg
+      }
+    })
+
+
+    Promise.resolve().then(() => callback(args)).catch(console.error)
+  } else {
+    const script = _url.fileURLToPath(import.meta.url)
+
+    /* Fork out ourselves with new options */
+    const execArgv = [ ...process.execArgv ]
+
+    /* Enable source maps if not done already */
+    if (! sourceMapsEnabled) execArgv.push('--enable-source-maps')
+
+    /* Enable our ESM TypeScript loader if not done already */
+    if (! typeScriptEnabled) {
+      const directory = _path.dirname(script)
+      const extension = _path.extname(script) // .mts or .mjs
+      const loader = _path.resolve(directory, `ts-loader${extension}`)
+      execArgv.push(`--experimental-loader=${loader}`, '--no-warnings')
+    }
+
+    /*
+     * It seems that setting "type" as "module" in "package.json" creates some
+     * problems when the module is being imported from a "commonjs" one.
+     *
+     * TypeScript _incorrectly_ says (regardless of how we set up our conditional
+     * exports) that we must use dynamic imports:
+     *
+     *     Module '@plugjs/plug' cannot be imported using this construct. The
+     *     specifier only resolves to an ES module, which cannot be imported
+     *     synchronously. Use dynamic import instead.
+     *     TS(1471)
+     *
+     * So for now our only option is to leave "type" as "commonjs", and for those
+     * brave souls willing to force ESM irregardless of what's in "package.json",
+     * we allow the "--force-esm" option, and instruct `ts-loader` that the
+     * current directory (and subdirs) will transpile as ESM always.
+     */
+
+    /* Fork ourselves! */
+    const child = _childProcess.fork(script, [ ...process.argv.slice(2) ], {
+      stdio: [ 'inherit', 'inherit', 'inherit', 'ipc' ],
+      execArgv,
+    })
+
+    /* Monitor child process... */
+    child.on('error', (error) => {
+      console.log('Error respawning CLI', error)
+      process.exit(1)
+    })
+
+    child.on('exit', (code, signal) => {
+      if (signal) {
+        console.log(`CLI process exited with signal ${signal}`)
+        process.exit(1)
+      } else if (typeof code !== 'number') {
+        console.log('CLI process failed for an unknown reason')
+        process.exit(1)
+      } else {
+        process.exit(code)
+      }
+    })
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plugjs/plug",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "type": "commonjs",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -98,37 +98,27 @@
     }
   },
   "bin": {
-    "plug": "./extra/cli.mjs"
+    "plug": "./cli/plug.mjs",
+    "tsrun": "./cli/tsrun.mjs"
   },
-  "scripts": {
-    "bootstrap": "./bootstrap.sh",
-    "build": "./bootstrap.sh && ./extra/cli.mjs",
-    "dev": "./extra/cli.mjs -w ./src -w ./test"
-  },
-  "author": "",
-  "license": "ISC",
+  "author": "Juit Developers <developers@juit.com>",
+  "license": "Apache-2.0",
   "dependencies": {
     "@types/node": "<19",
-    "esbuild": "^0.15.18",
+    "esbuild": "^0.17.10",
     "picomatch": "^2.3.1",
-    "typescript": "^4.9.3"
+    "typescript": "^4.9.5"
   },
   "devDependencies": {
-    "@plugjs/cov8": "^0.1.2",
-    "@plugjs/eslint": "^0.1.2",
-    "@plugjs/eslint-plugin": "^0.1.1",
-    "@plugjs/jasmine": "^0.1.2",
-    "@plugjs/typescript": "^0.1.2",
     "@types/picomatch": "^2.3.0",
     "@types/yargs-parser": "^21.0.0",
-    "chai": "^4.3.7",
-    "chai-as-promised": "^7.1.1",
     "yargs-parser": "^21.1.1"
   },
   "files": [
     "*.md",
+    "cli/",
     "dist/",
-    "extra/*.mjs",
+    "extra/",
     "src/",
     "types/"
   ]

package/src/asserts.ts

@@ -12,17 +12,20 @@ export function isBuildFailure(arg: any): arg is BuildFailure {
 
 /** A {@link BuildFailure} represents an error _already logged_ in our build. */
 export class BuildFailure extends Error {
-  readonly errors!: readonly any[]
+  readonly errors?: readonly any[] | undefined
 
   /** Construct a {@link BuildFailure} */
-  private constructor(message: string | undefined, errors: any[]) {
+  constructor(message?: string | undefined, errors: any[] = []) {
     super(message || '')
 
-    /* Basic error setup, stack and marker */
+    /* Basic error setup: stack and errors */
     Error.captureStackTrace(this, BuildFailure)
+    if (errors.length) this.errors = Object.freeze([ ...errors ])
+
+    /* Other properties: marker and name */
     Object.defineProperties(this, {
-      'errors': { value: Object.freeze([ ...errors ]) },
       [buildFailure]: { value: buildFailure },
+      'name': { value: 'BuildFailure' },
     })
   }
 

package/src/build.ts

@@ -23,30 +23,40 @@ import type {
  * TASK                                                                       *
  * ========================================================================== */
 
-class TaskImpl implements Task {
-  constructor(
-      public readonly buildFile: AbsolutePath,
-      public readonly tasks: Tasks,
-      public readonly props: Props,
-      private readonly _def: TaskDef,
-  ) {}
+/** Symbol indicating that an object is a {@link Task} */
+const taskMarker = Symbol.for('plugjs:isTask')
 
-  invoke(state: State, taskName: string): Promise<Result> {
-    assert(! state.stack.includes(this), `Recursion detected calling ${$t(taskName)}`)
+/** Type guard for {@link Tasks} */
+function isTask(something: any): something is Task {
+  return something[taskMarker] === true
+}
+
+/** Create a new {@link Task} instance */
+function makeTask(
+    buildFile: AbsolutePath,
+    tasks: Tasks,
+    props: Props,
+    _def: TaskDef,
+    _name: string,
+): Task {
+  /* Invoke the task, checking call stack, caches, and merging builds */
+  function invoke(state: State, taskName: string): Promise<Result> {
+    assert(! state.stack.includes(task), `Recursion detected calling ${$t(taskName)}`)
 
     /* Check cache */
-    const cached = state.cache.get(this)
+    const cached = state.cache.get(task)
     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 props: Record<string, string> = Object.assign({}, task.props, state.props)
+    const tasks: Record<string, Task> = Object.assign({}, task.tasks, state.tasks)
+    const stack = [ ...state.stack, task ]
     const cache = state.cache
 
     /* Create run context and build */
-    const context = new Context(this.buildFile, taskName)
+    const context = new Context(task.buildFile, taskName)
 
+    /* The build (the `this` value calling the definition) is a proxy */
     const build = new Proxy({}, {
       get(_: any, name: string): void | string | (() => Pipe) {
         // Tasks first, props might come also from environment
@@ -68,18 +78,35 @@ class TaskImpl implements Task {
 
     /* Run asynchronously in an asynchronous context */
     const promise = runAsync(context, taskName, async () => {
-      return await this._def.call(build) || undefined
+      return await _def.call(build) || undefined
     }).then((result) => {
-      context.log.notice(`Success ${$ms(Date.now() - now)}`)
+      const level = taskName.startsWith('_') ? 'info' : 'notice'
+      context.log[level](`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)
+    cache.set(task, promise)
     return promise
   }
+
+  /* Create the new Task. The function will simply create an empty state */
+  const task: Task = Object.assign((overrideProps: Props = {}) => {
+    const state: State = {
+      cache: new Map<Task, Promise<Result>>(),
+      stack: [] as Task[],
+      props: Object.assign({}, props, overrideProps),
+      tasks: tasks,
+    }
+    return invoke(state, _name)
+  }, { buildFile, tasks, props, invoke })
+
+  /* Assign the task's marker and name and return it */
+  Object.defineProperty(task, taskMarker, { value: true })
+  Object.defineProperty(task, 'name', { value: _name })
+  return task
 }
 
 /* ========================================================================== *
@@ -100,13 +127,13 @@ export function build<
   /* Iterate through all definition extracting properties and tasks */
   for (const [ key, val ] of Object.entries(def)) {
     let len = 0
-    if (typeof val === 'string') {
+    if (isTask(val)) { // this goes first, tasks _are_ functions!
+      tasks[key] = val
+      len = key.length
+    } else 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
+      tasks[key] = makeTask(buildFile, tasks, props, val, key)
       len = key.length
     }
 

package/src/files.ts

@@ -31,8 +31,8 @@ export interface FilesBuilder {
  * identifying some _files_ rooted in a given _directory_.
  */
 export class Files {
-  readonly _directory: AbsolutePath
-  readonly _files: string[]
+  private readonly _directory: AbsolutePath
+  private readonly _files: string[]
 
   /**
    * Create a new {@link Files} instance rooted in the specified `directory`

package/src/fork.ts

@@ -53,7 +53,7 @@ export abstract class ForkingPlug implements Plug<PlugResult> {
   ) {}
 
   pipe(files: Files, context: Context): Promise<PlugResult> {
-    const message: ForkData = {
+    const request: ForkData = {
       scriptFile: this._scriptFile,
       exportName: this._exportName,
       constructorArgs: this._arguments,
@@ -93,7 +93,7 @@ export abstract class ForkingPlug implements Plug<PlugResult> {
     /* Return a promise from the child process events */
     let done = false // this will be fixed up in "finally" below
     return new Promise<PlugResult>((resolve, reject) => {
-      let result: ForkResult | undefined = undefined
+      let response: ForkResult | undefined = undefined
 
       child.on('error', (error) => {
         context.log.error('Child process error', error)
@@ -102,7 +102,7 @@ export abstract class ForkingPlug implements Plug<PlugResult> {
 
       child.on('message', (message: ForkResult) => {
         context.log.debug('Message from child process', message)
-        result = message
+        response = message
       })
 
       child.on('exit', (code, signal) => {
@@ -112,23 +112,23 @@ export abstract class ForkingPlug implements Plug<PlugResult> {
         } else if (code !== 0) {
           context.log.error(`Child process exited with code ${code}`, $gry(`(pid=${child.pid})`))
           return done || reject(BuildFailure.fail())
-        } else if (! result) {
+        } else if (! response) {
           context.log.error('Child process exited with no result', $gry(`(pid=${child.pid})`))
           return done || reject(BuildFailure.fail())
-        } else if (result.failed) {
+        } else if (response.failed) {
           // definitely logged on the child side
           return done || reject(BuildFailure.fail())
         }
 
         /* We definitely have a successful result! */
-        return done || resolve(message.filesDir && message.filesList ?
-            Files.builder(message.filesDir).add(...message.filesList).build() :
+        return done || resolve(response.filesDir && response.filesList ?
+            Files.builder(response.filesDir).add(...response.filesList).build() :
             undefined)
       })
 
       /* After the handlers have been setup, send the message */
       try {
-        const result = child.send(message, (error) => {
+        const result = child.send(request, (error) => {
           if (error) {
             context.log.error('Error sending message to child process (callback failure)', error)
             reject(BuildFailure.fail())
@@ -200,6 +200,7 @@ if ((process.argv[1] === requireFilename(__fileurl)) && (process.send)) {
         assert(typeof Ctor === 'function', `Script ${$p(scriptFile)} does not export a default constructor`)
       } else {
         Ctor = script[exportName]
+        if ((! Ctor) && (script.default)) Ctor = script.default[exportName]
         assert(typeof Ctor === 'function', `Script ${$p(scriptFile)} does not export "${exportName}"`)
       }
 

package/src/helpers.ts

@@ -1,6 +1,6 @@
+import { mkdtempSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { mkdtempSync } from 'node:fs'
 
 import { assert, assertPromises } from './asserts'
 import { requireContext } from './async'
@@ -101,7 +101,11 @@ export function merge(pipes: (Pipe | Files | Promise<Files>)[]): Pipe {
     if (pipes.length === 0) return Files.builder(getCurrentWorkingDirectory()).build()
 
     // Await for all pipes / files / files promises
-    const results = await assertPromises<Files>(pipes)
+    const awaited = await assertPromises<Files>(pipes)
+    const results = awaited.filter((result) => result.length)
+
+    // No files in anything to be merged? Again send off an empty pipe...
+    if (results.length === 0) return Files.builder(getCurrentWorkingDirectory()).build()
 
     // Find the common directory between all the Files instances
     const [ firstDir, ...otherDirs ] = results.map((f) => f.directory)

package/src/index.ts

@@ -6,6 +6,10 @@
 import type { Files } from './files'
 import type { Plug, PlugFunction } from './pipe'
 
+export { Files } from './files'
+export type { AbsolutePath } from './paths'
+export type { Plug, PlugFunction } from './pipe'
+
 /**
  * The {@link Pipe} interface defines a processing pipeline where multiple
  * {@link Plug}s can transform lists of {@link Files}.
@@ -31,7 +35,7 @@ export * as utils from './utils'
 
 // Individual utilities
 export { log, $ms, $p, $t, $blu, $cyn, $grn, $gry, $mgt, $red, $und, $wht, $ylw } from './logging'
-export { assert, fail } from './asserts'
+export { assert, fail, BuildFailure } from './asserts'
 
 // Our minimal exports
 export * from './build'

package/src/logging/logger.ts

@@ -99,7 +99,7 @@ class LoggerImpl implements Logger {
         _loggedFailures.add(arg)
 
         // If the build failure has any root cause, log those
-        arg.errors.forEach((error) => this._emit(level, [ error ]))
+        arg.errors?.forEach((error) => this._emit(level, [ error ]))
 
         // Log this only if it has a message
         if (! arg.message) return false

package/src/plugs/edit.ts

@@ -2,12 +2,13 @@ import { readFile, writeFile } from '../fs'
 import { install } from '../pipe'
 
 import type { Files } from '../files'
+import type { AbsolutePath } from '../paths'
 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
+    edit(callback: (content: string, fileName: AbsolutePath) => string | void | Promise<string | void>): Pipe
   }
 }
 
@@ -17,7 +18,7 @@ declare module '../index' {
 
 /** 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>
+  private readonly _callback: (content: string, fileName: AbsolutePath) => string | void | Promise<string | void>
 
   constructor(...args: PipeParameters<'edit'>) {
     this._callback = args[0]
@@ -26,7 +27,7 @@ install('edit', class Edit implements Plug<Files> {
   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)
+      const edited = await this._callback(data, file)
       if (edited !== undefined) await writeFile(file, edited, 'utf-8')
     }
     return files

package/src/plugs/esbuild.ts

@@ -65,7 +65,6 @@ install('esbuild', class ESBuild implements Plug<Files> {
       absWorkingDir,
       entryPoints,
       logLevel: 'silent',
-      watch: false,
     }
 
     if (options.format === 'cjs') {