@plugjs/plug 0.0.1

package/src/log/colors.ts

@@ -0,0 +1,119 @@
+import { sep } from 'node:path'
+import { AbsolutePath, getCurrentWorkingDirectory, resolveRelativeChildPath } from '../paths.js'
+import { logOptions } from './options.js'
+
+/* ========================================================================== */
+
+/* Initial value of log colors, and subscribe to changes */
+let _colors = logOptions.colors
+logOptions.on('changed', ({ colors }) => _colors = colors)
+
+/* ========================================================================== *
+ * PRETTY COLORS                                                              *
+ * ========================================================================== */
+
+const rst = '\u001b[0m' // reset all colors to default
+
+const und = '\u001b[4m' // underline on
+
+const gry = '\u001b[38;5;240m' // somewhat gray
+const red = '\u001b[38;5;203m' // light red (Leo's favorite)
+const grn = '\u001b[38;5;76m' // greenish
+const ylw = '\u001b[38;5;220m' // yellow
+const blu = '\u001b[38;5;69m' // brighter blue
+const mgt = '\u001b[38;5;213m' // pinky magenta
+const cyn = '\u001b[38;5;81m' // darker cyan
+const wht = '\u001b[1;38;5;255m' // full-bright white
+
+const tsk = '\u001b[38;5;141m' // the color for tasks (purple)
+
+/* ========================================================================== */
+
+function colorize(color: string, string: any): string {
+  if (! _colors) return `${string}`
+  const lines = `${string}`.split('\n')
+  return lines.map((line) => `${color}${line}${rst}`).join('\n')
+}
+
+/** Colorize an {@link AbsolutePath}. */
+export function $p(path: AbsolutePath): string {
+  const directory = getCurrentWorkingDirectory()
+  const relative = resolveRelativeChildPath(directory, path)
+  const resolved = relative == null ? path : `.${sep}${relative}`
+  return _colors ? `${und}${gry}${resolved}${rst}` : `"${resolved}"`
+}
+
+/** Colorize a _task name_. */
+export function $t(task: string): string {
+  return _colors ? `${tsk}${task}${rst}` : `"${task}"`
+}
+
+/** Colorize milliseconds. */
+export function $ms(millis: number): string {
+  let string: string
+  if (millis >= 60000) {
+    // One minute or more: style is Xm Ys
+    const minutes = Math.floor(millis / 60000)
+    const seconds = Math.floor((millis % 60000) / 1000)
+    string = `${minutes}m ${seconds}s`
+  } else if (millis >= 10000) {
+    // Ten seconds or more: style is 12.3s
+    const seconds = Math.floor(millis / 1000)
+    const decimal = Math.floor(millis % 1000 / 100)
+    string = `${seconds}.${decimal}s`
+  } else if (millis >= 1000) {
+    // One second or more: style is 1.23s
+    const seconds = Math.floor(millis / 1000)
+    const decimal = Math.floor(millis % 1000 / 10)
+    string = `${seconds}.${decimal}s`
+  } else {
+    // Milliseconds: style is 123ms
+    string = `${millis}ms`
+  }
+  return _colors ? `${gry}[${string}]${rst}` : `[${string}]`
+}
+
+/** Colorize in gray. */
+export function $gry(string: any): string {
+  return _colors ? `${gry}${string}${rst}` : string
+}
+
+/** Colorize in red. */
+export function $red(string: any): string {
+  return colorize(red, string)
+}
+
+/** Colorize in green. */
+export function $grn(string: any): string {
+  return colorize(grn, string)
+}
+
+/** Colorize in yellow. */
+export function $ylw(string: any): string {
+  return colorize(ylw, string)
+}
+
+/** Colorize in blue. */
+export function $blu(string: any): string {
+  return colorize(blu, string)
+}
+
+/** Colorize in magenta. */
+export function $mgt(string: any): string {
+  return colorize(mgt, string)
+}
+
+/** Colorize in cyan. */
+export function $cyn(string: any): string {
+  return colorize(cyn, string)
+}
+
+/** Colorize in white. */
+export function $wht(string: any): string {
+  return colorize(wht, string)
+}
+
+/** Underline. */
+export function $und(string: any): string {
+  return colorize(und, string)
+}

package/src/log/emit.ts

@@ -0,0 +1,125 @@
+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'
+
+/* ========================================================================== */
+
+/* Initial values, and subscribe to changes */
+let _output = logOptions.output
+let _indentSize = logOptions.indentSize
+let _taskLength = logOptions.taskLength
+let _lineLength = logOptions.lineLength
+let _inspectOptions = logOptions.inspectOptions
+logOptions.on('changed', (options) => {
+  _output = options.output
+  _indentSize = options.indentSize
+  _taskLength = options.taskLength
+  _lineLength = options.lineLength
+  _inspectOptions = options.inspectOptions
+})
+
+/* ========================================================================== *
+ * EMIT TEXT FOR LOGS / REPORTS                                               *
+ * ========================================================================== */
+
+/** Options for the {@link LogEmitter} function family */
+export interface LogEmitterOptions {
+  taskName: string,
+  level: LogLevel,
+  indent?: number,
+  prefix?: string,
+}
+
+/** Emit a line (or multiple lines) of text to the log */
+export type LogEmitter = (options: LogEmitterOptions, args: any[]) => void
+
+/* ========================================================================== */
+
+/** Emit in full colors! */
+export const emitColor: LogEmitter = (options: LogEmitterOptions, args: any[]): void => {
+  const { taskName, level, prefix, indent } = options
+  const logPrefix = prefix ? prefix : indent ? ''.padStart(indent * _indentSize) : ''
+
+  /* Prefixes, to prepend at the beginning of each line */
+  const prefixes: string[] = []
+
+  /* Task name or blank padding */
+  prefixes.push(''.padStart(_taskLength - taskName.length, ' ')) // padding
+  prefixes.push(`${$t(taskName)}`) // task name
+
+  /* Level indicator (our little colorful squares) */
+  if (level <= TRACE) {
+    prefixes.push(` ${$gry('\u25a1')} `) // trace: gray open
+  } else if (level <= DEBUG) {
+    prefixes.push(` ${$gry('\u25a0')} `) // debug: gray
+  } else if (level <= INFO) {
+    prefixes.push(` ${$grn('\u25a0')} `) // info: green
+  } else if (level <= NOTICE) {
+    prefixes.push(` ${$blu('\u25a0')} `) // notice: blue
+  } else if (level <= WARN) {
+    prefixes.push(` ${$ylw('\u25a0')} `) // warning: yellow
+  } else {
+    prefixes.push(` ${$red('\u25a0')} `) // error: red
+  }
+
+  /* The prefix (task name and level) */
+  prefixes.push(logPrefix)
+  const linePrefix = prefixes.join('')
+
+  /* Now for the normal logging of all our parameters */
+  const breakLength = _lineLength - _taskLength - logPrefix.length - 3 // 3 chas: space square space
+  const message = formatWithOptions({ ..._inspectOptions, breakLength }, ...args)
+
+  /* Write each individual line out */
+  for (const line of message.split('\n')) {
+    _output.write(zapSpinner)
+    _output.write(linePrefix)
+    _output.write(line)
+    _output.write('\n')
+  }
+}
+
+/* ========================================================================== */
+
+/** Emit in plain text! (no colors) */
+export const emitPlain: LogEmitter = (options: LogEmitterOptions, args: any[]): void => {
+  const { taskName, level, prefix, indent } = options
+  const logPrefix = prefix ? prefix : indent ? ''.padStart(indent * _indentSize) : ''
+
+  const prefixes: string[] = []
+
+  const pad = ''.padStart(_taskLength - taskName.length, ' ')
+  prefixes.push(`${pad}${taskName}`)
+
+  if (level <= TRACE) {
+    prefixes.push(' \u2502  trace \u2502 ')
+  } else if (level <= DEBUG) {
+    prefixes.push(' \u2502  debug \u2502 ')
+  } else if (level <= INFO) {
+    prefixes.push(' \u2502   info \u2502 ')
+  } else if (level <= NOTICE) {
+    prefixes.push(' \u2502 notice \u2502 ')
+  } else if (level <= WARN) {
+    prefixes.push(' \u2502   warn \u2502 ')
+  } else {
+    prefixes.push(' \u2502  error \u2502 ')
+  }
+
+  /* The prefix (task name and level) */
+  prefixes.push(logPrefix)
+  const linePrefix = prefixes.join('')
+
+  /* Now for the normal logging of all our parameters */
+  const breakLength = _lineLength - _taskLength - logPrefix.length - 12 // 12 chars of the level above
+  const message = formatWithOptions({ ..._inspectOptions, breakLength }, ...args)
+
+  /* Write each individual line out */
+  for (const line of message.split('\n')) {
+    _output.write(zapSpinner)
+    _output.write(linePrefix)
+    _output.write(line)
+    _output.write('\n')
+  }
+}

package/src/log/levels.ts

@@ -0,0 +1,65 @@
+/** Define a branded type for log levels */
+export type Level<N extends number> = N & { __brand_log_level: never }
+
+// Those are all our defined log levels: please note the absence of the ZERO
+// as it's falsy and 0x1fffffffffffff is Number.MAX_SAFE_INTEGER as a constant
+
+/** The `TRACE` log level */
+export const TRACE = 10 as Level<10>
+/** The `DEBUG` log level */
+export const DEBUG = 20 as Level<20>
+/** The `INFO` log level */
+export const INFO = 30 as Level<30>
+/** The `NOTICE` log level (our default) */
+export const NOTICE = 40 as Level<40>
+/** The `WARN` log level */
+export const WARN = 50 as Level<50>
+/** The `ERROR` log level */
+export const ERROR = 60 as Level<60>
+/** The `OFF` log level (no logs are emitted) */
+export const OFF = 0x1fffffffffffff as Level<0x1fffffffffffff>
+
+/**  All our known log levels */
+export const logLevels = Object.freeze({ TRACE, DEBUG, INFO, NOTICE, WARN, ERROR, OFF })
+
+/** The type of all our known log levels */
+export type LogLevels = typeof logLevels
+
+/** ID of each one of our log levels (upper case) */
+export type LogLevelKey = keyof LogLevels
+
+/** Canonical name of each one of our log levels (lower case) */
+export type LogLevelName = Lowercase<LogLevelKey>
+
+/** A type identifying all our log level numbers */
+export type LogLevel = LogLevels[LogLevelKey]
+
+/** The type identifying a recognized log level as a `string`. */
+export type LogLevelString = LogLevelKey | LogLevelName
+
+/**
+ * Convert a `string` (a {@link LogLevelString}) into a {@link LogLevel}.
+ *
+ * If the level specified is not a {@link LogLevelString}, the {@link NOTICE}
+ * level (our default) will be returned.
+ */
+export function getLevelNumber<L extends LogLevelString>(level: L): LogLevels[Uppercase<L>] {
+  const _level = level.toUpperCase() as LogLevelKey
+  return (_level in logLevels ? logLevels[_level] : NOTICE) as any
+}
+
+/**
+ * Convert a `number` (a {@link LogLevel}) into a {@link LogLevelName}.
+ *
+ * If the level specified is not precisely a {@link LogLevel}, the
+ * closer {@link LogLevelName} will be returned.
+ */
+export function getLevelName<L extends LogLevel>(level: L): LogLevelName {
+  if (level <= TRACE) return 'trace'
+  if (level <= DEBUG) return 'debug'
+  if (level <= INFO) return 'info'
+  if (level <= NOTICE) return 'notice'
+  if (level <= WARN) return 'warn'
+  if (level <= ERROR) return 'error'
+  return 'off'
+}

package/src/log/logger.ts

@@ -0,0 +1,171 @@
+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'
+
+/* ========================================================================== */
+
+/* Initial value of log colors, and subscribe to changes */
+let _level = logOptions.level
+let _colors = logOptions.colors
+let _defaultTaskName = logOptions.defaultTaskName
+logOptions.on('changed', ({ defaultTaskName, colors, level }) => {
+  _defaultTaskName = defaultTaskName
+  _colors = colors
+  _level = level
+})
+
+/* ========================================================================== *
+ * LOGGER                                                                     *
+ * ========================================================================== */
+
+/** The basic interface giving access to log facilities. */
+export interface Log {
+  /** Log a `TRACE` message */
+  trace(...args: [ any, ...any ]): this
+  /** Log a `DEBUG` message */
+  debug(...args: [ any, ...any ]): this
+  /** Log an `INFO` message */
+  info(...args: [ any, ...any ]): this
+  /** Log a `NOTICE` message */
+  notice(...args: [ any, ...any ]): this
+  /** Log a `WARNING` message */
+  warn(...args: [ any, ...any ]): this
+  /** Log an `ERROR` message */
+  error(...args: [ any, ...any ]): this
+}
+
+/** A {@link Logger} extends the basic {@link Log} adding some state. */
+export interface Logger extends Log {
+  /** The current level for logging. */
+  level: LogLevel,
+
+  /** Enter a sub-level of logging, increasing indent */
+  enter(): this
+  /** Enter a sub-level of logging, increasing indent */
+  enter(evel: LogLevel, message: string): this
+  /** Leave a sub-level of logging, decreasing indent */
+  leave(): this
+  /** Leave a sub-level of logging, decreasing indent */
+  leave(level: LogLevel, message: string): this
+}
+
+/** Return a {@link Logger} associated with the specified task name. */
+export function getLogger(task: string = _defaultTaskName): Logger {
+  let logger = _loggers.get(task)
+  if (! logger) {
+    const emitter = _colors ? emitColor : emitPlain
+    logger = new LoggerImpl(task, emitter)
+    _loggers.set(task, logger)
+  }
+  return logger
+}
+
+/* ========================================================================== */
+
+/** Cache of loggers by task-name. */
+const _loggers = new Map<string, Logger>()
+
+/** Default implementation of the {@link Logger} interface. */
+class LoggerImpl implements Logger {
+  private readonly _stack: { level: LogLevel, message: string, indent: number }[] = []
+  private _level = _level
+  private _indent = 0
+
+  constructor(
+      private readonly _task: string,
+      private readonly _emitter: LogEmitter,
+  ) {}
+
+  private _emit(level: LogLevel, args: [ any, ...any ]): this {
+    if (this._level > level) return this
+
+    // Filter out build failures (they are not to be logged)
+    const params = args.filter((arg) => ! isBuildFailure(arg))
+    if (params.length === 0) return this // no logging only build failures
+
+    // Prepare our options for logging
+    const options = { level, taskName: this._task, indent: this._indent }
+
+    // Dump any existing stack entry
+    if (this._stack.length) {
+      for (const { message, ...extras } of this._stack) {
+        this._emitter({ ...options, ...extras }, [ message ])
+      }
+      this._stack.splice(0)
+    }
+
+    // Print all `BuildError`s _before_ any other entry
+    const remaining = params.filter((arg) => {
+      if (isBuildError(arg)) {
+        this._emitter({ ...options, level: ERROR }, [ arg.message ])
+        return false
+      } else {
+        return true
+      }
+    })
+
+    // If we have any leftovers, dump them out, too!
+    if (remaining) this._emitter(options, remaining)
+    return this
+  }
+
+  get level(): LogLevel {
+    return this._level
+  }
+
+  set level(level: LogLevel) {
+    this._level = level
+  }
+
+  trace(...args: [ any, ...any ]): this {
+    return this._emit(TRACE, args)
+  }
+
+  debug(...args: [ any, ...any ]): this {
+    return this._emit(DEBUG, args)
+  }
+
+  info(...args: [ any, ...any ]): this {
+    return this._emit(INFO, args)
+  }
+
+  notice(...args: [ any, ...any ]): this {
+    return this._emit(NOTICE, args)
+  }
+
+  warn(...args: [ any, ...any ]): this {
+    return this._emit(WARN, args)
+  }
+
+  error(...args: [ any, ...any ]): this {
+    return this._emit(ERROR, args)
+  }
+
+  enter(): this
+  enter(level: LogLevel, message: string): this
+  enter(...args: [] | [ level: LogLevel, message: string ]): this {
+    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 {
+    this._stack.pop()
+    this._indent --
+
+    if (this._indent < 0) this._indent = 0
+
+    if (args.length) {
+      const [ level, message ] = args
+      this._emit(level, [ message ])
+    }
+
+    return this
+  }
+}

package/src/log/options.ts

@@ -0,0 +1,199 @@
+import { EventEmitter } from 'node:events'
+import { Writable } from 'node:stream'
+import { InspectOptions } from 'node:util'
+import { getLevelNumber, LogLevel, LogLevelString, NOTICE } from './levels.js'
+
+/* ========================================================================== */
+
+
+/** Options for our {@link Logger} instances */
+export interface LogOptions {
+  /** The current output. */
+  output: Writable,
+  /** The current level for logging. */
+  level: LogLevel,
+  /** Whether to log in colors or not. */
+  colors: boolean,
+  /** Whether to enable the tasks spinner or not. */
+  spinner: boolean,
+  /** Width of the current terminal (if any) or `80`. */
+  lineLength: number,
+  /** The maximum length of a task name (for pretty alignment). */
+  taskLength: number,
+  /** The number of spaces used for indenting. */
+  indentSize: number,
+  /** Whether to show sources in reports or not. */
+  showSources: boolean,
+  /** The task name to be used by default if a task is not contextualized. */
+  defaultTaskName: string,
+  /** The options used by NodeJS for object inspection. */
+  readonly inspectOptions: InspectOptions,
+
+  /** Set an inspect option in {@link LogOptions.inspectOptions}). */
+  setInspectOption<K extends keyof InspectOptions>(key: K, value: InspectOptions[K]): void
+
+  /** Add an event listener for the specified event. */
+  on(eventName: 'changed', listener: (logOptions: this) => void): this;
+  /** Add an event listener for the specified event triggering only once. */
+  once(eventName: 'changed', listener: (logOptions: this) => void): this;
+  /** Remove an event listener for the specified event. */
+  off(eventName: 'changed', listener: (logOptions: this) => void): this;
+
+  /** Convert for serialization, optionally overriding the default task name. */
+  fork(taskName?: string): Partial<LogOptions>
+}
+
+/* ========================================================================== *
+ * INTERNAL STATE                                                             *
+ * ========================================================================== */
+
+class LogOptionsImpl extends EventEmitter implements LogOptions {
+  private _output: Writable = process.stderr
+  private _level: LogLevel = NOTICE
+  private _colors = (<NodeJS.WriteStream> this._output).isTTY
+  private _spinner = true // by default, the spinner is enabled
+  private _lineLength = (<NodeJS.WriteStream> this._output).columns || 80
+  private _showSources = true // by default, always show source snippets
+  private _inspectOptions: InspectOptions = {}
+  private _defaultTaskName = ''
+  private _taskLength = 0
+  private _indentSize = 2
+
+  constructor() {
+    super()
+
+    /* The `LOG_LEVEL` variable is one of our `debug`, `info`, ... */
+    if (process.env.LOG_LEVEL) {
+      this._level = getLevelNumber(process.env.LOG_LEVEL as LogLevelString)
+    }
+
+    /* If the `LOG_COLOR` variable is specified, it should be `true` or `false` */
+    if (process.env.LOG_COLOR) {
+      if (process.env.LOG_COLOR.toLowerCase() === 'true') this.colors = true
+      if (process.env.LOG_COLOR.toLowerCase() === 'false') this.colors = false
+      // Other values don't change the value of `options.colors`
+    }
+
+    /*
+     * 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 || '{}'))
+  }
+
+  private _notifyListeners(): void {
+    super.emit('changed', this)
+  }
+
+  fork(taskName?: string): Partial<LogOptions> {
+    return {
+      level: this._level,
+      colors: this._colors,
+      lineLength: this._lineLength,
+      taskLength: this._taskLength,
+      defaultTaskName: taskName || this._defaultTaskName,
+      spinner: false, // forked spinner is always false
+    }
+  }
+
+  get output(): Writable {
+    return this._output
+  }
+
+  set output(output: Writable) {
+    this._output = output
+    this._colors = !! (<NodeJS.WriteStream> output).isTTY
+    this._lineLength = (<NodeJS.WriteStream> output).columns
+    this._notifyListeners()
+  }
+
+  get level(): LogLevel {
+    return this._level
+  }
+
+  set level(level: LogLevel) {
+    this._level = level
+    this._notifyListeners()
+  }
+
+  get colors(): boolean {
+    return this._colors
+  }
+
+  set colors(color: boolean) {
+    this._colors = color
+    this._notifyListeners()
+  }
+
+  get spinner(): boolean {
+    return this._spinner
+  }
+
+  set spinner(spinner: boolean) {
+    this._spinner = spinner
+    this._notifyListeners()
+  }
+
+  get lineLength(): number {
+    return this._lineLength
+  }
+
+  set lineLength(lineLength: number) {
+    this._lineLength = lineLength
+    this._notifyListeners()
+  }
+
+  get taskLength(): number {
+    return this._taskLength
+  }
+
+  set taskLength(taskLength: number) {
+    this._taskLength = taskLength
+    this._notifyListeners()
+  }
+
+  get indentSize(): number {
+    return this._indentSize
+  }
+
+  set indentSize(indentSize: number) {
+    this._indentSize = indentSize
+    if (this._indentSize < 1) this._indentSize = 1
+    this._notifyListeners()
+  }
+
+  get showSources(): boolean {
+    return this._showSources
+  }
+
+  set showSources(showSources: boolean) {
+    this._showSources = showSources
+    this._notifyListeners()
+  }
+
+  get defaultTaskName(): string {
+    return this._defaultTaskName
+  }
+
+  set defaultTaskName(defaultTaskName: string) {
+    this._defaultTaskName = defaultTaskName
+    this._notifyListeners()
+  }
+
+  get inspectOptions(): InspectOptions {
+    return {
+      colors: this._colors,
+      breakLength: this._lineLength,
+      ...this._inspectOptions,
+    }
+  }
+
+  setInspectOption<K extends keyof InspectOptions>(key: K, value: InspectOptions[K]): void {
+    this._inspectOptions[key] = value
+    this._notifyListeners()
+  }
+}
+
+/** Shared instance of our {@link LogOptions}. */
+export const logOptions: LogOptions = new LogOptionsImpl()