@lewishowles/cli-style 0.9.0 → 0.10.0

package/src/gallery/render-gallery.js

@@ -4,6 +4,7 @@ import { commandResult } from "../patterns/command-result.js";
 import { compactDataTable } from "../patterns/compact-data-table.js";
 import { confirmationResult } from "../patterns/confirmation-result.js";
 import { diagnosticReport } from "../patterns/diagnostic-report.js";
+import { diffBlock } from "../patterns/diff-block.js";
 import { nextStepBlock } from "../patterns/next-step-block.js";
 import { taskSummary } from "../patterns/task-summary.js";
 import { stripAnsi } from "../formatters/ansi.js";
@@ -15,6 +16,7 @@ import { panel } from "../primitives/panel.js";
 import { progressBar } from "../primitives/progress-bar.js";
 import { row } from "../primitives/row.js";
 import { rowGroup } from "../primitives/row-group.js";
+import { sparkline } from "../primitives/sparkline.js";
 import { span } from "../primitives/span.js";
 import { status } from "../primitives/status.js";
 import { step, stepProgress, stepStates } from "../primitives/step-progress.js";
@@ -115,7 +117,7 @@ export const galleryVariants = ["current", "no-colour", "no-unicode", "plain"];
 // Gallery sections available for focused output.
 export const gallerySections = ["primitives", "patterns"];
 
-// Pattern fixtures available for focused output and interactive search.
+// Fixtures available for focused output and interactive search.
 export const galleryFixtures = [
 	"diagnostic-report",
 	"reporter",
@@ -127,6 +129,8 @@ export const galleryFixtures = [
 	"compact-data-table-narrow",
 	"confirmation-result",
 	"next-step-block",
+	"diff-block",
+	"sparkline",
 ];
 
 /**
@@ -179,7 +183,11 @@ function renderVariant(variant, options, request) {
 	const sections = [];
 
 	if (request.fixture !== undefined) {
-		sections.push(renderPatterns(resolvedVariant.options, request.fixture));
+		sections.push(
+			request.fixture === "sparkline"
+				? renderSparklineFixture(resolvedVariant.options)
+				: renderPatterns(resolvedVariant.options, request.fixture),
+		);
 	} else {
 		if (request.section === undefined || request.section === "primitives") {
 			sections.push(renderPrimitives(resolvedVariant.options));
@@ -434,6 +442,36 @@ function renderPatterns(options, fixture) {
 		options,
 	);
 
+	const diff = diffBlock(
+		{
+			lines: [
+				{
+					text: "render()",
+					type: "header",
+				},
+				{
+					newLineNumber: 102,
+					text: "return nextStep;",
+					type: "added",
+				},
+				{
+					oldLineNumber: 101,
+					text: "return currentStep;",
+					type: "removed",
+				},
+				{
+					newLineNumber: 100,
+					oldLineNumber: 100,
+					text: "const currentStep = getStep();",
+					type: "context",
+				},
+			],
+			path: "src/render.js",
+			title: "Renderer change",
+		},
+		options,
+	);
+
 	const reporter = createReporter(options);
 
 	reporter.divider("Project setup", "Claude + Codex");
@@ -561,6 +599,7 @@ function renderPatterns(options, fixture) {
 		"compact-data-table-narrow": ["Compact data table (narrow)", narrowCompactTable],
 		"confirmation-result": ["Confirmation result", confirmation],
 		"diagnostic-report": ["Diagnostic report", report],
+		"diff-block": ["Diff block", diff],
 		"next-step-block": ["Next-step block", nextStep],
 		reporter: ["Reporter", reporterOutput],
 		"task-summary": ["Task summary", summary],
@@ -594,6 +633,9 @@ function renderPatterns(options, fixture) {
 		"Audit finding",
 		frameExample(audit, options),
 		"",
+		"Diff block",
+		frameExample(diff, options),
+		"",
 		"Compact data table",
 		frameExample(compactTable, options),
 		"",
@@ -622,6 +664,18 @@ function renderPatternFixture(fixture, options) {
 	return [fixture[0], frameExample(fixture[1], options)].join("\n");
 }
 
+/**
+ * Render the focused sparkline fixture.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Framed sparkline fixture output.
+ */
+function renderSparklineFixture(options) {
+	return ["Sparkline", frameExample(renderSparklineExample(options), options)].join("\n");
+}
+
 /**
  * Add gallery-only framing around one rendered example.
  *
@@ -668,6 +722,9 @@ function renderPrimitives(options) {
 		"Bar charts",
 		renderBarChartExample(options),
 		"",
+		"Sparklines",
+		renderSparklineExample(options),
+		"",
 		"Tables",
 		renderTableExample(options),
 		"",
@@ -806,6 +863,55 @@ function renderBarChartExample(options) {
 	});
 }
 
+/**
+ * Render representative sparkline sequences.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Sparkline examples.
+ */
+function renderSparklineExample(options) {
+	const examples = [
+		{
+			label: "Rising",
+			tone: "success",
+			values: [1, 2, 3, 4, 5, 6],
+		},
+		{
+			label: "Falling",
+			tone: "danger",
+			values: [6, 5, 4, 3, 2, 1],
+		},
+		{
+			label: "Flat",
+			tone: "info",
+			values: [4, 4, 4, 4, 4, 4],
+		},
+		{
+			label: "Negative",
+			tone: "warning",
+			values: [-6, -4, -5, -2, -3, -1],
+		},
+		{
+			label: "Narrow mixed",
+			tone: "info",
+			values: [0, 10, -5, 5, 2, 8, -2],
+			width: 4,
+		},
+	];
+
+	return examples
+		.map((example) =>
+			sparkline({
+				...options,
+				...example,
+				width: example.width ?? 16,
+			}),
+		)
+		.join("\n");
+}
+
 /**
  * Render common progress values and tones.
  *

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";
@@ -36,10 +46,12 @@ 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,
@@ -47,10 +59,12 @@ export {
 	renderReporterStatus,
 	renderSection,
 } from "./reporters/create-reporter.js";
+
 export {
 	chartColours,
 	chipColours,
 	colourTokens,
+	diffColours,
 	getColourToken,
 	getToneColour,
 	panelColours,
@@ -58,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}`;
 }