@effected/cli 0.9.0 → 0.11.0

package/internal/fileSink.js

@@ -0,0 +1,62 @@
+import { sanitize } from "../Fmt.js";
+import { formatNdjson, passes } from "./diagnostics.js";
+import { Cause, Console, Effect, Exit, Fiber, FileSystem, Logger, Path, Queue } from "effect";
+import { CommandNeutralizer } from "@effected/github-commands";
+
+//#region src/internal/fileSink.ts
+/** How long closing the scope waits for queued lines to reach the file before giving up on a hung filesystem. */
+const CLOSE_TIMEOUT = "2 seconds";
+/**
+* An asynchronous NDJSON file logger.
+*
+* @remarks
+* `Logger.make` takes a synchronous callback, so the logger only offers the line to a queue; a fiber scoped to the
+* layer drains it and appends each batch with `FileSystem.writeFileString(..., { flag: "a" })`. The first write
+* error prints one stderr line and disables the sink: later lines, including any still queued, are discarded
+* without a message. A defect from the filesystem counts as a write error. Closing the scope ends the queue and
+* waits for the drain for at most two seconds, so lines queued before the close are flushed unless the sink had
+* already disabled itself or the filesystem hangs; past the bound the drain is interrupted and the rest is lost.
+*
+* The stderr line is held to the rules of every other kit write: the path (which a workflow can set through an env
+* var) and the error's message are sanitised, and the line is neutralized when `underActions` says the drain's fiber
+* runs under GitHub Actions, the same decision the diagnostics sink makes.
+*
+* @internal
+*/
+const makeFileSink = (path, installed, underActions) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const location = yield* Path.Path;
+	const queue = yield* Queue.unbounded();
+	let disabled = false;
+	let directoryMade = false;
+	const append = (lines) => Effect.gen(function* () {
+		if (!directoryMade) {
+			yield* fs.makeDirectory(location.dirname(path), { recursive: true });
+			directoryMade = true;
+		}
+		yield* fs.writeFileString(path, lines.map((line) => `${line}\n`).join(""), { flag: "a" });
+	});
+	const drain = Effect.gen(function* () {
+		while (true) {
+			const batch = yield* Queue.takeAll(queue);
+			if (disabled) continue;
+			const exit = yield* Effect.exit(append(batch));
+			if (Exit.isFailure(exit)) {
+				disabled = true;
+				const error = Cause.squash(exit.cause);
+				const message = error instanceof Error ? error.message : String(error);
+				const line = sanitize(`diagnostics log file ${path} failed: ${message}; further file logging disabled`);
+				yield* Effect.withFiber((self) => Console.error(underActions(self) ? CommandNeutralizer.text(line) : line));
+			}
+		}
+	}).pipe(Effect.ignore);
+	const fiber = yield* Effect.forkScoped(drain);
+	yield* Effect.addFinalizer(() => Queue.end(queue).pipe(Effect.andThen(Fiber.join(fiber).pipe(Effect.timeout(CLOSE_TIMEOUT))), Effect.ignore));
+	return Logger.make((record) => {
+		if (!passes(record, installed)) return;
+		Queue.offerUnsafe(queue, formatNdjson(record));
+	});
+});
+
+//#endregion
+export { makeFileSink };

package/internal/format.js

@@ -37,14 +37,69 @@ const formatter = SchemaIssue.makeFormatterStandardSchemaV1({ leafHook: (issue)
 *
 * @internal
 */
-const formatIssue = (issue) => {
+const formatIssue = (issue) => issueEntries(issue).map((entry) => entry.path.length === 0 ? entry.message : `${entry.message} at ${entry.path.join(".")}`);
+/**
+* The rejected values of an issue tree, once each: what both the lines and the tree are built from.
+*
+* @remarks
+* Anything that is not an issue tree yields none rather than throwing. A rendering helper on an error path must never
+* become the reason a program dies: it is called when something has already gone wrong. A union reports every branch
+* it tried, so one wrong key in a three-member union is the same entry three times; the per-branch "Missing key"
+* entries differ and are kept, since they say which shapes were allowed, but the repeat is pure noise in front of them.
+*
+* @internal
+*/
+const issueEntries = (issue) => {
 	if (!SchemaIssue.isIssue(issue)) return [];
-	const lines = formatter(issue).issues.map((entry) => {
-		const path = (entry.path ?? []).map(String).join(".");
-		return path === "" ? entry.message : `${entry.message} at ${path}`;
-	});
-	return [...new Set(lines)];
+	const seen = /* @__PURE__ */ new Set();
+	const entries = [];
+	for (const entry of formatter(issue).issues) {
+		const path = (entry.path ?? []).map(String);
+		const key = path.length === 0 ? entry.message : `${entry.message} at ${path.join(".")}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		entries.push({
+			message: entry.message,
+			path
+		});
+	}
+	return entries;
+};
+const emptyNode = () => ({
+	messages: [],
+	children: /* @__PURE__ */ new Map()
+});
+/**
+* The entries as the input of a `Doc.tree`: one node per path segment, so `groups.g.extra` is three nested nodes, and
+* the message at the end of a path is the node's label (`extra: unknown key`) or, when the node has more to say, its
+* leaves.
+*
+* @internal
+*/
+const issueTreeChildren = (entries) => {
+	const root = emptyNode();
+	for (const entry of entries) {
+		let node = root;
+		for (const segment of entry.path) {
+			let next = node.children.get(segment);
+			if (next === void 0) {
+				next = emptyNode();
+				node.children.set(segment, next);
+			}
+			node = next;
+		}
+		node.messages.push(entry.message);
+	}
+	const leaves = (node) => node.messages.map((message) => ({ label: message }));
+	const named = (segment, node) => {
+		if (node.children.size === 0 && node.messages.length === 1) return { label: `${segment}: ${node.messages[0]}` };
+		return {
+			label: segment,
+			children: [...leaves(node), ...[...node.children].map(([name, child]) => named(name, child))]
+		};
+	};
+	return [...leaves(root), ...[...root.children].map(([name, child]) => named(name, child))];
 };
 
 //#endregion
-export { formatIssue };
+export { formatIssue, issueEntries, issueTreeChildren };

package/internal/layout.js

@@ -0,0 +1,250 @@
+import { displayWidth, graphemes } from "./displayWidth.js";
+import { sanitize } from "../Fmt.js";
+
+//#region src/internal/layout.ts
+const pathSeparator = (ctx) => ctx.audience === "agent" ? ctx.glyphs.pathSeparator.agent : ` ${ctx.glyphs.pathSeparator.human} `;
+/** A link target is sanitized like content, and loses its line breaks, which no URL or path holds. */
+const safeTargetText = (text) => sanitize(text).replace(/[\r\n]/g, "");
+const safeTarget = (target) => "url" in target ? { url: safeTargetText(target.url) } : {
+	...target,
+	file: safeTargetText(target.file)
+};
+const spansOf = (inline, ctx) => {
+	switch (inline._tag) {
+		case "Text": return [{
+			text: sanitize(inline.value),
+			...inline.token === void 0 ? {} : { token: inline.token }
+		}];
+		case "Code": return [{
+			text: sanitize(inline.value),
+			code: true
+		}];
+		case "Link": {
+			const link = safeTarget(inline.target);
+			const suffix = inline.suffix === void 0 ? {} : { suffix: inline.suffix };
+			return inline.label.flatMap((part) => spansOf(part, ctx)).map((span) => ({
+				...span,
+				link,
+				...suffix
+			}));
+		}
+		case "StatusMark": return [{
+			text: sanitize(ctx.glyphs.kind === "ascii" ? inline.def.ascii : inline.def.glyph),
+			token: inline.def.token,
+			glyph: true
+		}];
+		case "Path": return [{ text: inline.segments.map(sanitize).join(pathSeparator(ctx)) }];
+		case "Strong": return inline.content.flatMap((part) => spansOf(part, ctx)).map((span) => ({
+			...span,
+			strong: true
+		}));
+		case "Emphasis": return inline.content.flatMap((part) => spansOf(part, ctx)).map((span) => ({
+			...span,
+			em: true
+		}));
+		case "File": return [{ text: safeTargetText(ctx.displayPath(inline.path)) }];
+	}
+};
+/**
+* Flatten inline nodes into spans.
+*
+* @remarks
+* A `Path` becomes its segments joined by the audience's separator (`›` with spaces around it for a person, ` > `
+* for an agent), a `StatusMark` its glyph from the context's glyph set painted with the definition's token, and a
+* `Code` its text with `code` set. Escape sequences in content and in link targets are removed and empty spans
+* dropped.
+*
+* @internal
+*/
+const flatten = (inlines, ctx) => inlines.flatMap((inline) => spansOf(inline, ctx)).filter((span) => span.text !== "");
+/**
+* The display width of spans in terminal columns.
+*
+* @remarks
+* Graphemes are measured within a span, deliberately: a cluster split across two spans (the two halves of a flag,
+* a joiner and the next emoji) counts as two characters, as it is laid out. Content does not split a cluster unless
+* the caller does.
+*
+* @internal
+*/
+const widthOf = (spans) => spans.reduce((sum, span) => sum + displayWidth(span.text), 0);
+const cellsOf = (spans) => spans.flatMap((span) => graphemes(span.text).map((grapheme) => ({
+	grapheme,
+	width: displayWidth(grapheme),
+	span
+})));
+/** Rebuild spans from cells, merging a run that came from the same span. */
+const spansFromCells = (cells) => {
+	const out = [];
+	let current;
+	for (const cell of cells) if (cell.span === current) {
+		const last = out[out.length - 1];
+		out[out.length - 1] = {
+			...last,
+			text: last.text + cell.grapheme
+		};
+	} else {
+		current = cell.span;
+		out.push({
+			...cell.span,
+			text: cell.grapheme
+		});
+	}
+	return out;
+};
+/**
+* Cut spans to at most `width` columns, marking the cut with `ellipsis`.
+*
+* @remarks
+* Cuts on grapheme boundaries and before any painting, so a colour or hyperlink is never cut in half: the kept
+* text keeps its span's token and link, and the marker joins the last kept span (or follows a `Code` span as plain
+* text under the same link). When nothing but the marker fits, it takes the first span's token and link, as it
+* stands for the whole label. Spans that already fit are returned as they are. An ellipsis that cannot fit is
+* omitted, and a `width` of 0 or less gives no spans.
+*
+* @internal
+*/
+const truncateSpans = (spans, width, ellipsis) => {
+	const limit = Number.isNaN(width) ? 0 : Math.floor(width);
+	if (limit <= 0) return [];
+	if (widthOf(spans) <= limit) return spans;
+	const ellipsisWidth = displayWidth(ellipsis);
+	const useEllipsis = ellipsis !== "" && ellipsisWidth <= limit;
+	const budget = useEllipsis ? limit - ellipsisWidth : limit;
+	const kept = [];
+	let used = 0;
+	for (const cell of cellsOf(spans)) {
+		if (used + cell.width > budget) break;
+		kept.push(cell);
+		used += cell.width;
+	}
+	const out = spansFromCells(kept);
+	if (!useEllipsis) return out;
+	const last = out[out.length - 1];
+	if (last === void 0) {
+		const first = spans[0];
+		return [{
+			text: ellipsis,
+			...first.token === void 0 ? {} : { token: first.token },
+			...first.link === void 0 ? {} : { link: first.link }
+		}];
+	}
+	if (last.code === true) return [...out, {
+		text: ellipsis,
+		...last.link === void 0 ? {} : { link: last.link }
+	}];
+	return [...out.slice(0, -1), {
+		...last,
+		text: last.text + ellipsis
+	}];
+};
+/**
+* Paint spans, then link them: the string a terminal shows.
+*
+* @remarks
+* Each span is painted with its token, and consecutive spans that share a link (by identity) are wrapped in one
+* hyperlink. Truncate and wrap first: painting is last, so an escape sequence is never cut.
+*
+* @internal
+*/
+const paintSpans = (spans, ctx) => {
+	const paint = (span) => {
+		const toned = span.token === void 0 ? span.text : ctx.paint(span.token, span.text);
+		const bold = span.strong === true ? ctx.paint({ bold: true }, toned) : toned;
+		return span.em === true ? ctx.paint({ italic: true }, bold) : bold;
+	};
+	let out = "";
+	let i = 0;
+	while (i < spans.length) {
+		const start = spans[i];
+		let run = paint(start);
+		i++;
+		if (start.link === void 0) {
+			out += run;
+			continue;
+		}
+		while (i < spans.length && spans[i].link === start.link) {
+			run += paint(spans[i]);
+			i++;
+		}
+		out += ctx.link(start.link, run);
+	}
+	return out;
+};
+const isLineBreak = (grapheme) => grapheme === "\n" || grapheme === "\r\n" || grapheme === "\r";
+const cellsWidth = (cells) => cells.reduce((sum, cell) => sum + cell.width, 0);
+/**
+* Word-wrap spans to `width` columns.
+*
+* @remarks
+* Spaces are the break points, and the space at a break is dropped, as are trailing spaces; spaces inside a line,
+* and the indentation of the first line or one after a newline, are kept. A newline is a forced break. A word
+* longer than the width starts on a line of its own and is broken at the edge, never inside a grapheme, so a wide
+* character never straddles it. A grapheme wider than the width (a width of 1 and a wide character) takes a line
+* to itself, the only way to make progress. With `hardBreak: false` a long word is not broken at all: it keeps a line
+* of its own and runs past the width, which is right for a URL or a path. A `width` under 1 is treated as 1. Each character keeps its span's
+* token and link.
+*
+* @internal
+*/
+const wrapSpans = (spans, width, options) => {
+	const limit = Number.isNaN(width) ? 1 : Math.max(1, Math.floor(width));
+	const cells = cellsOf(spans);
+	const lines = [];
+	let line = [];
+	let used = 0;
+	let keepLeading = true;
+	const flush = () => {
+		lines.push(line);
+		line = [];
+		used = 0;
+	};
+	let i = 0;
+	while (i < cells.length) {
+		if (isLineBreak(cells[i].grapheme)) {
+			flush();
+			keepLeading = true;
+			i++;
+			continue;
+		}
+		const spaces = [];
+		while (i < cells.length && cells[i].grapheme === " ") spaces.push(cells[i++]);
+		const word = [];
+		while (i < cells.length) {
+			const { grapheme } = cells[i];
+			if (grapheme === " " || isLineBreak(grapheme)) break;
+			word.push(cells[i++]);
+		}
+		if (word.length === 0) continue;
+		const lead = line.length > 0 || keepLeading ? spaces : [];
+		const leadWidth = cellsWidth(lead);
+		const wordWidth = cellsWidth(word);
+		if (used + leadWidth + wordWidth <= limit) {
+			line.push(...lead, ...word);
+			used += leadWidth + wordWidth;
+			continue;
+		}
+		if (line.length > 0) {
+			flush();
+			keepLeading = false;
+		}
+		if (wordWidth <= limit || options?.hardBreak === false) {
+			line.push(...word);
+			used = wordWidth;
+			continue;
+		}
+		for (const cell of word) {
+			if (used + cell.width > limit && line.length > 0) {
+				flush();
+				keepLeading = false;
+			}
+			line.push(cell);
+			used += cell.width;
+		}
+	}
+	if (line.length > 0 || lines.length === 0) flush();
+	return lines.map(spansFromCells);
+};
+
+//#endregion
+export { flatten, paintSpans, truncateSpans, widthOf, wrapSpans };

package/internal/linkScheme.js

@@ -0,0 +1,30 @@
+import { sanitize } from "../Fmt.js";
+
+//#region src/internal/linkScheme.ts
+/** The URL schemes a link may have, besides a relative URL. */
+const ALLOWED = /* @__PURE__ */ new Set([
+	"http",
+	"https",
+	"mailto",
+	"file",
+	"vscode",
+	"vscode-insiders"
+]);
+/**
+* Whether a link may point at this URL: its scheme is one of `http`, `https`, `mailto`, `file`, `vscode` and
+* `vscode-insiders`, or it has none (a relative URL or a fragment).
+*
+* @remarks
+* The scheme is read from a normalised copy, with control characters and whitespace removed and the case folded,
+* because a browser ignores them inside a scheme (`java<tab>script:`). One list serves every renderer that writes a
+* link, so `javascript:`, `data:` and the like are refused the same way in markdown and in a terminal's OSC 8.
+*
+* @internal
+*/
+const isAllowedLinkUrl = (url) => {
+	const scheme = /^([a-z][a-z0-9+.-]*):/.exec(sanitize(url).replace(/\s/g, "").toLowerCase());
+	return scheme === null || ALLOWED.has(scheme[1]);
+};
+
+//#endregion
+export { isAllowedLinkUrl };

package/internal/linkTarget.js

@@ -0,0 +1,50 @@
+//#region src/internal/linkTarget.ts
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+/**
+* A Windows drive path (`C:\x`, `C:/x`): absolute whatever the `Path` flavour, so never resolved against a directory.
+*
+* The one false positive is a relative POSIX path whose first directory is a single letter followed by a colon, such
+* as `a:/b.txt`, which reads as drive `a`. Such a filename is vanishingly rare, and recognising a drive is what makes
+* `C:\x` work on a POSIX `Path`, where it is otherwise a relative filename. A colon anywhere else (`/a/C:b`,
+* `./C:x`, `src/C:/x.ts`) is data and stays encoded.
+*
+* @internal
+*/
+const DRIVE = /^[A-Za-z]:[\\/]/;
+/**
+* A UNC path (`\\server\share\a.ts`, `//server/share/a.ts`): neither a drive nor a path on this machine, so it has no
+* link target. Left to a POSIX `Path` it would be read as a relative filename and linked to a file that does not exist.
+*
+* @internal
+*/
+const UNC = /^(?:\\\\|\/\/)/;
+/**
+* RFC 3986: everything but the unreserved characters is percent-encoded, in each segment, and `/` is kept.
+*
+* @internal
+*/
+const encodePath = (path) => path.replace(LONE_SURROGATE, "�").split("/").map((segment) => encodeURIComponent(segment).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)).join("/");
+/**
+* The encoded path part of a `file:` URL for an absolute path (the part after `file://`), or `undefined` for a UNC
+* path. One builder, so `CliLinks` and `Render.markdown` link a file the same way.
+*
+* @remarks
+* A drive path keeps its drive and becomes `/C:/x/y.ts`: the colon is part of the URL's path, not data to encode.
+*
+* @internal
+*/
+const fileUrlPath = (absolute) => {
+	if (UNC.test(absolute)) return void 0;
+	if (DRIVE.test(absolute)) return `/${absolute.slice(0, 2)}${encodePath(absolute.slice(2).replace(/\\/g, "/"))}`;
+	return encodePath(absolute.startsWith("/") ? absolute : `/${absolute.replace(/\\/g, "/")}`);
+};
+/**
+* A URL for an OSC 8 sequence: every character outside printable ASCII (32 to 126) is percent-encoded as its UTF-8
+* bytes, as the OSC 8 convention asks, and nothing already encoded is touched, so `%C3%A9` is not encoded twice.
+*
+* @internal
+*/
+const encodeForOsc8 = (url) => url.replace(LONE_SURROGATE, "�").replace(/[^\x20-\x7e]/gu, (char) => encodeURIComponent(char));
+
+//#endregion
+export { DRIVE, UNC, encodeForOsc8, encodePath, fileUrlPath };

package/internal/logSafety.js

@@ -0,0 +1,46 @@
+import { sanitize } from "../Fmt.js";
+import { Context, Option } from "effect";
+import { CurrentRuntimeEnv } from "@effected/env";
+
+//#region src/internal/logSafety.ts
+/**
+* Marks a log line the kit has already rendered, so the logger does not strip the escapes the kit painted into it.
+*
+* @remarks
+* The failure report renders a document for the audience (painted for a person) and writes each line through the
+* logger. That text is not consumer-supplied any more: its consumer text was sanitised when the document was built. A
+* `Reference` rather than a log annotation, so it never appears in a diagnostics record.
+*
+* @internal
+*/
+const TrustedLine = Context.Reference("@effected/cli/TrustedLine", { defaultValue: () => false });
+/**
+* Whether the logging fiber runs under GitHub Actions: `CurrentRuntimeEnv`, read from the fiber's own context (a
+* `Logger` callback is synchronous and cannot `yield*`), says so. Absent, no.
+*
+* @internal
+*/
+const underActionsIn = (fiber) => {
+	const runtime = Context.getOption(fiber.context, CurrentRuntimeEnv);
+	return Option.contains(Option.flatMap(runtime, (env) => env.ci), "github-actions");
+};
+/**
+* The string parts of a log message, sanitised: what a custom `render` receives, so it paints over clean input.
+*
+* @internal
+*/
+const sanitizeParts = (message) => {
+	if (typeof message === "string") return sanitize(message);
+	if (Array.isArray(message)) return message.map((part) => typeof part === "string" ? sanitize(part) : part);
+	return message;
+};
+/**
+* Neutralize the `##[` the runner's legacy parser finds anywhere in a line, inside an NDJSON record, as the JSON escape
+* `##[`: it decodes to the identical text, so the record loses nothing. A `##[` can only sit in a string there.
+*
+* @internal
+*/
+const neutralizeJson = (line) => line.replaceAll("##[", "#\\u0023[");
+
+//#endregion
+export { TrustedLine, neutralizeJson, sanitizeParts, underActionsIn };

package/internal/renderAnsi.js

@@ -0,0 +1,52 @@
+import { flatten, paintSpans } from "./layout.js";
+import { renderDoc, showsSuffix, targetText } from "./renderDoc.js";
+
+//#region src/internal/renderAnsi.ts
+/**
+* Inline content as styled spans: code painted `accent` with no backticks, and links kept on their spans so that
+* painting wraps them through `ctx.link`.
+*
+* When `ctx.link` does not make a hyperlink (it returns the label unchanged), the target would be lost, so it follows
+* the label in parentheses, muted, unless the label already is the target. That is decided here, before layout, so
+* widths and wrapping count it.
+*/
+const inline = (inlines, ctx) => {
+	const flat = flatten(inlines, ctx);
+	const out = [];
+	let i = 0;
+	while (i < flat.length) {
+		const link = flat[i].link;
+		let label = "";
+		do {
+			const span = flat[i];
+			label += span.text;
+			out.push(span.code === true && span.token === void 0 ? {
+				...span,
+				token: "accent"
+			} : span);
+			i++;
+		} while (link !== void 0 && i < flat.length && flat[i].link === link);
+		if (link !== void 0 && ctx.link(link, label) === label) {
+			const target = targetText(link, ctx);
+			if (showsSuffix(flat[i - 1].suffix, label, target)) out.push({
+				text: ` (${target})`,
+				token: "muted"
+			});
+		}
+	}
+	return out;
+};
+const ansi = {
+	inline,
+	finish: (line, ctx) => paintSpans(line, ctx)
+};
+/**
+* Render a document for a person: the layout of plain text, painted with the context's tokens and linked through its
+* `link` function.
+*
+* @internal
+*/
+const renderAnsi = (doc, ctx) => renderDoc(doc, ctx, ansi);
+
+//#endregion
+export { renderAnsi };