/**
 * The narrative — what a handler says about its work on the trace, in the
 * words the console leads with. A step's narrator reaches the handler as the
 * argument of its `ctx.step` callback; the action's own is `ctx.trace`.
 *
 * Everything here is best effort: with no tracing configured it is silent,
 * and nothing a narrator does can fail an action. The console names a node
 * from `explain.title` first (the plan's title stands in when a handler
 * leaves it out), leads with `what`, and keeps `why` / `impact` / `next`
 * under it — so say what happened with the facts in it, and why.
 */

export interface Explanation {
  /** The node's display name. Defaults to the plan's title for this step (or action). */
  title?: string;
  /** What happened, in one sentence with the facts in it. */
  what?: string;
  /** Why it was done, or why it went the way it did. */
  why?: string;
  /** What it means for the reader. */
  impact?: string;
  /** What to do now, when there is something to do. */
  next?: string;
  severity?: "ok" | "warn" | "error";
}

/** Somewhere to go from the node: the job run, the bundle folder, the commit. */
export interface ExternalLink {
  rel: string;
  uri: string;
  label?: string;
}

export interface Narrative {
  /** `tracing.explain` — the plain words the console leads with. Later calls replace earlier ones. */
  explain(body: Explanation): void;
  /** `tracing.external_links` — a link out of the node. */
  link(link: ExternalLink): void;
  /** `tracing.output` — a fact worth keeping as data (ids, hosts, versions). */
  output(name: string, value: unknown): void;
}

/** Says nothing: the narrator with no tracing behind it. */
export const silentNarrative: Narrative = {
  explain() {},
  link() {},
  output() {},
};