@plugjs/plug 0.0.1

package/types/plugs/coverage/report.d.ts

@@ -0,0 +1,53 @@
+import { Logger } from '../../log.js';
+import { AbsolutePath } from '../../paths.js';
+import { CoverageAnalyser } from './analysis.js';
+/**
+ * A constant indicating that coverage was skipped (is irrelevant, for e.g.
+ * comment or typescript definition nodes)
+ */
+export declare const COVERAGE_SKIPPED = -2;
+/**
+ * A constant indicating that coverage was intentionally ignored because of a
+ * specific "coverage ignore ..." comment
+ */
+export declare const COVERAGE_IGNORED = -1;
+/** Node coverage summary */
+export interface NodeCoverageResult {
+    /** Number of _covered_ nodes (good!) */
+    coveredNodes: number;
+    /** Number of nodes with _no coverage_ (bad!) */
+    missingNodes: number;
+    /** Number of nodes ignored by comments like `coverage ignore xxx` */
+    ignoredNodes: number;
+    /** Total number of nodes (sum of `covered`, `missing` and `ignored`) */
+    totalNodes: number;
+    /** Percentage of code coverage (covered as a % of total - ignored nodes)*/
+    coverage: number;
+}
+/** Per-file coverage result */
+export interface CoverageResult {
+    /** The actual code this coverage is for */
+    code: string;
+    /**
+     * Per _character_ coverage report:
+     * - `-2`: coverage skipped (comments, typescript declarations, ...)
+     * - `-1`: coverage ignored (when using `coverage ignore xxx`)
+     * - `0`: no coverage collected for this character
+     * - _any number greater than zero_: number of times this was covered
+     */
+    codeCoverage: number[];
+    /** Node coverage summary */
+    nodeCoverage: NodeCoverageResult;
+}
+/** Aggregation of {@link CoverageResult} over all files */
+export declare type CoverageResults = Record<AbsolutePath, CoverageResult>;
+/** Our coverage report, per file */
+export interface CoverageReport {
+    results: CoverageResults;
+    nodes: NodeCoverageResult;
+}
+/**
+ * Analyse coverage for the specified source files, using the data from the
+ * specified coverage files and produce a {@link CoverageReport}.
+ */
+export declare function coverageReport(analyser: CoverageAnalyser, sourceFiles: AbsolutePath[], log: Logger): Promise<CoverageReport>;

package/types/plugs/coverage.d.ts

@@ -0,0 +1,46 @@
+import { Files } from '../files.js';
+import { Plug } from '../pipe.js';
+import { Run } from '../run.js';
+import { SourceMapBias } from './coverage/analysis.js';
+/** 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) */
+    minimumCoverage?: number;
+    /** Optimal _overall_ coverage (as a percentage)  */
+    optimalCoverage?: number;
+    /** Minimum _per-file_ coverage (as a percentage) */
+    minimumFileCoverage?: number;
+    /** Optimal _per-file_ coverage (as a percentage) */
+    optimalFileCoverage?: number;
+}
+export interface CoverageReportOptions extends CoverageOptions {
+    /** If specified, a JSON and HTML report will be written to this directory */
+    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`...
+ */
+declare type CoverageConstructor = {
+    new (coverageDir: string): Coverage<CoverageOptions>;
+    new (coverageDir: string, options: CoverageOptions): Coverage<CoverageOptions>;
+    new (coverageDir: string, options: CoverageReportOptions): Coverage<CoverageReportOptions>;
+};
+/** Analyse coverage using files generated by V8/NodeJS. */
+export declare class Coverage<T extends CoverageOptions | CoverageReportOptions> implements Plug<T extends CoverageReportOptions ? Files : undefined> {
+    private readonly _coverageDir;
+    private readonly _options;
+    constructor(coverageDir: string);
+    constructor(coverageDir: string, options?: T);
+    pipe(files: Files, run: Run): Promise<T extends CoverageReportOptions ? Files : undefined>;
+}
+declare module '../pipe.js' {
+    interface Pipe {
+        /** Analyse coverage using files generated by V8/NodeJS. */
+        coverage: PipeExtension<CoverageConstructor>;
+    }
+}
+export {};

package/types/plugs/debug.d.ts

@@ -0,0 +1,14 @@
+import { Files } from '../files.js';
+import { Plug } from '../pipe.js';
+import { Run } from '../run.js';
+/** Writes some info about the current {@link Files} being passed around. */
+export declare class Debug implements Plug<Files> {
+    constructor();
+    pipe(files: Files, run: Run): Promise<Files>;
+}
+declare module '../pipe.js' {
+    interface Pipe {
+        /** Writes some info about the current {@link Files} being passed around. */
+        debug: PipeExtension<typeof Debug>;
+    }
+}

package/types/plugs/esbuild/bundle-locals.d.ts

@@ -0,0 +1,6 @@
+import { Plugin } from 'esbuild';
+/**
+ * A simple ESBuild plugin bundling _only_ local files, and marking anything
+ * imported from `node_modules` as _external_.
+ */
+export declare function bundleLocals(): Plugin;

package/types/plugs/esbuild/check-dependencies.d.ts

@@ -0,0 +1,12 @@
+import { Plugin } from 'esbuild';
+export interface CheckDependenciesOptions {
+    allowDev?: boolean | 'warn' | 'error';
+    allowPeer?: boolean | 'warn' | 'error';
+    allowOptional?: boolean | 'warn' | 'error';
+    allowUnused?: boolean | 'warn' | 'error';
+    ignored?: string[];
+}
+export declare function checkDependencies(): Plugin;
+export declare function checkDependencies(packageJson: string): Plugin;
+export declare function checkDependencies(options: CheckDependenciesOptions): Plugin;
+export declare function checkDependencies(packageJson: string, options: CheckDependenciesOptions): Plugin;

package/types/plugs/esbuild/fix-extensions.d.ts

@@ -0,0 +1,29 @@
+import { Plugin } from 'esbuild';
+/**
+ * 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 declare function fixExtensions(): Plugin;

package/types/plugs/esbuild.d.ts

@@ -0,0 +1,24 @@
+import { BuildOptions } from 'esbuild';
+import { Files } from '../files.js';
+import { Plug } from '../pipe.js';
+import { Run } from '../run.js';
+export declare type ESBuildOptions = Omit<BuildOptions, 'absWorkingDir' | 'entryPoints' | 'watch'>;
+/**
+ * Transpile and bundle files with {@link https://esbuild.github.io/ | esbuild}.
+ */
+export declare class ESBuild implements Plug<Files> {
+    private readonly _options;
+    constructor(options: ESBuildOptions);
+    pipe(files: Files, run: Run): Promise<Files>;
+}
+declare module '../pipe.js' {
+    interface Pipe {
+        /**
+         * Transpile and bundle files with {@link https://esbuild.github.io/ esbuild}.
+         */
+        esbuild: PipeExtension<typeof ESBuild>;
+    }
+}
+export * from './esbuild/bundle-locals.js';
+export * from './esbuild/check-dependencies.js';
+export * from './esbuild/fix-extensions.js';

package/types/plugs/eslint/runner.d.ts

@@ -0,0 +1,22 @@
+import { Files } from '../../files.js';
+import { Plug } from '../../pipe.js';
+import { Run } from '../../run.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;
+    constructor();
+    constructor(configFile: string);
+    constructor(options: ESLintOptions);
+    pipe(files: Files, run: Run): Promise<undefined>;
+}

package/types/plugs/exec.d.ts

@@ -0,0 +1,90 @@
+import { Files } from '../files.js';
+import { Plug } from '../pipe.js';
+import { Run } from '../run.js';
+import { ParseOptions } from '../utils/options.js';
+/** Options for executing scripts */
+export interface ExecOptions {
+    /** Extra environment variables, or overrides for existing ones */
+    env?: Record<string, any>;
+    /** Whether to run in the context of a _shell_ or not */
+    shell?: string | boolean;
+    /**
+     * The current working directory of the process to execute.
+     *
+     * Defaults to the current {@link Files.directory | Files' directory} when
+     * used as a {@link Plug} or `process.cwd()` when used from {@link exec}.
+     */
+    cwd?: string;
+    /**
+     * When used as a {@link Plug}, the {@link Files} will be appended to the
+     * current arguments as _relative_ files (default) or _absolute_ (if false).
+     */
+    relativePaths?: boolean;
+}
+/**
+ * Execute a shell command, adding to its _arguments_ the list of files from
+ * the current pipe (much like `xargs` does on Unix systems).
+ *
+ * This {@link Plug} returns the same {@link Files} it was given, so that
+ * executing a shell command doesn't interrupt a {@link Pipe}.
+ *
+ * For example:
+ *
+ * ```
+ * import { find, exec } from '@plugjs/plugjs'
+ *
+ * export default build({
+ *   async runme() {
+ *     find('*.ts', { directory: 'src' })
+ *       .plug(new Exec('chmod', '755' }))
+ *       .plug(new Exec('chown root:root', { shell: true }))
+ *   },
+ * })
+ * ```
+ */
+export declare class Exec implements Plug<Files> {
+    private readonly _cmd;
+    private readonly _args;
+    private readonly _options;
+    constructor(cmd: string, ...args: ParseOptions<ExecOptions>);
+    pipe(files: Files, run: Run): Promise<Files>;
+}
+/**
+ * Execute a command and await for its result from within a task.
+ *
+ * For example:
+ *
+ * ```
+ * import { exec } from '@plugjs/plugjs'
+ *
+ * export default build({
+ *   async runme() {
+ *     await exec('ls', '-la', '/')
+ *   },
+ * })
+ * ```
+ */
+export declare function exec(cmd: string, ...args: ParseOptions<ExecOptions>): Promise<void>;
+declare module '../pipe.js' {
+    interface Pipe {
+        /**
+         * Execute a shell command, adding to its _arguments_ the list of files
+         * from the current pipe (much like `xargs` does on Unix systems).
+         *
+         * For example:
+         *
+         * ```
+         * import { find, exec } from '@plugjs/plugjs'
+         *
+         * export default build({
+         *   async runme() {
+         *     find('*.ts', { directory: 'src' })
+         *       .exec('chmod', '755' })
+         *       .exec('chown root:root', { shell: true })
+         *   },
+         * })
+         * ```
+         */
+        exec: PipeExtension<typeof Exec>;
+    }
+}

package/types/plugs/filter.d.ts

@@ -0,0 +1,23 @@
+import { Files } from '../files.js';
+import { Plug } from '../pipe.js';
+import { Run } from '../run.js';
+import { MatchOptions } from '../utils/match.js';
+import { ParseOptions } from '../utils/options.js';
+/** Options for filtering {@link Files}. */
+export interface FilterOptions extends MatchOptions {
+    /** The base directory for filtering, and relativising the resulting files. */
+    directory?: string;
+}
+/** Filter the current {@link Files} using globs. */
+export declare class Filter implements Plug<Files> {
+    private readonly _globs;
+    private readonly _options;
+    constructor(glob: string, ...args: ParseOptions<FilterOptions>);
+    pipe(files: Files, run: Run): Files;
+}
+declare module '../pipe.js' {
+    interface Pipe {
+        /** Filter the current {@link Files} using globs. */
+        filter: PipeExtension<typeof Filter>;
+    }
+}

package/types/plugs/mocha/reporter.d.ts

@@ -0,0 +1,8 @@
+import RealMocha from 'mocha';
+/** Symbol to inject `Logger` in reporter options */
+export declare const logSymbol: unique symbol;
+/** Symbol to inject `Run` in reporter options */
+export declare const runSymbol: unique symbol;
+export declare class PlugReporter extends RealMocha.reporters.Base {
+    constructor(runner: RealMocha.Runner, options: RealMocha.MochaOptions);
+}

package/types/plugs/mocha/runner.d.ts

@@ -0,0 +1,34 @@
+import { Files } from '../../files.js';
+import { Plug } from '../../pipe.js';
+import { Run } from '../../run.js';
+/** Options to construct our {@link Mocha} plug. */
+export interface MochaOptions {
+    /** Specify the directory where coverage data will be saved */
+    coverageDir?: string;
+    /** Bail after first test failure? */
+    bail?: boolean;
+    /** Show diff on failure? */
+    diff?: boolean;
+    /** Report tests without running them? */
+    dryRun?: boolean;
+    /** Tests marked `only` fail the suite? */
+    forbidOnly?: boolean;
+    /** Pending tests fail the suite? */
+    forbidPending?: false;
+    /** Reporter name. */
+    reporter?: string;
+    /** Options for the reporter */
+    reporterOptions?: Record<string, any>;
+    /** Number of times to retry failed tests. */
+    retries?: number;
+    /** Slow threshold value. */
+    slow?: number;
+    /** Timeout threshold value. */
+    timeout?: number;
+}
+/** Writes some info about the current {@link Files} being passed around. */
+export default class Mocha implements Plug<undefined> {
+    private readonly _options;
+    constructor(_options?: MochaOptions);
+    pipe(files: Files, run: Run): Promise<undefined>;
+}

package/types/plugs/tsc/compiler.d.ts

@@ -0,0 +1,24 @@
+import ts from 'typescript';
+import { AbsolutePath } from '../../paths.js';
+export declare class TypeScriptHost implements ts.CompilerHost {
+    private readonly _directory;
+    constructor(directory: AbsolutePath);
+    /** Get a source file parsing one of our virtual files */
+    getSourceFile(fileName: string, languageVersion: ts.ScriptTarget): ts.SourceFile | undefined;
+    /** Never write any files */
+    writeFile(fileName: string): void;
+    /** Get the default library associated with the given options */
+    getDefaultLibFileName(options: ts.CompilerOptions): string;
+    /** Check for filesystem case sensitivity */
+    useCaseSensitiveFileNames(): boolean;
+    /** Check for the existence of a given file */
+    fileExists(fileName: string): boolean;
+    /** Read the file if it exists, otherwise return undefined */
+    readFile(fileName: string): string | undefined;
+    /** Return the current working directory */
+    getCurrentDirectory(): AbsolutePath;
+    /** Return the canonical name for the specified file */
+    getCanonicalFileName(fileName: string): string;
+    /** Return the new line sequence used by this platform */
+    getNewLine(): string;
+}

package/types/plugs/tsc/options.d.ts

@@ -0,0 +1,8 @@
+import ts from 'typescript';
+import { AbsolutePath } from '../../paths.js';
+export declare type CompilerOptionsAndDiagnostics = {
+    options: ts.CompilerOptions;
+    errors: readonly ts.Diagnostic[];
+};
+export declare function getCompilerOptions(file?: AbsolutePath): Promise<CompilerOptionsAndDiagnostics>;
+export declare function getCompilerOptions(file: AbsolutePath | undefined, overrides: ts.CompilerOptions, overridesFile: AbsolutePath): Promise<CompilerOptionsAndDiagnostics>;

package/types/plugs/tsc/report.d.ts

@@ -0,0 +1,5 @@
+import ts from 'typescript';
+import { Report } from '../../log.js';
+import { AbsolutePath } from '../../paths.js';
+/** Update a report, adding records from an array of {@link ts.Diagnostic} */
+export declare function updateReport(report: Report, diagnostics: readonly ts.Diagnostic[], directory: AbsolutePath): void;

package/types/plugs/tsc/runner.d.ts

@@ -0,0 +1,13 @@
+import ts from 'typescript';
+import { Files } from '../../files.js';
+import { Plug } from '../../pipe.js';
+import { Run } from '../../run.js';
+export default class Tsc implements Plug<Files> {
+    private readonly _tsconfig?;
+    private readonly _options;
+    constructor();
+    constructor(config: string);
+    constructor(options: ts.CompilerOptions);
+    constructor(config: string, options: ts.CompilerOptions);
+    pipe(files: Files, run: Run): Promise<Files>;
+}

package/types/plugs.d.ts

@@ -0,0 +1,16 @@
+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' {
+    interface Pipe {
+        eslint: PipeExtension<typeof ESLint>;
+        mocha: PipeExtension<typeof Mocha>;
+        tsc: PipeExtension<typeof Tsc>;
+    }
+}
+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/types/run.d.ts

@@ -0,0 +1,89 @@
+import { Files, FilesBuilder } from './files.js';
+import { Logger, LogLevelString, Report } from './log.js';
+import { AbsolutePath } from './paths.js';
+import { Pipe } from './pipe.js';
+import { ParseOptions } from './utils/options.js';
+import { 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 declare class RunImpl implements Run {
+    readonly taskName: string;
+    readonly buildFile: AbsolutePath;
+    readonly buildDir: AbsolutePath;
+    readonly log: Logger;
+    constructor(options: RunConstructionOptions);
+    /** Set the logging level within this {@link Run} */
+    setLogLevel(level: LogLevelString): void;
+    report(title: string): Report;
+    resolve(...paths: string[]): AbsolutePath;
+    files(files: Files): FilesBuilder;
+    files(...paths: string[]): FilesBuilder;
+    find(glob: string, ...args: ParseOptions<FindOptions>): Pipe & Promise<Files>;
+    pipe(files: Files | Promise<Files>): Pipe & Promise<Files>;
+    call(name: string): Promise<Files | undefined>;
+}

package/types/task.d.ts

@@ -0,0 +1,15 @@
+import type { BuildContext, TaskDefinition, ThisBuild } from './build.js';
+import type { Files } from './files.js';
+import type { Run } from './run.js';
+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 declare class TaskImpl implements Task<Files | undefined> {
+    readonly context: BuildContext;
+    private readonly _definition;
+    constructor(context: BuildContext, _definition: TaskDefinition<any>);
+    call(self: ThisBuild<any>, run: Run): Promise<Files | undefined>;
+}

package/types/utils/asyncfs.d.ts

@@ -0,0 +1,37 @@
+/// <reference types="node" resolution-mode="require"/>
+import { constants } from 'node:fs';
+import fsp from 'node:fs/promises';
+declare const fs: typeof fsp & {
+    constants: typeof constants;
+};
+export default fs;
+export declare const access: typeof fsp.access;
+export declare const copyFile: typeof fsp.copyFile;
+export declare const cp: typeof fsp.cp;
+export declare const open: typeof fsp.open;
+export declare const opendir: typeof fsp.opendir;
+export declare const rename: typeof fsp.rename;
+export declare const truncate: typeof fsp.truncate;
+export declare const rm: typeof fsp.rm;
+export declare const rmdir: typeof fsp.rmdir;
+export declare const mkdir: typeof fsp.mkdir;
+export declare const readdir: typeof fsp.readdir;
+export declare const readlink: typeof fsp.readlink;
+export declare const symlink: typeof fsp.symlink;
+export declare const lstat: typeof fsp.lstat;
+export declare const stat: typeof fsp.stat;
+export declare const link: typeof fsp.link;
+export declare const unlink: typeof fsp.unlink;
+export declare const chmod: typeof fsp.chmod;
+export declare const lchmod: typeof fsp.lchmod;
+export declare const lchown: typeof fsp.lchown;
+export declare const chown: typeof fsp.chown;
+export declare const utimes: typeof fsp.utimes;
+export declare const lutimes: typeof fsp.lutimes;
+export declare const realpath: typeof fsp.realpath;
+export declare const mkdtemp: typeof fsp.mkdtemp;
+export declare const writeFile: typeof fsp.writeFile;
+export declare const appendFile: typeof fsp.appendFile;
+export declare const readFile: typeof fsp.readFile;
+export declare const watch: typeof fsp.watch;
+export { constants } from 'node:fs';

package/types/utils/caller.d.ts

@@ -0,0 +1,7 @@
+import { AbsolutePath } from '../paths.js';
+export interface Location {
+    file: AbsolutePath;
+    line?: number | undefined;
+    column?: number | undefined;
+}
+export declare function findCaller(of: (...args: any[]) => any): Location;