depflow 3.0.0-dev.10 → 3.0.0-dev.11

package/dist/builder/Builder.js

@@ -0,0 +1,391 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Runs dependency build pipelines: shell commands, file extraction and content transformations.
+ * @license Apache-2.0
+ */
+import { File, Path } from "@netfeez/common-node";
+import Task from "../task/Task.js";
+import Group from "../task/Group.js";
+export class Builder {
+    pipeline;
+    cwd;
+    projectRoot;
+    logger;
+    policy;
+    /** The step that stopped the pipeline, or `null` while it is still walking it. */
+    vStopped = null;
+    constructor(info) {
+        this.pipeline = info.pipeline;
+        this.cwd = info.cwd;
+        this.projectRoot = info.projectRoot;
+        this.logger = info.logger || null;
+        this.policy = info.policy || null;
+    }
+    /**
+     * Runs the pipeline and reports what every step of it did.
+     * @returns A promise resolving with the report of the run, or rejecting with a
+     * {@link Builder.Failure} carrying that same report, when a step stopped the pipeline.
+     *
+     * @remarks The report is the verdict of the run, and it is produced whether the run succeeded or
+     * failed: a caller that catches a {@link Builder.Failure} gets the steps that ran before the one
+     * that stopped it, and the steps that never ran at all, so nothing about the pipeline is missing
+     * from a failure.
+     *
+     * @remarks The group of the run is closed in a `finally`, so the steps of a pipeline that threw leave
+     * the output as closed as the ones of a pipeline that finished. It is opened only when the run
+     * decorates its output, because a group that draws nothing still leaves a box and an indentation
+     * around every line written inside it.
+     */
+    async run() {
+        const boxed = this.policy === null || this.policy.decoration === 'on';
+        if (boxed)
+            this.logger?.group(Group.create('#00FFB4'));
+        try {
+            const steps = await this.walk();
+            const report = Builder.report(steps);
+            this.policy?.settleBuild(report);
+            if (!report.ok)
+                throw new Builder.Failure(report, Builder.reason(report));
+            return report;
+        }
+        finally {
+            if (boxed)
+                this.logger?.end();
+        }
+    }
+    /**
+     * Walks the pipeline in order, running each step until one of them stops it.
+     * @returns A promise resolving with one report per step of the pipeline, the ones that ran and the
+     * ones the stop left behind.
+     */
+    async walk() {
+        const steps = [];
+        for (const [position, entry] of this.pipeline.entries()) {
+            const index = position + 1;
+            if (this.vStopped)
+                steps.push(Builder.pending(index, Builder.kind(entry)));
+            else
+                steps.push(await this.runStep(index, entry));
+        }
+        return steps;
+    }
+    /**
+     * Runs one step of the pipeline and turns it into its report.
+     * @param index - The position of the step inside the pipeline, starting at 1.
+     * @param entry - The entry of the pipeline describing the step.
+     * @returns A promise resolving with the report of the step.
+     *
+     * @remarks An entry that carries no step at all is reported as one that did not run, the way the
+     * pipeline has always walked over it, and the report accounts for it all the same.
+     */
+    async runStep(index, entry) {
+        if ('run' in entry && entry.run)
+            return this.runRun(index, entry);
+        if ('extract' in entry && entry.extract)
+            await this.runExtractor(entry.extract);
+        else if ('transform' in entry && entry.transform)
+            await this.runGlobalTransform(entry.transform);
+        else
+            return Builder.pending(index, null);
+        return Builder.settled(index, 'extract' in entry ? 'extract' : 'transform');
+    }
+    /**
+     * Runs the commands of a `run` step as a Task, settling the step with the verdict of the task.
+     * @param index - The position of the step inside the pipeline, starting at 1.
+     * @param entry - The `run` entry describing the step.
+     * @returns A promise resolving with the report of the step.
+     *
+     * @remarks A step that does not tolerate its failures stops the pipeline, so the steps after it are
+     * reported as steps that never ran. The step itself is not rethrown from here: the report of the run
+     * is the verdict of the pipeline, and rejecting twice would report the same failure twice.
+     */
+    async runRun(index, entry) {
+        const commands = typeof entry.run === 'string' ? [entry.run] : entry.run;
+        const identity = Builder.identity(index, this.steps);
+        try {
+            const outcome = await this.runTask(commands, this.cwd, { maxTimeMs: entry.maxTimeMs, allowFails: entry.allowFails }, identity);
+            return {
+                index,
+                kind: 'run',
+                ran: true,
+                success: outcome.success,
+                failed: outcome.fails,
+                tolerated: entry.allowFails === true && outcome.fails > 0,
+                reason: null,
+                commands: outcome.results.map(Builder.commandReport)
+            };
+        }
+        catch (failure) {
+            const outcome = failure instanceof Task.Failure ? failure.outcome : null;
+            this.vStopped = { index, reason: failure instanceof Task.Failure ? failure.reason : 'step' };
+            if (failure instanceof Task.Failure)
+                this.policy?.stepFailed(identity, failure);
+            return {
+                index,
+                kind: 'run',
+                ran: true,
+                success: false,
+                failed: outcome?.fails ?? 0,
+                tolerated: false,
+                reason: this.vStopped.reason,
+                commands: (outcome?.results ?? []).map(Builder.commandReport)
+            };
+        }
+    }
+    /**
+     * How many steps of the pipeline run commands, the number a command identity is qualified by.
+     * @returns The amount of `run` entries in the pipeline.
+     */
+    get steps() {
+        return this.pipeline.filter(entry => Builder.kind(entry) === 'run').length;
+    }
+    /**
+     * Runs the shell commands of a build step as a Task, reporting them through the policy of the run.
+     * The verdict of the task is the verdict of the step: it is awaited, never read from an event.
+     * @param commands - The shell commands to run, in order.
+     * @param cwd - The working directory the commands run in.
+     * @param options - The options of the step: its deadline and whether its failures are tolerated.
+     * @param identity - The identity the commands of this task are reported under.
+     * @returns A promise resolving with the summary of the run of the task.
+     * @throws { Task.Failure } When the step fails and does not tolerate failures.
+     */
+    async runTask(commands, cwd, options, identity) {
+        const task = new Task(cwd, commands, options);
+        if (this.policy) {
+            task.on('line', (line, ordinal) => this.policy?.live(identity, line, ordinal, 'stdout'));
+            task.on('err', (line, ordinal) => this.policy?.live(identity, line, ordinal, 'stderr'));
+            task.once('finish', (data) => this.policy?.settleTask(identity, data));
+        }
+        else if (this.logger) {
+            task.on('line', (line) => this.logger?.info(`${line}`));
+            task.on('err', (line) => this.logger?.error(`${line}`));
+        }
+        return task.run();
+    }
+    /**
+     * Applies a global transformation to every file of the working directory, the one the configuration
+     * asks for through its glob.
+     * @param options - The transformation to apply, either as a search and replace pair or as a plain
+     * regular expression.
+     * @returns A promise resolving when every file of the glob has been transformed.
+     */
+    async runGlobalTransform(options) {
+        this.logger?.log(`&C7Applying global transformation in &C3${this.cwd}&C7...`);
+        const transformAction = Builder.replacer(options);
+        const glob = options.glob;
+        await File.smartProcess(glob, this.cwd, {
+            cwd: this.cwd,
+        }, async ({ src, dest }) => {
+            const content = await File.read(src);
+            const transformedContent = transformAction(content);
+            await File.write(dest, transformedContent);
+        });
+    }
+    /**
+     * Resolves the destination folder of an extraction entry, which is relative to the project root, and
+     * guarantees it stays inside it.
+     * @param to - The destination folder declared by the entry.
+     * @returns The normalized path of the destination folder.
+     * @throws { Error } When a relative destination escapes the project root.
+     *
+     * @remarks An absolute destination is taken as it stands: writing outside the project is a decision
+     * the configuration takes on purpose, and spelling it out as an absolute path is what makes it one.
+     * A relative destination cannot, because a `..` that walks out of the project is a mistake and not a
+     * decision. The project root is a destination like any other, so it is not treated as an escape.
+     */
+    resolveDestination(to) {
+        if (Path.isAbsolute(to))
+            return to;
+        const root = Path.normalize(this.projectRoot);
+        const destination = Path.normalize(Path.join(root, to));
+        if (destination !== root && !Path.isInside(root, destination))
+            throw new Error(`Extraction destination resolves outside of the project root: ${destination}`);
+        return destination;
+    }
+    /**
+     * Runs the extraction process based on the provided entry configuration, which can be either a string or an array of extraction entries.
+     * It handles the copying of files from the specified source to the target location, applying any necessary path transformations based on the provided replacer configuration.
+     * This method is essential for managing the file extraction phase of the build process, allowing for flexible and customizable file handling as defined in the builder configuration.
+     * @param entry - A string or an array of extraction entries that define the source, target, and optional path transformation for the extraction process.
+     * @returns A promise that resolves when the extraction process is complete, or rejects with an error if any issues occur during the file copying or transformation.
+     * @throws Will throw an error if any issues occur during the file copying process, such as problems with reading or writing files, or if the provided entry configuration is invalid.
+     */
+    async runExtractor(entry) {
+        const extractor = typeof entry === 'string'
+            ? { '**/*': { to: entry } }
+            : entry;
+        for (const [from, entry] of Object.entries(extractor)) {
+            const { to, map, transform } = typeof entry === 'string' ? { to: entry } : entry;
+            const mapper = Builder.replacer(map);
+            const replacer = Builder.replacer(transform);
+            const destination = this.resolveDestination(to);
+            this.logger?.log(`&C7Extracting &C3${from}&C7 to &C3${to}&C7...`);
+            await File.smartProcess(from, destination, {
+                cwd: this.cwd,
+                map: mapper,
+            }, async ({ src, dest }) => {
+                const content = await File.read(src);
+                const transformedContent = replacer(content);
+                await File.write(dest, transformedContent);
+            });
+        }
+    }
+    /**
+     * Creates a string replacement function based on the provided replacer configuration, which can be either a simple string or an object defining a search pattern and replacement string. This method is used to generate a function that can be applied to strings for dynamic transformations during the build process, allowing for flexible and customizable string manipulation as defined in the builder configuration.
+     * @param replacer - A configuration for string replacement, which can be either a string (used as a regex pattern) or an object containing a search pattern and replacement string.
+     * @returns A function that takes a string as input and returns a new string with the specified replacements applied, based on the provided replacer configuration.
+     * @throws Will throw an error if the provided replacer configuration is invalid, such as if it is neither a string nor an object with the required properties.
+     */
+    static replacer(replacer) {
+        if (typeof replacer === 'string') {
+            const search = new RegExp(replacer, 'g');
+            return (str) => str.replace(search, '');
+        }
+        else if (replacer !== null && typeof replacer === 'object') {
+            const flags = replacer.flags || 'g';
+            const search = new RegExp(replacer.search, flags);
+            const replace = replacer.replace || '';
+            return (str) => str.replace(search, replace);
+        }
+        else
+            return (str) => str;
+    }
+    /**
+     * The kind of step an entry of the pipeline describes, decided by the key it carries.
+     * @param entry - The entry of the pipeline.
+     * @returns The kind of the step, or `null` when the entry describes no step at all.
+     */
+    static kind(entry) {
+        if ('run' in entry && entry.run)
+            return 'run';
+        if ('extract' in entry && entry.extract)
+            return 'extract';
+        if ('transform' in entry && entry.transform)
+            return 'transform';
+        return null;
+    }
+    /**
+     * The identity the commands of a `run` step are reported under.
+     *
+     * @remarks A command is identified as `C<M>` inside its own task, and as `S<N> · C<M>` when the
+     * pipeline runs more than one of them: with a single `run` step there is nothing to qualify it
+     * against, and with more than one there is, so `C1` alone would name two different commands.
+     *
+     * @param index - The position of the step inside the pipeline, starting at 1.
+     * @param steps - How many `run` steps the pipeline has.
+     * @returns The identity of the commands of the step.
+     */
+    static identity(index, steps) {
+        return { step: steps > 1 ? index : null };
+    }
+    /**
+     * The report of a command inside a step: who it was and how it ended, without what it printed.
+     *
+     * @remarks The output of a command is not part of the report: a report says what the pipeline did,
+     * and a build that printed a log would carry that log in every summary it produced, in every layer
+     * that received it. The output stays where it was produced, in the results of the task, and it is
+     * read once, when the task settles.
+     *
+     * @param result - The result of the command.
+     * @returns The report of the command.
+     */
+    static commandReport(result) {
+        return {
+            ordinal: result.ordinal,
+            label: result.label,
+            success: result.success,
+            code: result.code,
+            signal: result.signal,
+            reason: result.reason,
+            time: result.time
+        };
+    }
+    /**
+     * The report of a step that ran and had nothing to report beyond having run.
+     * @param index - The position of the step inside the pipeline, starting at 1.
+     * @param kind - The kind of the step, which a step that only works on files never has.
+     * @returns The report of the step.
+     */
+    static settled(index, kind) {
+        return { index, kind, ran: true, success: true, failed: 0, tolerated: false, reason: null, commands: [] };
+    }
+    /**
+     * The report of a step that never ran, either because an earlier one stopped the pipeline or because
+     * the entry describes no step at all.
+     * @param index - The position of the step inside the pipeline, starting at 1.
+     * @param kind - The kind of the step, `null` when the entry describes none.
+     * @returns The report of the step that did not run.
+     */
+    static pending(index, kind) {
+        return { index, kind, ran: false, success: false, failed: 0, tolerated: false, reason: null, commands: [] };
+    }
+    /**
+     * The report of a whole pipeline.
+     * @param steps - One report per step of the pipeline, in order.
+     * @returns The report of the run.
+     */
+    static report(steps) {
+        const ran = steps.filter(step => step.ran);
+        return {
+            ok: ran.length === steps.length && ran.every(step => step.success),
+            commands: ran.reduce((total, step) => total + step.commands.length, 0),
+            failed: ran.reduce((total, step) => total + step.failed, 0),
+            tolerated: ran.filter(step => step.tolerated).reduce((total, step) => total + step.failed, 0),
+            steps
+        };
+    }
+    /**
+     * Why the pipeline stopped, read from the step that stopped it: the reason the step could not
+     * complete, or the commands that failed and it did not tolerate.
+     * @param report - The report of the run.
+     * @returns The reason the run did not finish successfully.
+     */
+    static reason(report) {
+        const step = report.steps.find(entry => entry.ran && !entry.success);
+        if (!step)
+            return 'step';
+        if (step.reason !== null)
+            return step.reason;
+        return step.failed > 0 ? 'command' : 'step';
+    }
+}
+(function (Builder) {
+    /**
+     * The failure of a pipeline, carrying the report of the run that produced it.
+     *
+     * @remarks The report is the same one the run would have resolved with, so a caller that only wants
+     * to know how the pipeline went catches this and reads it instead of rebuilding it from the steps
+     * that did run.
+     */
+    class Failure extends Error {
+        report;
+        reason;
+        /**
+         * Creates the failure of a pipeline.
+         * @param report - The report of the run.
+         * @param reason - Why the pipeline stopped.
+         */
+        constructor(report, reason = 'step') {
+            super(Failure.message(report, reason));
+            this.report = report;
+            this.reason = reason;
+            this.name = 'Builder.Failure';
+        }
+        /**
+         * The message describing which step stopped the pipeline and why, in one line.
+         * @param report - The report of the run.
+         * @param reason - Why the pipeline stopped.
+         * @returns The message of the failure.
+         */
+        static message(report, reason) {
+            const step = report.steps.find(entry => entry.ran && !entry.success);
+            const where = step ? `Step ${step.index}` : 'The pipeline';
+            const because = reason === 'command' ? `${report.failed} failed command(s)`
+                : reason === 'step' ? 'a step of it failed' : reason;
+            return `${where} stopped the pipeline: ${because}.`;
+        }
+    }
+    Builder.Failure = Failure;
+})(Builder || (Builder = {}));
+export default Builder;
+//# sourceMappingURL=Builder.js.map

package/dist/builder/Builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Builder.js","sourceRoot":"","sources":["../../src/builder/Builder.ts"],"names":[],"mappings":"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"}

package/dist/cli/CLI.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description The console interface the CLI is built on: it reads a command, runs it and answers it,
+ *              and it draws the help the global flags and the arguments of every command are told in.
+ * @license Apache-2.0
+ */
+import type { Engine, ConsoleTransport } from '@netfeez/vterm';
+import type Flags from './Flags.js';
+export declare class CLI {
+    /** What reads the input of the console interface. */
+    protected dataHandleInstance: CLI.dataHandler;
+    /** What is written before every command the interface reads. */
+    prompt: string;
+    /** The input the interface reads commands from. */
+    in: NodeJS.ReadStream;
+    /** The engine the interface answers through. */
+    out: Engine;
+    /** The commands the interface accepts, keyed by the name each one is invoked with. */
+    commandMap: CLI.CommandMap;
+    /** The terminal the prompt and the help are written to. */
+    protected console: ConsoleTransport;
+    /** The flags that are not specific to a command, keyed by the name each one is declared under. */
+    protected globals: Flags.Declaration;
+    /** The branded line the help opens with. */
+    protected title: string;
+    /**
+     * Wires a console interface to its terminal, its global flags and its commands.
+     * @param globals - The flags no command owns, declared as `Flags` declares them.
+     * @param config - How the interface presents itself: the name of its runs, its prompt and its title.
+     */
+    constructor(globals?: Flags.Declaration, config?: CLI.Config);
+    /** Starts reading what is written to the input. **/
+    protected startReadIn(): void;
+    /** Stops reading what is written to the input. **/
+    protected stopReadIn(): void;
+    /** Starts the console UI. **/
+    start(): void;
+    /** Stops the console UI. **/
+    stop(): void;
+    /**
+     * Runs the command the input carries, and writes the prompt again unless the command leaves.
+     * @param data - What arrived in the input.
+     * @returns A promise of the command being over.
+     */
+    protected dataHandler(data: Buffer): Promise<void>;
+    /**
+     * The command of that name, when the map carries one.
+     * @param command - The name of the command.
+     * @returns The command, or undefined when the map carries no command of that name.
+     */
+    getCommand(command: string): CLI.Command | undefined;
+    /**
+     * Puts a command in the map.
+     * @param command - The name of the command.
+     * @param exec - What the command does when it is written.
+     * @param info - What `help` tells about it, the arguments it accepts among it.
+     * @returns This instance, so commands can be added one after another.
+     */
+    addCommand(command: string, exec: CLI.commandExec, info?: CLI.CommandInfo): this;
+    /**
+     * Takes a command out of the map.
+     * @param command - The name of the command.
+     * @returns This instance, so commands can be removed one after another.
+     */
+    removeCommand(command: string): this;
+    /**
+     * Puts the commands every console interface carries in the map.
+     **/
+    protected addDefaultCommands(): void;
+    /**
+     * Writes the banner, the global flags and every command of the map with its usage, its description
+     * and the arguments it accepts.
+     *
+     * @remarks The help belongs to the terminal and not to a run, so it is written as it is composed
+     * and it is not announced through the engine: no timestamp, level or name is put in front of it,
+     * and a line is only broken where this method breaks it.
+     **/
+    protected showHelp(): void;
+    /**
+     * The name of a flag as the help writes it, with the aliases it accepts and the value it takes.
+     * @param name - The name the flag is declared under.
+     * @param flag - The declared flag.
+     * @returns The name of the flag, colored.
+     */
+    protected static flagKey(name: string, flag: Flags.Flag): string;
+    /**
+     * The name of an argument as the help writes it, telling an optional one and a variadic one apart.
+     * @param name - The name the argument is declared under.
+     * @param argument - The declared argument.
+     * @returns The name of the argument, colored.
+     */
+    protected static argumentKey(name: string, argument: CLI.Argument): string;
+    /**
+     * Lays out a name and what it is for in the columns left after the name.
+     * @param key - The name, with the tokens that color it.
+     * @param description - What the name is for.
+     * @param width - The visible width every line is kept within.
+     * @param indent - The visible columns the entry starts at.
+     * @returns The lines of the entry, the description broken in as many lines as it needs.
+     */
+    protected static describe(key: string, description: string, width: number, indent?: number): string[];
+    /**
+     * Breaks a text in as many lines as it needs to fit a visible width, on its word boundaries.
+     * @param text - The text to break, without tokens in it.
+     * @param width - The visible width every line is kept within.
+     * @returns The lines the text was broken in.
+     */
+    protected static wrap(text: string, width: number): string[];
+    /**
+     * The columns a text paints, with its tokens taken out.
+     * @param text - The text to measure, with the tokens of the grammar in it.
+     * @returns The number of visible columns it paints.
+     */
+    protected static visibleWidth(text: string): number;
+}
+export declare namespace CLI {
+    type dataHandler = (data: Buffer) => void;
+    type commandExec = (this: CLI, command: string, args: string[]) => Promise<void> | void;
+    /** A positional argument a command accepts. **/
+    interface Argument {
+        /** What the argument is for. **/
+        description: string;
+        /** Whether the command cannot run without it. Defaults to `true`. **/
+        required?: boolean;
+        /** Whether the argument takes every token that follows, written with a trailing ellipsis. **/
+        variadic?: boolean;
+    }
+    /** The positional arguments a command accepts, keyed by the name each one is declared under. **/
+    type Arguments = {
+        readonly [name: string]: Argument;
+    };
+    /** What `help` tells about a command. **/
+    interface CommandInfo {
+        description?: string;
+        usage?: string;
+        args?: Arguments;
+    }
+    /** A command of the console interface, with what it does and what `help` tells about it. **/
+    interface Command extends CommandInfo {
+        name: string;
+        exec: commandExec;
+    }
+    /** The commands of the interface, keyed by the name each one is invoked with. **/
+    interface CommandMap {
+        [command: string]: Command;
+    }
+    /** How the console interface presents itself. **/
+    interface Config {
+        /** The name every run of the interface is written with. **/
+        name?: string;
+        /** The prompt written before every command, with the tokens of the console grammar. **/
+        prompt?: string;
+        /** The branded line the help opens with, with the tokens of the console grammar. **/
+        title?: string;
+    }
+}
+export default CLI;