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

package/README.md

@@ -14,6 +14,7 @@ Key goals:
 - NPM dependency extraction and local mirroring
 - Automatic `tsconfig` paths and browser `importmap` generation via `dep sync`
 - Flexible resolver aliases for local and CDN targets
+- Reproducible checkouts: every install lands on the tag the configuration asks for
 
 ---
 
@@ -31,16 +32,16 @@ Alternatively, add it as a dev-dependency for project-specific usage.
 
 ## Quick Start
 
-1. Create a configuration file (recommended name: `depflow.json`).
+1. Create a configuration file, `depflow.yml` (or any other name, passed with `--flow`).
 2. Run `dep install` to fetch and build all configured dependencies.
 3. Run `dep sync` to update `tsconfig` paths and `importmap` (if configured).
 
 CLI examples:
 
 ```bash
-# install dependencies defined in .df.json
+# install the dependencies declared in depflow.yml
 dep install
-# --flow filepath.json for use an specific config
+# --flow <file> to use a specific config instead
 
 # sync tsconfig/importmap from the configuration
 dep sync
@@ -50,24 +51,27 @@ dep sync
 
 ## Configuration
 
-DepFlow uses a JSON configuration file describing where to fetch dependencies and how to build and expose them. The minimal structure:
+DepFlow uses a single configuration file describing where to fetch dependencies and how to build and expose them. The format follows the extension: `.yml` and `.yaml` are read and written as YAML, `.json` as JSON. Without `--flow`, the CLI reads `depflow.yml` from the current working directory.
 
-- `flowFolder` (string): folder where DepFlow stores temporary state (default: `.depflow`).
-- `outDir` (string): project output root used by extract rules.
+A YAML config is read as a document, so key order, indentation and the comments of the keys a save does not touch are preserved; a config created from scratch is written in block style, documented with a comment per key, and accompanied by an editor JSON Schema at `.depflow/schema.json`.
+
+The minimal structure:
+
+- `outDir` (string): project output root scanned by `rewrite-paths` (and by the watcher). Defaults to `dist`. Extraction targets are *not* relative to it, they are relative to the project root, see [Builder rules](#builder-rules).
 - `tsconfig` (string|null): optional path to TypeScript `tsconfig.json` to update `compilerOptions.paths`.
 - `importmap` (string|null): optional path to write a browser `importmap`.
+- `actions` (object): named pipelines runnable with `dep run <action>`.
 - `dependencies` (array): Git-based dependencies.
 - `npmDependencies` (array): NPM packages to extract files from.
 
-Each dependency supports `builder` steps (run commands, file extraction) and `resolver` entries that map aliases to local or CDN targets.
+Each dependency supports `builder` steps (run commands, file extraction, content transformation) and `resolver` entries that map aliases to local or CDN targets.
 
 ### Example Configuration
 
-Below is an example adapted from a real project configuration. Use it as a template for your repository.
+Shown as JSON, which the CLI reads and writes just as well as YAML whenever the file is named `.json`. The extraction targets are shown as absolute paths, which is the only form that survives being copied between machines: a relative one is resolved against the project root, the same as every other relative path of the configuration.
 
 ```json
 {
-    "flowFolder": ".depflow",
     "outDir": ".",
     "tsconfig": "tsconfig.web.json",
     "importmap": "public/importmap.json",
@@ -75,19 +79,22 @@ Below is an example adapted from a real project configuration. Use it as a templ
         {
             "name": "NetFeez.Vizui",
             "repo": "https://github.com/NetFeez/Vizui.git",
+            "tag": "v1.2.0",
             "builder": [
                 {
-                    "run": ["npm install", "npm run compile"],
-                    "extract": [
-                        { "from": "build/**/*.js", "to": "public/lib/vizui/", "replacer": "^build/" },
-                        { "from": "build/**/*.d.ts", "to": "public/lib/vizui/", "replacer": "^build/" }
-                    ]
+                    "run": [ "npm install", "npm run compile" ]
+                },
+                {
+                    "extract": {
+                        "build/**/*.js": { "to": "/abs/path/to/app/public/lib/vizui/", "map": "^build/" },
+                        "build/**/*.d.ts": { "to": "/abs/path/to/app/public/lib/vizui/", "map": "^build/" }
+                    }
                 }
             ],
-            "resolver": [
-                { "alias": "vizui", "target": "public/lib/vizui/vizui.js" },
-                { "alias": "vizui/*", "target": "public/lib/vizui/*" }
-            ]
+            "resolver": {
+                "vizui": "public/lib/vizui/vizui.js",
+                "vizui/*": "public/lib/vizui/*"
+            }
         }
     ],
     "npmDependencies": [
@@ -96,40 +103,88 @@ Below is an example adapted from a real project configuration. Use it as a templ
             "version": "latest",
             "builder": [
                 {
-                    "extract": [
-                        { "from": "build/**/*.js", "to": "public/lib/common/", "replacer": "^build/" },
-                        { "from": "build/**/*.d.ts", "to": "public/lib/common/", "replacer": "^build/" }
-                    ]
+                    "extract": {
+                        "build/**/*.js": { "to": "/abs/path/to/app/public/lib/common/", "map": "^build/" },
+                        "build/**/*.d.ts": { "to": "/abs/path/to/app/public/lib/common/", "map": "^build/" }
+                    }
                 }
             ],
-            "resolver": [
-                { "alias": "@netfeez/common", "target": "public/lib/common/index.js" },
-                { "alias": "@netfeez/common/*", "target": "public/lib/common/*" }
-            ]
+            "resolver": {
+                "@netfeez/common": "public/lib/common/index.js",
+                "@netfeez/common/*": "public/lib/common/*"
+            }
         }
     ]
 }
 ```
 
+### Dependency identity
+
+The `name` of a dependency is its identity, not a path: it is a single path segment, and it is also the
+name of its checkout folder inside `.depflow`. A name may not be a path, may not start with a dot, and may
+not be one of the names the flow folder reserves for itself (`schema.json` and `node_modules`).
+
+The `repo` of a git dependency is any value `git clone` accepts: a URL with its scheme, an SSH address or a
+local path of a repository. It always carries the `.git` suffix, whichever transport it comes in. `tag` is the
+revision the checkout lands on after cloning and after every reinstall; it defaults to `main`.
+
 ### Builder rules
-- `run`: a string or array of shell commands executed inside the dependency checkout.
-- `extract`: patterns describing which files to copy from the dependency build output into your project. Each extractor may include `from`, `to`, and an optional `replacer` regex used to rewrite paths.
+
+A pipeline is an ordered list of steps, each of them exactly one of:
+
+- `run`: a string or a list of shell commands executed inside the dependency checkout. It accepts
+  `maxTimeMs` (deadline in milliseconds, `-1` for no deadline, defaults to `60000`) and `allowFails`
+  (whether a failed command is tolerated, defaults to `false`).
+- `extract`: a mapping of source globs to extraction entries, or a destination folder as a shorthand for
+  `**/*` → that folder. The globs are matched against the folder the pipeline works in (the dependency
+  checkout, or the project itself for a `dep run` action) and an entry is a destination (`to`) plus,
+  optionally, a `map` transformation applied to the destination path and a `transform` transformation
+  applied to the content of the files. A relative `to` is resolved against the project root and an
+  absolute one is used as it stands, so a pipeline reads from the dependency and deposits into the
+  project. `map` runs against the *relative* path of the matched file, inside the destination.
+- `transform`: a `glob` plus a `search`/`replace` transformation applied in place to the matched files.
+
+Every transformation (`map`, `transform`, and the in-place `transform` step) takes one of two forms, and
+they do not mean the same thing:
+
+- a **string** is a pattern to *remove*: `"^build/"` strips that prefix from the path of every matched
+  file, globally;
+- an **object** `{ "search": ..., "flags": ..., "replace": ... }` is the only form that *substitutes*
+  something: `search` is the pattern, `replace` what takes its place, and `flags` defaults to `g`.
+
+```json
+{ "map": "^build/" }
+{ "map": { "search": "^build/(.*)\\.js$", "replace": "$1.js" } }
+```
+
+An object whose `replace` is empty removes the matches exactly as the string form does.
 
 ### Resolver entries
-- `alias`: module alias exposed to your project (used in `importmap` and `tsconfig` paths).
-- `target`: a string path or an object with `local` and `cdn` properties for multi-target deployments.
+
+The `resolver` of a dependency, and the `resolver` of the configuration, are mappings of an alias to its
+target. The target is either a string path or an object with these keys:
+
+- `local` (string, required): the path the alias resolves to, resolved against the project root. `sync`
+  turns it into the `tsconfig` `paths` entry (and into the `importmap` entry unless `--cdn` is given),
+  and `rewrite-paths` rewrites the built files' imports that point at it.
+- `type` (string, optional): the target holding the type declarations. It becomes the *first* entry of
+  the generated `paths` array, so the editor finds the `.d.ts` next to the value. Unlike `local`, it is
+  not resolved against the project root, so it has to be an absolute path.
+- `cdn` (string, optional): the URL that replaces `local` when `--cdn` is given.
+
+A `*` suffix on the alias turns it into a mapping, so `vizui/*` also covers `vizui/Button`.
 
 ---
 
 ## CLI Reference
 
-Use the distribution script in `build/cli/bin.js` or install the package globally.
+Use the distribution script in `dist/cli/bin.js` or install the package globally.
 
 - `install`: Clone, build and extract artifacts for all dependencies in your config.
 - `sync`: Generate/update `tsconfig` paths and browser `importmap` according to `resolver` entries.
-- `list`: Show configured dependencies and their status.
+- `list`: Show configured dependencies and whether each one is installed.
 
-Use `node ./build/cli/bin.js <command> --flow <config>` when running locally from the repository.
+Use `node ./dist/cli/bin.js <command> --flow <config>` when running locally from the repository.
 
 ### Commands
 
@@ -137,20 +192,21 @@ The CLI exposes the following commands (all commands accept the global `--flow <
 
 | Command | Usage | Description |
 |---|---|---|
-| `add` | `dep add <repo_url> [name] [--flow <file>]` | Add a git dependency to the configuration file. If the configuration file does not exist it will be created automatically (default: `depflow.json`). If `name` is omitted the repo name is used. |
-| `remove` | `dep remove <name|repo_url> [--flow <file>]` | Remove a dependency by `name` or repository URL. |
-| `install` | `dep install [name1 name2 ...] [--flow <file>]` | Clone, build and extract artifacts for all or specific dependencies. Runs `dep sync` after install. |
-| `uninstall` | `dep uninstall [name1 name2 ...] [--flow <file>]` | Remove local files for configured dependencies. |
-| `list` | `dep list [--flow <file>]` | List all dependencies declared in the configuration. |
-| `rewrite-paths` | `dep rewrite-paths [--watch] [--cdn] [--flow <file>]` | Rewrite built files' paths according to resolver aliases. Use `--watch` to run a watcher; use `--cdn` to apply CDN targets instead of local targets. |
+| `add` | `dep add <repo_url> [name] [--flow <file>]` | Add a git dependency to the configuration file. If the configuration file does not exist it will be created automatically, in the format its extension asks for (default: `depflow.yml`). When the name is omitted it is derived from the repository, which only a GitHub repository allows; any other repository needs the name to be given. A name already taken by another dependency is refused. |
+| `remove` | `dep remove <name\|repo_url> [--flow <file>]` | Remove a dependency by `name` or repository URL and uninstall its local files. An identifier that no dependency declares is an error. |
+| `install` | `dep install [name1 name2 ...] [--flow <file>]` | Clone, build and extract artifacts for all or specific dependencies. Runs `dep sync` after install. A dependency that is already present is brought to the revision of its `tag` instead of being cloned again. |
+| `list` | `dep list [--flow <file>]` | List all dependencies declared in the configuration, telling an `installed` one (its folder is in place under `.depflow`) from a `missing` one. |
+| `rewrite-paths` | `dep rewrite-paths [--watch] [--cdn] [--flow <file>]` | Rewrite built files' paths according to resolver aliases. Use `--watch` to run a watcher; use `--cdn` to apply CDN targets instead of local targets. A built file that cannot be rewritten makes the command fail instead of being left pointing at the source tree. |
 | `sync` | `dep sync [--cdn] [--flow <file>]` | Update `tsconfig` paths and generate `importmap` from resolver aliases. Use `--cdn` to prefer CDN targets when generating the importmap. |
 
 ### Flags
 
-- `--flow <file>`: Specify an alternate configuration file (for example `.df.json` or `depflow.json`). If omitted, the CLI defaults to `depflow.json` in the current working directory.
+- `--flow <file>` / `-f <file>` / `-p <file>`: Specify an alternate configuration file (for example `depflow.json` or `depflow.yaml`). When omitted, the CLI uses `depflow.yml` in the current working directory; any other file has to be named here.
 - `--cdn`: When present for `sync` or `rewrite-paths`, instructs the tool to use CDN targets from resolver entries instead of `local` targets when generating the `importmap` or rewriting paths.
 - `--watch` / `-w`: For `rewrite-paths` only — run a file watcher that keeps rewriting paths as files change.
 
+Every token starting with a dash is a flag, and a flag is the whole token, so short clusters are not expanded (`-abc` is the single flag `-abc`, not `-a -b -c`). A value flag takes the value from the next token when that token is not a flag, or written inline as `--flag=value`; a boolean flag never consumes the next token and only accepts `=true` or `=false` inline. Names are matched with or without their dash prefix, so `-f` and `--flow` reach the same flag. The last occurrence of a flag wins, `--` ends the flags and turns the remaining tokens into positional arguments, and an undeclared flag is reported as an error.
+
 Examples:
 
 ```bash
@@ -166,6 +222,15 @@ dep rewrite-paths --flow .df.json --watch
 
 ---
 
-If you want, I can also:
-- add quick examples for `tsconfig` path snippets generated by `dep sync`,
-- or produce a Spanish summary for quick internal reference.
+## Build steps in depth
+
+A `run` step is the only place where a shell script is interpreted, and it is where the failure semantics
+live:
+
+- every command of the step runs, even after one of them fails, so a build reports the whole picture;
+- `allowFails: true` turns a failed command into information: the step completes and the build continues;
+- `maxTimeMs` is a deadline for the whole step, not per command, and a deadline that is reached fails the
+  step even when `allowFails` is set: the work never finished, so the result is not the one that was asked for.
+
+The verdict of a step is awaited, never read from a log: a build that cannot do what it was configured to
+do fails, and the failure travels up to whoever asked for the build.

package/dist/builder/Builder.d.ts

@@ -0,0 +1,279 @@
+import type Logger from "@netfeez/vterm";
+import Task from "../task/Task.js";
+import OutputPolicy from "../task/OutputPolicy.js";
+import schema from "../schema/schema.js";
+export declare class Builder {
+    protected readonly pipeline: schema.Builder;
+    protected readonly cwd: string;
+    protected readonly projectRoot: string;
+    protected readonly logger: Logger | null;
+    protected readonly policy: OutputPolicy | null;
+    /** The step that stopped the pipeline, or `null` while it is still walking it. */
+    protected vStopped: Builder.Stopped | null;
+    constructor(info: Builder.Info);
+    /**
+     * 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.
+     */
+    run(): Promise<Builder.Report>;
+    /**
+     * 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.
+     */
+    protected walk(): Promise<Builder.StepReport[]>;
+    /**
+     * 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.
+     */
+    protected runStep(index: number, entry: schema.BuilderEntry): Promise<Builder.StepReport>;
+    /**
+     * 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.
+     */
+    protected runRun(index: number, entry: schema.RunEntry): Promise<Builder.StepReport>;
+    /**
+     * 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.
+     */
+    protected get steps(): number;
+    /**
+     * 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.
+     */
+    protected runTask(commands: string[], cwd: string, options: Task.Options, identity: OutputPolicy.Identity): Promise<Task.FinishData>;
+    /**
+     * 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.
+     */
+    protected runGlobalTransform(options: schema.GlobalTransform): Promise<void>;
+    /**
+     * 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.
+     */
+    protected resolveDestination(to: string): string;
+    /**
+     * 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.
+     */
+    protected runExtractor(entry: string | schema.Extractor): Promise<void>;
+    /**
+     * 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.
+     */
+    protected static replacer(replacer?: schema.Transform): Builder.Transformer;
+    /**
+     * 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.
+     */
+    protected static kind(entry: schema.BuilderEntry): Builder.Kind | 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.
+     */
+    protected static identity(index: number, steps: number): OutputPolicy.Identity;
+    /**
+     * 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.
+     */
+    protected static commandReport(result: Task.commandResult): Builder.CommandReport;
+    /**
+     * 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.
+     */
+    protected static settled(index: number, kind: Builder.Kind): Builder.StepReport;
+    /**
+     * 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.
+     */
+    protected static pending(index: number, kind: Builder.Kind | null): Builder.StepReport;
+    /**
+     * The report of a whole pipeline.
+     * @param steps - One report per step of the pipeline, in order.
+     * @returns The report of the run.
+     */
+    protected static report(steps: Builder.StepReport[]): Builder.Report;
+    /**
+     * 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.
+     */
+    protected static reason(report: Builder.Report): Builder.Reason;
+}
+export declare namespace Builder {
+    type Transformer = (str: string) => string;
+    type Kind = 'run' | 'extract' | 'transform';
+    type Entry = schema.RunEntry | schema.ExtractEntry | schema.TransformEntry;
+    type Reason = Task.Reason | 'command' | 'step';
+    interface Info {
+        pipeline: schema.Builder;
+        /**
+         * The folder the pipeline reads and works in: the checkout of a dependency, or the project itself
+         * for a `dep run` action. It is the base of every glob, of every `run` step and of every `map`.
+         */
+        cwd: string;
+        /**
+         * The root of the project the pipeline deposits into. It is the base of every relative `to` of an
+         * extraction step, which is where the artifacts of a dependency are meant to land.
+         */
+        projectRoot: string;
+        logger?: Logger | null;
+        /**
+         * The policy the output of the commands of the pipeline is reported through. Without it the
+         * builder falls back to the logger it was given, which streams the live output and says nothing
+         * else about it.
+         */
+        policy?: OutputPolicy | null;
+    }
+    /** What one command of a `run` step did, without what it printed. */
+    interface CommandReport {
+        /** The position of the command inside its step, starting at 1. */
+        ordinal: number;
+        /** The human readable form of the command, whole, as it was given. */
+        label: string;
+        /** Whether the command ended as it was asked to. */
+        success: boolean;
+        /** The exit status, or `null` when there was none. */
+        code: number | null;
+        /** The signal that took the command down, or `null` when there was none. */
+        signal: NodeJS.Signals | null;
+        /** Why there is no status at all, or `null` when the command reported one. */
+        reason: Task.Reason | null;
+        /** The time the command took, in milliseconds. */
+        time: number;
+    }
+    /**
+     * What one step of the pipeline did.
+     *
+     * @remarks The kind of a step is `null` only for an entry that describes no step at all, which the
+     * pipeline walks over: the report accounts for every entry of the pipeline, and an entry that runs
+     * nothing has no kind to account for it with.
+     */
+    interface StepReport {
+        /** The position of the step inside the pipeline, starting at 1. */
+        index: number;
+        /** The kind of the step, `null` when the entry describes none. */
+        kind: Kind | null;
+        /** Whether the step ran, `false` for the steps an earlier failure left behind. */
+        ran: boolean;
+        /** Whether the step ended as it was asked to. */
+        success: boolean;
+        /** How many commands of the step failed. */
+        failed: number;
+        /** Whether the step tolerated the failures it had, so the pipeline kept going. */
+        tolerated: boolean;
+        /** Why the step could not complete, or `null` when it completed. */
+        reason: Reason | null;
+        /** One report per command of a `run` step, empty for every other kind. */
+        commands: CommandReport[];
+    }
+    /** What a whole pipeline did. */
+    interface Report {
+        /** Whether every step of the pipeline ran and succeeded. */
+        ok: boolean;
+        /** How many commands ran, across every step. */
+        commands: number;
+        /** How many of them failed. */
+        failed: number;
+        /** How many of those failures a step tolerated, so the pipeline kept going. */
+        tolerated: number;
+        /** One report per step of the pipeline, in order, the ones that ran and the ones that did not. */
+        steps: StepReport[];
+    }
+    /** Why the pipeline stopped, and at which step, kept while the remaining steps are still being reported. */
+    interface Stopped {
+        index: number;
+        reason: Reason;
+    }
+    /**
+     * 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 {
+        readonly report: Report;
+        readonly reason: Reason;
+        /**
+         * Creates the failure of a pipeline.
+         * @param report - The report of the run.
+         * @param reason - Why the pipeline stopped.
+         */
+        constructor(report: Report, reason?: Reason);
+        /**
+         * 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.
+         */
+        private static message;
+    }
+}
+export default Builder;