@effected/cli 0.10.0 → 0.12.0

package/Doc.js

@@ -0,0 +1,536 @@
+import { autoFormat } from "./internal/autoFormat.js";
+import { totalOf, visibleCountersOf } from "./internal/counts.js";
+import { Render } from "./Render.js";
+import { Console, Effect } from "effect";
+
+//#region src/Doc.ts
+const isList = (input) => Array.isArray(input);
+const freeze = (value) => Object.freeze(value);
+const frozenArray = (items) => Object.freeze([...items]);
+const text = (value, token) => freeze({
+	_tag: "Text",
+	value,
+	...token === void 0 ? {} : { token }
+});
+const inlineOne = (part) => typeof part === "string" ? text(part) : part;
+const inlines = (input) => frozenArray(isList(input) ? input.map(inlineOne) : [inlineOne(input)]);
+const overflowOf = (overflow) => (hidden) => inlines(overflow(hidden));
+const overflowFields = (options) => ({
+	...options?.cap === void 0 ? {} : { cap: options.cap },
+	...options?.overflow === void 0 ? {} : { overflow: overflowOf(options.overflow) }
+});
+const treeNode = (input) => freeze({
+	label: inlines(input.label),
+	children: frozenArray((input.children ?? []).map(treeNode))
+});
+const counterOf = (counter) => freeze({
+	...counter,
+	label: typeof counter.label === "string" ? counter.label : freeze({
+		one: counter.label.one,
+		other: counter.label.other
+	}),
+	status: freeze({
+		name: counter.status.name,
+		def: freeze({ ...counter.status.def })
+	})
+});
+/**
+* Constructors for the document IR, and two helpers a renderer shares.
+*
+* @remarks
+* Every constructor returns a frozen node and copies the arrays it is given, so editing an input afterwards
+* cannot change a document. An optional field that is not given is absent from the node, not `undefined`.
+* Content arguments accept a string, an `Inline` or an array of either.
+*
+* A node is plain data: nothing decodes or encodes one, so a function field such as `overflow` or `total` is fine
+* and a document is not meant to be serialised.
+*
+* Freezing covers what a `Doc` constructor builds. A literal you write by hand is not frozen, and a `Style` object
+* given as a token is shared by reference (the freeze of a status definition is shallow for the same reason).
+*
+* @example
+* ```ts
+* import { Doc, Status } from "@effected/cli"
+*
+* const report = [
+* 	Doc.heading(2, "Results"),
+* 	Doc.paragraph(Doc.status(Status.core, "success"), " ", "3 checks passed"),
+* 	Doc.table([{ header: "Check" }, { header: "Time", align: "right" }], [["lint", "1.2s"]]),
+* ]
+* // Written for whoever is reading: `yield* Doc.print(report)`
+* ```
+*
+* @public
+*/
+var Doc = class {
+	constructor() {}
+	/**
+	* A run of text.
+	*
+	* @param value - the text
+	* @param token - a semantic token or a style to paint it with
+	*/
+	static text(value, token) {
+		return text(value, token);
+	}
+	/**
+	* Code in a monospace span.
+	*
+	* @param value - the code
+	*/
+	static code(value) {
+		return freeze({
+			_tag: "Code",
+			value
+		});
+	}
+	static link(target, label, options) {
+		if (target === void 0) return typeof label === "string" ? text(label) : label;
+		const fallback = "url" in target ? target.url : target.file;
+		return freeze({
+			_tag: "Link",
+			target: freeze({ ...target }),
+			label: inlines(label ?? fallback),
+			...options?.suffix === void 0 ? {} : { suffix: options.suffix }
+		});
+	}
+	/**
+	* A status glyph, holding the resolved definition.
+	*
+	* @remarks
+	* A name the vocabulary does not have is a compile error.
+	*
+	* @param vocab - the vocabulary the name belongs to
+	* @param name - a status name in it
+	*/
+	static status(vocab, name) {
+		return freeze({
+			_tag: "StatusMark",
+			name,
+			def: vocab.resolve(name)
+		});
+	}
+	/**
+	* Content in bold: markdown `**…**`, bold in `ansi`, and the content as is in plain and `githubLog`.
+	*
+	* @param content - any number of strings, inlines or arrays of them, in order
+	*/
+	static strong(...content) {
+		return freeze({
+			_tag: "Strong",
+			content: inlines(content.flatMap((part) => isList(part) ? part : [part]))
+		});
+	}
+	/**
+	* Content in italic: markdown `*…*` (which GFM reads inside a word too), italic in `ansi`, and the content as is in
+	* plain and `githubLog`.
+	*
+	* @param content - any number of strings, inlines or arrays of them, in order
+	*/
+	static em(...content) {
+		return freeze({
+			_tag: "Emphasis",
+			content: inlines(content.flatMap((part) => isList(part) ? part : [part]))
+		});
+	}
+	/**
+	* A file path, shown through the context's `displayPath` and never linked.
+	*
+	* @param path - the path, usually absolute
+	*/
+	static file(path) {
+		return freeze({
+			_tag: "File",
+			path
+		});
+	}
+	/**
+	* A path or breadcrumb; a renderer joins the segments with the audience's separator.
+	*
+	* @param segments - the segments, in order
+	*/
+	static path(...segments) {
+		return freeze({
+			_tag: "Path",
+			segments: frozenArray(segments)
+		});
+	}
+	/**
+	* A heading.
+	*
+	* @param level - 1 to 4
+	* @param content - the heading text
+	*/
+	static heading(level, content) {
+		return freeze({
+			_tag: "Heading",
+			level,
+			content: inlines(content)
+		});
+	}
+	/**
+	* One logical line of content.
+	*
+	* @param content - any number of strings, inlines or arrays of them, in order
+	*/
+	static paragraph(...content) {
+		return freeze({
+			_tag: "Paragraph",
+			content: inlines(content.flatMap((part) => isList(part) ? part : [part]))
+		});
+	}
+	/**
+	* A list of blocks.
+	*
+	* @param items - the items
+	* @param options - `cap`, `overflow`, and `compact` for no blank lines inside an item
+	*/
+	static list(items, options) {
+		return freeze({
+			_tag: "List",
+			items: frozenArray(items),
+			...overflowFields(options),
+			...options?.compact === void 0 ? {} : { compact: options.compact }
+		});
+	}
+	/**
+	* A table.
+	*
+	* @param columns - the columns: a header and an optional alignment each
+	* @param rows - the rows; each cell takes a string, an inline or an array of either
+	* @param options - `cap`, `overflow`, and `style: "pipe"` for istanbul's shape in plain and `ansi`
+	*/
+	static table(columns, rows, options) {
+		return freeze({
+			_tag: "Table",
+			columns: frozenArray(columns.map((column) => freeze({
+				header: inlines(column.header),
+				...column.align === void 0 ? {} : { align: column.align }
+			}))),
+			rows: frozenArray(rows.map((row) => frozenArray(row.map(inlines)))),
+			...overflowFields(options),
+			...options?.style === void 0 ? {} : { style: options.style }
+		});
+	}
+	/**
+	* A tree of labels.
+	*
+	* @param root - the root; a node's `children` may be left out
+	*/
+	static tree(root) {
+		return freeze({
+			_tag: "Tree",
+			root: treeNode(root)
+		});
+	}
+	/**
+	* A titled body a renderer may fold.
+	*
+	* @param title - the title
+	* @param body - the body
+	* @param options - `open` asks for it to start unfolded
+	*/
+	static collapsible(title, body, options) {
+		return freeze({
+			_tag: "Collapsible",
+			title: inlines(title),
+			body: frozenArray(body),
+			...options?.open === void 0 ? {} : { open: options.open }
+		});
+	}
+	/**
+	* A callout.
+	*
+	* @param kind - `note`, `tip`, `important`, `warning` or `caution`
+	* @param body - the body
+	*/
+	static callout(kind, body) {
+		return freeze({
+			_tag: "Callout",
+			kind,
+			body: frozenArray(body)
+		});
+	}
+	/**
+	* Preformatted text.
+	*
+	* @param text - the text
+	* @param lang - its language, for a renderer that fences it
+	*/
+	static codeBlock(text, lang) {
+		return freeze({
+			_tag: "CodeBlock",
+			...lang === void 0 ? {} : { lang },
+			text
+		});
+	}
+	/**
+	* Expected against received text.
+	*
+	* @param expected - the expected text
+	* @param received - the received text
+	* @param options - `cap` limits the lines shown
+	*/
+	static diff(expected, received, options) {
+		return freeze({
+			_tag: "Diff",
+			expected,
+			received,
+			...options?.cap === void 0 ? {} : { cap: options.cap }
+		});
+	}
+	/**
+	* 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
+	*/
+	static section(title, children) {
+		return freeze({
+			_tag: "Section",
+			...title === void 0 ? {} : { title: inlines(title) },
+			children: frozenArray(children)
+		});
+	}
+	/**
+	* One counter of a `Counts` block, with its status definition resolved.
+	*
+	* @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`, its `label` (one string, or `{ one, other }`), its count `n`, and `showZero`
+	* to keep it when `n` is zero
+	*/
+	static counter(vocab, name, options) {
+		return counterOf({
+			key: options.key,
+			label: options.label,
+			n: options.n,
+			status: {
+				name,
+				def: vocab.resolve(name)
+			},
+			...options.showZero === void 0 ? {} : { showZero: options.showZero }
+		});
+	}
+	/**
+	* Counters in one of three layouts.
+	*
+	* @param options - the counters, the layout and the optional label, total rule, qualifier and duration
+	*/
+	static counts(options) {
+		return freeze({
+			_tag: "Counts",
+			...options.label === void 0 ? {} : { label: inlines(options.label) },
+			counters: frozenArray(options.counters.map(counterOf)),
+			...options.total === void 0 ? {} : { total: options.total },
+			...options.qualifier === void 0 ? {} : { qualifier: inlines(options.qualifier) },
+			...options.durationMs === void 0 ? {} : { durationMs: options.durationMs },
+			layout: options.layout,
+			...options.share === void 0 ? {} : { share: options.share },
+			...options.paint === void 0 ? {} : { paint: options.paint },
+			...options.suffix === void 0 ? {} : { suffix: inlines(options.suffix) }
+		});
+	}
+	/**
+	* Counters as a table: a row per entry, a column per counter key (in the order the keys first appear, headed by
+	* the counter's label), and an optional total row summing each column.
+	*
+	* @remarks
+	* A row without a counter for some key leaves that cell empty, and it counts as zero in the total. A counter whose
+	* `n` is zero shows `0`, as a `Doc.table` cell would: a counter's `showZero` has no effect in a table, only in a
+	* `Counts` block, so there is no need to set it. `totalRow`
+	* labels the total row with a plain `Total` when `true`, or with the content given: for a bold one, pass
+	* `totalRow: Doc.strong("Total")`. A column is headed by its counter's `label`; a counter's status paints its cells
+	* in `ansi` and is ignored in markdown, so a plain numbers table may pass any status. `labelHeader` heads the label column, which
+	* is otherwise empty. When some row has a `durationMs`, a last column shows it with `Fmt.duration`, headed
+	* `durationHeader` (`duration` by default); a row without one has an empty cell there and counts as zero in the
+	* total row's summed duration.
+	*
+	* @param rows - each row's label, counters and optional duration
+	* @param options - `totalRow`, to add the summed row; the label and duration column headers
+	*/
+	static countsTable(rows, options) {
+		const totalRow = options?.totalRow;
+		return freeze({
+			_tag: "CountsTable",
+			rows: frozenArray(rows.map((row) => freeze({
+				label: inlines(row.label),
+				counters: frozenArray(row.counters.map(counterOf)),
+				...row.durationMs === void 0 ? {} : { durationMs: row.durationMs }
+			}))),
+			...totalRow === void 0 ? {} : { totalRow: typeof totalRow === "boolean" ? totalRow : inlines(totalRow) },
+			...options?.labelHeader === void 0 ? {} : { labelHeader: inlines(options.labelHeader) },
+			...options?.durationHeader === void 0 ? {} : { durationHeader: inlines(options.durationHeader) }
+		});
+	}
+	/**
+	* Lines, one per entry, in every renderer: markdown joins them with hard breaks so they never collapse into one.
+	*
+	* @param lines - the entries; each takes a string, an inline or an array of either
+	*/
+	static lines(lines) {
+		return freeze({
+			_tag: "Lines",
+			lines: frozenArray(lines.map(inlines))
+		});
+	}
+	/**
+	* 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
+	* 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`, to cut it to the width; `wrap: false`, to keep it whole
+	*/
+	static line(content, options) {
+		return freeze({
+			_tag: "Line",
+			content: inlines(content),
+			...options?.truncate === void 0 ? {} : { truncate: options.truncate },
+			...options?.wrap === void 0 ? {} : { wrap: options.wrap }
+		});
+	}
+	/**
+	* A unified diff as given, such as a test runner's: sanitized, its `+` and `-` lines painted `success` and
+	* `failure` in `ansi`, and a `diff` fence in markdown.
+	*
+	* @remarks
+	* With `truncate`, plain and `ansi` cut each line to the width with the glyph set's ellipsis instead of wrapping
+	* it; an agent's or a CI's width is unbounded, so nothing is cut for them unless the context gives a finite width.
+	* Markdown keeps every line whole. Inside a compact list item a blank line of the diff keeps the item's indent.
+	*
+	* A trailing line break ends the last line, as in a unified diff file, and adds no blank line after it: `"a\n"` is
+	* one line. To end on a blank line, end the text with two line breaks.
+	*
+	* @param unified - the diff
+	* @param options - `cap`, the most lines shown; `truncate`, to cut each line to the width
+	*/
+	static diffText(unified, options) {
+		return freeze({
+			_tag: "DiffText",
+			text: unified,
+			...options?.cap === void 0 ? {} : { cap: options.cap },
+			...options?.truncate === void 0 ? {} : { truncate: options.truncate }
+		});
+	}
+	/**
+	* Lines kept exactly: each indented by `indent` spaces, sanitized, and never wrapped.
+	*
+	* @remarks
+	* Plain, `ansi` and `githubLog` write the lines as they are; markdown fences them, so the indentation survives.
+	*
+	* It is the tool for a single line that must never wrap nor be cut, whatever the width: {@link Doc.line} wraps at
+	* the width, or cuts with `truncate`, and `verbatim` does neither.
+	*
+	* @param text - the lines
+	* @param options - `indent`, the spaces in front of every line; none by default
+	*/
+	static verbatim(text, options) {
+		return freeze({
+			_tag: "Verbatim",
+			text,
+			...options?.indent === void 0 ? {} : { indent: options.indent }
+		});
+	}
+	/**
+	* A GitHub Actions annotation: `Render.githubLog` writes it as one workflow command (`::error file=…::message`),
+	* and every other renderer writes nothing.
+	*
+	* @remarks
+	* It is the kit's own command, so `githubLog` does not neutralize it; its message and properties are escaped, so
+	* no text in them can end the command or start another. It is a command where a line starts: at the top level, as a
+	* top-level section's child, or as a direct child of a group's body. Nested deeper, it is dropped.
+	*
+	* @param options - the level, and the optional file, position and title
+	* @param message - what it says
+	*/
+	static annotation(options, message) {
+		return freeze({
+			_tag: "Annotation",
+			level: options.level,
+			...options.file === void 0 ? {} : { file: options.file },
+			...options.line === void 0 ? {} : { line: options.line },
+			...options.col === void 0 ? {} : { col: options.col },
+			...options.endLine === void 0 ? {} : { endLine: options.endLine },
+			...options.endColumn === void 0 ? {} : { endColumn: options.endColumn },
+			...options.title === void 0 ? {} : { title: options.title },
+			message
+		});
+	}
+	/**
+	* The total of a `Counts` block: the caller's rule when it has one, otherwise the sum of `n` over every counter.
+	*
+	* @remarks
+	* The rule sees every counter, including the ones a renderer hides, so hiding never changes the total.
+	*
+	* @param block - the `Counts` block
+	*/
+	static total(block) {
+		return totalOf(block);
+	}
+	/**
+	* The counters a renderer shows: every one except a zero counter that does not ask for `showZero`.
+	*
+	* @param block - the `Counts` block
+	*/
+	static visibleCounters(block) {
+		return visibleCountersOf(block);
+	}
+	/**
+	* Render a document for whoever is running the program and write it to a stream.
+	*
+	* @remarks
+	* 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, 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.
+	*
+	* @param doc - the document
+	* @param options - the stream and the format
+	*/
+	static print = (doc, options) => Effect.gen(function* () {
+		const stream = options?.stream ?? "stdout";
+		const ctx = yield* Render.context(stream, {
+			...options?.displayPath === void 0 ? {} : { displayPath: options.displayPath },
+			...options?.width === void 0 ? {} : { width: options.width }
+		});
+		const requested = options?.format ?? "auto";
+		const format = requested === "auto" ? yield* autoFormat(ctx.audience) : requested;
+		const text = Render[format](doc, ctx);
+		if (text === "") return;
+		yield* stream === "stderr" ? Console.error(text) : Console.log(text);
+	});
+};
+
+//#endregion
+export { Doc };

package/Fmt.js

@@ -0,0 +1,133 @@
+import { displayWidth, graphemes, stripAnsi } from "./internal/displayWidth.js";
+
+//#region src/Fmt.ts
+const CONTROL = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
+/**
+* Text made safe to lay out and print: complete ANSI and OSC sequences removed, every remaining control character
+* removed (a stray ESC, BEL, BS, DEL, the C1 range) except line feed and carriage return, and a tab turned into a
+* space.
+*
+* @remarks
+* Stripping complete sequences is not enough on its own: a lone ESC survives it, and so does whatever would
+* complete a sequence once two adjacent pieces of text are joined (`ESC` in one node, `[31m` in the next). With
+* every ESC and C0 or C1 control gone after the strip, nothing can reassemble, so the width of the text equals what
+* a terminal shows. A tab counts as no columns but draws up to eight, hence the space.
+*
+* @internal
+*/
+const sanitize = (input) => stripAnsi(input).replace(/\t/g, " ").replace(CONTROL, "");
+/**
+* Small, pure formatting primitives for terminal output.
+*
+* @public
+*/
+var Fmt = class {
+	constructor() {}
+	/**
+	* Text made safe to lay out and print, exactly as the renderers make it: complete ANSI and OSC sequences removed,
+	* every other control character removed (a stray ESC, BEL, BS, DEL, the C1 range) except line feed and carriage
+	* return, and a tab turned into a space.
+	*
+	* @remarks
+	* For a `render` or any other text a program builds by hand from data it does not control: an error message, a
+	* file name, a value from the environment. Line breaks are kept, so split on them if the text must be one line.
+	*
+	* @param text - the text
+	*/
+	static sanitize = sanitize;
+	/**
+	* The display width of `text` in terminal columns: wide East Asian characters and emoji count two,
+	* combining marks and ANSI escapes count none.
+	*
+	* @param text - the text to measure
+	*/
+	static width = (text) => displayWidth(text);
+	/**
+	* Cut `text` to at most `width` columns, ending in `ellipsis` when it was cut.
+	*
+	* @remarks
+	* Grapheme-safe: a grapheme, such as a wide character or an emoji ZWJ family, is kept whole or dropped
+	* whole, so the result is never wider than `width`. Text that already fits is returned unchanged, colour
+	* escapes included. Text that must be cut is cut as plain text: its ANSI escapes are dropped rather than cut
+	* in half. When the ellipsis cannot fit, it is omitted and the text is cut to `width`; a `width` of 0 or
+	* less gives `""`.
+	*
+	* @param text - the text to truncate
+	* @param width - the most columns the result may take
+	* @param options - the ellipsis
+	*/
+	static truncate = (text, width, options) => {
+		const limit = Number.isFinite(width) ? Math.floor(width) : width === Number.POSITIVE_INFINITY ? Infinity : 0;
+		if (limit <= 0) return "";
+		if (displayWidth(text) <= limit) return text;
+		const plain = stripAnsi(text);
+		const ellipsis = options?.ellipsis ?? "…";
+		const ellipsisWidth = displayWidth(ellipsis);
+		const useEllipsis = ellipsisWidth <= limit && ellipsis !== "";
+		const budget = useEllipsis ? limit - ellipsisWidth : limit;
+		let out = "";
+		let used = 0;
+		for (const grapheme of graphemes(plain)) {
+			const w = displayWidth(grapheme);
+			if (used + w > budget) break;
+			out += grapheme;
+			used += w;
+		}
+		return useEllipsis ? `${out}${ellipsis}` : out;
+	};
+	/**
+	* A duration in milliseconds as short human text: `250ms`, `1.2s`, `2s`, `1m 3s`, `2m`, `1h 2m`, `2h`.
+	*
+	* @remarks
+	* Under a second it is whole milliseconds; under a minute, seconds to one decimal with a trailing `.0`
+	* dropped; under an hour, minutes and whole seconds, with the seconds dropped when zero; from an hour, hours and
+	* whole minutes, the seconds dropped. A value that rounds up to the next unit (`999.6` to a second, `59999` to a
+	* minute, `3599999` to an hour) is written in that unit, so `1000ms`, `60s` and `60m` never appear. There is no
+	* days unit. A negative or non-finite input is `0ms`.
+	*
+	* @param ms - the duration in milliseconds
+	*/
+	static duration = (ms) => {
+		const value = Number.isFinite(ms) ? Math.max(0, ms) : 0;
+		const whole = Math.round(value);
+		if (whole < 1e3) return `${whole}ms`;
+		const tenths = Math.round(value / 100);
+		if (tenths < 600) return `${Number((tenths / 10).toFixed(1))}s`;
+		const seconds = Math.round(value / 1e3);
+		if (seconds >= 3600) {
+			const hours = Math.floor(seconds / 3600);
+			const remaining = Math.floor(seconds % 3600 / 60);
+			return remaining === 0 ? `${hours}h` : `${hours}h ${remaining}m`;
+		}
+		const minutes = Math.floor(seconds / 60);
+		const rest = seconds % 60;
+		return rest === 0 ? `${minutes}m` : `${minutes}m ${rest}s`;
+	};
+	/**
+	* A ratio from 0 to 1 as a percentage, or a number already from 0 to 100 with `scale: 100`: `83.3%`, `50%`,
+	* `100%`.
+	*
+	* @remarks
+	* Rounded to `digits` decimal places (one by default) with trailing zeros dropped, so whole values print
+	* without a decimal. A value that rounds to zero prints `0%`, never `-0%`. The input is not validated.
+	*
+	* @param n - the ratio, 0 to 1 (0 to 100 with `scale: 100`)
+	* @param options - the decimal places and the scale
+	*/
+	static percent = (n, options) => {
+		const digits = Math.min(10, Math.max(0, Math.floor(options?.digits ?? 1)));
+		const percent = options?.scale === 100 ? n : n * 100;
+		return `${Number(percent.toFixed(digits))}%`;
+	};
+	/**
+	* A count with its noun: `1 test`, `2 tests`, `0 tests`.
+	*
+	* @param n - the count
+	* @param singular - the noun for exactly one
+	* @param plural - the noun otherwise; `singular` with an `s` appended by default
+	*/
+	static plural = (n, singular, plural) => `${n} ${n === 1 ? singular : plural ?? `${singular}s`}`;
+};
+
+//#endregion
+export { Fmt, sanitize };