@plugjs/plug 0.0.14 → 0.0.16

package/src/plugs/coverage.ts

@@ -1,25 +1,25 @@
 import { html, initFunction } from '@plugjs/cov8-html'
 import { sep } from 'node:path'
-import { fail } from '../assert.js'
-import { Files } from '../files.js'
-import { $gry, $ms, $p, $red, $ylw, ERROR, NOTICE, WARN } from '../log.js'
-import { AbsolutePath } from '../paths.js'
-import { install, Plug } from '../pipe.js'
-import { Run } from '../run.js'
-import { createAnalyser, SourceMapBias } from './coverage/analysis.js'
-import { coverageReport, CoverageResult } from './coverage/report.js'
+import { fail } from '../assert'
+import { Files } from '../files'
+import { $gry, $ms, $p, $red, $ylw, ERROR, NOTICE, WARN } from '../log'
+import { AbsolutePath, resolveAbsolutePath } from '../paths'
+import { install, PipeParameters, Plug, Context } from '../pipe'
+import { walk } from '../utils/walk'
+import { createAnalyser, SourceMapBias } from './coverage/analysis'
+import { coverageReport, CoverageResult } from './coverage/report'
 
 /** Options to analyse coverage reports */
 export interface CoverageOptions {
   /** The bias for source map analisys (defaults to `greatest_lower_bound`) */
   sourceMapBias?: SourceMapBias
-  /** Minimum _overall_ coverage (as a percentage) */
+  /** Minimum _overall_ coverage (as a percentage, defaults to 50) */
   minimumCoverage?: number,
-  /** Optimal _overall_ coverage (as a percentage)  */
+  /** Optimal _overall_ coverage (as a percentage, defaults to 50)  */
   optimalCoverage?: number,
-  /** Minimum _per-file_ coverage (as a percentage) */
+  /** Minimum _per-file_ coverage (as a percentage, defaults to 75) */
   minimumFileCoverage?: number,
-  /** Optimal _per-file_ coverage (as a percentage) */
+  /** Optimal _per-file_ coverage (as a percentage, defaults to 75) */
   optimalFileCoverage?: number,
 }
 
@@ -28,35 +28,58 @@ export interface CoverageReportOptions extends CoverageOptions {
   reportDir: string,
 }
 
-/**
- * The {@link Coverage} plug type is inferred from the constructor, so this
- * type helps to declare the correct types as we can't really infer them from
- * `typeof Coverage`...
- */
-type CoverageConstructor = {
-  new (coverageDir: string): Coverage<CoverageOptions>
-  new (coverageDir: string, options: CoverageOptions): Coverage<CoverageOptions>
-  new (coverageDir: string, options: CoverageReportOptions): Coverage<CoverageReportOptions>
+declare module '../pipe' {
+  export interface Pipe {
+    /**
+     * Analyse coverage using files generated by V8/NodeJS.
+     *
+     * @param coverageDir The directory where the `coverage-XXX.json` files
+     *                    generated by V8/NodeJS can be found.
+     */
+    coverage(coverageDir: string): Promise<undefined>
+    /**
+     * Analyse coverage using files generated by V8/NodeJS.
+     *
+     * @param coverageDir The directory where the `coverage-XXX.json` files
+     *                    generated by V8/NodeJS can be found.
+     * @param options Extra {@link CoverageOptions | options} allowing to
+     *                specify coverage thresholds.
+     */
+    coverage(coverageDir: string, options: CoverageOptions): Promise<undefined>
+    /**
+     * Analyse coverage using files generated by V8/NodeJS and produce an HTML
+     * report in the directory specified in `options`.
+     *
+     * @param coverageDir The directory where the `coverage-XXX.json` files
+     *                    generated by V8/NodeJS can be found.
+     * @param options Extra {@link CoverageOptions | options} allowing to
+     *                specify coverage thresholds where the HTML report should
+     *                be written to.
+     */
+    coverage(coverageDir: string, options: CoverageReportOptions): Pipe
+  }
 }
 
-/** Analyse coverage using files generated by V8/NodeJS. */
-export class Coverage<
-  T extends CoverageOptions | CoverageReportOptions,
-> implements Plug<T extends CoverageReportOptions ? Files : undefined> {
-  constructor(coverageDir: string)
-  constructor(coverageDir: string, options?: T)
+/* ========================================================================== *
+ * INSTALLATION / IMPLEMENTATION                                              *
+ * ========================================================================== */
+
+install('coverage', class Coverage implements Plug<Files | undefined> {
+  constructor(...args: PipeParameters<'coverage'>)
   constructor(
       private readonly _coverageDir: string,
       private readonly _options: Partial<CoverageReportOptions> = {},
   ) {}
 
-  async pipe(files: Files, run: Run): Promise<T extends CoverageReportOptions ? Files : undefined> {
-    const coverageFiles = await run.find('coverage-*.json', {
-      directory: this._coverageDir,
-    })
+  async pipe(files: Files, context: Context): Promise<Files | undefined> {
+    const coverageDir = context.resolve(this._coverageDir)
+    const coverageFiles: AbsolutePath[] = []
+    for await (const file of walk(coverageDir, [ 'coverage-*.json' ])) {
+      coverageFiles.push(resolveAbsolutePath(coverageDir, file))
+    }
 
     if (coverageFiles.length === 0) {
-      fail(`No coverage files found in ${$p(coverageFiles.directory)}`)
+      fail(`No coverage files found in ${$p(coverageDir)}`)
     }
 
     const sourceFiles = [ ...files.absolutePaths() ]
@@ -64,15 +87,15 @@ export class Coverage<
     const ms1 = Date.now()
     const analyser = await createAnalyser(
         sourceFiles,
-        [ ...coverageFiles.absolutePaths() ],
+        coverageFiles,
         this._options.sourceMapBias || 'least_upper_bound',
-        run.log,
+        context.log,
     )
-    run.log.info('Parsed', coverageFiles.length, 'coverage files', $ms(Date.now() - ms1))
+    context.log.info('Parsed', coverageFiles.length, 'coverage files', $ms(Date.now() - ms1))
 
     const ms2 = Date.now()
-    const report = await coverageReport(analyser, sourceFiles, run.log)
-    run.log.info('Analysed', sourceFiles.length, 'source files', $ms(Date.now() - ms2))
+    const report = await coverageReport(analyser, sourceFiles, context.log)
+    context.log.info('Analysed', sourceFiles.length, 'source files', $ms(Date.now() - ms2))
 
     analyser.destroy()
 
@@ -95,7 +118,7 @@ export class Coverage<
 
     let fileErrors = 0
     let fileWarnings = 0
-    const _report = run.report('Coverage report')
+    const _report = context.log.report('Coverage report')
 
     for (const [ _file, result ] of Object.entries(report.results)) {
       const { coverage, totalNodes } = result.nodeCoverage
@@ -135,7 +158,8 @@ export class Coverage<
     if (this._options.reportDir == null) return _report.done(false) as any
 
     /* Create a builder to emit our reports */
-    const builder = run.files(this._options.reportDir)
+    const reportDir = context.resolve(this._options.reportDir)
+    const builder = Files.builder(reportDir)
 
     /* Thresholds to inject in the report */
     const date = new Date().toISOString()
@@ -180,17 +204,4 @@ export class Coverage<
     /* Return emitted files */
     return builder.build() as any
   }
-}
-
-/* ========================================================================== *
- * INSTALLATION                                                               *
- * ========================================================================== */
-
-install('coverage', Coverage)
-
-declare module '../pipe.js' {
-  export interface Pipe {
-    /** Analyse coverage using files generated by V8/NodeJS. */
-    coverage: PipeExtension<CoverageConstructor>
-  }
-}
+})

package/src/plugs/debug.ts

@@ -1,35 +1,37 @@
-import { Files } from '../files.js'
-import { $gry, $p, $und } from '../log.js'
-import { install, Plug } from '../pipe.js'
-import { Run } from '../run.js'
+import { Files } from '../files'
+import { $gry, $p, $und, $ylw } from '../log'
+import { install, Plug, Context, PipeParameters } from '../pipe'
 
-/** Writes some info about the current {@link Files} being passed around. */
-export class Debug implements Plug<Files> {
-  constructor() {}
-
-  async pipe(files: Files, run: Run): Promise<Files> {
-    run.log.notice('Debugging', files.length, 'files')
-    run.log.notice('-        base dir:', $p(run.resolve('@')))
-    run.log.notice('-  build file dir:', $p(run.resolve('.')))
-    run.log.notice('-       files dir:', $p(files.directory))
-    if (files.length) {
-      const [ path, ...paths ] = files
-      run.log.notice('-  relative paths:', $und($gry(path)))
-      for (const p of paths) run.log.notice('-                :', $und($gry(p)))
-    }
-    return files
+declare module '../pipe' {
+  export interface Pipe {
+    /** Log some info about the current {@link Files} being passed around. */
+    debug(title?: string): Pipe
   }
 }
 
 /* ========================================================================== *
- * INSTALLATION                                                               *
+ * INSTALLATION / IMPLEMENTATION                                              *
  * ========================================================================== */
 
-install('debug', Debug)
+/** Writes some info about the current {@link Files} being passed around. */
+install('debug', class Debug implements Plug<Files> {
+  private readonly _title: string
+
+  constructor(...args: PipeParameters<'debug'>) {
+    const [ title = 'Debugging' ] = args
+    this._title = title
+  }
 
-declare module '../pipe.js' {
-  export interface Pipe {
-    /** Writes some info about the current {@link Files} being passed around. */
-    debug: PipeExtension<typeof Debug>
+  async pipe(files: Files, context: Context): Promise<Files> {
+    context.log.notice(this._title, `${$gry('(')}${$ylw(files.length)} ${$gry('files)')}`)
+    context.log.notice('-        base dir:', $p(context.resolve('@')))
+    context.log.notice('-  build file dir:', $p(context.resolve('.')))
+    context.log.notice('-       files dir:', $p(files.directory))
+    if (files.length) {
+      const [ path, ...paths ] = files
+      context.log.notice('-  relative paths:', $und($gry(path)))
+      for (const p of paths) context.log.notice('-                :', $und($gry(p)))
+    }
+    return files
   }
-}
+})

package/src/plugs/esbuild/fix-extensions.ts

@@ -1,8 +1,8 @@
 import path from 'node:path'
 
 import { Plugin } from 'esbuild'
-import { assertAbsolutePath, resolveFile, resolveAbsolutePath } from '../../paths.js'
-import { stat } from '../../utils/asyncfs.js'
+import { assertAbsolutePath, resolveAbsolutePath, resolveFile } from '../../paths'
+import { stat } from '../../utils/asyncfs'
 
 /**
  * A simple ESBuild plugin fixing extensions for `require` and `import` calls.

package/src/plugs/esbuild.ts

@@ -1,23 +1,41 @@
 import { build, BuildFailure, BuildOptions, BuildResult, Format, Message, Metafile } from 'esbuild'
 import { basename } from 'node:path'
-import { assert } from '../assert.js'
-import { Files, FilesBuilder } from '../files.js'
-import { $p, ERROR, Logger, ReportLevel, ReportRecord, WARN } from '../log.js'
-import { AbsolutePath, getAbsoluteParent, resolveAbsolutePath } from '../paths.js'
-import { install, Plug } from '../pipe.js'
-import { Run } from '../run.js'
-import { readFile } from '../utils/asyncfs.js'
+import { assert } from '../assert'
+import { Files, FilesBuilder } from '../files'
+import { $p, ERROR, Logger, ReportLevel, ReportRecord, WARN } from '../log'
+import { AbsolutePath, getAbsoluteParent, resolveAbsolutePath } from '../paths'
+import { install, PipeParameters, Plug, Context } from '../pipe'
+import { readFile } from '../utils/asyncfs'
 
 export type ESBuildOptions = Omit<BuildOptions, 'absWorkingDir' | 'entryPoints' | 'watch'>
 
-/**
- * Transpile and bundle files with {@link https://esbuild.github.io/ | esbuild}.
- */
-export class ESBuild implements Plug<Files> {
-  constructor(options: ESBuildOptions)
+export * from './esbuild/bundle-locals'
+export * from './esbuild/fix-extensions'
+
+declare module '../pipe' {
+  export interface Pipe {
+    /**
+     * Transpile and bundle with {@link https://esbuild.github.io/ esbuild}.
+     *
+     * For documentation on the _options_ to pass to _esbuild_ refer to its
+     * {@link https://esbuild.github.io/api/#build-api documentation}.
+     *
+     * @param options Build {@link ESBuildOptions | options} to pass to esbuild.
+     *
+     */
+    esbuild(options: ESBuildOptions): Pipe
+  }
+}
+
+/* ========================================================================== *
+ * INSTALLATION / IMPLEMENTATION                                              *
+ * ========================================================================== */
+
+install('esbuild', class ESBuild implements Plug<Files> {
+  constructor(...args: PipeParameters<'esbuild'>)
   constructor(private readonly _options: ESBuildOptions) {}
 
-  async pipe(files: Files, run: Run): Promise<Files> {
+  async pipe(files: Files, context: Context): Promise<Files> {
     const entryPoints = [ ...files ]
     const absWorkingDir = files.directory
 
@@ -27,7 +45,7 @@ export class ESBuild implements Plug<Files> {
       target: `node${process.versions['node'].split('.')[0]}`,
 
       /* The default format (if not specified in options) is from package.json */
-      format: this._options.format || await _moduleFormat(files.directory, run.log),
+      format: this._options.format || await _moduleFormat(files.directory, context.log),
 
       /* Output bese directory */
       outbase: absWorkingDir,
@@ -48,29 +66,29 @@ export class ESBuild implements Plug<Files> {
     /* Where to write, where to write? */
     let builder: FilesBuilder
     if (options.bundle && options.outfile && (entryPoints.length === 1)) {
-      builder = run.files(absWorkingDir)
+      builder = Files.builder(absWorkingDir)
       const outputFile = resolveAbsolutePath(absWorkingDir, options.outfile)
       const entryPoint = resolveAbsolutePath(absWorkingDir, entryPoints[0])
       options.outfile = outputFile
 
-      run.log.debug('Bundling', $p(entryPoint), 'into', $p(outputFile))
+      context.log.debug('Bundling', $p(entryPoint), 'into', $p(outputFile))
     } else {
       assert(options.outdir, 'Option "outdir" must be specified')
 
-      builder = run.files(options.outdir)
+      builder = Files.builder(context.resolve(options.outdir))
       options.outdir = builder.directory
 
       const message = options.bundle ? 'Bundling' : 'Transpiling'
-      run.log.debug(message, entryPoints.length, 'files to', $p(builder.directory))
+      context.log.debug(message, entryPoints.length, 'files to', $p(builder.directory))
     }
 
-    const report = run.report('ESBuild Report')
+    const report = context.log.report('ESBuild Report')
 
-    run.log.trace('Running ESBuild', options)
+    context.log.trace('Running ESBuild', options)
     let esbuild: undefined | (BuildResult & { metafile: Metafile })
     try {
       esbuild = await build({ ...options, metafile: true })
-      run.log.trace('ESBuild Results', esbuild)
+      context.log.trace('ESBuild Results', esbuild)
 
       report.add(...esbuild.warnings.map((m) => convertMessage(WARN, m, absWorkingDir)))
       report.add(...esbuild.errors.map((m) => convertMessage(ERROR, m, absWorkingDir)))
@@ -86,14 +104,14 @@ export class ESBuild implements Plug<Files> {
     assert(esbuild, 'ESBuild did not produce any result')
 
     for (const file in esbuild.metafile.outputs) {
-      builder.unchecked(resolveAbsolutePath(absWorkingDir, file))
+      builder.add(resolveAbsolutePath(absWorkingDir, file))
     }
 
     const result = builder.build()
-    run.log.info('ESBuild produced', result.length, 'files into', $p(result.directory))
+    context.log.info('ESBuild produced', result.length, 'files into', $p(result.directory))
     return result
   }
-}
+})
 
 function convertMessage(level: ReportLevel, message: Message, directory: AbsolutePath): ReportRecord {
   const record: ReportRecord = { level, message: message.text }
@@ -109,28 +127,6 @@ function convertMessage(level: ReportLevel, message: Message, directory: Absolut
   return record
 }
 
-/* ========================================================================== *
- * INSTALLATION                                                               *
- * ========================================================================== */
-
-install('esbuild', ESBuild)
-
-declare module '../pipe.js' {
-  export interface Pipe {
-    /**
-     * Transpile and bundle files with {@link https://esbuild.github.io/ esbuild}.
-     */
-    esbuild: PipeExtension<typeof ESBuild>
-  }
-}
-
-/* ========================================================================== *
- * PLUGINS                                                                    *
- * ========================================================================== */
-
-export * from './esbuild/bundle-locals.js'
-export * from './esbuild/fix-extensions.js'
-
 /* ========================================================================== *
  * DEFAULT MODULE FORMAT FROM PACKAGE.JSON                                    *
  * ========================================================================== */

package/src/plugs/eslint/runner.ts

@@ -1,42 +1,28 @@
 import { ESLint as RealESLint } from 'eslint'
-import { assert, failure } from '../../assert.js'
-import { Files } from '../../files.js'
-import { $p, ERROR, NOTICE, WARN } from '../../log.js'
-import { getCurrentWorkingDirectory, resolveDirectory, resolveFile, resolveAbsolutePath } from '../../paths.js'
-import { Plug } from '../../pipe.js'
-import { Run } from '../../run.js'
-import { readFile } from '../../utils/asyncfs.js'
-
-export interface ESLintOptions {
-  /** ESLint's own _current working directory_, where config files are. */
-  directory?: string
-  /** Show sources in report? */
-  showSources?: boolean
-  /**
-   * ESLint's _override_ configuration file: configurations specified in this
-   * file will override any other configuration specified elsewhere.
-   */
-  configFile?: string
-}
-
-/** Writes some info about the current {@link Files} being passed around. */
-export default class ESLint implements Plug<undefined> {
+import { assert, failure } from '../../assert'
+import { Files } from '../../files'
+import { $p, ERROR, NOTICE, WARN } from '../../log'
+import { getCurrentWorkingDirectory, resolveAbsolutePath, resolveDirectory, resolveFile } from '../../paths'
+import { PipeParameters, Plug, Context } from '../../pipe'
+import { readFile } from '../../utils/asyncfs'
+import { ESLintOptions } from '../eslint'
+
+/** Runner implementation for the `ESLint` plug. */
+export default class ESLint implements Plug<void> {
   private readonly _options: Readonly<ESLintOptions>
 
-  constructor()
-  constructor(configFile: string)
-  constructor(options: ESLintOptions)
+  constructor(...arg: PipeParameters<'eslint'>)
   constructor(arg: string | ESLintOptions = {}) {
     this._options = typeof arg === 'string' ? { configFile: arg } : arg
   }
 
-  async pipe(files: Files, run: Run): Promise<undefined> {
+  async pipe(files: Files, context: Context): Promise<void> {
     const { directory, configFile } = this._options
 
-    const cwd = directory ? run.resolve(directory) : getCurrentWorkingDirectory()
+    const cwd = directory ? context.resolve(directory) : getCurrentWorkingDirectory()
     assert(resolveDirectory(cwd), `ESLint directory ${$p(cwd)} does not exist`)
 
-    const overrideConfigFile = configFile ? run.resolve(configFile) : undefined
+    const overrideConfigFile = configFile ? context.resolve(configFile) : undefined
     if (overrideConfigFile) {
       assert(resolveFile(overrideConfigFile), `ESLint configuration ${$p(overrideConfigFile)} does not exist`)
     }
@@ -58,7 +44,7 @@ export default class ESLint implements Plug<undefined> {
     const summary = settlements.reduce((summary, settlement, i) => {
       /* Promise rejected, meaining hard failure */
       if (settlement.status === 'rejected') {
-        run.log.error('Error linting', $p(paths[i]), settlement.reason)
+        context.log.error('Error linting', $p(paths[i]), settlement.reason)
         summary.failures ++
         return summary
       }
@@ -76,7 +62,7 @@ export default class ESLint implements Plug<undefined> {
     if (failures) throw failure() // already logged above
 
     /* Create our report */
-    const report = run.report('ESLint Report')
+    const report = context.log.report('ESLint Report')
 
     /* Convert ESLint results into our report records */
     for (const result of results) {
@@ -107,6 +93,5 @@ export default class ESLint implements Plug<undefined> {
 
     /* Emit our report and fail on errors */
     report.done(this._options.showSources)
-    return undefined
   }
 }

package/src/plugs/eslint.ts

@@ -0,0 +1,42 @@
+import { requireResolve } from '../paths'
+import { installForking } from '../pipe'
+
+export interface ESLintOptions {
+  /** ESLint's own _current working directory_, where config files are. */
+  directory?: string
+  /** Show sources in report? */
+  showSources?: boolean
+  /**
+   * ESLint's _override_ configuration file: configurations specified in this
+   * file will override any other configuration specified elsewhere.
+   */
+  configFile?: string
+}
+
+declare module '../pipe' {
+  export interface Pipe {
+    /**
+     * Run {@link https://eslint.org/ _ESlint_} over the input source files,
+     * using the configuration from the local `.eslintrc.*` file.
+     */
+    eslint(): Promise<undefined>
+
+    /**
+     * Run {@link https://eslint.org/ _ESlint_} over the input source files,
+     * using the configuration from the specified `configFile` (this wil
+     * override any `.eslintrc.*` file).
+     *
+     * @param configFile The configuration file to use
+     */
+    eslint(configFile: string): Promise<undefined>
+
+    /**
+     * Run {@link https://eslint.org/ _ESlint_} over the input source files..
+     *
+     * @param options {@link ESLintOptions | Options} to pass to _ESLint_
+     */
+    eslint(options: ESLintOptions): Promise<undefined>
+  }
+}
+
+installForking('eslint', requireResolve(__fileurl, './eslint/runner'))