@effected/cli 0.11.0 → 0.13.0

package/index.d.ts

@@ -493,7 +493,9 @@ export declare class Status<Names extends string> {
    * that draws it itself (an Ink tree, a reporter).
    *
    * @remarks
-   * Throws on an unknown name, as {@link Status.def} does.
+   * Throws on an unknown name, as {@link Status.def} does. The glyph is sanitised, as text in a document is: escape
+   * sequences and control characters in a vocabulary's glyph are removed, so a glyph built from data cannot paint the
+   * terminal, plant a hyperlink or move the cursor. Every kit path that draws a status glyph takes it from here.
    *
    * @param name - a name in this vocabulary
    * @param glyphs - the glyph set, such as `Glyphs.unicode`, `Glyphs.ascii` or a theme's
@@ -567,7 +569,10 @@ interface StreamTheme {
   readonly glyphs: GlyphSet;
   /** The colour level of the stream. */
   readonly color: ColorLevel;
-  /** Render a status from a vocabulary: its glyph, painted with its token, then `text` when given. */
+  /**
+   * Render a status from a vocabulary: its glyph, sanitised (see `Status.glyph`) and painted with its token, then
+   * `text` when given, as it is: sanitising `text` is the caller's, as `CliMessage` and `CliLog.status` do.
+   */
   readonly status: <N extends string>(vocab: Status<N>, name: N, text?: string) => string;
 }
 /**
@@ -617,6 +622,30 @@ export declare class CliTheme extends CliTheme_base {
    * @param options - token overrides and the glyph set
    */
   static readonly layer: (options?: CliThemeOptions) => Layer.Layer<CliTheme, never, TerminalEnv>;
+  /**
+   * The theme an audience sees of `theme`: for an agent, the same theme at colour `none` (`paint` the identity, `sgr`
+   * empty, `status` unpainted), whatever the terminal could do, because an agent never gets an escape of any kind; for
+   * anyone else, or when the audience is not known, `theme` itself.
+   *
+   * @remarks
+   * The one rule the kit applies wherever it paints for an audience: `Render.context` takes its colour and `paint`
+   * from it, `CliMessage` and `CliLog.status` paint their glyphs through it, and `./ui` gives it to the trees it
+   * mounts, so `useTheme`, `Styled` and the widgets' colour-`none` text markers all agree. A program that paints its
+   * own lines applies the same rule with it rather than re-implementing it:
+   *
+   * ```ts
+   * const line = Effect.gen(function* () {
+   *   const theme = CliTheme.forAudience((yield* CliTheme).forStream("stdout"), (yield* Audience).kind)
+   *   return theme.status(Status.core, "success", Fmt.sanitize(name))
+   * })
+   * ```
+   *
+   * Pure: it reads nothing, so the audience is the caller's to pass, `undefined` when it is not known.
+   *
+   * @param theme - a stream's theme, such as `CliTheme.forStream("stdout")`
+   * @param audience - who the output is for, or `undefined` when that is not known
+   */
+  static readonly forAudience: (theme: StreamTheme, audience: AudienceKind | undefined) => StreamTheme;
   /**
    * A fixed theme that needs nothing; `none` colour and Unicode glyphs unless told otherwise.
    *
@@ -738,8 +767,16 @@ interface Column {
 interface Counter {
   /** A stable identifier, for a caller's total rule. */
   readonly key: string;
-  /** What the counter is called when shown. */
-  readonly label: string;
+  /**
+   * What the counter is called when shown: one label, or a singular and a plural form, `one` for a count of exactly 1
+   * and `other` for any other, 0 included. The count is the counter's own `n`, except in a share headline
+   * (`1/3 repos`), which reads by the total. A `CountsTable` heads its column with `other`, since the column holds
+   * every row's count.
+   */
+  readonly label: string | {
+    readonly one: string;
+    readonly other: string;
+  };
   /** The count. */
   readonly n: number;
   /** The status the count is painted with. */
@@ -767,7 +804,7 @@ interface Counter {
  * - `CountsTable`: a table of `Counts` rows, a column per counter key, a `duration` column when some row has one, and
  *   an optional summed total row.
  * - `Lines`: one line per entry; markdown keeps them apart with hard breaks.
- * - `Line`: one line, which `truncate` cuts to the width instead of wrapping.
+ * - `Line`: one line, which `truncate` cuts to the width instead of wrapping, and `wrap: false` keeps whole.
  * - `DiffText`: a unified diff, as given; `truncate` cuts each line to the width.
  * - A `List` may be `compact`, with no blank lines between an item's children (a blank line of an item's own content
  *   keeps the item's indent in plain and `ansi`), and a `Table` may be `style: "pipe"`.
@@ -846,6 +883,7 @@ type Block = {
   readonly _tag: "Line";
   readonly content: ReadonlyArray<Inline>;
   readonly truncate?: boolean;
+  readonly wrap?: boolean;
 } | {
   readonly _tag: "DiffText";
   readonly text: string;
@@ -1208,6 +1246,11 @@ export declare class Doc {
   /**
    * Children under an optional title.
    *
+   * @remarks
+   * The children are separated by blank lines (unless the document is compact); a title sits directly above the first.
+   * `Doc.section(undefined, blocks)` is the way to space a document's top-level blocks, which are otherwise joined with
+   * no blank line.
+   *
    * @param title - the title, or `undefined` for none
    * @param children - the blocks
    */
@@ -1218,13 +1261,22 @@ export declare class Doc {
    * @remarks
    * A name the vocabulary does not have is a compile error.
    *
+   * The label is one string, or `{ one, other }` to pluralise by count: `one` when the count is exactly 1 and `other`
+   * for every other count, 0 included. A count standing alone reads by its own `n` (`1 change`, `2 changes`); a
+   * headline shown as a share of the total reads by that total, the noun it counts (`1/1 repo`, `1/3 repos`,
+   * `2/3 repos`).
+   *
    * @param vocab - the vocabulary the status belongs to
    * @param name - a status name in it
-   * @param options - the counter's `key`, `label` and count `n`, and `showZero` to keep it when `n` is zero
+   * @param options - the counter's `key`, its `label` (one string, or `{ one, other }`), its count `n`, and `showZero`
+   * to keep it when `n` is zero
    */
   static counter<N extends string>(vocab: Status<N>, name: NoInfer<N>, options: {
     readonly key: string;
-    readonly label: string;
+    readonly label: string | {
+      readonly one: string;
+      readonly other: string;
+    };
     readonly n: number;
     readonly showZero?: boolean;
   }): Counter;
@@ -1264,17 +1316,22 @@ export declare class Doc {
    */
   static lines(lines: ReadonlyArray<InlineInput>): BlockOf<"Lines">;
   /**
-   * One line of content; with `truncate`, it is cut to the width with the glyph set's ellipsis instead of wrapping.
+   * One line of content; with `truncate`, it is cut to the width with the glyph set's ellipsis instead of wrapping,
+   * and with `wrap: false` it is kept whole on one line whatever the width.
    *
    * @remarks
-   * Without `truncate` a line longer than the width wraps. For a single line that must never wrap nor be cut, such
-   * as a test's full name used as a title, use {@link Doc.verbatim}.
+   * By default a line longer than the width wraps. `wrap: false` keeps it atomic in every audience and renderer, still
+   * carrying its status glyphs, theme tokens and links, which {@link Doc.verbatim} (a plain string) cannot: the tool for
+   * a finding such as `✗ path:line:col  rule  message` that a reader greps or reads line by line, while the prose around
+   * it still wraps. A line break inside it is still a space. With both `truncate` and `wrap: false`, `truncate` wins:
+   * the line is cut to the width.
    *
    * @param content - the line
-   * @param options - `truncate`
+   * @param options - `truncate`, to cut it to the width; `wrap: false`, to keep it whole
    */
   static line(content: InlineInput, options?: {
     readonly truncate?: boolean;
+    readonly wrap?: boolean;
   }): BlockOf<"Line">;
   /**
    * A unified diff as given, such as a test runner's: sanitized, its `+` and `-` lines painted `success` and
@@ -1345,11 +1402,15 @@ export declare class Doc {
    * The context is {@link Render.context} for the stream, so the width, the colour, the links and the audience
    * come from the services the program already has, and the text is written with `Console.log` or
    * `Console.error`: a test captures it by swapping the `Console`. With `format: "auto"` the renderer follows
-   * the audience, and the width is unbounded for an agent and a CI.
+   * the audience, and the width is unbounded for an agent, a CI, and a human whose stream is not a terminal.
    *
    * An agent is never written an escape of any kind, even with an explicit `format: "ansi"`: its context is
    * colourless and its links are off. A document that renders to nothing prints nothing.
    *
+   * The whole document is written as one `Console.log` (or `Console.error`) call, with its line breaks embedded, so a
+   * captured `Console` holds one entry per document, not one per line. Top-level blocks are joined with no blank
+   * line between them; wrap them in `Doc.section(undefined, [...])` to space them.
+   *
    * `CurrentRuntimeEnv` is read if the environment has one and is not required: a `ci` audience prints
    * GitHub's log format only when it says GitHub Actions, and plain text otherwise, including when it is
    * absent. An explicit `format` is honoured whatever the audience.
@@ -1565,6 +1626,24 @@ export declare class CliLogger {
 }
 //#endregion
 //#region src/CliLog.d.ts
+/**
+ * Options for `CliLog.status`.
+ *
+ * @public
+ */
+interface CliLogStatusOptions {
+  /**
+   * The level the line is logged at. By default it follows the status's rank in its vocabulary: `Error` at or above
+   * `failure`'s rank, `Warn` at or above `warning`'s, and `Info` below that.
+   */
+  readonly level?: LogLevel.Severity | undefined;
+  /**
+   * What the line starts with, before the glyph, so an indented report line keeps its place in a block: a number of
+   * spaces (floored, at most 64; zero, a negative or a non-finite number is none), or a string. A string is sanitised as text is (escapes and controls removed, a tab a space) and its line
+   * breaks dropped, so the indent can never carry an escape onto the trusted line. None by default.
+   */
+  readonly indent?: number | string | undefined;
+}
 /**
  * Options for `CliLog.layer`.
  *
@@ -1861,6 +1940,41 @@ export declare class CliLog {
    * @param options - the level, the env var, the format, the `CliLogger` options and the file sink
    */
   static layer(options: CliLogFileOptions): Layer.Layer<never, never, Audience | TerminalEnv | FileSystem.FileSystem | Path.Path>;
+  /**
+   * Log a status line: its glyph painted through the theme, then `text`, at a level that follows the status.
+   *
+   * @remarks
+   * The line goes through the logger, so it is a diagnostic like any `Effect.log*` call: filtered by the level in
+   * force (`--log-level`, `CliLog.Level`), routed by `CliLogger`'s `stderrFrom` (stderr by default) and neutralized
+   * under GitHub Actions. What differs is the glyph: the logger sanitises every line a program logs, which strips a
+   * colour a program painted itself, so a glyph on the log channel was always drawn bare. Here the kit paints it and
+   * marks the line as its own, so the plain `CliLogger` line keeps the colour, while `text` is still sanitised:
+   * escape sequences and control characters in it are removed, as in every line the kit writes.
+   *
+   * The glyph is painted with stderr's theme (where diagnostics go) through {@link CliTheme.forAudience}, so an agent
+   * gets it unpainted, and an `Audience` is read only when provided, so it stays out of the requirements. ASCII glyphs
+   * give the status's ASCII form. A diagnostics record carries the line as its message as any record does: the `CliLog`
+   * sink's pretty line sanitises it (the glyph is drawn bare there), and NDJSON keeps it, JSON-escaped.
+   *
+   * The level defaults to the status's rank in `vocab`: `Error` at or above `failure`'s, `Warn` at or above
+   * `warning`'s, `Info` below, so a custom status follows its own rank. Pass `level` to choose it, and `indent` (a
+   * number of spaces, or a string, sanitised) to start the line inside an indented block: `    ✗ error   x: red`.
+   *
+   * @example
+   * ```ts
+   * import { CliLog, Status } from "@effected/cli"
+   *
+   * // ✗ in the failure colour, then the message: on stderr, filtered by the log level.
+   * const reportError = (resource: string, message: string) =>
+   *   CliLog.status(Status.core, "failure", `${resource}: ${message}`)
+   * ```
+   *
+   * @param vocab - the vocabulary the status belongs to
+   * @param name - the status
+   * @param text - the text after the glyph, sanitised
+   * @param options - the level to log at, and the indent before the glyph
+   */
+  static readonly status: <N extends string>(vocab: Status<N>, name: N, text: string, options?: CliLogStatusOptions) => Effect.Effect<void, never, CliTheme>;
   /**
    * Mark the log records an effect emits as coming from `name`.
    *
@@ -1935,6 +2049,27 @@ interface CliEnvOptions {
    * `CliRuntime.main` reads this.
    */
   readonly stackFrames?: "app" | "all" | undefined;
+  /**
+   * Which spans the default failure report's `in: outer › inner` trail names: `app`, the default, leaves out the spans
+   * the kit's own packages and Effect define (judged by the file of each span's definition site under `node_modules`),
+   * `all` shows every span, and `off` drops the trail. Applies to the report `main` writes,
+   * `FailureDetails.defaultLines` and `FailureDetails.lines`. Only `CliRuntime.main` reads this.
+   */
+  readonly spans?: "app" | "all" | "off" | undefined;
+  /**
+   * The environment variable that sets `spans` at run time (`app`, `all` or `off`, case-insensitive), read through
+   * `Config`, as `log.envVar` sets the log level: so a user filing a bug can run `TOOL_SPANS=all tool …` without a
+   * rebuild. `spans` beats it (the variable is then not read at all); unset or empty is the default; a value that is
+   * not a setting is ignored with one warning. Not read unless named. Only `CliRuntime.main` reads this.
+   */
+  readonly spansEnvVar?: string | undefined;
+  /**
+   * A module of the running program itself, as a `file:` URL or an absolute path: pass the bin's `import.meta.url`.
+   * `spans: "app"` keeps the spans of the package that holds it, even when it is installed under
+   * `node_modules/@effected/` (a kit companion's bin); see `CliFailureOptions.appModule`. Only `CliRuntime.main`
+   * reads this.
+   */
+  readonly appModule?: string | undefined;
   /** Whether file links open in an editor; `auto` by default. See {@link CliLinks}. */
   readonly editorLinks?: EditorLinks | undefined;
   /** The environment variable that overrides `editorLinks`, read through `Config`. Not read unless named. */
@@ -2137,6 +2272,32 @@ interface CliFailureOptions {
    * shows every frame, unfiltered.
    */
   readonly stackFrames?: "app" | "all" | undefined;
+  /**
+   * Which spans the `in: outer › inner` trail after a failure names. `app`, the default, leaves out the spans the kit
+   * and Effect define themselves: a span whose definition site (an `Effect.fn`'s, or where the span was opened) is a
+   * file under `node_modules/@effected/` or `node_modules/effect/`. A config that fails to decode under
+   * `@effected/config-file` then reports no `ConfigFile.loadFrom` trail, while the program's own spans stay. `all`
+   * shows every span, and `off` drops the trail. Under either, an `Effect.fn` call and its definition are one entry,
+   * `name`, never `name (definition) › name`.
+   *
+   * @remarks
+   * The rule reads file paths, never span names, and it fails open: when it cannot tell, it shows the span. A span
+   * with no captured stack is kept. A kit package linked into a workspace (`link:`, `workspace:`) runs from its own
+   * checkout rather than from `node_modules`, so its spans show as the program's. A bundled program is one file, so
+   * `app` shows what `all` does, unless the bundle is itself installed under `node_modules/@effected/`. A program that
+   * is installed under `node_modules/@effected/` (a kit companion's bin) names itself with `appModule`, or its own
+   * spans are left out with the kit's.
+   */
+  readonly spans?: "app" | "all" | "off" | undefined;
+  /**
+   * A module of the running program itself, as a `file:` URL or an absolute path: its bin's `import.meta.url`. With
+   * `spans: "app"`, a span defined in the installed package that holds this module is the program's, kept even under
+   * `node_modules/@effected/`, while the packages it depends on (beside it, or nested in its own `node_modules`) are
+   * still left out. The package is the path through the last `node_modules/<name>` (or `node_modules/@scope/name`)
+   * in it, read from the path alone with no file system. A module not under `node_modules` changes nothing: the rule
+   * already keeps its spans. Unset by default.
+   */
+  readonly appModule?: string | undefined;
 }
 /**
  * A failure as a document: what the default report prints, and a building block for a custom one.
@@ -2155,7 +2316,7 @@ interface CliFailureOptions {
  * `Error.cause` chain as a tree. When cleaning leaves no frame the stack says
  * `no user frames (N internal frames hidden)`, never an empty block; when frames survive and some were left out, the
  * count follows them as `(+N internal frames hidden)`. A reason that ran under spans is followed by
- * `in: outer › inner`. Interrupts are not rendered beside a real failure, and a cause with only interrupts is the
+ * `in: outer › inner`: by default only the program's own spans, the kit's and Effect's left out (`spans`). Interrupts are not rendered beside a real failure, and a cause with only interrupts is the
  * one line `interrupted`.
  *
  * All text goes through the document, so a control character in a message or a stack frame never reaches the terminal.
@@ -2257,8 +2418,8 @@ interface CliMessageOptions {
  *
  * The text is whatever the caller supplies, so it is sanitised: escape sequences and control characters are removed
  * (a line break is kept as one, a tab becomes a space), as in a document. Under GitHub Actions, where
- * `CurrentRuntimeEnv` says so, a line the runner would read as a workflow command is neutralized as well. The glyphs
- * come from the vocabulary, which is configuration, and are not.
+ * `CurrentRuntimeEnv` says so, a line the runner would read as a workflow command is neutralized as well. The glyph
+ * comes from the vocabulary, sanitised too (`Status.glyph`), so a glyph built from data cannot inject an escape either.
  *
  * @public
  */
@@ -2407,6 +2568,24 @@ interface FailureDetails {
    * failure from the error channel.
    */
   readonly isDefect: boolean;
+  /**
+   * `true` when the squashed `error` is the kit's {@link Cancelled}: the person quit a prompt or screen (Esc, Ctrl-C).
+   * It is not a bug and there is nothing to report, whichever channel it arrived through.
+   *
+   * @remarks
+   * A cancel from `CliPrompt.fallback` is a defect (`isDefect` is `true`) and one from `CliUi.run` is a typed failure
+   * (`isDefect` is `false`), so a `render` that gives a defect the "please report this" treatment must test this flag
+   * first, or Esc prints an issue-report request. `isDefect` keeps its plain meaning, the absence of a typed failure,
+   * and the exit code is unchanged (`130` for the `interrupt` reason). `defaultLines` and `lines()` already draw it as
+   * its one fixed line.
+   */
+  readonly isCancelled: boolean;
+  /**
+   * `true` when the squashed `error` is the kit's {@link NotInteractive}: the program asked for a prompt or a screen in
+   * a run that cannot show one (a pipe, an agent, a CI). It is a usage problem, not a bug, whichever channel it
+   * arrived through; `isDefect` is as for {@link FailureDetails.isCancelled}.
+   */
+  readonly isNotInteractive: boolean;
   /**
    * The report the kit writes for this failure when there is no `render`: for this run, in this audience, with its
    * colour, links and `displayPath`. A `render` that hands a failure back returns these lines unchanged, and the
@@ -2429,10 +2608,14 @@ interface FailureDetails {
    *   details.lines({ status: false }).map((line, i) => (i === 0 ? `prog: ${line}` : line))
    * ```
    *
-   * @param options - `status: false` leaves off the leading status
+   * `spans` chooses the `in:` trail for these lines alone, as `CliFailureOptions.spans` does (`app`, `all` or
+   * `off`); without it the run's own setting (`env.spans`, `app` by default) applies.
+   *
+   * @param options - `status: false` leaves off the leading status; `spans` chooses the span trail
    */
   readonly lines: (options?: {
     readonly status?: boolean | undefined;
+    readonly spans?: "app" | "all" | "off" | undefined;
   }) => ReadonlyArray<string>;
 }
 /**
@@ -2522,9 +2705,11 @@ interface MainOptions<RP, EP> extends ReportFailuresOptions {
    * one that writes output must use `Console` or `Stdio`, never `Terminal`.
    *
    * Stderr's colour mirrors stdout's terminal check unless `env.stderrIsTerminal` says otherwise, so with stderr
-   * redirected and stdout a terminal the failure report is painted into the file. On Node, pass the real check:
-   * `env: { stderrIsTerminal: Effect.sync(() => process.stderr.isTTY === true) }` (core's `Stdio` reports only
-   * stdout; upstream Effect-TS/effect#8639).
+   * redirected and stdout a terminal the failure report is painted into the file. On Node, pass the real check from
+   * the bin's entry, the one place it reads the host:
+   * `env: { stderrIsTerminal: Effect.sync(() => process.stderr.isTTY === true) }`. Core's `Stdio` reports only
+   * stdout (upstream Effect-TS/effect#8639); once core has a stderr check, this option reads it and the bin passes
+   * nothing.
    */
   readonly env?: CliEnvOptions | undefined;
   /**
@@ -2541,8 +2726,12 @@ interface MainOptions<RP, EP> extends ReportFailuresOptions {
    *
    * Two cases keep help on stdout even under `"stderr"`. A `CliOutput`
    * Formatter or a `Console` provided inside `program` is not seen by
-   * `main`, so its help is not rerouted; provide the Formatter through
-   * `platform` instead. And with `Command.runWith`'s `renderErrors: false`
+   * `main`, so its help is not rerouted. To change the Formatter, pass
+   * `env.formatter` (for example `formatVersion`): `main` installs its own
+   * Formatter inside the platform, so that is the way in, and a Formatter
+   * provided inside the program is invisible to the routing. A Formatter
+   * the platform provides is shadowed by `main`'s, so pass it through
+   * `env.formatter` as well. And with `Command.runWith`'s `renderErrors: false`
    * no errors are printed, so nothing marks the help as a usage error's.
    */
   readonly helpOnUsageError?: "stdout" | "stderr" | undefined;
@@ -3007,8 +3196,9 @@ interface RenderContext {
    *
    * @remarks
    * `Infinity` is no limit. A renderer clamps what it is given: zero or a negative width is 1, and `NaN` is 80.
-   * `Render.context` gives a human `TerminalEnv.width()`, which is the terminal's columns as stdout reports them, even
-   * for a context built for `"stderr"` (core's `Terminal` has one width); pass `width` to override it.
+   * `Render.context` gives a human writing to a terminal `TerminalEnv.width()`, which is the terminal's columns as
+   * stdout reports them, even for a context built for `"stderr"` (core's `Terminal` has one width), and gives no limit
+   * when the stream is not a terminal; pass `width` to override it.
    */
   readonly width: number;
   /** Who the output is for. */
@@ -3088,8 +3278,9 @@ interface RenderContextOfOptions {
  */
 interface RenderContextOptions {
   /**
-   * The display columns to lay out at. By default a human gets `TerminalEnv.width()`, the terminal's columns as
-   * stdout reports them even when the stream is `"stderr"`, and an agent or a CI gets no limit at all.
+   * The display columns to lay out at. By default a human writing to a terminal gets `TerminalEnv.width()`, the
+   * terminal's columns as stdout reports them even when the stream is `"stderr"`; a human whose stream is not a
+   * terminal (a pipe, a file), an agent and a CI get no limit at all.
    */
   readonly width?: number | undefined;
   /** Turns an absolute path into its display form, for example relative to the working directory; the identity by default. */
@@ -3131,8 +3322,9 @@ export declare class Render {
    *   gets an escape and a terminal without OSC 8 gets the label;
    * - `neutralizeWorkflowCommands` is set when `CurrentRuntimeEnv` says GitHub Actions (read if present, not
    *   required), for every audience, since the runner reads whatever is written there;
-   * - `width` is the option, else `TerminalEnv.width()` for a human, and **unbounded** (`Infinity`) for an agent
-   *   or a CI, so nothing a reader needs is truncated or wrapped for a terminal that is not there.
+   * - `width` is the option, else `TerminalEnv.width()` for a human whose stream is a terminal, and **unbounded**
+   *   (`Infinity`) for a human whose stream is not one (`tool | grep`, `tool > out.txt`), an agent or a CI, so nothing
+   *   a reader needs is truncated or wrapped for a terminal that is not there: a pipe has no width to honour.
    *
    * @param stream - the stream the output is for
    * @param options - an explicit width and a path display function
@@ -3335,5 +3527,5 @@ export declare class SchemaIssueRenderer {
   static readonly render: (issue: unknown) => ReadonlyArray<string>;
 }
 //#endregion
-export type { AnnotationLevel, AnnotationOptions, AudienceFlagInput, Block, BlockOf, CliAudienceFlagsOptions, CliDocSource, CliEnvOptions, CliEnvServices, CliEnvTestOptions, CliEnvTestServices, CliExitShape, CliFailureOptions, CliLinksLinkerOptions, CliLinksOptions, CliLinksShape, CliLogFile, CliLogFileOptions, CliLogOptions, CliLoggerOptions, CliMessageOptions, CliPromptFallbackOptions, CliPromptTarget, CliThemeOptions, CliThemeShape, CliThemeTestOptions, Column, CoreStatusName, Counter, CountsOptions, CountsRow, CountsTableOptions, DocPrintOptions, Document, EditorLinks, FailureDetails, GithubAnnotationProperties, GlyphSelectOptions, GlyphSet, Inline, InlineInput, InlineOf, LinkOptions, LinkTarget, ListOptions, MainOptions, NamedColor, OverflowOptions, PercentOptions, RenderContext, RenderContextOfOptions, RenderContextOptions, ReportFailuresOptions, RequiresAudienceFlags, StatusDef, StatusRef, StreamTheme, Style, TableOptions, TokenName, TreeInput, TreeNode, TruncateOptions };
+export type { AnnotationLevel, AnnotationOptions, AudienceFlagInput, Block, BlockOf, CliAudienceFlagsOptions, CliDocSource, CliEnvOptions, CliEnvServices, CliEnvTestOptions, CliEnvTestServices, CliExitShape, CliFailureOptions, CliLinksLinkerOptions, CliLinksOptions, CliLinksShape, CliLogFile, CliLogFileOptions, CliLogOptions, CliLogStatusOptions, CliLoggerOptions, CliMessageOptions, CliPromptFallbackOptions, CliPromptTarget, CliThemeOptions, CliThemeShape, CliThemeTestOptions, Column, CoreStatusName, Counter, CountsOptions, CountsRow, CountsTableOptions, DocPrintOptions, Document, EditorLinks, FailureDetails, GithubAnnotationProperties, GlyphSelectOptions, GlyphSet, Inline, InlineInput, InlineOf, LinkOptions, LinkTarget, ListOptions, MainOptions, NamedColor, OverflowOptions, PercentOptions, RenderContext, RenderContextOfOptions, RenderContextOptions, ReportFailuresOptions, RequiresAudienceFlags, StatusDef, StatusRef, StreamTheme, Style, TableOptions, TokenName, TreeInput, TreeNode, TruncateOptions };
 //# sourceMappingURL=index.d.ts.map

package/internal/counts.js

@@ -2,6 +2,21 @@ import { Fmt } from "../Fmt.js";
 
 //#region src/internal/counts.ts
 /**
+* The label a counter shows for a count: its one label, or `one` when the count is exactly 1 and `other` otherwise.
+* The count is the counter's own `n`, except in a share headline (`1/3 repos`), which reads by the denominator, the
+* total, and passes it.
+*
+* @internal
+*/
+const counterLabel = (counter, count = counter.n) => typeof counter.label === "string" ? counter.label : count === 1 ? counter.label.one : counter.label.other;
+/**
+* The label a counter's column is headed with in a `CountsTable`: its one label, or its plural form, since a column
+* holds every row's count.
+*
+* @internal
+*/
+const columnLabel = (counter) => typeof counter.label === "string" ? counter.label : counter.label.other;
+/**
 * The total of a `Counts` block: the caller's rule when it has one, otherwise the sum of `n` over every counter.
 *
 * @remarks
@@ -58,7 +73,7 @@ const countsTableOf = (block) => {
 		_tag: "Table",
 		columns: [
 			{ header: block.labelHeader ?? [] },
-			...keys.map((key) => ({ header: [text(key.label)] })),
+			...keys.map((key) => ({ header: [text(columnLabel(key))] })),
 			...timed ? [{ header: block.durationHeader ?? [text("duration")] }] : []
 		],
 		rows: [...rows, ...total]
@@ -66,4 +81,4 @@ const countsTableOf = (block) => {
 };
 
 //#endregion
-export { countsTableOf, totalOf, visibleCountersOf };
+export { columnLabel, counterLabel, countsTableOf, totalOf, visibleCountersOf };

package/internal/failureTarget.js

@@ -5,7 +5,7 @@ import { Glyphs } from "../Glyphs.js";
 import { CliTheme } from "../CliTheme.js";
 import { Render } from "../Render.js";
 import { CliFailure } from "../CliFailure.js";
-import { Context, Effect, MutableRef, Option } from "effect";
+import { Config, Context, Effect, MutableRef, Option } from "effect";
 import { Audience, TerminalEnv } from "@effected/env";
 import { CommandNeutralizer } from "@effected/github-commands";
 
@@ -52,16 +52,14 @@ const build = (audience, settings = {}) => Effect.gen(function* () {
 	if (Option.isNone(theme) || Option.isNone(terminal) || Option.isNone(links)) return void 0;
 	const shape = audience ?? (Option.isSome(current) ? current.value : void 0);
 	if (shape === void 0) return void 0;
-	const { displayPath, stackFrames } = settings;
+	const { displayPath, stackFrames, spans, appModule } = settings;
 	const ctx = yield* Render.context("stderr", displayPath === void 0 ? void 0 : { displayPath }).pipe(Effect.provideService(CliTheme, theme.value), Effect.provideService(TerminalEnv, terminal.value), Effect.provideService(CliLinks, links.value), Effect.provideService(Audience, shape));
-	const format = yield* autoFormat(ctx.audience);
-	return stackFrames === void 0 ? {
+	return {
 		ctx,
-		format
-	} : {
-		ctx,
-		format,
-		stackFrames
+		format: yield* autoFormat(ctx.audience),
+		...stackFrames === void 0 ? {} : { stackFrames },
+		...spans === void 0 ? {} : { spans },
+		...appModule === void 0 ? {} : { appModule }
 	};
 });
 /**
@@ -75,7 +73,9 @@ const refreshFailureTarget = (audience, settings) => Effect.gen(function* () {
 	const recorded = MutableRef.get(cell);
 	const target = yield* build(audience, settings ?? {
 		displayPath: recorded?.ctx.displayPath,
-		stackFrames: recorded?.stackFrames
+		stackFrames: recorded?.stackFrames,
+		spans: recorded?.spans,
+		appModule: recorded?.appModule
 	});
 	if (target !== void 0) MutableRef.set(cell, target);
 });
@@ -119,10 +119,12 @@ const withoutStatus = (doc) => doc.map((block) => {
 *
 * @internal
 */
-const linesOf = (cause, target, status = true) => {
+const linesOf = (cause, target, status = true, spans = target.spans) => {
 	const full = CliFailure.toDoc(cause, {
 		displayPath: target.ctx.displayPath,
-		...target.stackFrames === void 0 ? {} : { stackFrames: target.stackFrames }
+		...target.stackFrames === void 0 ? {} : { stackFrames: target.stackFrames },
+		...spans === void 0 ? {} : { spans },
+		...target.appModule === void 0 ? {} : { appModule: target.appModule }
 	});
 	const doc = status ? full : withoutStatus(full);
 	const text = Render[target.format](doc, target.ctx);
@@ -150,7 +152,44 @@ const guardConsumerLines = (lines) => Effect.map(currentTarget, (target) => {
 *
 * @internal
 */
-const plainFailureLines = (cause, status = true) => linesOf(cause, fallbackTarget, status);
+const plainFailureLines = (cause, status = true, spans) => linesOf(cause, fallbackTarget, status, spans);
+const SPAN_SETTINGS = [
+	"app",
+	"all",
+	"off"
+];
+/**
+* The span trail setting, as `CliLog`'s level is read: the explicit `spans` when given (the variable is then not read
+* at all), else the variable named `envVar` through `Config`, case-insensitive, unset or empty meaning the default.
+* A value that is not a setting is ignored, with the warning to log.
+*
+* @internal
+*/
+const readSpans = (explicit, envVar) => Effect.gen(function* () {
+	if (explicit !== void 0) return {
+		spans: explicit,
+		invalid: void 0
+	};
+	if (envVar === void 0) return {
+		spans: void 0,
+		invalid: void 0
+	};
+	const raw = yield* Config.option(Config.String(envVar)).pipe(Effect.orElseSucceed(() => Option.none()));
+	if (Option.isNone(raw) || raw.value === "") return {
+		spans: void 0,
+		invalid: void 0
+	};
+	const value = raw.value.toLowerCase();
+	const spans = SPAN_SETTINGS.find((setting) => setting === value);
+	if (spans !== void 0) return {
+		spans,
+		invalid: void 0
+	};
+	return {
+		spans: void 0,
+		invalid: `${envVar}=${raw.value} is not a span setting (${SPAN_SETTINGS.join("|")}); ignoring it`
+	};
+});
 
 //#endregion
-export { FailureTargetCell, currentTarget, fallbackTarget, guardConsumerLines, linesOf, plainFailureLines, refreshFailureTarget };
+export { FailureTargetCell, currentTarget, fallbackTarget, guardConsumerLines, linesOf, plainFailureLines, readSpans, refreshFailureTarget };

package/internal/renderDoc.js

@@ -1,5 +1,5 @@
 import { Fmt, sanitize } from "../Fmt.js";
-import { countsTableOf, totalOf, visibleCountersOf } from "./counts.js";
+import { counterLabel, countsTableOf, totalOf, visibleCountersOf } from "./counts.js";
 import { truncateSpans, widthOf, wrapSpans } from "./layout.js";
 
 //#region src/internal/renderDoc.ts
@@ -190,10 +190,10 @@ const countsLayout = (walk, block) => {
 	const qualifier = block.qualifier === void 0 ? [] : toned(oneLine(inline(walk, block.qualifier)), "muted");
 	const duration = block.durationMs === void 0 ? "" : Fmt.duration(block.durationMs);
 	const suffix = block.suffix === void 0 ? [] : toned(oneLine(inline(walk, block.suffix)), "muted");
-	const nameOf = (counter) => sanitize(counter.label).replace(/\r\n|\r|\n/g, " ");
+	const nameOf = (counter, count) => sanitize(counterLabel(counter, count)).replace(/\r\n|\r|\n/g, " ");
 	const counters = visible.map((counter, index) => {
-		const name = nameOf(counter);
 		const share = index === 0 && block.share !== false;
+		const name = nameOf(counter, share ? total : counter.n);
 		return [span(share ? `${counter.n}/${total} ${name}` : `${counter.n} ${name}`, counter.status.def.token)];
 	});
 	if (block.layout === "row") return [trimLine(joinChunks([
@@ -281,6 +281,7 @@ const blockLines = (walk, block, width, compact = false) => {
 		case "Line": {
 			const spans = oneLine(inline(walk, block.content));
 			if (block.truncate === true) return [trimLine(truncateSpans(spans, width, walk.ctx.glyphs.ellipsis))];
+			if (block.wrap === false) return [trimLine(spans)];
 			return spans.length === 0 ? [[]] : wrapSpans(spans, width, { hardBreak: false }).map(trimLine);
 		}
 		case "DiffText": {

package/internal/renderMarkdown.js

@@ -1,5 +1,5 @@
 import { Fmt, sanitize } from "../Fmt.js";
-import { countsTableOf, totalOf, visibleCountersOf } from "./counts.js";
+import { counterLabel, countsTableOf, totalOf, visibleCountersOf } from "./counts.js";
 import { isAllowedLinkUrl } from "./linkScheme.js";
 import { DRIVE, encodePath, fileUrlPath } from "./linkTarget.js";
 import { flatten } from "./layout.js";
@@ -52,7 +52,7 @@ const codeSpan = (text, mode) => {
 	const longest = Math.max(0, ...[...flat.matchAll(/`+/g)].map((run) => run[0].length));
 	const fence = "`".repeat(longest + 1);
 	const padded = /^`|`$/.test(flat) || /^ .* $/.test(flat) && flat.trim() !== "" || flat === "";
-	const body = mode === "cell" ? flat.replace(/\|/g, "\\|") : flat;
+	const body = mode === "cell" ? flat.split("|").join("\\|") : flat;
 	const pad = padded ? " " : "";
 	return `${fence}${pad}${body === "" ? " " : body}${pad}${fence}`;
 };
@@ -194,9 +194,10 @@ const countsMd = (walk, block) => {
 	const qualifier = block.qualifier === void 0 ? "" : inlineMd(block.qualifier, ctx, "line").trim();
 	const duration = block.durationMs === void 0 ? "" : Fmt.duration(block.durationMs);
 	const suffix = block.suffix === void 0 ? "" : inlineMd(block.suffix, ctx, "line").trim();
-	const name = (counter) => escapeText(sanitize(counter.label).replace(/\r\n|\r|\n/g, " "));
+	const name = (counter, count) => escapeText(sanitize(counterLabel(counter, count)).replace(/\r\n|\r|\n/g, " "));
+	const headlineName = (counter, index) => index === 0 && block.share !== false ? name(counter, total) : name(counter);
 	if (block.layout === "row") {
-		const header = [...visible.map(name), ...duration === "" ? [] : ["duration"]];
+		const header = [...visible.map(headlineName), ...duration === "" ? [] : ["duration"]];
 		const cells = [...visible.map((counter, index) => index === 0 && block.share !== false ? `${counter.n}/${total}` : String(counter.n)), ...duration === "" ? [] : [duration]];
 		const after = [qualifier, suffix].filter((part) => part !== "").join(" ");
 		return [
@@ -212,7 +213,7 @@ const countsMd = (walk, block) => {
 		...duration === "" ? [] : [[duration]],
 		...suffix === "" ? [] : [flowLines(suffix)]
 	];
-	const tally = visible.map((counter, index) => index === 0 && block.share !== false ? `${counter.n}/${total} ${name(counter)}` : `${counter.n} ${name(counter)}`).join(", ");
+	const tally = visible.map((counter, index) => index === 0 && block.share !== false ? `${counter.n}/${total} ${headlineName(counter, index)}` : `${counter.n} ${name(counter)}`).join(", ");
 	const line = [
 		[label === "" ? "" : `${label}:`, tally].filter((part) => part !== "").join(" "),
 		qualifier,