@plugjs/plug 0.0.1

package/src/utils/match.ts

@@ -0,0 +1,286 @@
+import picomatch from 'picomatch'
+
+export interface MatchResult {
+  /** The glob that matched this `MatchResult` */
+  glob: string;
+  /** The regular expression that matched this `MatchResult` */
+  regex: RegExp;
+  /** The input string of this `MatchResult` */
+  input: string;
+  /** The input string of this `MatchResult` */
+  output: string;
+  /** The match result of this instance, if any */
+  match?: boolean | RegExpExecArray | null;
+  /** Whether the string matched or not */
+  isMatch: boolean;
+}
+
+export interface MatchOptions {
+  /**
+   * If set, then patterns without slashes will be matched against the basename
+   * of the path if it contains slashes.
+   *
+   * For example, `a?b` would match the path `/xyz/123/acb`, but not
+   * `/xyz/acb/123`.
+   *
+   * @defaultValue `false`
+   */
+  basename?: boolean,
+
+  /**
+   * Follow bash matching rules more strictly - disallows backslashes as escape
+   * characters, and treats single stars as globstars (`**`).
+   *
+   * @defaultValue `false`
+   */
+  bash?: boolean,
+
+  /**
+   * Return regex matches in `onIgnore(..)`, `onMatch(..)` and `onResult(..)`.
+   *
+   * @defaultValue `false`
+   */
+  capture?: boolean,
+
+  /**
+   * Allows glob to match any part of the given string(s).
+   *
+   * @defaultValue `false`
+   */
+  contains?: boolean,
+
+  /**
+   * Debug regular expressions when an error is thrown.
+   *
+   * @defaultValue `false`
+   */
+  debug?: boolean,
+
+  /**
+   * Enable dotfile matching.
+   *
+   * By default, dotfiles are ignored unless a `.` is explicitly defined in
+   * the pattern, or this option is `true`.
+   *
+   * @defaultValue `false`
+   */
+  dot?: boolean,
+
+  /**
+   * Custom function for expanding ranges in brace patterns, such as `{a..z}`.
+   *
+   * The function receives the range values as two arguments, and it must
+   * return a string to be used in the generated regex.
+   *
+   * It's recommended that returned strings be wrapped in parentheses.
+   *
+   * @defaultValue `undefined`
+   */
+  expandRange?: (a: string, b: string) => string,
+
+  /**
+   * To speed up processing, full parsing is skipped for a handful common glob
+   * patterns.
+   *
+   * Disable this behavior by setting this option to `false`.
+   *
+   * @defaultValue `true`
+   */
+  fastpaths?: boolean,
+
+  /**
+   * Regex flags to use in the generated regex.
+   *
+   * If defined, the nocase option will be overridden.
+   *
+   * @defaultValue `undefined`
+   */
+  flags?: string,
+
+  /**
+   * One or more glob patterns for excluding strings that should not be matched
+   * from the result.
+   *
+   * @defaultValue  `undefined`
+   */
+  ignore?: string | string[],
+
+  /**
+   * Retain quotes in the generated regular expressions, since quotes may also
+   * be used as an alternative to backslashes.
+   *
+   * @defaultValue `false`
+   */
+  keepQuotes?: boolean,
+
+  /**
+   * When `true`, brackets in the glob pattern will be escaped so that only
+   * literal brackets will be matched.
+   *
+   * @defaultValue `false`
+   */
+  literalBrackets?: boolean,
+
+  /**
+   * Disable brace matching, so that `{a,b}` and `{1..3}` would be treated as
+   * literal characters.
+   *
+   * @defaultValue `false`
+   */
+  nobrace?: boolean,
+
+  /**
+   * Disable matching with regex brackets.
+   *
+   * @defaultValue `false`
+   */
+  nobracket?: boolean,
+
+  /**
+   * Make matching case-insensitive (equivalent to the regex `i` flag).
+   *
+   * Note that this option is overridden by the flags option.
+   *
+   * @defaultValue `false`
+   */
+  nocase?: boolean,
+
+  /**
+   * Disable support for matching with extglobs (like `+(a|b)`).
+   *
+   * @defaultValue `false`
+   */
+  noextglob?: boolean,
+
+  /**
+   * Disable support for matching nested directories with globstars (`**`).
+   *
+   * @defaultValue `false`
+   */
+  noglobstar?: boolean,
+
+  /**
+   * Disable support for negating with leading `!`.
+   *
+   * @defaultValue `false`
+   */
+  nonegate?: boolean,
+
+  /**
+   * Disable support for regex quantifiers (like `a{1,2}`) and treat them as
+   * brace patterns to be expanded.
+   *
+   * @defaultValue `false`
+   */
+  noquantifiers?: boolean,
+
+  /**
+   * Function to be called on ignored items.
+   *
+   * @defaultValue `undefined`
+   */
+  onIgnore?: (result: MatchResult) => void,
+
+  /**
+   * Function to be called on matched items.
+   *
+   * @defaultValue `undefined`
+   */
+  onMatch?: (result: MatchResult) => void,
+
+  /**
+   * Function to be called on all items, regardless of whether or not they
+   * are matched or ignored.
+   *
+   * @defaultValue `undefined`
+   */
+  onResult?: (result: MatchResult) => void,
+
+  /**
+   * Support POSIX character classes ("posix brackets").
+   *
+   * @defaultValue `false`
+   */
+  posix?: boolean,
+
+  // /**
+  //  * String to prepend to the generated regex used for matching.
+  //  *
+  //  * @defaultValue `undefined`
+  //  */
+  // prepend?: string,
+
+  /**
+   * Use regular expression rules for `+` (instead of matching literal `+`),
+   * and for stars that follow closing parentheses or brackets (as in `)*`
+   * and `]*`).
+   *
+   * @defaultValue `false`
+   */
+  regex?: boolean,
+
+  /**
+   * Throw an error if brackets, braces, or parens are imbalanced.
+   *
+   * @defaultValue `false`
+   */
+  strictBrackets?: boolean,
+
+  /**
+   * When true, picomatch won't match trailing slashes with single stars.
+   *
+   * @defaultValue `false`
+   */
+  strictSlashes?: boolean,
+
+  /**
+   * Remove backslashes preceding escaped characters in the glob pattern.
+   *
+   * By default, backslashes are retained.
+   *
+   * @defaultValue `false`
+   */
+  unescape?: boolean,
+}
+
+/** A _function_ matching a string. */
+export type Matcher = (string: string) => boolean
+
+/**
+ * Create a {@link Matcher} according to the globs and options specified.
+ *
+ * Remember that no globs here means an always-failing matcher.
+ */
+export function match(globs: readonly string[], options: MatchOptions = {}): Matcher {
+  return picomatch([ ...globs ], {
+    basename: false,
+    bash: false,
+    capture: false,
+    contains: false,
+    debug: false,
+    dot: false,
+    expandRange: undefined,
+    fastpaths: true,
+    flags: undefined,
+    ignore: undefined,
+    keepQuotes: false,
+    literalBrackets: false,
+    nobrace: false,
+    nobracket: false,
+    nocase: false,
+    noextglob: false,
+    noglobstar: false,
+    nonegate: false,
+    noquantifiers: false,
+    onIgnore: undefined,
+    onMatch: undefined,
+    onResult: undefined,
+    posix: false,
+    // prepend: undefined,
+    regex: false,
+    strictBrackets: false,
+    strictSlashes: false,
+    unescape: false,
+    ...options,
+  })
+}

package/src/utils/options.ts

@@ -0,0 +1,22 @@
+export type ParsedOptions<Options> = { params: string[], options: Options }
+export type ParsedOptionalOptions<Options> = { params: string[], options?: Options | undefined }
+export type ParseOptions<Options> = string[] | [ ...string[], Options ] | [ Options ]
+
+/** Parse an array of at least one string, followed by an optional `Options` argument. */
+export function parseOptions<Options>(args: ParseOptions<Options>): ParsedOptionalOptions<Options>
+/** Parse an array of at least one string, followed by an optional `Options` argument. */
+export function parseOptions<Options>(args: ParseOptions<Options>, defaults?: undefined): ParsedOptionalOptions<Options>
+/** Parse an array of at least one string, followed by an optional `Options` argument, ensuring some defaults are present. */
+export function parseOptions<Options, Defaults extends Options>(args: ParseOptions<Options>, defaults: Defaults): ParsedOptions<Options & Defaults>
+// overloaded implementation
+export function parseOptions<Options, Defaults extends Options>(args: ParseOptions<Options>, defaults?: Defaults): ParsedOptions<any> {
+  const params: string[] = []
+  const options: any = { ...defaults }
+
+  for (const arg of args) {
+    if (typeof arg === 'string') params.push(arg)
+    else Object.assign(options, arg)
+  }
+
+  return { params, options }
+}

package/src/utils/walk.ts

@@ -0,0 +1,136 @@
+import { basename, join } from 'node:path'
+import { $p, log } from '../log.js'
+import { AbsolutePath, resolveAbsolutePath } from '../paths.js'
+import { readdir, stat } from './asyncfs.js'
+import { match, MatchOptions } from './match.js'
+
+/** Specific options for walking a directory */
+export interface WalkOptions extends MatchOptions {
+  /**
+   * Whether symlinks should be followed or not.
+   *
+   * @defaultValue `true`
+   */
+  followSymlinks?: boolean,
+
+  /**
+   * The maximum depth (in directory levels) to recurse into.
+   *
+   * @defaultValue `Infinity`
+   */
+  maxDepth?: number,
+
+  /**
+   * Whether to allow walking any `node_modules` directory or not.
+   *
+   * @defaultValue `false`
+   */
+  allowNodeModules?: boolean,
+}
+
+/**
+ * Walk the specified directory, returning an asynchronous iterator over all
+ * the _relative_ files found matching the specified globs and matching options.
+ */
+export function walk(
+    directory: AbsolutePath,
+    globs: string[],
+    options: WalkOptions = {},
+): AsyncGenerator<string, void, void> {
+  const {
+    maxDepth = Infinity,
+    followSymlinks = true,
+    allowNodeModules = false,
+    ...opts
+  } = options
+
+  /* Make sure to also ignore node modules or dot directories if we have to */
+  const onDirectory = (dir: AbsolutePath): boolean => {
+    // if we were told to start looking into "node_modules", or in a directory
+    // starting with ".", then we ignore any whatsoever option here!
+    if (dir === directory) return true
+    const name = basename(dir)
+    if (name === 'node_modules') return !!allowNodeModules
+    if (name.startsWith('.')) return !!opts.dot
+    return true
+  }
+
+  /* Create our positive matcher to match our globs */
+  const positiveMatcher = match(globs, opts)
+
+  /* Do the walk! */
+  log.debug('Walking directory', $p(directory), { globs, options })
+  return walker({
+    directory,
+    relative: '',
+    matcher: positiveMatcher,
+    onDirectory,
+    followSymlinks,
+    maxDepth,
+    depth: 0,
+  })
+}
+
+/* ========================================================================== *
+ * INTERNALS                                                                  *
+ * ========================================================================== */
+
+interface WalkerArguments {
+  directory: AbsolutePath,
+  relative: string,
+  matcher: (path: string) => boolean,
+  onDirectory: (directory: AbsolutePath) => boolean,
+  followSymlinks: boolean,
+  maxDepth: number,
+  depth: number,
+}
+
+/* Walk a directory and yield matching results until the given `maxDepth` */
+async function* walker(args: WalkerArguments): AsyncGenerator<string, void, void> {
+  const {
+    directory,
+    relative,
+    matcher: positiveMatcher,
+    onDirectory,
+    followSymlinks,
+    maxDepth,
+    depth,
+  } = args
+
+  /* Read the directory, including file types */
+  const dir = resolveAbsolutePath(directory, relative)
+  if (! onDirectory(dir)) return
+  log.trace('Reading directory', $p(dir))
+  const dirents = await readdir(dir, { withFileTypes: true }).catch((error) => {
+    if (error.code !== 'ENOENT') throw error
+    log.warn('Directory', $p(dir), 'not found')
+    return []
+  })
+
+  /* For each entry we determine the full path */
+  for (const dirent of dirents) {
+    const path = join(relative, dirent.name)
+
+    /* If the entry is a file and matches, yield it */
+    if (dirent.isFile() && positiveMatcher(path)) yield path
+
+    /* If the entry is a directory within our depth, walk it recursively */
+    else if (dirent.isDirectory() && (depth < maxDepth)) {
+      const children = walker({ ...args, relative: path, depth: depth + 1 })
+      for await (const child of children) yield child
+
+    /* If this is a symlink and we're told to check them let's see what we have */
+    } else if (dirent.isSymbolicLink() && followSymlinks) {
+      const info = await stat(join(directory, path))
+
+      /* If the link is a file and matches, yield it */
+      if (info.isFile() && positiveMatcher(path)) yield path
+
+      /* If the link is a directory within our depth, walk it recursively */
+      else if (info.isDirectory() && (depth < maxDepth)) {
+        const children = walker({ ...args, relative: path, depth: depth + 1 })
+        for await (const child of children) yield child
+      }
+    }
+  }
+}

package/types/assert.d.ts

@@ -0,0 +1,18 @@
+/** Check if the specified argument is a {@link BuildError} */
+export declare function isBuildError(arg: any): arg is BuildError;
+/** Check if the specified argument is a {@link BuildFailure} */
+export declare function isBuildFailure(arg: any): arg is BuildFailure;
+/** An error produced in our build, with proper inspection for logging */
+export declare class BuildError extends Error {
+    constructor(message: string);
+}
+/** A {@link BuildFailure} represents an error _already logged_ in our build. */
+export declare class BuildFailure extends Error {
+    constructor();
+}
+/** Asserts something as _truthy_ and fail the build if not */
+export declare function assert(assertion: any, message: string): asserts assertion;
+/** Throw a {@link BuildError} (an {@link Error} printed nicely) */
+export declare function fail(message: string): never;
+/** Return a non-logged {@link BuildFailure} */
+export declare function failure(): BuildFailure;

package/types/async.d.ts

@@ -0,0 +1,20 @@
+import { Run } from './run.js';
+/**
+ * Run the specified `callback` associating the specified {@link Run} and task
+ * name with the current asynchronous invocation context.
+ */
+export declare function runAsync<T>(run: Run, task: string, callback: () => Promise<T>): Promise<T>;
+/**
+ * Returns the _task name_ associated with the current asynchronous invocation
+ * context or `undefined`.
+ */
+export declare function currentTask(): string | undefined;
+/**
+ * Returns the {@link Run} associated with the current asynchronous invocation
+ * context or `undefined`.
+ */
+export declare function currentRun(): Run | undefined;
+/**
+ * Return an array of all _task names_ currently running
+ */
+export declare function runningTasks(): string[];

package/types/build.d.ts

@@ -0,0 +1,56 @@
+import { Files } from './files.js';
+import { AbsolutePath } from './paths.js';
+import { Pipe } from './pipe.js';
+import { Run } from './run.js';
+import { Task } from './task.js';
+/**
+ * The {@link BuildContext} interface exposes the _internal_ representation of
+ * a build file, including all {@link Task | Tasks}.
+ */
+export declare type BuildContext = {
+    /** The absolute file name of the build */
+    readonly buildFile: AbsolutePath;
+    /** For convenience, the directory of the build file */
+    readonly buildDir: AbsolutePath;
+    /** A record of all tasks keyed by name */
+    readonly tasks: Readonly<Record<string, Task>>;
+};
+/**
+ * A {@link TaskDefinition} is a _function_ defining a {@link Task}.
+ */
+export declare type TaskDefinition<B> = (this: ThisBuild<B>, self: ThisBuild<B>, run: Run) => Files | undefined | void | Promise<Files | undefined | void>;
+/**
+ * A {@link TaskCall} describes a _function_ calling a {@link Task}, and
+ * it is exposed to outside users of the {@link Build}.
+ */
+export declare type TaskCall<T extends Files | undefined> = ((run?: Run) => Promise<Run>) & {
+    readonly task: Task<T>;
+};
+/**
+ * A {@link Build} is a collection of {@link TaskCall | TaskCalls}, as produced
+ * by the {@link build} function from a {@link BuildDefinition}.
+ */
+export declare type Build<B> = {
+    [K in keyof B]: B[K] extends TaskCall<infer T> ? TaskCall<T> : B[K] extends () => Files | Promise<Files> ? TaskCall<Files> : B[K] extends () => undefined | void | Promise<undefined | void> ? TaskCall<undefined> : never;
+};
+/**
+ * The type supplied as `this` to a {@link TaskDefinition} when invoking it.
+ */
+export declare type ThisBuild<B> = {
+    [K in keyof B]: B[K] extends () => Files | Promise<Files> ? () => Pipe & Promise<Files> : B[K] extends () => undefined | void | Promise<undefined | void> ? () => Promise<undefined> : never;
+};
+/**
+ * A {@link BuildDefinition} is a collection of
+ * {@link TaskDefinition | TaskDefinitions} that the {@link build} function will
+ * use to create a {@link Build}.
+ *
+ * A {@link BuildDefinition} can also include other {@link TaskCall | TaskCalls},
+ * thus giving the ability to extend other {@link Build | Builds}.
+ */
+export declare type BuildDefinition<B> = {
+    [K in keyof B]: TaskDefinition<B> | TaskCall<Files | undefined>;
+};
+/** Check if the specified build is actually a {@link Build} */
+export declare function isBuild(build: any): build is Build<any>;
+/** Create a new {@link Build} from its {@link BuildDefinition}. */
+export declare function build<D extends BuildDefinition<D>>(definition: D & ThisType<ThisBuild<D>>): Build<D>;

package/types/files.d.ts

@@ -0,0 +1,44 @@
+/// <reference types="node" resolution-mode="require"/>
+/// <reference types="node" resolution-mode="require"/>
+import { inspect } from 'node:util';
+import { AbsolutePath } from './paths.js';
+/** The {@link FilesBuilder} interface defines a builder for {@link Files}. */
+export interface FilesBuilder {
+    /** The (resolved) directory the {@link Files} will be associated with */
+    readonly directory: AbsolutePath;
+    /** Push files into the {@link Files} instance being built */
+    add(...files: string[]): this;
+    /** Merge orther {@link Files} instance to the {@link Files} being built */
+    merge(...files: Files[]): this;
+    /** Write a file and add it to the {@link Files} instance being built */
+    write(file: string, content: string | Buffer): Promise<AbsolutePath>;
+    /** Build and return a {@link Files} instance */
+    build(): Files;
+}
+/**
+ * The {@link Files} class represents a collection of relative path names
+ * identifying some _files_ rooted in a given _directory_.
+ */
+export declare class Files {
+    readonly _directory: AbsolutePath;
+    readonly _files: string[];
+    /**
+     * Create a new {@link Files} instance rooted in the specified `directory`
+     * relative to the specified {@link Run}'s directory.
+     */
+    constructor(directory: AbsolutePath);
+    /** Return the _directory_ where this {@link Files} is rooted */
+    get directory(): AbsolutePath;
+    /** Return the number of files tracked by this instance. */
+    get length(): number;
+    /** Return an iterator over all _relative_ files of this instance */
+    [Symbol.iterator](): Generator<string>;
+    /** Return an iterator over all _absolute_ files of this instance */
+    absolutePaths(): Generator<AbsolutePath>;
+    /** Return an iterator over all _relative_ to _absolute_ mappings */
+    pathMappings(): Generator<[relative: string, absolute: AbsolutePath]>;
+    [inspect.custom](): any;
+    /** Create a new {@link FilesBuilder} creating {@link Files} instances. */
+    static builder(files: Files): FilesBuilder;
+    static builder(directory: AbsolutePath): FilesBuilder;
+}

package/types/fork.d.ts

@@ -0,0 +1,57 @@
+import { Files } from './files.js';
+import { LogOptions } from './log.js';
+import { AbsolutePath } from './paths.js';
+import { Plug, PlugName } from './pipe.js';
+import { Run } from './run.js';
+/** Fork data, from parent to child process */
+export interface ForkData {
+    /** Script name for the Plug to execute */
+    scriptFile: AbsolutePath;
+    /** Plug constructor arguments */
+    constructorArgs: any[];
+    /** Task name (for logs) */
+    taskName: string;
+    /** Build file name */
+    buildFile: AbsolutePath;
+    /** Build directory */
+    buildDir: AbsolutePath;
+    /** Files directory */
+    filesDir: AbsolutePath;
+    /** All files to pipe */
+    filesList: AbsolutePath[];
+    /** Options for our logger in the child process */
+    logOpts: Partial<LogOptions>;
+}
+/** Fork result, from child to parent process */
+export interface ForkResult {
+    /** If this is `true` we _might_ have `filesDir` and `filesList` */
+    failed: boolean;
+    /** Files directory of the result */
+    filesDir?: AbsolutePath | undefined;
+    /** All files returned by the plug */
+    filesList?: AbsolutePath[] | undefined;
+}
+/**
+ * Install a _forking_ {@link Plug} in the {@link Pipe}, in other words
+ * execute the plug in a separate process.
+ *
+ * As a contract, if the _last non-null_ parameter of the constructor is an
+ * object and contains the key `coverageDir`, the process will be forked with
+ * the approptiately resolved `NODE_V8_COVERAGE` environment variable.
+ *
+ * Also, forking plugs require some special attention:
+ *
+ * * plug functions are not supported, only classes implementing the
+ *   {@link Plug} interface can be used with this.
+ *
+ * * the class itself _MUST_ be exported as the _default_ export for the
+ *   `scriptFile` specified below. This is to simplify interoperability between
+ *   CommonJS and ESM modules as we use dynamic `import(...)` statements.
+ */
+export declare function installForking(plugName: PlugName, scriptFile: AbsolutePath): void;
+export declare abstract class ForkingPlug implements Plug<Files | undefined> {
+    private readonly _scriptFile;
+    private readonly _arguments;
+    constructor(_scriptFile: AbsolutePath, _arguments: any[]);
+    pipe(files: Files, run: Run): Promise<Files | undefined>;
+}

package/types/helpers.d.ts

@@ -0,0 +1,49 @@
+import { Files, FilesBuilder } from './files.js';
+import { LogLevelString } from './log.js';
+import { AbsolutePath } from './paths.js';
+import { Pipe } from './pipe.js';
+import { FindOptions } from './run.js';
+import { ParseOptions } from './utils/options.js';
+/**
+ * Recursively remove the specified directory _**(use with care)**_.
+ */
+export declare function rmrf(directory: string): Promise<void>;
+/**
+ * Set the current _log level_.
+ *
+ * The _level_ will be applied _only_ within the execution of the current task.
+ */
+export declare function setLogLevel(level: LogLevelString): void;
+/**
+ * Resolve a path into an {@link AbsolutePath}.
+ *
+ * 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.
+ */
+export declare function resolve(...paths: string[]): AbsolutePath;
+/**
+ * Create a new {@link Files} instance.
+ */
+export declare function files(files: Files): FilesBuilder;
+export declare function files(...paths: string[]): FilesBuilder;
+/**
+ * Merge multiple {@link Files} instance.
+ */
+export declare function merge(args: (Files | Promise<Files>)[]): Promise<Files> & Pipe;
+/**
+ * Find files according to the globs and {@link FindOptions} specified.
+ */
+export declare function find(glob: string, ...args: ParseOptions<FindOptions>): Pipe & Promise<Files>;
+/** Create a {@link Pipe} from a {@link Files} instance. */
+export declare function pipe(files: Files | Promise<Files>): Pipe & Promise<Files>;
+/** Await for the settlement of all the promises, then return their results. */
+export declare function parallel<P extends readonly any[]>(promises: P): Promise<ParallelResult<P>>;
+declare type ParallelResult<T extends readonly any[]> = T extends readonly [infer First, ...infer Rest] ? [
+    Awaited<First>,
+    ...ParallelResult<Rest>
+] : T extends readonly [infer Only] ? [
+    Awaited<Only>
+] : T extends readonly [] ? [
+] : never;
+export {};