@sous-io/plugin-api 0.0.0-stage → 1.0.1

package/dist/report-styles.d.ts

@@ -0,0 +1,220 @@
+/**
+ * The kinds of entry a reporter shows, and the facts each one carries in `details`. A style says what
+ * an entry IS, never how it looks: each front end's reporter decides that. A new style is added here
+ * when an output needs one, together with its convenience method in `BaseReporter` (reporter.ts),
+ * which is the only way callers produce it.
+ *
+ * Every styled message also carries a plain-text `message`, so a reporter that ignores styles (a
+ * log file, a test buffer) still has something readable.
+ */
+/** What kind of entry a reported message is. */
+export declare const ReportEntryStyle: {
+    /** A paragraph of text, which a front end may wrap. `details` is optional data. */
+    readonly Plain: "plain";
+    /** Text shown exactly as given: no wrapping, no color (a value printed for a script to read). No details. */
+    readonly Text: "text";
+    /** An explanation that is neither a warning nor an error. No details. */
+    readonly Note: "note";
+    /** The start of an operation, such as "Building the project". {@link OperationStartDetails}. */
+    readonly OperationStart: "operation-start";
+    /** A step inside the current operation, such as one target being compiled. {@link StepStartDetails}. */
+    readonly StepStart: "step-start";
+    /** One line of detail inside the current operation or step. No details. */
+    readonly Detail: "detail";
+    /** One action done (or to be done) to one target, such as a file written. {@link OperationDetails}. */
+    readonly Operation: "operation";
+    /** How an operation ended, such as "Done." {@link OperationEndDetails}. */
+    readonly OperationEnd: "operation-end";
+    /** One label and its value. The message is a `VariableSet`. */
+    readonly Variable: "variable";
+    /** Labels and values, read as one block, under an optional title. The message is a `VariableSet`. */
+    readonly VariableList: "variable-list";
+    /** The facts a command runs with: the project, its config, ... The message is a `VariableSet`. */
+    readonly CommandVariables: "command-variables";
+    /** A list of items, with an optional title and closing sentence. The message is an `ItemList`. */
+    readonly List: "list";
+    /** A table of rows. The message is a `Table`. */
+    readonly Table: "table";
+    /** Items nested under other items, such as each contributor and the changes it made. The message is a `Tree`. */
+    readonly Tree: "tree";
+    /** How many things were found. {@link CountDetails}. */
+    readonly Count: "count";
+    /** Says that a run is a dry run, or what a dry run left undone. No details. */
+    readonly DryRun: "dry-run";
+    /** Something wrong, with its cause and what to do about it. {@link ProblemDetails}. */
+    readonly Problem: "problem";
+    /** What a name on the command line resolved to, and why. {@link ResolvedReferenceFacts}. */
+    readonly ResolvedReference: "resolved-reference";
+    /** The question about to be asked, and where its answer goes. {@link QuestionDetails}. */
+    readonly Question: "question";
+    /** A command sous runs (or would run). {@link CommandDetails}. */
+    readonly Command: "command";
+    /** Progress through a longer step. {@link ProgressEvent}. */
+    readonly Progress: "progress";
+    /** A structured value, such as a command's result as data. The message is a `DataValue`. */
+    readonly Data: "data";
+    /** The sous banner. No details. */
+    readonly Banner: "banner";
+    /** A command's result: the message is `IntentOutputs`. */
+    readonly Result: "result";
+};
+/** One of the {@link ReportEntryStyle} values. */
+export type ReportEntryStyle = (typeof ReportEntryStyle)[keyof typeof ReportEntryStyle];
+/** {@link ReportEntryStyle.OperationStart}. */
+export interface OperationStartDetails {
+    /** What the operation does, in a few words: `Building the project`. */
+    readonly name: string;
+}
+/** {@link ReportEntryStyle.StepStart}. */
+export interface StepStartDetails {
+    /** What the step does or works on: `CLAUDE.md`. */
+    readonly name: string;
+}
+/**
+ * What was done to a target. The `would-` actions are a dry run's: what a real run would do.
+ *
+ * - `written`: created or changed.
+ * - `unchanged`: already as it should be; nothing written.
+ * - `skipped`: left alone on purpose (the note says why).
+ * - `failed`: not done because of an error.
+ * - `removed`: deleted, such as an output no target produces any more.
+ */
+export type OperationAction = "written" | "would-write" | "unchanged" | "skipped" | "failed" | "removed" | "would-remove";
+/** {@link ReportEntryStyle.Operation}. */
+export interface OperationDetails {
+    readonly action: OperationAction;
+    /** What the action was done to: usually an absolute file path. */
+    readonly target: string;
+    /** Why, or anything else worth knowing, in a few words: `left out by the transform "strip"`. */
+    readonly note?: string;
+    /** For a written file: roughly how many tokens it holds. */
+    readonly tokens?: number;
+}
+/** {@link ReportEntryStyle.OperationEnd}. */
+export interface OperationEndDetails {
+    /** Whether the operation succeeded. */
+    readonly ok: boolean;
+}
+/** One label and its value. */
+export interface VariableEntry {
+    /** The name on the left. An empty label continues the entry above. */
+    readonly label: string;
+    /** The value. */
+    readonly value: unknown;
+    /** A secondary fact (where it came from), shown less prominently after the value. */
+    readonly detail?: string;
+}
+/** What a column holds, which decides how it aligns and where it is cut. */
+export type ColumnKind = "text" | "path" | "url" | "number";
+/** What a column does with a cell too long for it. */
+export type ColumnOverflow = "wrap" | "truncate";
+/** Which end of a cell is given up when it is cut. */
+export type TruncateSide = "start" | "middle" | "end";
+/** Where a cell sits inside its column. */
+export type ColumnAlign = "left" | "right" | "center";
+/** How willingly a column is hidden when there is no room for it. */
+export type ColumnPriority = "low" | "medium" | "high";
+/** One column of a table. Every field after `header` is a hint a front end may ignore. */
+export interface TableColumn {
+    /** The property each row is read from. */
+    key: string;
+    /** The heading shown above the column. */
+    header: string;
+    /** Whether a long cell wraps onto more lines or is cut. Defaults to wrapping. */
+    overflow?: ColumnOverflow;
+    /** Which end a cut takes from. Defaults by kind: the middle of a path or a URL, the end of anything else. */
+    truncate?: TruncateSide;
+    /** What the column holds. Defaults to plain text. */
+    kind?: ColumnKind;
+    /** Where a cell sits in the column. Defaults to the right for a number, the left for everything else. */
+    align?: ColumnAlign;
+    /** This column's share of any width left over once every column has its natural width. Defaults to none. */
+    flex?: number;
+    /** The narrowest this column is ever squeezed to. Defaults to the width of its heading. */
+    minWidth?: number;
+    /** How willingly the column is hidden. A high column is never hidden; a low one goes first. Defaults to high. */
+    priority?: ColumnPriority;
+}
+/** One item of a `Tree` payload, with the items nested under it. */
+export interface TreeNode {
+    readonly label: string;
+    /** A secondary fact, shown less prominently after the label. */
+    readonly detail?: string;
+    readonly children?: readonly TreeNode[];
+}
+/** {@link ReportEntryStyle.Count}. */
+export interface CountDetails {
+    readonly count: number;
+    /** What was counted, already in the right number: `recipes`. */
+    readonly entity: string;
+    /** The verb before the count. Default `Found`; an empty string for none. */
+    readonly verb?: string;
+}
+/** {@link ReportEntryStyle.Problem}. */
+export interface ProblemDetails {
+    /** What went wrong, in one sentence. */
+    readonly summary: string;
+    /** Why: the underlying error or the facts behind it. */
+    readonly cause?: string;
+    /** What to do about it. */
+    readonly hint?: string;
+    /** What it is about, such as a file or a recipe. */
+    readonly subject?: string;
+    /** For a problem in a file: the line. */
+    readonly line?: number;
+}
+/** {@link ReportEntryStyle.ResolvedReference}: what a reference resolved to. */
+export interface ResolvedReferenceFacts {
+    /** What was typed. */
+    readonly search: string;
+    /** What it resolved to, in full. */
+    readonly resolvedTo: string;
+    /** What kind of thing it is: `recipe`, `namespace`, ... */
+    readonly kind: string;
+    readonly variable?: string;
+    readonly recipe?: string;
+    readonly namespace?: string;
+    readonly repository?: string;
+    readonly location?: string;
+    readonly description?: string;
+    /** Why this candidate won, in one sentence. */
+    readonly reason?: string;
+}
+/** {@link ReportEntryStyle.Question}. */
+export interface QuestionDetails {
+    /** Its place in the run: question `index` of `total`. */
+    readonly index: number;
+    readonly total: number;
+    /** The variable's name. */
+    readonly name: string;
+    readonly description?: string;
+    readonly example?: string;
+    /** The recipe that asks it. */
+    readonly recipe?: string;
+    /** The file its answer goes into. */
+    readonly storedIn?: string;
+    /** The environment variable name its answer is stored as. */
+    readonly storedAs?: string;
+}
+/** {@link ReportEntryStyle.Command}. */
+export interface CommandDetails {
+    readonly command: string;
+    readonly args: readonly string[];
+    /** The directory it runs in. */
+    readonly cwd?: string;
+    /** True when it would run, but a dry run does not run it. */
+    readonly dryRun?: boolean;
+}
+/** {@link ReportEntryStyle.Progress}: progress through a longer step, such as downloading recipes. */
+export interface ProgressEvent {
+    /** What is in progress, in a few words: `Downloading recipes`. */
+    label: string;
+    /** How far along: items done so far. */
+    done?: number;
+    /** How far along: items in total, when known. */
+    total?: number;
+    /** The item being worked on now. */
+    item?: string;
+    /** True on the last event of this label. */
+    finished?: boolean;
+}

package/dist/report-styles.js

@@ -0,0 +1,60 @@
+/**
+ * The kinds of entry a reporter shows, and the facts each one carries in `details`. A style says what
+ * an entry IS, never how it looks: each front end's reporter decides that. A new style is added here
+ * when an output needs one, together with its convenience method in `BaseReporter` (reporter.ts),
+ * which is the only way callers produce it.
+ *
+ * Every styled message also carries a plain-text `message`, so a reporter that ignores styles (a
+ * log file, a test buffer) still has something readable.
+ */
+/** What kind of entry a reported message is. */
+export const ReportEntryStyle = {
+    /** A paragraph of text, which a front end may wrap. `details` is optional data. */
+    Plain: "plain",
+    /** Text shown exactly as given: no wrapping, no color (a value printed for a script to read). No details. */
+    Text: "text",
+    /** An explanation that is neither a warning nor an error. No details. */
+    Note: "note",
+    /** The start of an operation, such as "Building the project". {@link OperationStartDetails}. */
+    OperationStart: "operation-start",
+    /** A step inside the current operation, such as one target being compiled. {@link StepStartDetails}. */
+    StepStart: "step-start",
+    /** One line of detail inside the current operation or step. No details. */
+    Detail: "detail",
+    /** One action done (or to be done) to one target, such as a file written. {@link OperationDetails}. */
+    Operation: "operation",
+    /** How an operation ended, such as "Done." {@link OperationEndDetails}. */
+    OperationEnd: "operation-end",
+    /** One label and its value. The message is a `VariableSet`. */
+    Variable: "variable",
+    /** Labels and values, read as one block, under an optional title. The message is a `VariableSet`. */
+    VariableList: "variable-list",
+    /** The facts a command runs with: the project, its config, ... The message is a `VariableSet`. */
+    CommandVariables: "command-variables",
+    /** A list of items, with an optional title and closing sentence. The message is an `ItemList`. */
+    List: "list",
+    /** A table of rows. The message is a `Table`. */
+    Table: "table",
+    /** Items nested under other items, such as each contributor and the changes it made. The message is a `Tree`. */
+    Tree: "tree",
+    /** How many things were found. {@link CountDetails}. */
+    Count: "count",
+    /** Says that a run is a dry run, or what a dry run left undone. No details. */
+    DryRun: "dry-run",
+    /** Something wrong, with its cause and what to do about it. {@link ProblemDetails}. */
+    Problem: "problem",
+    /** What a name on the command line resolved to, and why. {@link ResolvedReferenceFacts}. */
+    ResolvedReference: "resolved-reference",
+    /** The question about to be asked, and where its answer goes. {@link QuestionDetails}. */
+    Question: "question",
+    /** A command sous runs (or would run). {@link CommandDetails}. */
+    Command: "command",
+    /** Progress through a longer step. {@link ProgressEvent}. */
+    Progress: "progress",
+    /** A structured value, such as a command's result as data. The message is a `DataValue`. */
+    Data: "data",
+    /** The sous banner. No details. */
+    Banner: "banner",
+    /** A command's result: the message is `IntentOutputs`. */
+    Result: "result",
+};

package/dist/reporter.d.ts

@@ -0,0 +1,270 @@
+/**
+ * Reporting: services and intents never print. They report through the `Reporter` the front
+ * end handed over with the chain (`ctx.reporter`), and the front end decides how it looks.
+ *
+ * Every message goes through one method, `log(level, message, details?, style?)`. The level says how
+ * important it is, `details` carries its facts, and the style says what kind of entry it is (an
+ * operation, a labeled value, a table, ...). Each front end's reporter decides how each style looks:
+ * the CLI draws it with colors and alignment, MCP sends `details` as data. On top of `log` sit one
+ * method per level (`info`, `warn`, ...) and one or more methods per style (`operationStart`, ...),
+ * all defined once, in {@link BaseReporter}.
+ */
+import { IntentOutputs, Payload } from "./outputs.js";
+import { type CommandDetails, type OperationAction, type OperationDetails, type ProblemDetails, type ProgressEvent, type QuestionDetails, ReportEntryStyle, type ResolvedReferenceFacts, type TableColumn, type TreeNode, type VariableEntry } from "./report-styles.js";
+export { ReportEntryStyle } from "./report-styles.js";
+export type * from "./report-styles.js";
+/** The eight syslog levels, by name. */
+export declare const LogLevel: {
+    readonly Debug: "debug";
+    readonly Info: "info";
+    readonly Notice: "notice";
+    readonly Warning: "warning";
+    readonly Error: "error";
+    readonly Critical: "critical";
+    readonly Alert: "alert";
+    readonly Emergency: "emergency";
+};
+/** One of the eight syslog levels. */
+export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
+/** The eight syslog levels, from least to most severe. */
+export declare const LOG_LEVELS: readonly LogLevel[];
+/** Whether a string names a log level. */
+export declare function isLogLevel(value: unknown): value is LogLevel;
+/**
+ * Whether a message at `level` shows when the threshold is `threshold`.
+ *
+ * ```ts
+ * isLevelShown("warning", "notice");   // true
+ * isLevelShown("debug", "info");       // false
+ * ```
+ */
+export declare function isLevelShown(level: LogLevel, threshold: LogLevel): boolean;
+/**
+ * What a reported message is, for people: text; an `Error`, shown with its whole cause chain; a
+ * payload (a `VariableSet`, a `Table`, ...); or, for a command's result, `IntentOutputs`.
+ */
+export type ReportMessage = string | Error | Payload | IntentOutputs<object>;
+/**
+ * The text of any message: an error's chain one cause per line, a payload's or outputs' text.
+ *
+ * ```ts
+ * messageText(new Error("Could not download", { cause: new Error("DNS failed") }));
+ * // "Could not download\nCaused by: DNS failed"
+ * ```
+ */
+export declare function messageText(message: ReportMessage): string;
+/** An error and every error under it through `cause`, outermost first (a cycle stops it). */
+export declare function errorChain(error: Error): Error[];
+/**
+ * The facts a message carries, which a front end may show or keep (MCP sends them as data). For a
+ * styled message, its style's details type (`OperationDetails` for `ReportEntryStyle.Operation`, ...).
+ */
+export type ReportDetails = object;
+/**
+ * The shared part of every reporter, and the ONE place every reporting method is defined.
+ * `Reporter`, the type plugins see, is derived from this class's public members, and the
+ * {@link Reporting} mixin copies its convenience methods onto other classes, so a method added here
+ * reaches every reporter and every class that mixes it in.
+ *
+ * A subclass writes a message that passes the threshold (`write`); everything else is shared.
+ *
+ * ```ts
+ * class LinesReporter extends BaseReporter {
+ *     readonly lines: string[] = [];
+ *
+ *     protected write(level: LogLevel, message: string): void {
+ *         this.lines.push(`${level}: ${message}`);
+ *     }
+ * }
+ *
+ * const reporter = new LinesReporter(LogLevel.Warning);
+ * reporter.notice("Skipped.");   // below the threshold: dropped
+ * reporter.warn("Stale.");       // lines: ["warning: Stale."]
+ * ```
+ */
+export declare abstract class BaseReporter {
+    private readonly thresholdSource;
+    /**
+     * @param thresholdSource - The least severe level shown (default `debug`, everything). A function
+     *   is read on every message, for a threshold that changes while the reporter is in use.
+     */
+    constructor(thresholdSource?: LogLevel | (() => LogLevel));
+    /** The least severe level shown now. */
+    protected threshold(): LogLevel;
+    /** Whether a message at `level` passes the threshold now. */
+    protected shows(level: LogLevel): boolean;
+    /** Writes one message that passed the threshold, in the way this reporter shows `style`. */
+    protected abstract write(level: LogLevel, message: ReportMessage, details: ReportDetails | undefined, style: ReportEntryStyle): void;
+    /**
+     * Reports one message. Every other reporting method ends here.
+     *
+     * @param style - What kind of entry it is (default `ReportEntryStyle.Plain`, a paragraph).
+     */
+    log(level: LogLevel, message: ReportMessage, details?: ReportDetails, style?: ReportEntryStyle): void;
+    /** Reports a message for whoever is debugging sous. */
+    debug(message: string | Error, details?: ReportDetails, style?: ReportEntryStyle): void;
+    /** Reports an ordinary message. */
+    info(message: string | Error, details?: ReportDetails, style?: ReportEntryStyle): void;
+    /** Reports a normal but significant event. */
+    notice(message: string | Error, details?: ReportDetails, style?: ReportEntryStyle): void;
+    /** Reports something that may need the user's attention. */
+    warning(message: string | Error, details?: ReportDetails, style?: ReportEntryStyle): void;
+    /** Shorthand for {@link warning}. */
+    warn(message: string | Error, details?: ReportDetails, style?: ReportEntryStyle): void;
+    /** Reports something that failed. */
+    error(message: string | Error, details?: ReportDetails, style?: ReportEntryStyle): void;
+    /** Reports a failure that stops the run. */
+    critical(message: string | Error, details?: ReportDetails, style?: ReportEntryStyle): void;
+    /** Reports something that must be acted on at once. */
+    alert(message: string | Error, details?: ReportDetails, style?: ReportEntryStyle): void;
+    /** Reports that sous cannot work at all. */
+    emergency(message: string | Error, details?: ReportDetails, style?: ReportEntryStyle): void;
+    /** Shorthand for {@link emergency}. */
+    emerg(message: string | Error, details?: ReportDetails, style?: ReportEntryStyle): void;
+    /** Text shown exactly as given, such as a value a script reads: no wrapping, no color. */
+    text(content: string, level?: LogLevel): void;
+    /** An explanation that is neither a warning nor an error. */
+    note(text: string, level?: LogLevel): void;
+    /** The start of an operation: `Building the project`. */
+    operationStart(operationName: string, level?: LogLevel): void;
+    /** A step inside the current operation: one target, one recipe, one check. */
+    stepStart(stepName: string, level?: LogLevel): void;
+    /** One line of detail inside the current operation or step: `Read 12 recipes.` */
+    detail(text: string, level?: LogLevel): void;
+    /**
+     * One action done (or, in a dry run, to be done) to one target. The level defaults to `error`
+     * for `failed` and `info` for everything else.
+     *
+     * ```ts
+     * reporter.operation("written", "/work/app/CLAUDE.md", { tokens: 1840 });
+     * reporter.operation("skipped", "/work/app/AGENTS.md", { note: 'left out by the transform "strip"' });
+     * ```
+     */
+    operation(action: OperationAction, target: string, facts?: Omit<OperationDetails, "action" | "target">, level?: LogLevel): void;
+    /** How an operation ended: `Done.`, or `Done with 2 errors.` The level defaults to `info`, or `error` when it failed. */
+    operationEnd(summary: string, ok?: boolean, level?: LogLevel): void;
+    /** One label and its value: `Repository: /work/recipes`. */
+    variable(label: string, value: unknown, detail?: string, level?: LogLevel): void;
+    /**
+     * Labels and values, read as one block (a terminal lines their colons up). A record is read as
+     * label and value pairs, in its key order.
+     */
+    variables(entries: readonly VariableEntry[] | Readonly<Record<string, unknown>>, title?: string, level?: LogLevel): void;
+    /** The facts a command runs with (its project, its config, what it reads), shown before its output. */
+    commandVariables(entries: readonly VariableEntry[] | Readonly<Record<string, unknown>>, level?: LogLevel): void;
+    /** A list of items, with an optional title before it and an optional sentence after it. */
+    list(items: readonly string[], options?: {
+        title?: string;
+        footer?: string;
+    }, level?: LogLevel): void;
+    /**
+     * A table of rows. With no rows, a front end shows `options.empty` when it is given;
+     * `options.rowNotes[i]` is a note shown under row `i`.
+     */
+    table(columns: readonly TableColumn[], rows: readonly Readonly<Record<string, unknown>>[], options?: {
+        title?: string;
+        empty?: string;
+        rowNotes?: readonly (string | undefined)[];
+    }, level?: LogLevel): void;
+    /** Items nested under other items, such as each contributor and the changes it made. */
+    tree(nodes: readonly TreeNode[], title?: string, level?: LogLevel): void;
+    /** How many things were found: `Found 5 recipes`. `entity` is already in the right number. */
+    count(count: number, entity: string, verb?: string, level?: LogLevel): void;
+    /** Says that a run is a dry run, or what a dry run left undone: `Nothing was written.` */
+    dryRun(text: string, level?: LogLevel): void;
+    /**
+     * Something wrong, with its cause and what to do about it. A one-sentence warning with nothing
+     * more to say is `warn(text)` instead.
+     *
+     * ```ts
+     * reporter.problem("The compilation transform \"strip\" is not registered.", { subject: "CLAUDE.md", hint: "Install the plugin that adds it." });
+     * ```
+     */
+    problem(summary: string, facts?: Omit<ProblemDetails, "summary">, level?: LogLevel): void;
+    /** What a name on the command line resolved to, and why (`reason`, one sentence). */
+    resolvedReference(reason: string, facts: ResolvedReferenceFacts, level?: LogLevel): void;
+    /** The question about to be asked, and where its answer goes. */
+    question(facts: QuestionDetails, level?: LogLevel): void;
+    /** A command sous runs, or (with `dryRun`) would run. */
+    command(command: string, args: readonly string[], facts?: Omit<CommandDetails, "command" | "args">, level?: LogLevel): void;
+    /**
+     * Progress through a longer step. A terminal draws one bar and redraws it in place; the event
+     * with `finished: true` ends it.
+     */
+    progress(event: ProgressEvent, level?: LogLevel): void;
+    /** A structured value shown as data (a config as JSON). */
+    data(value: unknown, level?: LogLevel): void;
+    /**
+     * A command's result: what its intent returned. A terminal sends it to standard output, and
+     * everything else to standard error.
+     */
+    result(outputs: IntentOutputs<object>, level?: LogLevel): void;
+    /** The sous banner. */
+    banner(level?: LogLevel): void;
+}
+/**
+ * Where a chain's output goes: every public method of {@link BaseReporter}. Each front end supplies
+ * its own (the CLI writes to the terminal, MCP sends log notifications) by extending `BaseReporter`.
+ */
+export type Reporter = {
+    [K in keyof BaseReporter]: BaseReporter[K];
+};
+/** The reporting methods {@link Reporting} copies onto a class: every one except `log`. */
+export type ReportingMethods = Omit<Reporter, "log">;
+/** A class, abstract or not. */
+export type AbstractConstructor<T = object> = abstract new (...args: any[]) => T;
+/**
+ * Gives a class every reporting method of {@link BaseReporter} (`info`, `warn`, `operationStart`,
+ * ...) as a shorthand for the same method on its `reporter`, which the class provides. The methods
+ * are copied from `BaseReporter.prototype` when the mixin is applied, so nothing lists them twice.
+ * They are public, since a type can only make a member protected inside a class body.
+ *
+ * ```ts
+ * class Compiler extends Reporting(Object) {
+ *     constructor(private readonly deps: { reporter: Reporter }) {
+ *         super();
+ *     }
+ *
+ *     protected get reporter(): Reporter {
+ *         return this.deps.reporter;
+ *     }
+ *
+ *     run(): void {
+ *         this.info("Compiling");   // this.deps.reporter.info("Compiling")
+ *     }
+ * }
+ * ```
+ */
+export declare function Reporting<TBase extends AbstractConstructor>(Base: TBase): TBase & AbstractConstructor<ReportingMethods>;
+/** One message a {@link BufferedReporter} kept. */
+export interface ReportedMessage {
+    level: LogLevel;
+    message: ReportMessage;
+    details?: ReportDetails;
+    style: ReportEntryStyle;
+}
+/**
+ * Builds a reporter from a function that receives every message, whatever its level.
+ *
+ * ```ts
+ * const reporter = createReporter((level, message) => lines.push(`${level}: ${message}`));
+ * reporter.warn("Recipe X declares a variable no template reads.");
+ * ```
+ */
+export declare function createReporter(log: (level: LogLevel, message: ReportMessage, details: ReportDetails | undefined, style: ReportEntryStyle) => void): Reporter;
+/** A reporter that drops everything. */
+export declare const nullReporter: Reporter;
+/**
+ * A reporter that keeps every message, to hand on later ({@link flushTo}) or to read in tests.
+ */
+export declare class BufferedReporter extends BaseReporter {
+    /** Every message, in order. */
+    readonly messages: ReportedMessage[];
+    protected write(level: LogLevel, message: ReportMessage, details: ReportDetails | undefined, style: ReportEntryStyle): void;
+    /** The text of the messages at a level ({@link messageText}). */
+    at(level: LogLevel): string[];
+    /** The messages of a style. */
+    styled(style: ReportEntryStyle): ReportedMessage[];
+    /** Sends every kept message to another reporter, in order, and forgets them. */
+    flushTo(reporter: Reporter): void;
+}