@plugjs/plug 0.2.5 → 0.2.7

package/extra/tsrun.mts

@@ -2,8 +2,15 @@
 /* eslint-disable no-console */
 
 import _path from 'node:path'
+import _repl from 'node:repl'
+import _module from 'node:module'
 
-import { $blu, $gry, $rst, $und, $wht, main, version } from './utils.js'
+import _yargs from 'yargs-parser'
+
+import { $blu, $gry, $rst, $und, $wht, main } from './utils.js'
+
+/** Version injected by esbuild */
+declare const __version: string
 
 /** Our minimalistic help */
 function help(): never {
@@ -13,8 +20,10 @@ function help(): never {
 
   ${$blu}${$und}Options:${$rst}
 
-      ${$wht}-h --help${$rst}       Help! You're reading it now!
-      ${$wht}-v --version${$rst}    Version! This one: ${version()}!
+      ${$wht}-h --help     ${$rst}  Help! You're reading it now!
+      ${$wht}-v --version  ${$rst}  Version! This one: ${__version}!
+      ${$wht}-e --eval     ${$rst}  Evaluate the script
+      ${$wht}-p --print    ${$rst}  Evaluate the script and print the result
       ${$wht}   --force-esm${$rst}  Force transpilation of ".ts" files to EcmaScript modules
       ${$wht}   --force-cjs${$rst}  Force transpilation of ".ts" files to CommonJS modules
 
@@ -31,34 +40,88 @@ function help(): never {
 
 /** Process the command line */
 main((args: string[]): void => {
-  let script: string | undefined
-  let scriptArgs: string[] = []
+  let _script: string | undefined
+  let _scriptArgs: string[] = []
+  let _print: boolean = false
+  let _eval: boolean = false
+
+  /* Yargs-parse our arguments */
+  const parsed = _yargs(args, {
+    configuration: {
+      'camel-case-expansion': false,
+      'strip-aliased': true,
+      'strip-dashed': true,
+    },
+
+    alias: {
+      'version': [ 'v' ],
+      'help': [ 'h' ],
+      'eval': [ 'e' ],
+      'print': [ 'p' ],
+    },
+
+    boolean: [ 'help', 'eval', 'print', 'force-esm', 'version', 'force-cjs' ],
+  })
 
   // Parse options, leaving script and scriptArgs with our code to run
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i]
-
-    if ((arg === '-h') || (arg === '--help')) help()
-    if ((arg === '-v') || (arg === '--version')) {
-      console.log(`v${version()}`)
-      process.exit(1)
-    }
-
-    if (arg!.startsWith('-')) {
-      console.log(`${$wht}tsrun${$rst}: Uknown option "${$wht}${arg}${$rst}"`)
-      process.exit(1)
+  for (const [ key, value ] of Object.entries(parsed)) {
+    switch (key) {
+      case '_': // extra arguments
+        [ _script, ..._scriptArgs ] = value
+        break
+      case 'help': // help screen
+        help()
+        break
+      case 'version': // version dump
+        console.log(`v${__version}`)
+        process.exit(0)
+        break
+      case 'eval': // eval script
+        _eval = value
+        break
+      case 'print': // eval script and print return value
+        _print = true
+        _eval = true
+        break
     }
-
-    ([ script, ...scriptArgs ] = args.slice(i))
-    break
   }
 
-  // No script? Then help
-  if (! script) help()
-
-  // Resolve the _full_ path of the script, and tweak our process.argv
-  // arguments, them simply import the script and let Node do its thing...
-  script = _path.resolve(process.cwd(), script)
-  process.argv = [ process.argv0, script, ...scriptArgs ]
-  import(script)
+  // Start the repl or run the script?
+  if (! _script) {
+    // No script? Then repl
+    console.log(`Welcome to Node.js ${process.version} (tsrun v${__version}).`)
+    console.log('Type ".help" for more information.')
+    _repl.start()
+  } else if (_eval) {
+    // If we are evaluating a script, we need to use some node internals to do
+    // all the tricks to run this... We a fake script running the code to
+    // evaluate, instrumenting "globalThis" with all required vars and modules
+    const script = `
+      globalThis.module = module;
+      globalThis.require = require;
+      globalThis.exports = exports;
+      globalThis.__dirname = __dirname;
+      globalThis.__filename = __filename;
+
+      for (const module of require('repl').builtinModules) {
+        if (module.indexOf('/') >= 0) continue;
+        if (Object.hasOwn(globalThis, module)) continue;
+        Object.defineProperty(globalThis, module, { get: () => require(module) });
+      }
+
+      return require('node:vm').runInThisContext(${JSON.stringify(_script)}, '[eval]')
+    `
+
+    // Use the Node internal "Module._compile" to compile and run our script
+    const result = (new _module('[eval]') as any)._compile(script, '[eval]')
+
+    // If we need to print, then let's do it!
+    if (_print) console.log(result)
+  } else {
+    // Resolve the _full_ path of the script, and tweak our process.argv
+    // arguments, them simply import the script and let Node do its thing...
+    _script = _path.resolve(process.cwd(), _script)
+    process.argv = [ process.argv0, _script, ..._scriptArgs ]
+    import(_script)
+  }
 })

package/extra/utils.ts

@@ -17,24 +17,6 @@ export const $wht = process.stdout.isTTY ? '\u001b[1;38;5;255m' : '' // full-bri
 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                                                       *
  * ========================================================================== */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plugjs/plug",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "type": "commonjs",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",

package/src/asserts.ts

@@ -2,6 +2,8 @@
  * BUILD FAILURES                                                             *
  * ========================================================================== */
 
+import { githubAnnotation } from './logging/github'
+
 /** A symbol marking {@link BuildFailure} instances */
 const buildFailure = Symbol.for('plugjs:buildFailure')
 
@@ -18,6 +20,11 @@ export class BuildFailure extends Error {
   constructor(message?: string | undefined, errors: any[] = []) {
     super(message || '')
 
+    // Annotate this build failure in GitHub
+    if (message) {
+      githubAnnotation({ type: 'error', title: 'Build Failure' }, message)
+    }
+
     /* Basic error setup: stack and errors */
     Error.captureStackTrace(this, BuildFailure)
     if (errors.length) this.errors = Object.freeze([ ...errors ])

package/src/fork.ts

@@ -62,10 +62,10 @@ export abstract class ForkingPlug implements Plug<PlugResult> {
 
     /* Get _this_ filename to spawn */
     const script = requireFilename(__fileurl)
-    context.log.debug('About to fork plug from', $p(script))
+    context.log.debug('About to fork plug from', $p(this._scriptFile))
 
     /* Environment variables */
-    const env = { ...process.env, ...logOptions.forkEnv(context.taskName) }
+    const env = { ...process.env, ...logOptions.forkEnv(context.taskName, 4) }
 
     /* Check our args (reversed) to see if the last specifies `coverageDir` */
     for (let i = this._arguments.length - 1; i >= 0; i --) {
@@ -80,10 +80,15 @@ export abstract class ForkingPlug implements Plug<PlugResult> {
 
     /* Run our script in a _separate_ process */
     const child = fork(script, {
-      stdio: [ 'ignore', 'inherit', 'inherit', 'ipc' ],
+      stdio: [ 'ignore', 'inherit', 'inherit', 'ipc', 'pipe' ],
       env,
     })
 
+    /* Pipe child logs directly to the writer */
+    if (child.stdio[4]) {
+      child.stdio[4].on('data', (data) => logOptions.output.write(data))
+    }
+
     context.log.info('Running', $p(script), $gry(`(pid=${child.pid})`))
 
     /* Return a promise from the child process events */
@@ -97,7 +102,7 @@ export abstract class ForkingPlug implements Plug<PlugResult> {
       })
 
       child.on('message', (message: ForkResult) => {
-        context.log.debug('Message from child process', message)
+        context.log.debug('Message from child process with PID', child.pid, message)
         response = message
       })
 
@@ -176,7 +181,7 @@ if ((process.argv[1] === requireFilename(__fileurl)) && (process.send)) {
 
     /* First of all, our plug context */
     const context = new Context(buildFile, taskName)
-    context.log.debug('Message from parent process', message)
+    context.log.debug('Message from parent process for PID', process.pid, message)
 
     /* Contextualize this run, and go! */
     const result = runAsync(context, taskName, async () => {

package/src/helpers.ts

@@ -1,4 +1,4 @@
-import { mkdtempSync } from 'node:fs'
+import { mkdtempSync, readFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
@@ -207,3 +207,26 @@ export function exec(
   const { params, options } = parseOptions(args)
   return execChild(cmd, params, options, requireContext())
 }
+
+/**
+ * Read and parse a JSON file, throwing an error if not found.
+ *
+ * @params file The JSON file to parse
+ */
+export function parseJson(file: string): any {
+  const jsonFile = requireContext().resolve(file)
+  let jsonText: string
+  try {
+    jsonText = readFileSync(jsonFile, 'utf-8')
+  } catch (error: any) {
+    if (error.code === 'ENOENT') log.fail(`File ${$p(jsonFile)} not found`)
+    if (error.code === 'EACCES') log.fail(`File ${$p(jsonFile)} can not be accessed`)
+    log.fail(`Error reading ${$p(jsonFile)}`, error)
+  }
+
+  try {
+    return JSON.parse(jsonText)
+  } catch (error) {
+    log.fail(`Error parsing ${$p(jsonFile)}`, error)
+  }
+}

package/src/logging/emit.ts

@@ -77,10 +77,7 @@ export const emitColor: LogEmitter = (options: LogEmitterOptions, args: any[]):
 
   /* Write each individual line out */
   for (const line of message.split('\n')) {
-    _output.write(zapSpinner)
-    _output.write(linePrefix)
-    _output.write(line)
-    _output.write('\n')
+    _output.write(`${zapSpinner}${linePrefix}${line}\n`)
   }
 }
 
@@ -120,8 +117,6 @@ export const emitPlain: LogEmitter = (options: LogEmitterOptions, args: any[]):
 
   /* Write each individual line out */
   for (const line of message.split('\n')) {
-    _output.write(linePrefix)
-    _output.write(line)
-    _output.write('\n')
+    _output.write(`${linePrefix}${line}\n`)
   }
 }

package/src/logging/github.ts

@@ -0,0 +1,71 @@
+import { EOL } from 'node:os'
+import { formatWithOptions } from 'node:util'
+
+import { logOptions } from './options'
+
+import type { AbsolutePath } from '../paths'
+
+
+/* Initial values, and subscribe to changes */
+let _colors = logOptions.colors
+let _output = logOptions.output
+let _inspectOptions = logOptions.inspectOptions
+let _githubAnnotations = logOptions.githubAnnotations
+logOptions.on('changed', (options) => {
+  _colors = options.colors
+  _output = options.output
+  _githubAnnotations = options.githubAnnotations
+  _inspectOptions = { ...options.inspectOptions, breakLength: Infinity }
+})
+
+
+function escapeData(data: string): string {
+  return data
+      .replace(/%/g, '%25')
+      .replace(/\r/g, '%0D')
+      .replace(/\n/g, '%0A')
+}
+
+function escapeProp(prop: string | number): string {
+  return `${prop}`
+      .replace(/%/g, '%25')
+      .replace(/\r/g, '%0D')
+      .replace(/\n/g, '%0A')
+      .replace(/:/g, '%3A')
+      .replace(/,/g, '%2C')
+}
+
+export type GithubAnnotationType = 'warning' | 'error'
+
+export interface GithubAnnotationOptions {
+  type: GithubAnnotationType
+  title?: string
+  file?: AbsolutePath
+  line?: number
+  endLine?: number
+  col?: number
+  endColumn?: number
+}
+
+export function githubAnnotation(type: GithubAnnotationType, message: string, ...args: any[]): void
+export function githubAnnotation(options: GithubAnnotationOptions, message: string, ...args: any[]): void
+
+export function githubAnnotation(options: GithubAnnotationType | GithubAnnotationOptions, ...args: any[]): void {
+  if (_colors || (! _githubAnnotations)) return
+
+  if (typeof options === 'string') options = { type: options }
+  const { type, ...parameters } = options
+
+  const attributes = Object.entries(parameters)
+      .filter(([ key, value ]) => !!(key && value))
+      .map(([ key, value ]) => `${key}=${escapeProp(value)}`)
+      .join(',')
+
+  const msg = escapeData(formatWithOptions(_inspectOptions, ...args))
+
+  if (attributes) {
+    _output.write(`::${type} ${attributes}::${msg}${EOL}`)
+  } else {
+    _output.write(`::${type}::${msg}${EOL}`)
+  }
+}

package/src/logging/options.ts

@@ -1,4 +1,5 @@
 import { EventEmitter } from 'node:events'
+import { Socket } from 'node:net'
 
 import { getLevelNumber, NOTICE } from './levels'
 
@@ -28,6 +29,8 @@ export interface LogOptions {
   showSources: boolean,
   /** The task name to be used by default if a task is not contextualized. */
   defaultTaskName: string,
+  /** Whether GitHub annotations are enabled or not. */
+  githubAnnotations: boolean,
   /** The options used by NodeJS for object inspection. */
   readonly inspectOptions: InspectOptions,
 
@@ -41,8 +44,13 @@ export interface LogOptions {
   /** Remove an event listener for the specified event. */
   off(eventName: 'changed', listener: (logOptions: this) => void): this;
 
-  /** Return a record of environment variables for forking. */
-  forkEnv(taskName?: string): Record<string, string>
+  /**
+   * Return a record of environment variables for forking.
+   *
+   * @param taskName The default task name of the forked process
+   * @param logFd A file descriptor where logs should be sinked to
+   */
+  forkEnv(taskName?: string, logFd?: number): Record<string, string>
 }
 
 /* ========================================================================== *
@@ -58,6 +66,7 @@ class LogOptionsImpl extends EventEmitter implements LogOptions {
   private _lineLength = (<NodeJS.WriteStream> this._output).columns || 80
   private _lineLengthSet = false // has line length been set manually?
   private _showSources = true // by default, always show source snippets
+  private _githubAnnotations = false // ultimately set by the constructor
   private _inspectOptions: InspectOptions = {}
   private _defaultTaskName = ''
   private _taskLength = 0
@@ -78,27 +87,34 @@ class LogOptionsImpl extends EventEmitter implements LogOptions {
       // Other values don't change the value of `options.colors`
     }
 
+    /* If the `GITHUB_ACTIONS` is `true` then enable annotations */
+    this._githubAnnotations = process.env.GITHUB_ACTIONS === 'true'
+
     /*
      * The `__LOG_OPTIONS` variable is a JSON-serialized `LogOptions` object
      * and it's processed _last_ as it's normally only created by fork below
      * and consumed by the `Exec` plug (which has no other way of communicating)
      */
-    Object.assign(this, JSON.parse(process.env.__LOG_OPTIONS || '{}'))
+    const { fd, ...options } = JSON.parse(process.env.__LOG_OPTIONS || '{}')
+    if (fd) this.output = new Socket({ fd }).unref()
+    Object.assign(this, options)
   }
 
   private _notifyListeners(): void {
     super.emit('changed', this)
   }
 
-  forkEnv(taskName?: string): Record<string, string> {
+  forkEnv(taskName?: string, fd?: number): Record<string, string> {
     return {
       __LOG_OPTIONS: JSON.stringify({
         level: this._level,
         colors: this._colors,
         lineLength: this._lineLength,
         taskLength: this._taskLength,
+        githubAnnotations: this.githubAnnotations,
         defaultTaskName: taskName || this._defaultTaskName,
         spinner: false, // forked spinner is always false
+        fd, // file descriptor for logs
       }),
     }
   }
@@ -189,6 +205,15 @@ class LogOptionsImpl extends EventEmitter implements LogOptions {
     this._notifyListeners()
   }
 
+  get githubAnnotations(): boolean {
+    return this._githubAnnotations
+  }
+
+  set githubAnnotations(githubAnnotations: boolean) {
+    this._githubAnnotations = githubAnnotations
+    this._notifyListeners()
+  }
+
   get inspectOptions(): InspectOptions {
     return {
       colors: this._colors,

package/src/logging/report.ts

@@ -1,13 +1,22 @@
 import { BuildFailure } from '../asserts'
 import { readFile } from '../fs'
 import { $blu, $cyn, $gry, $red, $und, $wht, $ylw } from './colors'
-import { ERROR, NOTICE, WARN } from './levels'
+import { ERROR, logLevels, NOTICE, WARN } from './levels'
 import { logOptions } from './options'
+import { githubAnnotation } from './github'
 
 import type { AbsolutePath } from '../paths'
 import type { LogEmitter } from './emit'
 import type { LogLevels } from './levels'
 
+let _showSources = logOptions.showSources
+let _githubAnnotations = logOptions.githubAnnotations
+logOptions.on('changed', (options) => {
+  _showSources = options.showSources
+  _githubAnnotations = options.githubAnnotations
+})
+
+
 /* ========================================================================== */
 
 /** Levels used in a {@link Report}  */
@@ -267,12 +276,12 @@ export class ReportImpl implements Report {
 
 
   done(showSources?: boolean | undefined): void {
-    if (showSources == null) showSources = logOptions.showSources
+    if (showSources == null) showSources = _showSources
     if (! this.empty) this._emit(showSources)
     if (this.errors) throw BuildFailure.fail()
   }
 
-  private _emit(showSources: boolean): this {
+  private _emit(showSources: boolean): void {
     /* Counters for all we need to print nicely */
     let fPad = 0
     let aPad = 0
@@ -281,7 +290,7 @@ export class ReportImpl implements Report {
     let cPad = 0
 
     /* Skip report all together if empty! */
-    if ((this._annotations.size === 0) && (this._records.size === 0)) return this
+    if ((this._annotations.size === 0) && (this._records.size === 0)) return
 
     /* This is GIANT: sort and convert our data for easy reporting */
     const entries = [ ...this._annotations.keys(), ...this._records.keys() ]
@@ -431,7 +440,32 @@ export class ReportImpl implements Report {
       this._emitter(options, [ '' ])
     }
 
-    /* Done! */
-    return this
+    /* Annotate in GitHub */
+    if (_githubAnnotations) {
+      for (const entry of entries) {
+        const file = entry.file === nul ? undefined : entry.file
+
+        for (const report of entry.records) {
+          const type: 'error' | 'warning' | null =
+            report.level === logLevels.ERROR ? 'error' :
+            report.level === logLevels.WARN ? 'warning' :
+            null
+
+          if (! type) continue
+
+          const title = `${this._title} (task "${this._task}")`
+          const col = report.column || undefined
+          const line = report.line || undefined
+          const endColumn =
+            report.column ?
+              report.length >= Number.MAX_SAFE_INTEGER ? undefined :
+              ((report.column + report.length) || undefined) :
+            undefined
+          const message = report.messages.join('\n')
+
+          githubAnnotation({ type, title, file, col, line, endColumn }, message)
+        }
+      }
+    }
   }
 }

package/src/logging.ts

@@ -3,6 +3,7 @@ import { getLogger, type Log } from './logging/logger'
 import { setupSpinner } from './logging/spinner'
 
 export * from './logging/colors'
+export * from './logging/github'
 export * from './logging/levels'
 export * from './logging/logger'
 export * from './logging/options'

package/src/utils/exec.ts

@@ -1,5 +1,5 @@
 import path from 'node:path'
-import reaadline from 'node:readline'
+import readline from 'node:readline'
 import { fork as forkProcess, spawn as spawnProcess } from 'node:child_process'
 
 import { assert, BuildFailure } from '../asserts'
@@ -62,7 +62,7 @@ export async function execChild(
 
   // Build our environment variables record
   const PATH = childPaths.join(path.delimiter)
-  const logForkEnv = logOptions.forkEnv(context.taskName)
+  const logForkEnv = logOptions.forkEnv(context.taskName, 4)
   const childEnv: Record<string, string> = { ...process.env, ...env, ...logForkEnv, PATH }
 
   // Instrument coverage directory if needed
@@ -71,32 +71,43 @@ export async function execChild(
   // Prepare the options for calling `spawn`
   const childOptions: SpawnOptions = {
     ...extraOptions,
-    stdio: [ 'ignore', 'pipe', 'pipe' ],
+    stdio: [ 'ignore', 'pipe', 'pipe', 'ipc', 'pipe' ],
     cwd: childCwd,
     env: childEnv,
     shell,
   }
 
-  // Add the 'ipc' channel to stdio options if forking
-  if (fork) childOptions.stdio = [ 'ignore', 'pipe', 'pipe', 'ipc' ]
-
   // Spawn our subprocess and monitor its stdout/stderr
-  context.log.info('Executing', [ cmd, ...args ])
-  context.log.info('Execution options', childOptions)
+  context.log.info(fork ? 'Forking' : 'Executing', [ cmd, ...args ])
+  context.log.debug('Child process options', childOptions)
+
   const child = fork ?
     forkProcess(cmd, args, childOptions) :
     spawnProcess(cmd, args, childOptions)
 
-  // Standard output to "notice"
-  if (child.stdout) {
-    const out = reaadline.createInterface(child.stdout)
-    out.on('line', (line) => line ? context.log.notice(line) : context.log.notice('\u00a0'))
-  }
-
-  // Standard error to "warning"
-  if (child.stderr) {
-    const err = reaadline.createInterface(child.stderr)
-    err.on('line', (line) => line ? context.log.warn(line) : context.log.warn('\u00a0'))
+  try {
+    context.log.info('Child process PID', child.pid)
+
+    // Standard output to "notice"
+    if (child.stdout) {
+      const out = readline.createInterface(child.stdout)
+      out.on('line', (line) => context.log.notice(line || '\u00a0'))
+    }
+
+    // Standard error to "warning"
+    if (child.stderr) {
+      const err = readline.createInterface(child.stderr)
+      err.on('line', (line) => context.log.warn(line ||'\u00a0'))
+    }
+
+    // Log output bypass
+    if (child.stdio[4]) {
+      child.stdio[4].on('data', (data) => logOptions.output.write(data))
+    }
+  } catch (error) {
+    // If something happens before returning our promise, kill the child...
+    child.kill()
+    throw error
   }
 
   // Return our promise from the spawn events