@lewishowles/cli-style 0.9.0 → 0.11.0

package/src/patterns/diff-block.js

@@ -0,0 +1,333 @@
+import { background, foreground, stripAnsi } from "../formatters/ansi.js";
+import { profiles } from "../profiles/profiles.js";
+import { diffColours } from "../theme/colours.js";
+import { isNonEmptyString, isRecord, renderTitle } from "./helpers.js";
+
+// Diff line types map stable prefixes and semantic tones for text profiles.
+const diffLineTypes = {
+	added: {
+		prefix: "+ ",
+		tone: "success",
+	},
+	context: {
+		prefix: "  ",
+		tone: "muted",
+	},
+	header: {
+		prefix: "@@ ",
+		tone: "info",
+	},
+	removed: {
+		prefix: "- ",
+		tone: "danger",
+	},
+};
+
+// Full-row fills apply only to colour-enabled terminal text profiles.
+const backgroundProfiles = new Set([profiles.DIAGNOSTIC, profiles.HUMAN]);
+
+/**
+ * Render a structured diff block for human and agent output.
+ *
+ * @param  {object}  diff
+ *     Structured diff input.
+ * @param  {object[]}  diff.lines
+ *     Structured diff lines.
+ * @param  {number}  diff.lines[].oldLineNumber
+ *     Optional caller-supplied old line number.
+ * @param  {number}  diff.lines[].newLineNumber
+ *     Optional caller-supplied new line number.
+ * @param  {string}  diff.path
+ *     Optional affected path.
+ * @param  {string}  diff.title
+ *     Optional block title.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {object|string}
+ *     Structured JSON input or rendered diff block.
+ */
+export function diffBlock(diff, options = {}) {
+	if (options.profile === profiles.JSON) {
+		return diff;
+	}
+
+	if (!isRecord(diff)) {
+		return "";
+	}
+
+	const lines = normaliseLines(diff.lines);
+
+	if (lines.length === 0) {
+		return "";
+	}
+
+	const gutterWidth = getGutterWidth(lines);
+	const renderedLines = lines.map((line) => renderLine(line, options, gutterWidth));
+	const summary = gutterWidth === undefined ? "" : renderChangeSummary(lines, options);
+	const metadata = renderMetadata(diff, options, summary);
+
+	if (options.profile === profiles.AGENT) {
+		const codeFence = ["```diff", renderedLines.join("\n"), "```"].join("\n");
+
+		return [...metadata, codeFence].join("\n\n");
+	}
+
+	return [...metadata, renderedLines.join("\n")].filter((section) => section !== "").join("\n\n");
+}
+
+/**
+ * Return structured lines with supported types and text.
+ *
+ * @param  {*}  lines
+ *     Candidate diff lines.
+ * @returns  {object[]}
+ *     Valid diff lines.
+ */
+function normaliseLines(lines) {
+	if (!Array.isArray(lines)) {
+		return [];
+	}
+
+	return lines.filter(isValidLine).map((line) => ({
+		newLineNumber: normaliseLineNumber(line.newLineNumber),
+		oldLineNumber: normaliseLineNumber(line.oldLineNumber),
+		text: stripAnsi(line.text),
+		type: line.type,
+	}));
+}
+
+/**
+ * Return a valid positive line number or undefined.
+ *
+ * @param  {*}  value
+ *     Candidate line number.
+ * @returns  {number|undefined}
+ *     Normalised line number.
+ */
+function normaliseLineNumber(value) {
+	return Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+/**
+ * Return the stable gutter width for a fully numbered block.
+ *
+ * @param  {object[]}  lines
+ *     Normalised diff lines.
+ * @returns  {number|undefined}
+ *     Widest line-number width, or undefined when gutters are unavailable.
+ */
+function getGutterWidth(lines) {
+	const codeLines = lines.filter((line) => line.type !== "header");
+
+	if (codeLines.length === 0 || !codeLines.every(hasRequiredLineNumbers)) {
+		return undefined;
+	}
+
+	return Math.max(
+		...codeLines
+			.flatMap(getVisibleLineNumbers)
+			.filter((lineNumber) => lineNumber !== undefined)
+			.map((lineNumber) => String(lineNumber).length),
+	);
+}
+
+/**
+ * Return line numbers visible for one diff type.
+ *
+ * @param  {object}  line
+ *     Normalised diff line.
+ * @returns  {number[]}
+ *     Visible old and new line numbers.
+ */
+function getVisibleLineNumbers(line) {
+	if (line.type === "added") {
+		return [line.newLineNumber];
+	}
+
+	if (line.type === "removed") {
+		return [line.oldLineNumber];
+	}
+
+	return [line.oldLineNumber, line.newLineNumber];
+}
+
+/**
+ * Check whether a line has the numbers required by its diff type.
+ *
+ * @param  {object}  line
+ *     Normalised diff line.
+ * @returns  {boolean}
+ *     Whether the line can participate in a numbered gutter.
+ */
+function hasRequiredLineNumbers(line) {
+	if (line.type === "added") {
+		return line.newLineNumber !== undefined;
+	}
+
+	if (line.type === "removed") {
+		return line.oldLineNumber !== undefined;
+	}
+
+	return line.oldLineNumber !== undefined && line.newLineNumber !== undefined;
+}
+
+/**
+ * Check whether a candidate is a supported diff line.
+ *
+ * @param  {*}  line
+ *     Candidate diff line.
+ * @returns  {boolean}
+ *     Whether the line can be rendered safely.
+ */
+function isValidLine(line) {
+	return isRecord(line) && Object.hasOwn(diffLineTypes, line.type) && typeof line.text === "string";
+}
+
+/**
+ * Render optional diff metadata for the active profile.
+ *
+ * @param  {object}  diff
+ *     Structured diff input.
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {string}  summary
+ *     Optional added and removed line count.
+ * @returns  {string[]}
+ *     Rendered metadata sections.
+ */
+function renderMetadata(diff, options, summary) {
+	const metadata = [];
+
+	if (isNonEmptyString(diff.title)) {
+		const title = stripAnsi(diff.title);
+
+		metadata.push(renderTitle(formatMetadataValue(title, summary), options));
+	}
+
+	if (isNonEmptyString(diff.path)) {
+		const path = stripAnsi(diff.path);
+
+		metadata.push(`Path: ${formatMetadataValue(path, summary, diff.title)}`);
+	} else if (!isNonEmptyString(diff.title) && summary !== "") {
+		metadata.push(summary);
+	}
+
+	return metadata;
+}
+
+/**
+ * Append a change summary to the first available metadata value.
+ *
+ * @param  {string}  value
+ *     Metadata value.
+ * @param  {string}  summary
+ *     Optional change summary.
+ * @param  {*}  title
+ *     Title value used to avoid duplicating a summary on the path.
+ * @returns  {string}
+ *     Metadata value with optional summary.
+ */
+function formatMetadataValue(value, summary, title) {
+	return summary !== "" && !isNonEmptyString(title) ? `${value} ${summary}` : value;
+}
+
+/**
+ * Count added and removed lines already present in the block.
+ *
+ * @param  {object[]}  lines
+ *     Normalised diff lines.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Optional change summary.
+ */
+function renderChangeSummary(lines, options) {
+	const added = lines.filter((line) => line.type === "added").length;
+	const removed = lines.filter((line) => line.type === "removed").length;
+
+	if (added === 0 && removed === 0) {
+		return "";
+	}
+
+	const profile = options.profile ?? profiles.HUMAN;
+	const addedValue = `+${added}`;
+	const removedValue = `-${removed}`;
+
+	if (options.colour !== true || !backgroundProfiles.has(profile)) {
+		return `(${addedValue} ${removedValue})`;
+	}
+
+	return `(${foreground(addedValue, "success", options)} ${foreground(removedValue, "danger", options)})`;
+}
+
+/**
+ * Render one diff line with a stable semantic prefix.
+ *
+ * @param  {object}  line
+ *     Normalised diff line.
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {number|undefined}  gutterWidth
+ *     Stable gutter width for the block.
+ * @returns  {string}
+ *     Rendered diff line.
+ */
+function renderLine(line, options, gutterWidth) {
+	const lineType = diffLineTypes[line.type];
+	const gutter = gutterWidth === undefined ? "" : renderGutter(line, gutterWidth);
+	const lineValue = `${gutter}${lineType.prefix}${line.text}`;
+	const profile = options.profile ?? profiles.HUMAN;
+	const fill = diffColours[line.type];
+
+	if (options.colour === true && backgroundProfiles.has(profile) && fill !== undefined) {
+		return background(foreground(lineValue, fill.foreground, options), fill.background, options);
+	}
+
+	const prefix = foreground(lineType.prefix, lineType.tone, options);
+
+	return `${gutter}${prefix}${line.text}`;
+}
+
+/**
+ * Render one stable old/new line-number gutter.
+ *
+ * @param  {object}  line
+ *     Normalised diff line.
+ * @param  {number}  width
+ *     Widest line-number width in the block.
+ * @returns  {string}
+ *     Rendered gutter.
+ */
+function renderGutter(line, width) {
+	const blank = " ".repeat(width);
+	const oldNumber = formatLineNumber(line.oldLineNumber, width);
+	const newNumber = formatLineNumber(line.newLineNumber, width);
+
+	if (line.type === "added") {
+		return `${blank} ${newNumber} `;
+	}
+
+	if (line.type === "removed") {
+		return `${oldNumber} ${blank} `;
+	}
+
+	if (line.type === "context" && line.oldLineNumber === line.newLineNumber) {
+		return `${oldNumber} ${blank} `;
+	}
+
+	return `${oldNumber} ${newNumber} `;
+}
+
+/**
+ * Pad one line number to the block gutter width.
+ *
+ * @param  {number|undefined}  value
+ *     Line number to format.
+ * @param  {number}  width
+ *     Gutter width.
+ * @returns  {string}
+ *     Right-aligned number or blank placeholder.
+ */
+function formatLineNumber(value, width) {
+	return value === undefined ? " ".repeat(width) : String(value).padStart(width, " ");
+}

package/src/primitives/chip.js

@@ -21,7 +21,7 @@ const fallbackTone = "neutral";
 export function chip(label, tone = fallbackTone, options = {}) {
 	const token = chipColours[tone] ?? chipColours[fallbackTone];
 
-	if (options.colour !== true) {
+	if (options.colour !== true || options.theme === "auto") {
 		return `[${label}]`;
 	}
 

package/src/primitives/panel.js

@@ -72,7 +72,12 @@ function renderLine(line, width, isTitle, options) {
 	}
 
 	const renderedAccent = renderPanelColour(accent, options);
-	const renderedContent = background(content, panelColours.background, options);
+
+	const renderedContent = foreground(
+		background(content, panelColours.background, options),
+		panelColours.body,
+		options,
+	);
 
 	return `${renderedAccent}${isTitle ? style(renderedContent, "bold", options) : renderedContent}`;
 }

package/src/primitives/sparkline.js

@@ -0,0 +1,209 @@
+import { foreground } from "../formatters/ansi.js";
+import { getToneColour } from "../theme/colours.js";
+
+// Sparklines balance useful resolution with compact terminal output.
+const defaultWidth = 20;
+
+// Success gives an unconfigured trend a familiar positive semantic tone.
+const defaultTone = "success";
+
+// Unicode levels show eight graduated values without needing colour.
+const unicodeSymbols = "▁▂▃▄▅▆▇█";
+
+// ASCII levels provide the same eight-step visual fallback.
+const asciiSymbols = "._-:=+*#";
+
+/**
+ * Render a compact trend with stable numeric context.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @param  {string}  options.label
+ *     Optional trend label.
+ * @param  {string}  options.tone
+ *     Semantic colour tone for the trend.
+ * @param  {boolean}  options.unicode
+ *     Whether graduated Unicode characters should be used.
+ * @param  {number[]}  options.values
+ *     Finite numeric values in time order.
+ * @param  {number}  options.width
+ *     Maximum number of plotted samples.
+ * @returns  {string}
+ *     Rendered sparkline, or an empty string for unusable values.
+ */
+export function sparkline(options = {}) {
+	const values = normaliseValues(options.values);
+
+	if (values.length === 0) {
+		return "";
+	}
+
+	const range = resolveRange(values);
+	const width = normaliseWidth(options.width);
+	const sampledValues = sampleValues(values, width, range);
+	const symbols = options.unicode === false ? asciiSymbols : unicodeSymbols;
+	const trend = sampledValues.map((value) => renderValue(value, range, symbols)).join("");
+	const numericText = `latest=${values.at(-1)} min=${range.minimum} max=${range.maximum}`;
+
+	const label =
+		typeof options.label === "string" && options.label !== "" ? `${options.label}: ` : "";
+
+	const renderedTrend = renderTrend(trend, options);
+
+	return `${label}${renderedTrend} ${numericText}`;
+}
+
+/**
+ * Return finite numeric values when the input is usable.
+ *
+ * @param  {*}  values
+ *     Requested trend values.
+ * @returns  {number[]}
+ *     Finite values, or an empty array.
+ */
+function normaliseValues(values) {
+	if (
+		!Array.isArray(values) ||
+		values.length === 0 ||
+		values.some((value) => !Number.isFinite(value))
+	) {
+		return [];
+	}
+
+	return values;
+}
+
+/**
+ * Return a usable positive integer plot width.
+ *
+ * @param  {number}  width
+ *     Requested plot width.
+ * @returns  {number}
+ *     Positive integer width.
+ */
+function normaliseWidth(width) {
+	if (!Number.isFinite(width)) {
+		return defaultWidth;
+	}
+
+	return Math.max(Math.floor(width), 1);
+}
+
+/**
+ * Resolve the shared scale and extrema indexes for a trend.
+ *
+ * @param  {number[]}  values
+ *     Finite trend values.
+ * @returns  {object}
+ *     Trend range and first extrema indexes.
+ */
+function resolveRange(values) {
+	let minimum = values[0];
+	let maximum = values[0];
+	let minimumIndex = 0;
+	let maximumIndex = 0;
+
+	for (let index = 1; index < values.length; index += 1) {
+		if (values[index] < minimum) {
+			minimum = values[index];
+			minimumIndex = index;
+		}
+
+		if (values[index] > maximum) {
+			maximum = values[index];
+			maximumIndex = index;
+		}
+	}
+
+	return {
+		maximum,
+		maximumIndex,
+		minimum,
+		minimumIndex,
+	};
+}
+
+/**
+ * Reduce values to deterministic plotted samples while retaining key points.
+ *
+ * @param  {number[]}  values
+ *     Finite trend values.
+ * @param  {number}  width
+ *     Maximum number of plotted samples.
+ * @param  {object}  range
+ *     Shared trend range and extrema indexes.
+ * @returns  {number[]}
+ *     Sampled values in their original order.
+ */
+function sampleValues(values, width, range) {
+	if (values.length <= width) {
+		return values;
+	}
+
+	const latestIndex = values.length - 1;
+	const requiredIndexes = [...new Set([latestIndex, range.minimumIndex, range.maximumIndex])];
+	const selectedIndexes = new Set(requiredIndexes.slice(0, width));
+
+	const evenlySpacedIndexes = Array.from({ length: width }, (_, index) =>
+		Math.round((index * (values.length - 1)) / Math.max(width - 1, 1)),
+	);
+
+	for (const index of evenlySpacedIndexes) {
+		if (selectedIndexes.size >= width) {
+			break;
+		}
+
+		selectedIndexes.add(index);
+	}
+
+	for (let index = 0; selectedIndexes.size < width; index += 1) {
+		selectedIndexes.add(index);
+	}
+
+	return [...selectedIndexes].sort((left, right) => left - right).map((index) => values[index]);
+}
+
+/**
+ * Map one value onto the active graduated character set.
+ *
+ * @param  {number}  value
+ *     Value to render.
+ * @param  {object}  range
+ *     Full trend range used for the shared scale.
+ * @param  {string}  symbols
+ *     Graduated characters.
+ * @returns  {string}
+ *     One trend character.
+ */
+function renderValue(value, range, symbols) {
+	if (range.minimum === range.maximum) {
+		return symbols[Math.floor((symbols.length - 1) / 2)];
+	}
+
+	const ratio = (value - range.minimum) / (range.maximum - range.minimum);
+	const symbolIndex = Math.round(ratio * (symbols.length - 1));
+
+	return symbols[symbolIndex];
+}
+
+/**
+ * Apply a semantic tone only when colour output is explicitly enabled.
+ *
+ * @param  {string}  trend
+ *     Uncoloured trend text.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Trend text with optional ANSI colour.
+ */
+function renderTrend(trend, options) {
+	if (options.colour !== true) {
+		return trend;
+	}
+
+	const tone = getToneColour(options.tone, options) === null ? defaultTone : options.tone;
+
+	return foreground(trend, tone, options);
+}