@plugjs/plug 0.0.1

package/src/plugs/esbuild/check-dependencies.ts

@@ -0,0 +1,158 @@
+import { Message, OnStartResult, Plugin } from 'esbuild'
+import { currentRun } from '../../async.js'
+import { $p } from '../../log.js'
+import { AbsolutePath } from '../../paths.js'
+import { readFile } from '../../utils/asyncfs.js'
+import { ParseOptions, parseOptions } from '../../utils/options.js'
+
+export interface CheckDependenciesOptions {
+  allowDev?: boolean | 'warn' | 'error',
+  allowPeer?: boolean | 'warn' | 'error',
+  allowOptional?: boolean | 'warn' | 'error',
+  allowUnused?: boolean | 'warn' | 'error',
+  ignored?: string[]
+}
+
+export function checkDependencies(): Plugin
+export function checkDependencies(packageJson: string): Plugin
+export function checkDependencies(options: CheckDependenciesOptions): Plugin
+export function checkDependencies(packageJson: string, options: CheckDependenciesOptions): Plugin
+
+export function checkDependencies(...args: ParseOptions<CheckDependenciesOptions>): Plugin {
+  const run = currentRun() // outside of "onStart", goes into esbuild domain
+
+  const { params, options } = parseOptions(args, {
+    ignored: [] as string[],
+    allowDev: false,
+    allowPeer: true,
+    allowOptional: true,
+    allowUnused: false,
+  })
+
+  const allowDev = convertOption(options.allowDev)
+  const allowPeer = convertOption(options.allowPeer)
+  const allowOptional = convertOption(options.allowOptional)
+  const allowUnused = convertOption(options.allowUnused)
+
+  const dependencies: string[] = []
+  const devDependencies: string[] = []
+  const peerDependencies: string[] = []
+  const optionalDependencies: string[] = []
+  const ignored = new Set(options.ignored)
+  const used = new Set<string>()
+
+  return {
+    name: 'check-dependencies',
+    setup(build): void {
+      /* When using this, we fake esbuild's "bundle" functionality */
+      build.initialOptions.bundle = true
+
+      let packageJson: AbsolutePath
+
+      build.onStart(async (): Promise<OnStartResult | void> => {
+        if (! run) return { errors: [ { text: 'Unable to find current Run' } ] }
+
+        const resolved = run.resolve(params[0] || '@package.json')
+        packageJson = resolved
+
+        try {
+          const data = await readFile(resolved, 'utf-8')
+          const json = JSON.parse(data)
+          dependencies.push(...dependencyKeys(json.dependencies))
+          devDependencies.push(...dependencyKeys(json.devDependencies))
+          peerDependencies.push(...dependencyKeys(json.peerDependencies))
+          optionalDependencies.push(...dependencyKeys(json.optionalDependencies))
+        } catch (error) {
+          return { errors: [ { text: `Unable to parse ${$p(resolved)}` } ] }
+        }
+      })
+
+      /* Intercept resolution */
+      build.onResolve({ filter: /.*/ }, (args) => {
+        if (args.importer.match(/\/node_modules\//)) return // only our sources
+        if (args.path.startsWith('node:')) return // node imports
+        if (args.path.startsWith('.')) return // local imports
+
+        // Normal dependencies get the green light immediately
+        if (dependencies.includes(args.path)) {
+          used.add(args.path)
+          return { external: true }
+        }
+
+        // In order, here, we first check "optional" and "peers" (which should)
+        // also have a corresponding entry in "dev" for things to work, then
+        // "dev" is definitely checked last
+        const [ result, label ] =
+          optionalDependencies.includes(args.path) ? [ allowOptional, 'an optional' ] as const :
+          peerDependencies.includes(args.path) ? [ allowPeer, 'a peer' ] as const :
+          devDependencies.includes(args.path) ? [ allowDev, 'a dev' ] as const :
+          [ 'error', undefined ] as const
+
+        // If we're told to ignore, then... IGNORE!
+        if (ignored.has(args.path)) return { external: true }
+        if (result === 'ignore') return { external: true }
+
+        // Prep the message
+        const text = label ?
+            `Dependency "${args.path}" is ${label} dependency` :
+            `Dependency "${args.path}" not specified in "package.json"`
+
+        // Return the proper error or warning
+        return result === 'warn' ?
+            { external: true, warnings: [ { text } ] } :
+            { external: true, errors: [ { text } ] }
+      })
+
+      /* Check for unused */
+      build.onEnd((result) => {
+        if (allowUnused === 'ignore') return
+
+        // Figure out every unused dependency
+        const unused = new Set(dependencies)
+        ignored.forEach((dep) => unused.delete(dep))
+        used.forEach((dep) => unused.delete(dep))
+
+        // Convert the dependency name into a "message"
+        const messages = [ ...unused ]
+            .map((dep) => `Unused dependency "${dep}"`)
+            .map((text): Message => ({
+              id: '',
+              pluginName: 'check-dependencies',
+              location: {
+                file: packageJson,
+                namespace: 'file',
+                line: 0,
+                column: 0,
+                length: 0,
+                lineText: '',
+                suggestion: '',
+              },
+              text,
+              notes: [],
+              detail: undefined,
+            }))
+
+        // Inject our messages either as warnings or errors
+        if (allowUnused === 'warn') {
+          result.warnings.push(...messages)
+        } else {
+          result.errors.push(...messages)
+        }
+      })
+    },
+  }
+}
+
+function convertOption(option?: boolean | 'warn' | 'error'): 'ignore' | 'warn' | 'error' {
+  if (option === 'warn') return 'warn'
+  if (option === 'error') return 'error'
+  if (option) return 'ignore'
+  return 'error'
+}
+
+
+function dependencyKeys(dependencies: any): string[] {
+  if (! dependencies) return []
+  if (typeof dependencies !== 'object') return []
+  return Object.keys(dependencies).filter((key) => typeof key === 'string')
+}

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

@@ -0,0 +1,108 @@
+import path from 'node:path'
+
+import { Plugin } from 'esbuild'
+import { assertAbsolutePath, isFile, resolveAbsolutePath } from '../../paths.js'
+import { stat } from '../../utils/asyncfs.js'
+
+/**
+ * A simple ESBuild plugin fixing extensions for `require` and `import` calls.
+ *
+ * This can be useful when compiling dual-module packages (`esm` and `cjs`),
+ * where the file module type is determined by the `.mjs` or `.cjs` extension.
+ *
+ * For example this will make sure all `import` statements use the `.mjs`
+ * extensions, while all `require` use `.cjs`.
+ *
+ * ```
+ * await find('*.ts', { directory: 'src' })
+ *   .esbuild({
+ *     outdir: 'dist',
+ *     format: 'cjs',
+ *     plugins: [ fixExtensions ],
+ *     outExtension: { '.js': '.mjs' },
+ *   })
+ *
+ * await find('*.ts', { directory: 'src' })
+ *   .esbuild({
+ *     outdir: 'dist',
+ *     format: 'esm',
+ *     plugins: [ fixExtensions ],
+ *     outExtension: { '.js': '.mjs' },
+ *   })
+ * ```
+ */
+export function fixExtensions(): Plugin {
+  return {
+    name: 'fix-extensions',
+
+    setup(build): void {
+      /* When using this, we fake esbuild's "bundle" functionality */
+      build.initialOptions.bundle = true
+
+      /* Our ".js" extension, might be remapped by `outExtension`s */
+      const cjs = build.initialOptions.outExtension?.['.cjs'] || '.cjs'
+      const mjs = build.initialOptions.outExtension?.['.mjs'] || '.mjs'
+      const js = build.initialOptions.outExtension?.['.js'] || '.js'
+
+      /* Extensions for files to look for */
+      const exts = build.initialOptions.resolveExtensions || [ '.ts', '.js', '.tsx', '.jsx' ]
+
+      /* Intercept resolution */
+      build.onResolve({ filter: /.*/ }, async (args) => {
+        /* Ignore the entry points (when the file is not being imported) */
+        if (! args.importer) return null
+
+        /* Anything not starting with "."? external node module */
+        if (! args.path.match(/^\.\.?\//)) return { external: true }
+
+        /* Some easy pathing options */
+        const resolveDir = args.resolveDir
+        assertAbsolutePath(resolveDir)
+
+        /* First of all, check if the _real_ filename exists */
+        const resolved = resolveAbsolutePath(resolveDir, args.path)
+        if (isFile(resolved)) return { path: args.path, external: true }
+
+        /*
+         * Thank you TypeScript 4.7!!! If the file is ".js", ".mjs" or ".cjs" we
+         * need to check if we have the corresponding ".ts", ".mts" or ".cjs"
+         * and return whatever ESBuild maps that particular extension to.
+         */
+        const match = args.path.match(/(.*)(\.[mc]?js$)/)
+        if (match) {
+          const [ , name, ext ] = match
+          const tspath = name + ext.replace('js', 'ts')
+          const tsfile = resolveAbsolutePath(resolveDir, tspath)
+          if (isFile(tsfile)) {
+            const newext = ext === '.mjs' ? mjs : ext === '.cjs' ? cjs : js
+            return { path: name + newext, external: true }
+          }
+        }
+
+        /* Check if ".../filename.ext" exists in our sources */
+        for (const ext of exts) {
+          const fileName = `${args.path}${ext}`
+          const filePath = path.resolve(args.resolveDir, fileName)
+          const isFile = await stat(filePath).then((stat) => stat.isFile(), (error) => void error)
+          if (isFile) return { path: `${args.path}${js}`, external: true }
+        }
+
+        /* If ".../filename" is not a directory, we end here */
+        const dirPath = path.resolve(args.resolveDir, args.path)
+        const isDir = await stat(dirPath).then((stat) => stat.isDirectory(), (error) => void error)
+        if (! isDir) return { external: true }
+
+        /* Check if ".../filename/index.ext" exists in our sources */
+        for (const ext of exts) {
+          const fileName = path.join(args.path, `index${ext}`)
+          const filePath = path.resolve(args.resolveDir, fileName)
+          const isFile = await stat(filePath).then((stat) => stat.isFile(), (error) => void error)
+          if (isFile) return { path: `${args.path}/index${js}`, external: true }
+        }
+
+        /* Nothing was found, then just mark this external */
+        return { external: true }
+      })
+    },
+  }
+}

package/src/plugs/esbuild.ts

@@ -0,0 +1,128 @@
+import { build, BuildFailure, BuildOptions, BuildResult, Message, Metafile } from 'esbuild'
+import { assert } from '../assert.js'
+import { Files, FilesBuilder } from '../files.js'
+import { $p, ERROR, ReportLevel, ReportRecord, WARN } from '../log.js'
+import { AbsolutePath, resolveAbsolutePath } from '../paths.js'
+import { install, Plug } from '../pipe.js'
+import { Run } from '../run.js'
+
+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)
+  constructor(private readonly _options: ESBuildOptions) {}
+
+  async pipe(files: Files, run: Run): Promise<Files> {
+    const entryPoints = [ ...files ]
+    const absWorkingDir = files.directory
+
+    const options: BuildOptions = {
+      /* Defaults */
+      platform: 'node',
+      target: `node${process.versions['node']}`,
+      format: 'cjs',
+      outbase: absWorkingDir,
+
+      logLevel: 'silent',
+
+      /* Our options */
+      ...this._options,
+
+      /* Always override */
+      absWorkingDir,
+      entryPoints,
+      watch: false,
+    }
+
+    /* Sanity check on output file/directory */
+    assert(!(options.outdir && options.outfile), 'Options "outfile" and "outdir" can not coexist')
+
+    /* Where to write, where to write? */
+    let builder: FilesBuilder
+    if (options.bundle && options.outfile && (entryPoints.length === 1)) {
+      builder = run.files(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))
+    } else {
+      assert(options.outdir, 'Option "outdir" must be specified')
+
+      builder = run.files(options.outdir)
+      options.outdir = builder.directory
+
+      const message = options.bundle ? 'Bundling' : 'Transpiling'
+      run.log.debug(message, entryPoints.length, 'files to', $p(builder.directory))
+    }
+
+    const report = run.report('ESBuild Report')
+
+    run.log.trace('Running ESBuild', options)
+    let esbuild: undefined | (BuildResult & { metafile: Metafile })
+    try {
+      esbuild = await build({ ...options, metafile: true })
+      run.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)))
+    } catch (error: any) {
+      const e = error as BuildFailure
+      if (e.warnings) report.add(...e.warnings.map((m) => convertMessage(WARN, m, absWorkingDir)))
+      if (e.errors) report.add(...e.errors.map((m) => convertMessage(ERROR, m, absWorkingDir)))
+    }
+
+    await report.loadSources()
+    report.done()
+
+    assert(esbuild, 'ESBuild did not produce any result')
+
+    for (const file in esbuild.metafile.outputs) {
+      builder.add(resolveAbsolutePath(absWorkingDir, file))
+    }
+
+    const result = builder.build()
+    run.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 }
+  record.tags = [ message.id, message.pluginName ].filter((tag) => !! tag)
+
+  if (message.location) {
+    record.line = message.location.line,
+    record.column = message.location.column + 1
+    record.length = message.location.length
+    record.file = resolveAbsolutePath(directory, message.location.file)
+  }
+
+  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/check-dependencies.js'
+export * from './esbuild/fix-extensions.js'

package/src/plugs/eslint/runner.ts

@@ -0,0 +1,112 @@
+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, isDirectory, isFile, 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> {
+  private readonly _options: Readonly<ESLintOptions>
+
+  constructor()
+  constructor(configFile: string)
+  constructor(options: ESLintOptions)
+  constructor(arg: string | ESLintOptions = {}) {
+    this._options = typeof arg === 'string' ? { configFile: arg } : arg
+  }
+
+  async pipe(files: Files, run: Run): Promise<undefined> {
+    const { directory, configFile } = this._options
+
+    const cwd = directory ? run.resolve(directory) : getCurrentWorkingDirectory()
+    assert(isDirectory(cwd), `ESLint directory ${$p(cwd)} does not exist`)
+
+    const overrideConfigFile = configFile ? run.resolve(configFile) : undefined
+    if (overrideConfigFile) {
+      assert(isFile(overrideConfigFile), `ESLint configuration ${$p(overrideConfigFile)} does not exist`)
+    }
+
+    /* Create our ESLint instance */
+    const eslint = new RealESLint({ overrideConfigFile, cwd })
+
+    /* Lint all files in parallel */
+    const paths = [ ...files.absolutePaths() ]
+    const promises = paths.map(async (filePath) => {
+      const code = await readFile(filePath, 'utf-8')
+      return eslint.lintText(code, { filePath })
+    })
+
+    /* Await for all promises to be settled */
+    const settlements = await Promise.allSettled(promises)
+
+    /* Run through all promises settlements */
+    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)
+        summary.failures ++
+        return summary
+      }
+
+      /* Push all our results in the summary */
+      summary.results.push(...settlement.value)
+      return summary
+    }, {
+      results: [] as RealESLint.LintResult[],
+      failures: 0,
+    })
+
+    /* In case of failures from promises, fail! */
+    const { results, failures } = summary
+    if (failures) throw failure() // already logged above
+
+    /* Create our report */
+    const report = run.report('ESLint Report')
+
+    /* Convert ESLint results into our report records */
+    for (const result of results) {
+      const { filePath, source, messages } = result
+      const file = resolveAbsolutePath(getCurrentWorkingDirectory(), filePath)
+
+      for (const record of messages) {
+        const {
+          severity,
+          message,
+          ruleId: tags,
+          line,
+          column,
+          endLine = line,
+          endColumn = column + 1,
+        } = record
+
+        /* Severity becomes our "kind" */
+        const level = severity === 0 ? NOTICE : severity === 1 ? WARN : ERROR
+
+        /* Characters */
+        const length = endLine === line ? endColumn - column : endLine > line ? -1 : 1
+
+        /* Add our report */
+        report.add({ level, message, tags, line, column, length, file, source })
+      }
+    }
+
+    /* Emit our report and fail on errors */
+    report.done(this._options.showSources)
+    return undefined
+  }
+}