@plugjs/plug 0.0.1

package/src/paths.ts

@@ -0,0 +1,213 @@
+import { statSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { assert } from './assert.js'
+
+/** A _branded_ `string` representing an _absolute_ path name */
+export type AbsolutePath = string & { __brand_absolute_path: never }
+
+/* ========================================================================== *
+ * PATH FUNCTIONS                                                             *
+ * ========================================================================== */
+
+/** Resolve a path into an {@link AbsolutePath} */
+export function resolveAbsolutePath(directory: AbsolutePath, ...paths: string[]): AbsolutePath {
+  const resolved = resolve(directory, ...paths) as AbsolutePath
+  assert(isAbsolute(resolved), `Path "${join(...paths)}" resolved in "${directory}" is not absolute`)
+  return resolved
+}
+
+/**
+ * Resolve a path as a relative path to the directory specified, returning the
+ * relative child path or `undefined` if the specified path was not a child.
+ *
+ * The `path` specified here _could_ also be another {@link AbsolutePath}
+ * therefore something like this will work:
+ *
+ * ```
+ * resolveRelativeChildPath('/foo', '/foo/bar')
+ * // will yield `bar`
+ * ```
+ */
+export function resolveRelativeChildPath(directory: AbsolutePath, ...paths: string[]): string | undefined {
+  assertAbsolutePath(directory)
+
+  const abs = resolveAbsolutePath(directory, ...paths)
+  const rel = relative(directory, abs)
+  return (isAbsolute(rel) || (rel === '..') || rel.startsWith(`..${sep}`)) ? undefined : rel
+}
+
+/**
+ * Asserts that a path is a relative path to the directory specified, failing
+ * the build if it's not (see also {@link resolveRelativeChildPath}).
+ */
+
+export function assertRelativeChildPath(directory: AbsolutePath, ...paths: string[]): string {
+  const relative = resolveRelativeChildPath(directory, ...paths)
+  assert(relative, `Path "${join(...paths)}" not relative to "${directory}"`)
+  return relative
+}
+
+/** Checks that the specified path is an {@link AbsolutePath} */
+export function isAbsolutePath(path: string): path is AbsolutePath {
+  return isAbsolute(path)
+}
+
+/** Asserts that the specified path is an {@link AbsolutePath} */
+export function assertAbsolutePath(p: string): asserts p is AbsolutePath {
+  assert(isAbsolute(p), `Path "${p}" not absolute`)
+}
+
+/** Return the {@link AbsolutePath} parent of another */
+export function getAbsoluteParent(path: AbsolutePath): AbsolutePath {
+  assertAbsolutePath(path)
+  return dirname(path) as AbsolutePath
+}
+
+/**
+ * Return the {@link process.cwd() | current working directory} as an
+ * {@link AbsolutePath}.
+ */
+export function getCurrentWorkingDirectory(): AbsolutePath {
+  const cwd = process.cwd()
+  assertAbsolutePath(cwd)
+  return cwd
+}
+
+/* ========================================================================== *
+ * MODULE RESOLUTION FUNCTIONS                                                *
+ * ========================================================================== */
+
+/**
+ * Return the absolute path of a file relative to the given `__fileurl`, where
+ * `__fileurl` is either CommonJS's own `__filename` variable, or EcmaScript's
+ * `import.meta.url` (so either an absolute path name, or a `file:///...` url).
+ *
+ * If further `paths` are specified, those will be resolved as relative paths
+ * to the original `__fileurl` so we can easily write something like this:
+ *
+ * ```
+ * const dataFile = resolveFilename(__fileurl, 'data.json')
+ * // if we write this in "/foo/bar/baz.(ts|js|cjs|mjs)"
+ * // `dataFile` will now be "/foo/bar/data.json"
+ * ```
+ */
+export function requireFilename(__fileurl: string, ...paths: string[]): AbsolutePath {
+  /* Convert any "file:..." URL into a path name */
+  const file = __fileurl.startsWith('file:') ? fileURLToPath(__fileurl) : __fileurl
+
+  /* We should really have a proper absolute file name now */
+  assertAbsolutePath(file)
+
+  /* No paths? Return the file! */
+  if (! paths.length) return file
+
+  /* Resolve any paths, relative to the file */
+  const directory = getAbsoluteParent(file)
+  return resolveAbsolutePath(directory, ...paths)
+}
+
+/**
+ * Return the absolute path of a file which can be _required_ or _imported_
+ * by Node (or forked to via `child_process.fork`).
+ *
+ * This leverages {@link requireFilename} to figure out the starting point where
+ * to look for files, and will _try_ to match the same extension of `__fileurl`
+ * (so, `.ts` for `ts-node`, `.mjs` for ESM modules, ...).
+ */
+export function requireResolve(__fileurl: string, module: string): AbsolutePath {
+  const file = requireFilename(__fileurl)
+
+  // We do our custom resolution _only_ for local (./foo.bar) files...
+  if (module.match(/^\.\.?\//)) {
+    // If we import "../foo.ext" from "/a/b/c/bar.ts" we need to check:
+    // * /a/b/foo.ext
+    // * /a/b/foo.ext.ts
+    // * /a/b/foo.ext/index.ts
+    // ... then delegate to the standard "require.resolve(...)"
+    const url = pathToFileURL(file)
+    const ext = extname(file)
+    const checks = ext ? [ `${module}`, `${module}${ext}`, `${module}/index${ext}` ] : [ module ]
+
+    for (const check of checks) {
+      const resolved = fileURLToPath(new URL(check, url)) as AbsolutePath
+      if (isFile(resolved)) {
+        module = check
+        break
+      }
+    }
+  }
+
+  const require = createRequire(file)
+  const required = require.resolve(module)
+  assertAbsolutePath(required)
+  return required
+}
+
+/**
+ * Return the _common_ path amongst all specified paths.
+ *
+ * While the first `path` _must_ be an {@link AbsolutePath}, all other `paths`
+ * can be _relative_ and will be resolved against the first `path`.
+ */
+export function commonPath(path: AbsolutePath, ...paths: string[]): AbsolutePath {
+  assertAbsolutePath(path)
+
+  // Here the first path will be split into its components
+  // on win => [ 'C:', 'Windows', 'System32' ]
+  // on unx => [ '', 'usr'
+  const components = path.split(sep)
+
+  let length = components.length
+  for (const current of paths) {
+    const absolute = resolveAbsolutePath(path, current)
+    const parts = absolute.split(sep)
+    for (let i = 0; i < length; i++) {
+      if (components[i] !== parts[i]) {
+        length = i
+        break
+      }
+    }
+
+    assert(length, 'No common ancestors amongst paths')
+  }
+
+  const common = components.slice(0, length).join(sep)
+  assertAbsolutePath(common)
+  return common
+}
+
+/* ========================================================================== *
+ * FILE CHECKING FUNCTIONS                                                    *
+ * ========================================================================== */
+
+/**
+ * Resolves the specified path as an {@link AbsolutePath} and checks it is a
+ * _file_, returning `undefined` if it is not.
+ */
+export function isFile(path: AbsolutePath, ...paths: string[]): AbsolutePath | undefined {
+  const file = resolveAbsolutePath(path, ...paths)
+  try {
+    const stat = statSync(file)
+    if (stat.isFile()) return file
+  } catch (error: any) {
+    if (error.code !== 'ENOENT') throw error
+  }
+  return undefined
+}
+
+/**
+ * Resolves the specified path as an {@link AbsolutePath} and checks it is a
+ * _directory_, returning `undefined` if it is not.
+ */
+export function isDirectory(path: AbsolutePath, ...paths: string[]): AbsolutePath | undefined {
+  const directory = resolveAbsolutePath(path, ...paths)
+  try {
+    const stat = statSync(directory)
+    if (stat.isDirectory()) return directory
+  } catch (error: any) {
+    if (error.code !== 'ENOENT') throw error
+  }
+  return undefined
+}

package/src/pipe.ts

@@ -0,0 +1,231 @@
+import { assert } from './assert.js'
+import { Files } from './files.js'
+import { Run } from './run.js'
+
+/**
+ * The {@link Plug} interface describes an extension mechanism for our build.
+ */
+export interface Plug<T extends Files | undefined> {
+  pipe(files: Files, run: Run): T | Promise<T>
+}
+
+/**
+ * A type identifying a {@link Plug} as a `function`
+ */
+export type PlugFunction<T extends Files | undefined> = Plug<T>['pipe']
+
+/**
+ * A {@link Pipe} represents a sequence of operations performed by
+ * a series of {@link Plug | Plugs}.
+ */
+export interface Pipe {
+  /* Left empty, for definitions of installed plugs as extensions */
+}
+
+/**
+ * The {@link Pipe} abstract class exposes the prototype upon which all
+ * extension plugs will be installed on.
+ */
+export abstract class Pipe implements Pipe {
+  abstract plug(plug: Plug<Files> | PlugFunction<Files>): Pipe & Promise<Files>
+  abstract plug(plug: Plug<undefined> | PlugFunction<undefined>): Promise<undefined>
+}
+
+
+/** Implementation of our {@link Pipe}. */
+export class PipeImpl<T extends Files | undefined> extends Pipe implements Promise<T> {
+  readonly #promise: Promise<T>
+  readonly #run: Run
+
+  constructor(start: T | Promise<T>, run: Run) {
+    super()
+    this.#promise = Promise.resolve(start)
+    this.#run = run
+  }
+
+  plug<T extends Files | undefined>(arg: Plug<T> | PlugFunction<T>): Pipe & Promise<T> {
+    const plug = typeof arg === 'function' ? { pipe: arg } : arg
+    const promise = this.#promise.then((files) => {
+      assert(files, 'Pipe can not be further extended')
+      return plug.pipe(files, this.#run)
+    })
+    return new PipeImpl(promise, this.#run)
+  }
+
+  then<T1 = T, T2 = never>(
+      onfulfilled?: ((value: T) => T1 | PromiseLike<T1>) | null | undefined,
+      onrejected?: ((reason: any) => T2 | PromiseLike<T2>) | null | undefined,
+  ): Promise<T1 | T2> {
+    return this.#promise.then(onfulfilled, onrejected)
+  }
+
+  catch<T0 = never>(
+      onrejected?: ((reason: any) => T0 | PromiseLike<T0>) | null | undefined,
+  ): Promise<T0 | T> {
+    return this.#promise.catch(onrejected)
+  }
+
+  finally(
+      onfinally?: (() => void) | null | undefined,
+  ): Promise<T> {
+    return this.#promise.finally(onfinally)
+  }
+
+  [Symbol.toStringTag] = 'Pipe'
+}
+
+/* ========================================================================== *
+ * PLUG INSTALLATION (INTERNAL)                                               *
+ * ========================================================================== */
+
+/** The names which can be installed as direct plugs. */
+export type PlugName = string & Exclude<keyof Pipe, 'plug' | keyof Promise<Files>>
+
+/** A convenience type identifying a {@link Plug} constructor. */
+export type PlugConstructor = new (...args: any) => Plug<Files | undefined>
+
+/** Convert the resulting type of a {@link Plug} for use in a {@link Pipe} */
+type PlugReturnForPipe<T> =
+  T extends Plug<infer R> ?
+    R extends Files ?
+      Promise<Files> & Pipe :
+    R extends undefined ?
+      Promise<undefined> :
+    never :
+  never
+
+/**
+ * Map constructors into an array of all known overloads.
+ *
+ * This is a _royal_ pain in the ass, as we need to distinguish between
+ * all possible number of overloads of a constructor... Limit to 5 of them!
+ *
+ * Also, the empty constructor (when specified in the overloads) will simply
+ * match the first case (most overloads) and generate functions somewhat like
+ *
+ * (...args: unknown[]) => never
+ * (...args: unknown[]) => never
+ * (...args: unknown[]) => never
+ * () => PlugReturnForPipe<R3>
+ * (arg: Options) => PlugReturnForPipe<R4>
+ *
+ * Somehow inferring the result to `Function` or the right type and ANDing all
+ * those together here doesn't work, so we create this array and we'll AND
+ * all its members in the PipeExtension<...> type.
+ */
+type PlugConstructorOverloads<T extends PlugConstructor> =
+  T extends {
+    new (...args: infer A0): infer R0
+    new (...args: infer A1): infer R1
+    new (...args: infer A2): infer R2
+    new (...args: infer A3): infer R3
+    new (...args: infer A4): infer R4
+  } ? [
+    R0 extends Plug<Files | undefined> ? ((...args: A0) => PlugReturnForPipe<R0>) : Function,
+    R1 extends Plug<Files | undefined> ? ((...args: A1) => PlugReturnForPipe<R1>) : Function,
+    R2 extends Plug<Files | undefined> ? ((...args: A2) => PlugReturnForPipe<R2>) : Function,
+    R3 extends Plug<Files | undefined> ? ((...args: A3) => PlugReturnForPipe<R3>) : Function,
+    R4 extends Plug<Files | undefined> ? ((...args: A4) => PlugReturnForPipe<R4>) : Function,
+  ] :
+  T extends {
+    new (...args: infer A0): infer R0
+    new (...args: infer A1): infer R1
+    new (...args: infer A2): infer R2
+    new (...args: infer A3): infer R3
+  } ? [
+    R0 extends Plug<Files | undefined> ? (...args: A0) => PlugReturnForPipe<R0> : Function,
+    R1 extends Plug<Files | undefined> ? (...args: A1) => PlugReturnForPipe<R1> : Function,
+    R2 extends Plug<Files | undefined> ? (...args: A2) => PlugReturnForPipe<R2> : Function,
+    R3 extends Plug<Files | undefined> ? (...args: A3) => PlugReturnForPipe<R3> : Function,
+  ] :
+  T extends {
+    new (...args: infer A0): infer R0
+    new (...args: infer A1): infer R1
+    new (...args: infer A2): infer R2
+  } ? [
+    R0 extends Plug<Files | undefined> ? (...args: A0) => PlugReturnForPipe<R0> : Function,
+    R1 extends Plug<Files | undefined> ? (...args: A1) => PlugReturnForPipe<R1> : Function,
+    R2 extends Plug<Files | undefined> ? (...args: A2) => PlugReturnForPipe<R2> : Function,
+  ] :
+  T extends {
+    new (...args: infer A0): infer R0
+    new (...args: infer A1): infer R1
+  } ? [
+    R0 extends Plug<Files | undefined> ? (...args: A0) => PlugReturnForPipe<R0> : Function,
+    R1 extends Plug<Files | undefined> ? (...args: A1) => PlugReturnForPipe<R1> : Function,
+  ] :
+  T extends {
+    new (...args: infer A0): infer R0
+  } ? [
+    R0 extends Plug<Files | undefined> ? (...args: A0) => PlugReturnForPipe<R0> : Function,
+  ] :
+  never
+
+/**
+ * A convenience type to easily annotate installed {@link Plug Plugs}.
+ *
+ * See also {@link install}.
+ *
+ * ```
+ * export class Write implements Plug {
+ *   // ... the plug implementation lives here
+ * }
+ *
+ * install('write', Write)
+ *
+ * declare module '../pipe' {
+ *   export interface Pipe {
+ *     write: PipeExtension<typeof Write>
+ *   }
+ * }
+ * ```
+ */
+export type PipeExtension<T extends PlugConstructor, A = PlugConstructorOverloads<T>> =
+  A extends readonly [ infer First, ...infer Rest ] ?
+    First & PipeExtension<T, Rest> :
+  A extends readonly [ infer Only ] ?
+    Only :
+  Function
+
+/**
+ * Install a {@link Plug} into our {@link Pipe} prototype, and return a static
+ * creator function for the {@link Plug} itself.
+ *
+ * This allows our shorthand syntax for well-defined plugs such as:
+ *
+ * ```
+ * find('./src', '*.ts').write('./target')
+ * // Nicer and easier than...
+ * find('./src', '*.ts').plug(new Write('./target'))
+ * ```
+ *
+ * Use this alongside interface merging like:
+ *
+ * ```
+ * export class Write implements Plug {
+ *   // ... the plug implementation lives here
+ * }
+ *
+ * install('write', Write)
+ *
+ * declare module '../pipe' {
+ *   export interface Pipe {
+ *     write: PipeExtension<typeof Write>
+ *   }
+ * }
+ * ```
+ */
+export function install<C extends PlugConstructor>(name: PlugName, ctor: C): void {
+  /* This is quite hairy when it comes to types, so, just give up! :-P */
+
+  function create(this: Pipe, ...args: any): Pipe & Promise<Files | undefined> {
+    // eslint-disable-next-line new-cap
+    return this.plug(new ctor(...args) as any)
+  }
+
+  /* Setup name so that stack traces look better */
+  Object.defineProperty(create, 'name', { value: name })
+
+  /* Inject the create function in the Pipe's prototype */
+  Object.defineProperty(Pipe.prototype, name, { value: create })
+}

package/src/plugs/copy.ts

@@ -0,0 +1,113 @@
+import fs from '../utils/asyncfs.js'
+
+import { assert } from '../assert.js'
+import { Files } from '../files.js'
+import { $p } from '../log.js'
+import { assertAbsolutePath, getAbsoluteParent, resolveAbsolutePath } from '../paths.js'
+import { install, Plug } from '../pipe.js'
+import { Run } from '../run.js'
+
+/** Options for copying files */
+export interface CopyOptions {
+  /** Whether to allow overwriting or not (default `false`). */
+  overwrite?: boolean,
+  /** If specified, use this `mode` (octal string) when creating files. */
+  mode?: string | number,
+  /** If specified, use this `mode` (octal string) when creating directories. */
+  dirMode?: string | number,
+  /** If specified, this function will be invoked to rename files. */
+  rename?: (relative: string) => string
+}
+
+/** Copy the curent {@link Files} to a different directory */
+export class Copy implements Plug<Files> {
+  constructor(directory: string, options?: CopyOptions)
+  constructor(
+      private readonly _directory: string,
+      private readonly _options: CopyOptions = {},
+  ) {}
+
+  async pipe(files: Files, run: Run): Promise<Files> {
+    /* Destructure our options with some defaults and compute write flags */
+    const { mode, dirMode, overwrite, rename = (s): string => s } = this._options
+    const flags = overwrite ? fs.constants.COPYFILE_EXCL : 0
+    const dmode = parseMode(dirMode)
+    const fmode = parseMode(mode)
+
+    /* Our files builder for all written files */
+    const builder = run.files(this._directory)
+
+    /* Iterate through all the mappings of the source files */
+    for (const [ relative, absolute ] of files.pathMappings()) {
+      /* The target absolute is the (possibly) renamed relative source file
+       * relocated to the the target directory */
+      const target = resolveAbsolutePath(builder.directory, rename(relative))
+
+      /* We never copy a file onto itself, but not fail either */
+      if (target === absolute) {
+        run.log.warn('Cowardly refusing to copy same file', $p(absolute))
+        continue
+      }
+
+      /* Create the parent directory, recursively */
+      const directory = getAbsoluteParent(target)
+      const firstParent = await fs.mkdir(directory, { recursive: true })
+
+      /* Set the mode for all created directories */
+      if (firstParent && (dmode !== undefined)) {
+        assertAbsolutePath(firstParent)
+        for (let dir = directory; ; dir = getAbsoluteParent(dir)) {
+          run.log.trace(`Setting mode ${stringifyMode(dmode)} for directory`, $p(dir))
+          await fs.chmod(dir, dmode)
+          if (dir === firstParent) break
+        }
+      }
+
+      /* Actually _copy_ the file */
+      run.log.trace(`Copying "${$p(absolute)}" to "${$p(target)}"`)
+      await fs.copyFile(absolute, target, flags)
+
+      /* Set the mode, if we need to */
+      if (fmode !== undefined) {
+        run.log.trace(`Setting mode ${stringifyMode(fmode)} for file`, $p(target))
+        await fs.chmod(target, fmode)
+      }
+
+      /* Record this file */
+      builder.add(relative)
+    }
+
+    const result = builder.build()
+    run.log.info('Copied', result.length, 'files to', $p(builder.directory))
+    return result
+  }
+}
+
+/* ========================================================================== *
+ * INSTALLATION                                                               *
+ * ========================================================================== */
+
+install('copy', Copy)
+
+declare module '../pipe.js' {
+  export interface Pipe {
+    /** Copy the curent {@link Files} to a different directory */
+    copy: PipeExtension<typeof Copy>
+  }
+}
+
+/* ========================================================================== *
+ * INTERNALS                                                                  *
+ * ========================================================================== */
+
+function parseMode(mode: string | number | undefined): number | undefined {
+  if (mode === undefined) return undefined
+  if (typeof mode === 'number') return mode
+  const parsed = parseInt(mode, 8)
+  assert(! isNaN(parsed), `Invalid mode "${mode}"`)
+  return parsed
+}
+
+function stringifyMode(mode: number): string {
+  return mode.toString(8).padStart(4, '0')
+}