@plugjs/plug 0.0.1

package/src/plugs/tsc/report.ts

@@ -0,0 +1,74 @@
+import ts from 'typescript' // TypeScript does NOT support ESM modules
+
+import { ERROR, NOTICE, Report, ReportLevel, ReportRecord, WARN } from '../../log.js'
+import { AbsolutePath, resolveAbsolutePath } from '../../paths.js'
+
+function convertMessageChain(chain: ts.DiagnosticMessageChain, indent = 0): string[] {
+  const message = `${''.padStart(indent * 2)}${chain.messageText}`
+
+  if (chain.next) {
+    const next = chain.next.map((c) => convertMessageChain(c, indent + 1))
+    return [ message, ...next.flat(1) ]
+  } else {
+    return [ message ]
+  }
+}
+
+function convertDiagnostics(
+    diagnostics: readonly ts.Diagnostic[],
+    directory: AbsolutePath,
+): ReportRecord[] {
+  return diagnostics.map((diagnostic): ReportRecord => {
+    // console.log(diagnostic)
+    void directory
+
+    // Convert the `DiagnosticCategory` to our level
+    let level: ReportLevel
+    switch (diagnostic.category) {
+      case ts.DiagnosticCategory.Error: level = ERROR; break
+      case ts.DiagnosticCategory.Warning: level = WARN; break
+      default: level = NOTICE
+    }
+
+    // Convert the `messageText` to a string
+    let message: string | string[]
+    if (typeof diagnostic.messageText === 'string') {
+      message = diagnostic.messageText
+    } else {
+      message = convertMessageChain(diagnostic.messageText)
+    }
+
+    // Simple variables
+    const tags = `TS${diagnostic.code}`
+
+
+    if (diagnostic.file) {
+      const { file: sourceFile, start, length } = diagnostic
+      const file = resolveAbsolutePath(directory, sourceFile.fileName)
+      const source = sourceFile.getFullText()
+
+      if (start !== undefined) {
+        const position = sourceFile.getLineAndCharacterOfPosition(start)
+        let { line, character: column } = position
+        column += 1
+        line += 1
+
+        return { level, message, tags, file, source, line, column, length }
+      } else {
+        return { level, message, tags, file, source }
+      }
+    } else {
+      return { level, message, tags }
+    }
+  })
+}
+
+/** Update a report, adding records from an array of {@link ts.Diagnostic} */
+export function updateReport(
+    report: Report,
+    diagnostics: readonly ts.Diagnostic[],
+    directory: AbsolutePath,
+): void {
+  const records = convertDiagnostics(diagnostics, directory)
+  report.add(...records)
+}

package/src/plugs/tsc/runner.ts

@@ -0,0 +1,100 @@
+import ts from 'typescript' // TypeScript does NOT support ESM modules
+
+import { failure } from '../../assert.js'
+import { Files } from '../../files.js'
+import { $p, log } from '../../log.js'
+import { getCurrentWorkingDirectory, isFile } from '../../paths.js'
+import { Plug } from '../../pipe.js'
+import { Run } from '../../run.js'
+import { parseOptions, ParseOptions } from '../../utils/options.js'
+import { TypeScriptHost } from './compiler.js'
+import { getCompilerOptions } from './options.js'
+import { updateReport } from './report.js'
+
+/* ========================================================================== *
+ * WORKER PLUG                                                                *
+ * ========================================================================== */
+
+export default class Tsc implements Plug<Files> {
+  private readonly _tsconfig?: string
+  private readonly _options: ts.CompilerOptions
+
+  constructor()
+  constructor(config: string)
+  constructor(options: ts.CompilerOptions)
+  constructor(config: string, options: ts.CompilerOptions)
+
+  constructor(...args: ParseOptions<ts.CompilerOptions>) {
+    const { params: [ tsconfig ], options } = parseOptions(args, {})
+    this._tsconfig = tsconfig
+    this._options = options
+  }
+
+  async pipe(files: Files, run: Run): Promise<Files> {
+    const tsconfig = this._tsconfig ?
+      run.resolve(this._tsconfig) :
+      isFile(files.directory, 'tsconfig.json')
+
+    const overrides: ts.CompilerOptions = {
+      rootDir: files.directory, // by default, our "files" directory
+      ...this._options, // any other options specified in the constructor
+    }
+
+    const { errors, options } = await getCompilerOptions(
+        tsconfig, // resolved tsconfig.json from constructor, might be undefined
+        overrides, // overrides from constructor, might be an empty object
+        run.buildFile) // overrides are defined in the build file, sooo.....
+
+    const report = run.report('TypeScript Report')
+
+    // Update report and fail on errors
+    updateReport(report, errors, getCurrentWorkingDirectory())
+    if (report.errors) report.done(true)
+
+    const { rootDir, outDir } = options
+    const root = rootDir ? run.resolve(rootDir) : files.directory
+    const out = outDir ? run.resolve(outDir) : root
+
+    const host = new TypeScriptHost(root)
+
+    const paths = [ ...files.absolutePaths() ]
+    for (const path of paths) log.trace(`Compiling "${$p(path)}"`)
+
+    // Get our build file and create the master program
+    log.info('Compiling', paths.length, 'files')
+    log.debug('Compliation options', options)
+
+    const program = ts.createProgram(paths, options, host, undefined, errors)
+    const diagnostics = ts.getPreEmitDiagnostics(program)
+
+    // Update report and fail on errors
+    updateReport(report, diagnostics, root)
+    if (report.errors) report.done(true)
+
+    const builder = run.files(out)
+    const promises: Promise<void>[] = []
+    const result = program.emit(undefined, (fileName, code) => {
+      promises.push(builder.write(fileName, code).then((file) => {
+        log.trace('Written', $p(file))
+      }).catch((error) => {
+        run.log.error('Error writing to', fileName, error)
+        throw failure() // no more logs!
+      }))
+    })
+
+    // Update report and fail on errors
+    updateReport(report, result.diagnostics, root)
+    if (report.errors) report.done(true)
+
+    // Await for all files to be written and check
+    const settlements = await Promise.allSettled(promises)
+    const failures = settlements
+        .reduce((failures, s) => failures + s.status === 'rejected' ? 1 : 0, 0)
+    if (failures) throw failure() // already logged above
+
+    // All done, build our files and return it
+    const outputs = builder.build()
+    log.info('TSC produced', outputs.length, 'files into', $p(outputs.directory))
+    return outputs
+  }
+}

package/src/plugs.ts

@@ -0,0 +1,33 @@
+/* ========================================================================== *
+ * FORKING PLUGS                                                              *
+ * ========================================================================== */
+
+import { installForking } from './fork.js'
+import { requireResolve } from './paths.js'
+
+import type ESLint from './plugs/eslint/runner.js'
+import type Mocha from './plugs/mocha/runner.js'
+import type Tsc from './plugs/tsc/runner.js'
+
+declare module './pipe.js' {
+  export interface Pipe {
+    eslint: PipeExtension<typeof ESLint>
+    mocha: PipeExtension<typeof Mocha>
+    tsc: PipeExtension<typeof Tsc>
+  }
+}
+
+installForking('eslint', requireResolve(__fileurl, './plugs/eslint/runner'))
+installForking('mocha', requireResolve(__fileurl, './plugs/mocha/runner'))
+installForking('tsc', requireResolve(__fileurl, './plugs/tsc/runner'))
+
+/* ========================================================================== *
+ * STANDARD IN-PROCESS PLUGS                                                  *
+ * ========================================================================== */
+
+export * from './plugs/copy.js'
+export * from './plugs/coverage.js'
+export * from './plugs/debug.js'
+export * from './plugs/esbuild.js'
+export * from './plugs/exec.js'
+export * from './plugs/filter.js'

package/src/run.ts

@@ -0,0 +1,160 @@
+import { join } from 'node:path'
+import { assert } from './assert.js'
+import { Files, FilesBuilder } from './files.js'
+import { createReport, getLevelNumber, getLogger, Logger, LogLevelString, Report } from './log.js'
+import { AbsolutePath, getCurrentWorkingDirectory, isAbsolutePath, resolveAbsolutePath } from './paths.js'
+import { Pipe, PipeImpl } from './pipe.js'
+import { ParseOptions, parseOptions } from './utils/options.js'
+import { walk, WalkOptions } from './utils/walk.js'
+
+/** The {@link FindOptions} interface defines the options for finding files. */
+export interface FindOptions extends WalkOptions {
+  /**
+   * The directory where to start looking for files according to the rules
+   * specified in {@link Run.resolve}.
+   */
+  directory?: string
+}
+
+/**
+ * The {@link Run} interface defines the context in which a {@link Task} is
+ * invoked.
+ *
+ * Runs keep track of the invocation stack (to avoid circular dependencies) and
+ * of the cached results for {@link Task} invocations.
+ */
+export interface Run {
+  /**
+   * The _name_ of the task associated with this {@link Run} (if one is).
+   *
+   * Tasks can have different names in different builds, this refers to the
+   * _task name_ in the build being executed.
+   */
+  readonly taskName: string
+  /** The absolute file name of the build */
+  readonly buildFile: AbsolutePath,
+  /** For convenience, the directory of the build file */
+  readonly buildDir: AbsolutePath,
+  /** The {@link Logger} associated with this instance. */
+  readonly log: Logger
+
+  /** Set the logging level within this {@link Run} */
+  setLogLevel(level: LogLevelString): void
+
+  /** Call another {@link Task} from this one. */
+  call(name: string): Promise<Files | undefined>
+
+  /** Create a new {@link Report} with the given _title_ */
+  report(title: string): Report
+
+  /**
+   * Resolve a path in the context of this {@link Run}.
+   *
+   * If the path starts with `@...` it is considered to be relative to the
+   * {@link process.cwd | current working directory}, otherwise it will be
+   * resolved against the build file where the task was originally defined in.
+   */
+  resolve(...paths: string[]): AbsolutePath
+
+  /** Create a {@link FilesBuilder} cloning an existing {@link Files}. */
+  files(files: Files): FilesBuilder
+
+  /**
+   * Create a {@link FilesBuilder} instance resolving the directory specified
+   * according to the rules specified in {@link Run.resolve}.
+   */
+  files(...paths: string[]): FilesBuilder
+
+  /**
+   * Find files according to the globs and {@link FindOptions} specified.
+   */
+  find(glob: string, ...args: ParseOptions<FindOptions>): Pipe & Promise<Files>
+
+  /**
+   * Create a new {@link Pipe} wrapping the specified {@link Files}.
+   */
+  pipe(files: Files | Promise<Files>): Pipe & Promise<Files>
+}
+
+/** Constructor options for our default {@link Run} implementation */
+export interface RunConstructionOptions {
+  readonly taskName: string,
+  readonly buildDir: AbsolutePath,
+  readonly buildFile: AbsolutePath,
+  readonly log?: Logger,
+}
+
+/** Our default {@link Run} implementation */
+export class RunImpl implements Run {
+  readonly taskName: string
+  readonly buildFile: AbsolutePath
+  readonly buildDir: AbsolutePath
+  readonly log: Logger
+
+  constructor(options: RunConstructionOptions)
+
+  constructor({ taskName, buildDir, buildFile, log }: RunConstructionOptions) {
+    this.taskName = taskName
+    this.buildDir = buildDir
+    this.buildFile = buildFile
+    this.log = log || getLogger(taskName)
+  }
+
+  /** Set the logging level within this {@link Run} */
+  setLogLevel(level: LogLevelString): void {
+    this.log.level = getLevelNumber(level)
+  }
+
+  report(title: string): Report {
+    return createReport(title, this.taskName)
+  }
+
+  resolve(...paths: string[]): AbsolutePath {
+    const path = join(...paths)
+    if (! path) return this.buildDir
+
+    if (path.startsWith('@')) {
+      const relative = path.substring(1)
+      assert(! isAbsolutePath(relative), `Path component of "${path}" is absolute`)
+      return resolveAbsolutePath(getCurrentWorkingDirectory(), relative)
+    }
+
+    if (isAbsolutePath(path)) return path
+
+    return resolveAbsolutePath(this.buildDir, path)
+  }
+
+  files(files: Files): FilesBuilder
+  files(...paths: string[]): FilesBuilder
+  files(first: Files | string | undefined, ...paths: string[]): FilesBuilder {
+    if (typeof first === 'string') {
+      return Files.builder(this.resolve(first, ...paths))
+    } else if (first) {
+      return Files.builder(first)
+    } else {
+      return Files.builder(this.resolve())
+    }
+  }
+
+  find(glob: string, ...args: ParseOptions<FindOptions>): Pipe & Promise<Files> {
+    const { params, options: { directory, ...options } } = parseOptions(args, {})
+
+    const promise = Promise.resolve().then(async () => {
+      const builder = this.files(directory || '.')
+      for await (const file of walk(builder.directory, [ glob, ...params ], options)) {
+        builder.add(file)
+      }
+      return builder.build()
+    })
+
+    return this.pipe(promise)
+  }
+
+  pipe(files: Files | Promise<Files>): Pipe & Promise<Files> {
+    return new PipeImpl(files, this)
+  }
+
+  call(name: string): Promise<Files | undefined> {
+    throw new Error(`Unable to call task "${name}"`)
+  }
+}

package/src/task.ts

@@ -0,0 +1,26 @@
+import type { BuildContext, TaskDefinition, ThisBuild } from './build.js'
+import type { Files } from './files.js'
+import type { Run } from './run.js'
+
+/* ========================================================================== *
+ * TASK                                                                       *
+ * ========================================================================== */
+
+export interface Task<T extends Files | undefined = Files | undefined> {
+  /** The {@link BuildContext} of where this task was originally defined */
+  readonly context: BuildContext
+
+  /** Invoked by the {@link Run} when actually executing this {@link Task} */
+  call(thisBuild: ThisBuild<any>, run: Run): Promise<T>
+}
+
+export class TaskImpl implements Task<Files | undefined> {
+  constructor(
+      readonly context: BuildContext,
+      private readonly _definition: TaskDefinition<any>,
+  ) {}
+
+  async call(self: ThisBuild<any>, run: Run): Promise<Files | undefined> {
+    return (await this._definition.call(self, self, run)) || undefined
+  }
+}

package/src/utils/asyncfs.ts

@@ -0,0 +1,82 @@
+import { constants } from 'node:fs'
+import fsp from 'node:fs/promises'
+
+/*
+ * I have no idea why sometimes stacks don't have a trace when coming out of
+ * the "node:fs/promises" api... There is a _stack_ property on the object
+ * but it simply includes the first line (if so), no thing further...
+ *
+ * Upon further inspection, it _seems_ this is related to some issues with the
+ * Error.captureStackTrace(...) function. If we pass a function to it as
+ * second parameter in our functions below, we end up with no stacks as well!
+ *
+ * So, for now, let's catch all errors, invoke `Error.captureStackTrace`
+ * manually without any parameter (besides the error itself), and fail with
+ * this.
+ *
+ * Hopefully, it'll get fixed, eventually, but for now let's keep this wrapper
+ * around!
+ */
+
+/* Process every entry in "node:fs/promises" */
+const fs = Object.entries(fsp as any).reduce((fs, [ key, val ]) => {
+  if (typeof val === 'function') {
+    /* 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
+      })
+    }
+
+    /* Make sure that the functions are called correctly */
+    Object.defineProperty(f, 'name', { value: key })
+    /* Assign the wrapper to our exports */
+    fs[key] = f
+  } else {
+    /* Not a function, no wrapping... */
+    fs[key] = val
+  }
+
+  /* Return the "reduced" exports */
+  return fs
+}, { constants } as any) as typeof fsp & { constants: typeof constants }
+
+/* Export _our_ version of the "node:fs/promises" module */
+export default fs
+
+/* Export all the wrappers to "node:fs/promises" individually */
+export const access = fs.access
+export const copyFile = fs.copyFile
+export const cp = fs.cp
+export const open = fs.open
+export const opendir = fs.opendir
+export const rename = fs.rename
+export const truncate = fs.truncate
+export const rm = fs.rm
+export const rmdir = fs.rmdir
+export const mkdir = fs.mkdir
+export const readdir = fs.readdir
+export const readlink = fs.readlink
+export const symlink = fs.symlink
+export const lstat = fs.lstat
+export const stat = fs.stat
+export const link = fs.link
+export const unlink = fs.unlink
+export const chmod = fs.chmod
+export const lchmod = fs.lchmod
+export const lchown = fs.lchown
+export const chown = fs.chown
+export const utimes = fs.utimes
+export const lutimes = fs.lutimes
+export const realpath = fs.realpath
+export const mkdtemp = fs.mkdtemp
+export const writeFile = fs.writeFile
+export const appendFile = fs.appendFile
+export const readFile = fs.readFile
+export const watch = fs.watch
+
+/* Export constants from "node:/fs" in addition */
+export { constants } from 'node:fs'

package/src/utils/caller.ts

@@ -0,0 +1,45 @@
+import { statSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { assert } from '../assert.js'
+import { AbsolutePath, assertAbsolutePath } from '../paths.js'
+
+export interface Location {
+  file: AbsolutePath,
+  line?: number | undefined,
+  column?: number | undefined,
+}
+
+export function findCaller(of: (...args: any[]) => any): Location {
+  const oldPrepareStackTrace = Error.prepareStackTrace
+
+  try {
+    Error.prepareStackTrace = (_, stackTraces): Location | undefined => {
+      const nullableFileOrUrl = stackTraces[0].getFileName()
+      if (! nullableFileOrUrl) return
+
+      const nullableLine = stackTraces[0].getColumnNumber()
+      const nullableColumn = stackTraces[0].getColumnNumber()
+
+      const line = typeof nullableLine === 'number' ? nullableLine : undefined
+      const column = typeof nullableColumn === 'number' ? nullableColumn : undefined
+
+      const file =
+        nullableFileOrUrl.startsWith('file:/') ?
+          fileURLToPath(nullableFileOrUrl) :
+          nullableFileOrUrl
+
+      assertAbsolutePath(file)
+      return { file, line, column }
+    }
+
+    const record: { stack?: Location } = {}
+    Error.captureStackTrace(record, of)
+    const location = record.stack
+
+    assert(location, 'Unable to determine build file name')
+    assert(statSync(location.file).isFile(), `Build file "${location.file}" not found`)
+    return location
+  } finally {
+    Error.prepareStackTrace = oldPrepareStackTrace
+  }
+}