@lewishowles/cli-style 0.8.1 → 0.10.0

package/src/index.js

@@ -1,16 +1,25 @@
 export { createCliStyle, profiles } from "./create-cli-style.js";
 
 export { resolveProfile } from "./capability/resolve-profile.js";
-export { resolveTerminalCapabilities } from "./capability/terminal.js";
+export { resolveTerminalCapabilities, resolveTheme } from "./capability/terminal.js";
 export { isProfile } from "./profiles/profiles.js";
 
 export { renderHelp } from "./cli/help.js";
+export { parseCatalogueRequest, renderCatalogue } from "./cli/catalogue-command.js";
+export {
+	getRendererMetadata,
+	rendererCatalogue,
+	rendererNames,
+} from "./catalogue/renderer-catalogue.js";
+
 export {
 	adapterNames,
 	parseAdapterPathRequest,
 	renderAdapterPath,
 } from "./cli/adapter-path-command.js";
-export { parseRenderRequest, rendererNames, renderJsonInput } from "./cli/render-command.js";
+
+export { parseRenderRequest, renderJsonInput } from "./cli/render-command.js";
+
 export {
 	galleryFixtures,
 	gallerySections,
@@ -26,6 +35,7 @@ export { commandResult } from "./patterns/command-result.js";
 export { compactDataTable } from "./patterns/compact-data-table.js";
 export { confirmationResult } from "./patterns/confirmation-result.js";
 export { diagnosticReport } from "./patterns/diagnostic-report.js";
+export { diffBlock } from "./patterns/diff-block.js";
 export { nextStepBlock } from "./patterns/next-step-block.js";
 export { taskSummary } from "./patterns/task-summary.js";
 export { barChart } from "./primitives/bar-chart.js";
@@ -35,10 +45,13 @@ export { emptyState, errorBlock, hint } from "./primitives/feedback.js";
 export { panel } from "./primitives/panel.js";
 export { progressBar } from "./primitives/progress-bar.js";
 export { row } from "./primitives/row.js";
+export { rowGroup } from "./primitives/row-group.js";
+export { sparkline } from "./primitives/sparkline.js";
 export { span } from "./primitives/span.js";
 export { status } from "./primitives/status.js";
 export { step, stepProgress, stepStates } from "./primitives/step-progress.js";
 export { table } from "./primitives/table.js";
+
 export {
 	createReporter,
 	renderGroup,
@@ -46,10 +59,12 @@ export {
 	renderReporterStatus,
 	renderSection,
 } from "./reporters/create-reporter.js";
+
 export {
 	chartColours,
 	chipColours,
 	colourTokens,
+	diffColours,
 	getColourToken,
 	getToneColour,
 	panelColours,
@@ -57,8 +72,10 @@ export {
 	resolveColourValue,
 	tableColours,
 	terminalColours,
+	themes,
 	toneColours,
 } from "./theme/colours.js";
+
 export {
 	getHighestSeverityResult,
 	getResultSymbol,

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/row-group.js

@@ -0,0 +1,84 @@
+import { getResultSymbol } from "../theme/results.js";
+import { row } from "./row.js";
+
+/**
+ * Render related labelled values against a shared label width.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {number}  options.labelWidth
+ *     Optional minimum label width.
+ * @param  {object[]}  options.rows
+ *     Labelled values to render.
+ * @returns  {string}
+ *     Rendered row group.
+ */
+export function rowGroup(options = {}) {
+	const rows = normaliseRows(options.rows);
+
+	if (rows.length === 0) {
+		return "";
+	}
+
+	const labelWidth = Math.max(
+		...rows.map((entry) => displayedLabelLength(entry, options)),
+		options.labelWidth ?? 0,
+	);
+
+	return rows
+		.map((entry) =>
+			row(entry.label, entry.value ?? "", {
+				...options,
+				...entry,
+				labelWidth,
+			}),
+		)
+		.join("\n");
+}
+
+/**
+ * Return rows with usable labels.
+ *
+ * @param  {object[]}  rows
+ *     Requested row entries.
+ * @returns  {object[]}
+ *     Valid row entries.
+ */
+function normaliseRows(rows) {
+	if (!Array.isArray(rows)) {
+		return [];
+	}
+
+	return rows.filter(
+		(entry) =>
+			entry !== null &&
+			typeof entry === "object" &&
+			typeof entry.label === "string" &&
+			entry.label !== "",
+	);
+}
+
+/**
+ * Return the visible width of a row label.
+ *
+ * @param  {object}  entry
+ *     Row entry.
+ * @param  {object}  options
+ *     Group rendering options.
+ * @returns  {number}
+ *     Displayed label length.
+ */
+function displayedLabelLength(entry, options) {
+	if (typeof entry.result !== "string" || entry.result === "") {
+		return entry.label.length;
+	}
+
+	const entryOptions = {
+		...options,
+		...entry,
+	};
+
+	const symbol = getResultSymbol(entry.result, entryOptions);
+
+	return [symbol, entry.label].join(" ").length;
+}