@effected/cli-kit 0.0.0-stage → 0.27.0

package/ConfigIssueRenderer.js

@@ -0,0 +1,62 @@
+import { formatIssueWithHints } from "./internal/format.js";
+
+// src/ConfigIssueRenderer.ts
+/**
+* Turns a `@effected/config-file` `ConfigValidationError` into one line per rejected value.
+*
+* @remarks
+* `ConfigValidationError` carries the structured `issue` tree rather than a
+* string, so a caller holds a tree it has to turn into sentences. This is that
+* step, the same treatment {@link SchemaIssueRenderer} gives a bare issue.
+*
+* `ConfigValidationError.message` names the file but not the value, and the
+* value is the diagnostic: printing only the message tells a user their config
+* is invalid without saying which value is wrong or how it is shaped.
+*
+* The parameter is {@link ConfigIssueSource}, a structural type, so this module
+* names nothing from `@effected/config-file` and the package is not a peer. A
+* real `ConfigValidationError` is assignable to it.
+*
+* @example
+* ```ts
+* import { ConfigIssueRenderer } from "@effected/cli-kit"
+* import { Effect } from "effect"
+*
+* const load = configFile.load.pipe(
+*   Effect.catchTag("ConfigValidationError", (error) =>
+*     Effect.gen(function* () {
+*       yield* Effect.logError(String(error))
+*       for (const line of ConfigIssueRenderer.render(error)) yield* Effect.logError(`  ${line}`)
+*     }),
+*   ),
+* )
+* ```
+*
+* @public
+*/
+var ConfigIssueRenderer = class {
+	constructor() {}
+	/**
+	* One line per rejected value.
+	*
+	* @remarks
+	* Takes the **error**, not its `issue`, because that is what a `catchTag`
+	* hands you and because `issue` is typed `Schema.Defect`, which every call
+	* site would otherwise have to reach into. Inside
+	* `Effect.catchTag("ConfigValidationError", …)` the error is already this
+	* shape.
+	*
+	* An unknown key the schema has a near match for at the same path ends in a
+	* hint, `unknown key at theme.colour (did you mean "color"?)`, drawn from the
+	* keys the struct declares there (every branch's, under a union) with
+	* {@link Fmt.suggest}'s threshold. A key with no near match is drawn exactly
+	* as {@link SchemaIssueRenderer} draws it.
+	*
+	* It cannot throw on a malformed value: the issue tree is validated by
+	* a guard before it is read, so a renderer on an error path never becomes the
+	* reason a program dies.
+	*/
+	static render = (error) => formatIssueWithHints(error?.issue);
+};
+
+export { ConfigIssueRenderer };

package/Doc.js

@@ -0,0 +1,548 @@
+import { autoFormat } from "./internal/autoFormat.js";
+import { totalOf, visibleCountersOf } from "./internal/counts.js";
+import { Render } from "./Render.js";
+import { Console, Effect } from "effect";
+
+// 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-kit"
+*
+* 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.
+	*
+	* @remarks
+	* `truncate` and `wrap: false` hold for every entry as they do for {@link Doc.line}: each entry is cut to the width,
+	* or kept whole on one line, rather than wrapped. Markdown keeps every entry whole either way.
+	*
+	* @param lines - the entries; each takes a string, an inline or an array of either
+	* @param options - `truncate`, to cut each entry to the width; `wrap: false`, to keep each whole
+	*/
+	static lines(lines, options) {
+		return freeze({
+			_tag: "Lines",
+			lines: frozenArray(lines.map(inlines)),
+			...options?.truncate === void 0 ? {} : { truncate: options.truncate },
+			...options?.wrap === void 0 ? {} : { wrap: options.wrap }
+		});
+	}
+	/**
+	* 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 the command itself; its message and properties are
+	* escaped, so no text in them can end the command or start another, and a `##[` in its message, title or file gets
+	* a braille pattern blank (U+2800) before the `[`, as in plain text. 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.
+	*
+	* The context is built here, at print time, so it carries the fiber's count of open Actions log groups
+	* (`RenderContext.groupDepth`): printed inside an `ActionLogger.group` from `@effected/github-actions`, a
+	* document's top-level collapsible renders as plain text rather than as a second `::group::`, which would end
+	* the open one at the runner.
+	*
+	* @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);
+	});
+};
+
+export { Doc };