@plugjs/plug 0.0.27 → 0.1.1

package/src/build.ts

@@ -0,0 +1,179 @@
+import { assert } from './asserts'
+import { runAsync } from './async'
+import { $ms, $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 yoooo`)
+        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,5 +1,6 @@
+import { assert } from './asserts'
+import { mkdir, writeFile } from './fs'
 import { assertRelativeChildPath, getAbsoluteParent, resolveAbsolutePath } from './paths'
-import { mkdir, writeFile } from './utils/asyncfs'
 
 import type { AbsolutePath } 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/fork.ts

@@ -1,14 +1,13 @@
 import { fork } from 'node:child_process'
 
-import { assert } from './assert'
+import { assert, BuildFailure } from './asserts'
 import { runAsync } from './async'
-import { BuildFailure } from './failure'
 import { Files } from './files'
-import { $gry, $p, logOptions } from './log'
+import { $gry, $p, logOptions } from './logging'
 import { requireFilename, resolveFile } from './paths'
 import { Context, install } from './pipe'
 
-import type { LogOptions } from './log'
+import type { LogOptions } from './logging'
 import type { AbsolutePath } from './paths'
 import type { Plug, PlugName, PlugResult } from './pipe'
 
@@ -16,6 +15,8 @@ import type { Plug, PlugName, PlugResult } from './pipe'
 export interface ForkData {
   /** Script name for the Plug to execute */
   scriptFile: AbsolutePath,
+  /** Export name in the script for the Plug to execute */
+  exportName: string,
   /** Plug constructor arguments */
   constructorArgs: any[],
   /** Task name (for logs) */
@@ -48,11 +49,13 @@ export abstract class ForkingPlug implements Plug<PlugResult> {
   constructor(
       private readonly _scriptFile: AbsolutePath,
       private readonly _arguments: any[],
+      private readonly _exportName: string,
   ) {}
 
   pipe(files: Files, context: Context): Promise<PlugResult> {
     const message: ForkData = {
       scriptFile: this._scriptFile,
+      exportName: this._exportName,
       constructorArgs: this._arguments,
       taskName: context.taskName,
       buildFile: context.buildFile,
@@ -167,6 +170,7 @@ if ((process.argv[1] === requireFilename(__fileurl)) && (process.send)) {
 
     const {
       scriptFile,
+      exportName,
       constructorArgs,
       taskName,
       buildFile,
@@ -189,12 +193,15 @@ if ((process.argv[1] === requireFilename(__fileurl)) && (process.send)) {
       const script = await import(scriptFile)
 
       /* Figure out the constructor, in the "default" chain */
-      let Ctor = script
-      while (Ctor && (typeof Ctor !== 'function')) Ctor = Ctor.default
-
-      /* Check that we have a proper constructor */
-      assert(typeof Ctor === 'function',
-          `Script ${$p(scriptFile)} does not export a default constructor`)
+      let Ctor
+      if (exportName === 'default') {
+        Ctor = script
+        while (Ctor && (typeof Ctor !== 'function')) Ctor = Ctor.default
+        assert(typeof Ctor === 'function', `Script ${$p(scriptFile)} does not export a default constructor`)
+      } else {
+        Ctor = script[exportName]
+        assert(typeof Ctor === 'function', `Script ${$p(scriptFile)} does not export "${exportName}"`)
+      }
 
       /* Create the Plug instance and our Files instance */
       const plug = new Ctor(...constructorArgs) as Plug<PlugResult>
@@ -250,11 +257,12 @@ if ((process.argv[1] === requireFilename(__fileurl)) && (process.send)) {
 export function installForking<Name extends PlugName>(
     plugName: Name,
     scriptFile: AbsolutePath,
+    exportName: string = 'default',
 ): void {
   /** Extend out our ForkingPlug below */
   const ctor = class extends ForkingPlug {
     constructor(...args: any[]) {
-      super(scriptFile, args)
+      super(scriptFile, args, exportName)
     }
   }
 

package/src/{utils/asyncfs.ts → fs.ts}

@@ -1,5 +1,5 @@
-import { constants } from 'node:fs'
 import fsp from 'node:fs/promises'
+import { constants } from 'node:fs'
 
 type FsPromises = typeof fsp
 
@@ -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,14 +1,21 @@
-import { assert, assertPromises } from './assert'
+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'
-import { $p, log } from './log'
+import { rm } from './fs'
+import { $p, log } from './logging'
 import { commonPath, getCurrentWorkingDirectory, resolveDirectory, resolveFile } from './paths'
-import { Pipe } from './pipe'
-import { rm } from './utils/asyncfs'
+import { PipeImpl } from './pipe'
+import { execChild } from './utils/exec'
 import { parseOptions } from './utils/options'
 import { walk } from './utils/walk'
 
+import type { Pipe } from './index'
 import type { AbsolutePath } from './paths'
+import type { ExecChildOptions } from './utils/exec'
 import type { ParseOptions } from './utils/options'
 import type { WalkOptions } from './utils/walk'
 
@@ -35,7 +42,7 @@ export function find(...args: ParseOptions<FindOptions>): Pipe {
   const { params: globs, options } = parseOptions(args, {})
 
   const context = requireContext()
-  return new Pipe(context, Promise.resolve().then(async () => {
+  return new PipeImpl(context, Promise.resolve().then(async () => {
     const directory = options.directory ?
       context.resolve(options.directory) :
       getCurrentWorkingDirectory()
@@ -62,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
@@ -88,7 +96,7 @@ export async function rmrf(directory: string): Promise<void> {
  */
 export function merge(pipes: (Pipe | Files | Promise<Files>)[]): Pipe {
   const context = requireContext()
-  return new Pipe(context, Promise.resolve().then(async () => {
+  return new PipeImpl(context, Promise.resolve().then(async () => {
     // No pipes? Just send off an empty pipe...
     if (pipes.length === 0) return Files.builder(getCurrentWorkingDirectory()).build()
 
@@ -97,7 +105,7 @@ export function merge(pipes: (Pipe | Files | Promise<Files>)[]): Pipe {
 
     // Find the common directory between all the Files instances
     const [ firstDir, ...otherDirs ] = results.map((f) => f.directory)
-    const directory = commonPath(firstDir, ...otherDirs)
+    const directory = commonPath(firstDir!, ...otherDirs)
 
     // Build our new files instance merging all the results
     return Files.builder(directory).merge(...results).build()
@@ -121,7 +129,7 @@ export function merge(pipes: (Pipe | Files | Promise<Files>)[]): Pipe {
 export function noop(): Pipe {
   const context = requireContext()
   const files = new Files(getCurrentWorkingDirectory())
-  return new Pipe(context, Promise.resolve(files))
+  return new PipeImpl(context, Promise.resolve(files))
 }
 
 /**
@@ -155,3 +163,43 @@ export function isDirectory(...paths: [ string, ...string[] ]): AbsolutePath | u
   const path = requireContext().resolve(...paths)
   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.
+ *
+ * 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 ExecChildOptions | options} for process execution
+ */
+export function exec(
+    cmd: string,
+    ...args: [ ...args: string[] ] | [ ...args: string[], options: ExecChildOptions ]
+): Promise<void> {
+  const { params, options } = parseOptions(args)
+  return execChild(cmd, params, options, requireContext())
+}

package/src/index.ts

@@ -1,18 +1,40 @@
 // Reference our extra "webassembly" type fix here. As we're using esbuild
 // everywhere, we want our dependants to have this type known...
-/// <reference path="../types/webassembly.d.ts" />
+/// <reference path="../types/plugjs.d.ts" />
 
-export type { AbsolutePath } from './paths'
-export type { Files, FilesBuilder } from './files'
+// This is a main constituent of our build system!
+import type { Files } from './files'
+import type { Plug, PlugFunction } from './pipe'
 
-export { BuildFailure } from './failure'
-export type { Pipe } from './pipe'
+/**
+ * The {@link Pipe} interface defines a processing pipeline where multiple
+ * {@link Plug}s can transform lists of {@link Files}.
+ */
+export interface Pipe extends Promise<Files> {
+  plug(plug: Plug<Files>): Pipe
+  plug(plug: PlugFunction<Files>): Pipe
+  plug(plug: Plug<void | undefined>): Promise<undefined>
+  plug(plug: PlugFunction<void | undefined>): Promise<undefined>
+  plug(plug: Plug<Files | void | undefined>): Pipe | Promise<undefined>
+  plug(plug: PlugFunction<Files | void | undefined>): Pipe | Promise<undefined>
+}
+
+// Submodule exports (our package.json exports)
+export * as asserts from './asserts'
+export * as files from './files'
+export * as fork from './fork'
+export * as fs from './fs'
+export * as logging from './logging'
+export * as paths from './paths'
+export * as pipe from './pipe'
+export * as utils from './utils'
+
+// Individual utilities
+export { log } from './logging'
+export { assert } from './asserts'
 
 // Our minimal exports
-export * from './assert'
 export * from './build'
-export * from './fork'
 export * from './helpers'
-export * from './log'
 export * from './plugs'
 export * from './types'

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

@@ -120,7 +120,6 @@ export const emitPlain: 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')

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

@@ -1,4 +1,4 @@
-import { BuildFailure, isBuildFailure } from '../failure'
+import { BuildFailure, isBuildFailure } from '../asserts'
 import { emitColor, emitPlain } from './emit'
 import { DEBUG, ERROR, INFO, NOTICE, TRACE, WARN } from './levels'
 import { logOptions } from './options'
@@ -74,6 +74,8 @@ export function getLogger(task: string = _defaultTaskName): Logger {
 
 /** Cache of loggers by task-name. */
 const _loggers = new Map<string, Logger>()
+/** Weak set of already logged build failures */
+const _loggedFailures = new WeakSet<BuildFailure>()
 
 /** Default implementation of the {@link Logger} interface. */
 class LoggerImpl implements Logger {
@@ -93,14 +95,21 @@ class LoggerImpl implements Logger {
     const params = args.filter((arg) => {
       if (isBuildFailure(arg)) {
         // Filter out any previously logged build failure and mark
-        if (arg.logged) return false
-        arg.logged = true
+        if (_loggedFailures.has(arg)) return false
+        _loggedFailures.add(arg)
 
         // If the build failure has any root cause, log those
         arg.errors.forEach((error) => this._emit(level, [ error ]))
 
         // Log this only if it has a message
-        return !! arg.message
+        if (! arg.message) return false
+
+        // Log the full error (with stack) if the _default_ level is DEBUG
+        if (_level < INFO) return true
+
+        // Log only the message in other cases
+        this._emit(level, [ arg.message ])
+        return false
       } else {
         return true
       }

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

@@ -2,9 +2,9 @@ import { EventEmitter } from 'node:events'
 
 import { getLevelNumber, NOTICE } from './levels'
 
-import type { LogLevel, LogLevelString } from './levels'
 import type { Writable } from 'node:stream'
 import type { InspectOptions } from 'node:util'
+import type { LogLevel, LogLevelString } from './levels'
 
 /* ========================================================================== */
 
@@ -54,8 +54,10 @@ class LogOptionsImpl extends EventEmitter implements LogOptions {
   private _output: Writable = process.stderr
   private _level: LogLevel = NOTICE
   private _colors = (<NodeJS.WriteStream> this._output).isTTY
+  private _colorsSet = false // have colors been set manually?
   private _spinner = true // by default, the spinner is enabled
   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 _inspectOptions: InspectOptions = {}
   private _defaultTaskName = ''
@@ -70,10 +72,10 @@ class LogOptionsImpl extends EventEmitter implements LogOptions {
       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
+    /* If the `LOG_COLORS` variable is specified, it should be `true` or `false` */
+    if (process.env.LOG_COLORS) {
+      if (process.env.LOG_COLORS.toLowerCase() === 'true') this.colors = true
+      if (process.env.LOG_COLORS.toLowerCase() === 'false') this.colors = false
       // Other values don't change the value of `options.colors`
     }
 
@@ -106,8 +108,8 @@ class LogOptionsImpl extends EventEmitter implements LogOptions {
 
   set output(output: Writable) {
     this._output = output
-    this._colors = !! (<NodeJS.WriteStream> output).isTTY
-    this._lineLength = (<NodeJS.WriteStream> output).columns
+    if (! this._colorsSet) this._colors = !! (<NodeJS.WriteStream> output).isTTY
+    if (! this._lineLengthSet) this._lineLength = (<NodeJS.WriteStream> output).columns
     this._notifyListeners()
   }
 
@@ -126,6 +128,7 @@ class LogOptionsImpl extends EventEmitter implements LogOptions {
 
   set colors(color: boolean) {
     this._colors = color
+    this._colorsSet = true
     this._notifyListeners()
   }
 
@@ -144,6 +147,7 @@ class LogOptionsImpl extends EventEmitter implements LogOptions {
 
   set lineLength(lineLength: number) {
     this._lineLength = lineLength
+    this._lineLengthSet = true
     this._notifyListeners()
   }
 

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

@@ -1,5 +1,5 @@
-import { BuildFailure } from '../failure'
-import { readFile } from '../utils/asyncfs'
+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 { logOptions } from './options'
@@ -336,7 +336,7 @@ export class ReportImpl implements Report {
 
     /* Iterate through all our [file,reports] tuple */
     for (let f = 0; f < entries.length; f ++) {
-      const { file, records, annotation } = entries[f]
+      const { file, records, annotation } = entries[f]!
       const source = file && file != nul && this._sources.get(file)
 
       if ((f === 0) || entries[f - 1]?.records.length) {
@@ -358,7 +358,7 @@ export class ReportImpl implements Report {
 
       /* Now get each message and do our magic */
       for (let r = 0; r < records.length; r ++) {
-        const { level, messages, tags, line, column, length = 1 } = records[r]
+        const { level, messages, tags, line, column, length = 1 } = records[r]!
 
         /* Prefix includes line and column */
         let pfx: string
@@ -382,13 +382,13 @@ export class ReportImpl implements Report {
 
         /* Print out our messages, one by one */
         if (messages.length === 1) {
-          this._emitter({ ...options, level }, [ $gry(pfx), messages[0].padEnd(mPad), tag ])
+          this._emitter({ ...options, level }, [ $gry(pfx), messages[0]!.padEnd(mPad), tag ])
         } else {
           for (let m = 0; m < messages.length; m ++) {
             if (! m) { // first line
               this._emitter({ ...options, level }, [ $gry(pfx), messages[m] ])
             } else if (m === messages.length - 1) { // last line
-              this._emitter({ ...options, level, prefix }, [ messages[m].padEnd(mPad), tag ])
+              this._emitter({ ...options, level, prefix }, [ messages[m]!.padEnd(mPad), tag ])
             } else { // in between lines
               this._emitter({ ...options, level, prefix }, [ messages[m] ])
             }
@@ -400,9 +400,10 @@ export class ReportImpl implements Report {
           if (column) {
             const $col = level === NOTICE ? $blu : level === WARN ? $ylw : $red
             const offset = column - 1
-            const head = $gry(source[line - 1].substring(0, offset))
-            const body = $und($col(source[line - 1].substring(offset, offset + length)))
-            const tail = $gry(source[line - 1].substring(offset + length))
+            const text = source[line - 1] || ''
+            const head = $gry(text.substring(0, offset))
+            const body = $und($col(text.substring(offset, offset + length)))
+            const tail = $gry(text.substring(offset + length))
 
             this._emitter({ ...options, level, prefix }, [ $gry(`| ${head}${body}${tail}`) ])
           } else {