@lewishowles/cli-style 0.1.0

package/src/patterns/diagnostic-report.js

@@ -0,0 +1,144 @@
+import { profiles } from "../profiles/profiles.js";
+import { status } from "../primitives/status.js";
+import { resultTypes } from "../theme/results.js";
+import {
+	formatLabel,
+	isNonEmptyString,
+	isRecord,
+	renderSection,
+	renderTitle,
+} from "./helpers.js";
+
+// Diagnostic reports use a stable title when the caller does not provide one.
+const defaultTitle = "Diagnostic report";
+
+/**
+ * Render check summaries, findings, skipped checks, and next actions.
+ *
+ * @param  {object}  report
+ *     Structured diagnostic report.
+ * @param  {object[]}  report.checks
+ *     Checks with a name, result, and optional detail.
+ * @param  {object[]}  report.findings
+ *     Findings with a result and message.
+ * @param  {string[]}  report.nextActions
+ *     Ordered follow-up actions.
+ * @param  {object[]}  report.skippedChecks
+ *     Skipped checks with a name and optional reason.
+ * @param  {string}  report.title
+ *     Report title.
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {string}  options.profile
+ *     Active output profile.
+ * @returns  {object|string}
+ *     Structured JSON input or rendered diagnostic text.
+ */
+export function diagnosticReport(report, options = {}) {
+	if (options.profile === profiles.JSON) {
+		return report;
+	}
+
+	if (!isRecord(report)) {
+		return "";
+	}
+
+	const sections = [
+		renderChecks(report.checks, options),
+		renderFindings(report.findings, options),
+		renderSkippedChecks(report.skippedChecks, options),
+		renderNextActions(report.nextActions, options),
+	].filter((section) => section !== "");
+	const title = typeof report.title === "string" && report.title !== ""
+		? report.title
+		: defaultTitle;
+	return [renderTitle(title, options), ...sections].join("\n\n");
+}
+
+/**
+ * Render completed check summaries.
+ *
+ * @param  {object[]}  checks
+ *     Checks to render.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered checks section.
+ */
+function renderChecks(checks, options) {
+	const validChecks = Array.isArray(checks)
+		? checks.filter((check) => isRecord(check) && isNonEmptyString(check.name))
+		: [];
+	const lines = validChecks.map((check) => status(
+		check.result,
+		formatLabel(check.name, check.detail, options),
+		options,
+	));
+
+	return renderSection("Checks", lines, options);
+}
+
+/**
+ * Render diagnostic findings.
+ *
+ * @param  {object[]}  findings
+ *     Findings to render.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered findings section.
+ */
+function renderFindings(findings, options) {
+	const validFindings = Array.isArray(findings)
+		? findings.filter((finding) => isRecord(finding) && isNonEmptyString(finding.message))
+		: [];
+	const lines = validFindings.map((finding) => status(
+		finding.result,
+		finding.message,
+		options,
+	));
+
+	return renderSection("Findings", lines, options);
+}
+
+/**
+ * Render skipped checks.
+ *
+ * @param  {object[]}  skippedChecks
+ *     Skipped checks to render.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered skipped-check section.
+ */
+function renderSkippedChecks(skippedChecks, options) {
+	const validChecks = Array.isArray(skippedChecks)
+		? skippedChecks.filter((check) => isRecord(check) && isNonEmptyString(check.name))
+		: [];
+	const lines = validChecks.map((check) => status(
+		resultTypes.SKIPPED,
+		formatLabel(check.name, check.reason, options),
+		options,
+	));
+
+	return renderSection("Skipped checks", lines, options);
+}
+
+/**
+ * Render ordered next actions.
+ *
+ * @param  {string[]}  nextActions
+ *     Actions to render.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered next-action section.
+ */
+function renderNextActions(nextActions, options) {
+	const validActions = Array.isArray(nextActions)
+		? nextActions.filter(isNonEmptyString)
+		: [];
+	const lines = validActions.map((action, index) => `${index + 1}. ${action}`);
+
+	return renderSection("Next actions", lines, options, false);
+}

package/src/patterns/helpers.js

@@ -0,0 +1,106 @@
+import { profiles } from "../profiles/profiles.js";
+
+/**
+ * Join a primary label and optional detail.
+ *
+ * @param  {string}  label
+ *     Primary label.
+ * @param  {*}  detail
+ *     Optional detail value.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Combined detail text.
+ */
+export function formatLabel(label, detail, options) {
+	if (!isNonEmptyString(detail)) {
+		return label;
+	}
+
+	if (!isNonEmptyString(label)) {
+		return detail;
+	}
+
+	const separator = options.unicode === false ? " - " : " — ";
+
+	return `${label}${separator}${detail}`;
+}
+
+/**
+ * Check whether a value contains usable text.
+ *
+ * @param  {*}  value
+ *     Value to check.
+ * @returns  {boolean}
+ *     Whether the value is a non-empty string.
+ */
+export function isNonEmptyString(value) {
+	return typeof value === "string" && value !== "";
+}
+
+/**
+ * Check whether a value is a non-array object.
+ *
+ * @param  {*}  value
+ *     Value to check.
+ * @returns  {boolean}
+ *     Whether the value is a record.
+ */
+export function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Return usable text entries from an uncertain value.
+ *
+ * @param  {*}  values
+ *     Values to normalise.
+ * @returns  {string[]}
+ *     Non-empty strings.
+ */
+export function normaliseStringList(values) {
+	return Array.isArray(values) ? values.filter(isNonEmptyString) : [];
+}
+
+/**
+ * Render a titled pattern section.
+ *
+ * @param  {string}  title
+ *     Section title.
+ * @param  {string[]}  lines
+ *     Section content.
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {boolean}  listItems
+ *     Whether agent output should use bullet items.
+ * @returns  {string}
+ *     Rendered section.
+ */
+export function renderSection(title, lines, options, listItems = true) {
+	if (lines.length === 0) {
+		return "";
+	}
+
+	const heading = options.profile === profiles.AGENT
+		? `## ${title}`
+		: title;
+	const content = options.profile === profiles.AGENT && listItems
+		? lines.map((line) => `- ${line}`)
+		: lines;
+
+	return [heading, ...content].join("\n");
+}
+
+/**
+ * Render a pattern title for the active profile.
+ *
+ * @param  {string}  title
+ *     Pattern title.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered title.
+ */
+export function renderTitle(title, options) {
+	return options.profile === profiles.AGENT ? `# ${title}` : title;
+}

package/src/patterns/next-step-block.js

@@ -0,0 +1,118 @@
+import { profiles } from "../profiles/profiles.js";
+import { row } from "../primitives/row.js";
+import {
+	isNonEmptyString,
+	isRecord,
+	normaliseStringList,
+	renderSection,
+	renderTitle,
+} from "./helpers.js";
+
+// Next-step blocks use a stable title when the caller does not provide one.
+const defaultTitle = "Next step";
+
+/**
+ * Render the first concrete follow-up action and supporting context.
+ *
+ * @param  {object}  nextStep
+ *     Structured next-step block.
+ * @param  {string[]}  nextStep.alternatives
+ *     Secondary actions.
+ * @param  {string[]}  nextStep.commands
+ *     Commands needed for the action.
+ * @param  {string}  nextStep.next
+ *     Primary next action.
+ * @param  {string}  nextStep.reason
+ *     Why the action is next.
+ * @param  {string}  nextStep.title
+ *     Pattern title.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {object|string}
+ *     Structured JSON input or rendered next-step block.
+ */
+export function nextStepBlock(nextStep, options = {}) {
+	if (options.profile === profiles.JSON) {
+		return nextStep;
+	}
+
+	if (!isRecord(nextStep)) {
+		return "";
+	}
+
+	const title = isNonEmptyString(nextStep.title) ? nextStep.title : defaultTitle;
+	const next = renderNext(nextStep.next, options);
+	const reason = isNonEmptyString(nextStep.reason)
+		? renderSection("Why", [nextStep.reason], options, false)
+		: "";
+	const commands = renderCommands(nextStep.commands, options);
+	const alternatives = normaliseStringList(nextStep.alternatives)
+		.map((alternative) => `- ${alternative}`);
+	const sections = [
+		next,
+		reason,
+		commands,
+		renderSection("Alternatives", alternatives, options, false),
+	].filter((section) => section !== "");
+
+	return [renderTitle(title, options), ...sections].join("\n\n");
+}
+
+/**
+ * Render the primary next action.
+ *
+ * @param  {*}  next
+ *     Primary next action.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered next action.
+ */
+function renderNext(next, options) {
+	if (!isNonEmptyString(next)) {
+		return "";
+	}
+
+	if (options.profile === profiles.AGENT) {
+		return renderSection("Next", [next], options, false);
+	}
+
+	return row("Next", next, {
+		...options,
+		labelWidth: 4,
+	});
+}
+
+/**
+ * Render commands as shell text.
+ *
+ * @param  {*}  commands
+ *     Commands to render.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered commands.
+ */
+function renderCommands(commands, options) {
+	const validCommands = normaliseStringList(commands);
+
+	if (validCommands.length === 0) {
+		return "";
+	}
+
+	if (options.profile === profiles.AGENT) {
+		return [
+			"## Commands",
+			"```sh",
+			...validCommands,
+			"```",
+		].join("\n");
+	}
+
+	return renderSection(
+		"Commands",
+		validCommands.map((command) => `$ ${command}`),
+		options,
+		false,
+	);
+}

package/src/patterns/task-summary.js

@@ -0,0 +1,59 @@
+import { profiles } from "../profiles/profiles.js";
+import { status } from "../primitives/status.js";
+import { resultTypes } from "../theme/results.js";
+import {
+	formatLabel,
+	isNonEmptyString,
+	isRecord,
+	normaliseStringList,
+	renderSection,
+	renderTitle,
+} from "./helpers.js";
+
+// Task summaries use a stable title when the caller does not provide one.
+const defaultTitle = "Task summary";
+
+/**
+ * Render completed and remaining work for one task.
+ *
+ * @param  {object}  summary
+ *     Structured task summary.
+ * @param  {string[]}  summary.completed
+ *     Completed work.
+ * @param  {string[]}  summary.remaining
+ *     Remaining work.
+ * @param  {string}  summary.result
+ *     Semantic result state.
+ * @param  {string}  summary.summary
+ *     Short supporting summary.
+ * @param  {string}  summary.task
+ *     Task name.
+ * @param  {string}  summary.title
+ *     Pattern title.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {object|string}
+ *     Structured JSON input or rendered task summary.
+ */
+export function taskSummary(summary, options = {}) {
+	if (options.profile === profiles.JSON) {
+		return summary;
+	}
+
+	if (!isRecord(summary)) {
+		return "";
+	}
+
+	const title = isNonEmptyString(summary.title) ? summary.title : defaultTitle;
+	const task = isNonEmptyString(summary.task) ? summary.task : "";
+	const detail = formatLabel(task, summary.summary, options);
+	const completed = normaliseStringList(summary.completed).map((item) => `- ${item}`);
+	const remaining = normaliseStringList(summary.remaining).map((item) => `- ${item}`);
+	const sections = [
+		status(summary.result ?? resultTypes.UNKNOWN, detail, options),
+		renderSection("Completed", completed, options, false),
+		renderSection("Remaining", remaining, options, false),
+	].filter((section) => section !== "");
+
+	return [renderTitle(title, options), ...sections].join("\n\n");
+}

package/src/primitives/bar-chart.js

@@ -0,0 +1,131 @@
+import { foreground } from "../formatters/ansi.js";
+import { chartColours } from "../theme/colours.js";
+
+// Chart bars use the same compact default width as progress bars.
+const defaultWidth = 20;
+
+/**
+ * Render multiple labelled values against a shared scale.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {number}  options.barWidth
+ *     Number of characters used by the largest bar.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @param  {object[]}  options.rows
+ *     Labelled numeric values to render.
+ * @param  {boolean}  options.unicode
+ *     Whether Unicode bar characters should be used.
+ * @returns  {string}
+ *     Rendered bar chart.
+ */
+export function barChart(options = {}) {
+	const rows = normaliseRows(options.rows);
+
+	if (rows.length === 0) {
+		return "";
+	}
+
+	const labelWidth = Math.max(...rows.map((row) => row.label.length));
+	const maximum = Math.max(...rows.map((row) => Math.abs(row.value)), 1);
+	const width = normaliseWidth(options.barWidth);
+
+	return rows
+		.map((row) => renderRow(row, labelWidth, maximum, width, options))
+		.join("\n");
+}
+
+/**
+ * Return rows with usable labels and values.
+ *
+ * @param  {object[]}  rows
+ *     Requested chart rows.
+ * @returns  {object[]}
+ *     Valid chart rows.
+ */
+function normaliseRows(rows) {
+	if (!Array.isArray(rows)) {
+		return [];
+	}
+
+	return rows.filter((row) => (
+		row !== null
+		&& typeof row === "object"
+		&& typeof row.label === "string"
+		&& row.label !== ""
+		&& Number.isFinite(row.value)
+	));
+}
+
+/**
+ * Return a usable integer bar width.
+ *
+ * @param  {number}  width
+ *     Requested bar width.
+ * @returns  {number}
+ *     Positive integer width.
+ */
+function normaliseWidth(width) {
+	if (!Number.isFinite(width)) {
+		return defaultWidth;
+	}
+
+	return Math.max(Math.floor(width), 1);
+}
+
+/**
+ * Render one aligned chart row.
+ *
+ * @param  {object}  row
+ *     Chart row.
+ * @param  {number}  labelWidth
+ *     Shared label width.
+ * @param  {number}  maximum
+ *     Largest absolute chart value.
+ * @param  {number}  width
+ *     Maximum bar width.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Rendered chart row.
+ */
+function renderRow(row, labelWidth, maximum, width, options) {
+	const barWidth = Math.round((Math.abs(row.value) / maximum) * width);
+	const symbol = options.unicode === false ? "#" : "█";
+	const bar = symbol.repeat(barWidth).padEnd(width, " ");
+	const label = row.label.padEnd(labelWidth, " ");
+
+	if (options.colour !== true) {
+		return `${label}  ${bar} ${row.value}`;
+	}
+
+	const renderedLabel = foreground(label, chartColours.label, options);
+	const renderedBar = barWidth === 0
+		? ""
+		: foreground(bar.slice(0, barWidth), barColour(row), options);
+	const barPadding = bar.slice(barWidth);
+	const renderedValue = foreground(String(row.value), chartColours.value, options);
+
+	return `${renderedLabel}  ${renderedBar}${barPadding} ${renderedValue}`;
+}
+
+/**
+ * Return the colour for a chart row.
+ *
+ * @param  {object}  row
+ *     Chart row.
+ * @returns  {string}
+ *     Colour token or hex value.
+ */
+function barColour(row) {
+	if (row.value < 0) {
+		return chartColours.barNegative;
+	}
+
+	if (row.tone === "warning") {
+		return chartColours.barWarning;
+	}
+
+	return chartColours.barPositive;
+}

package/src/primitives/chip.js

@@ -0,0 +1,33 @@
+import { background, foreground, style } from "../formatters/ansi.js";
+import { chipColours } from "../theme/colours.js";
+
+// Chip style used when the requested tone is not configured.
+const fallbackTone = "neutral";
+
+/**
+ * Render a compact label chip.
+ *
+ * @param  {string}  label
+ *     Label text to render.
+ * @param  {string}  tone
+ *     Chip tone to use.
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @returns  {string}
+ *     Rendered chip.
+ */
+export function chip(label, tone = fallbackTone, options = {}) {
+	const token = chipColours[tone] ?? chipColours[fallbackTone];
+
+	if (options.colour !== true) {
+		return `[${label}]`;
+	}
+
+	const paddedLabel = ` ${label} `;
+	const colouredLabel = foreground(paddedLabel, token.foreground, options);
+	const boldLabel = style(colouredLabel, "bold", options);
+
+	return background(boldLabel, token.background, options);
+}

package/src/primitives/divider.js

@@ -0,0 +1,64 @@
+import { foreground } from "../formatters/ansi.js";
+
+// Dividers use enough width to read as a section break in compact output.
+const defaultWidth = 40;
+
+// Hyphen keeps the divider stable in plain and ASCII-only terminals.
+const defaultCharacter = "-";
+
+// Divider colour should expose the border token in diagnostic output.
+const defaultColour = "border";
+
+/**
+ * Render a horizontal divider.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {string}  options.character
+ *     Character to repeat.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @param  {string}  options.dividerColour
+ *     Colour token for the divider.
+ * @param  {number}  options.dividerWidth
+ *     Divider width.
+ * @param  {string}  options.label
+ *     Optional label to render before the divider line.
+ * @param  {string}  options.labelColour
+ *     Colour token for the label.
+ * @returns  {string}
+ *     Rendered divider.
+ */
+export function divider(options = {}) {
+	const character = options.character ?? defaultCharacter;
+	const label = options.label ?? "";
+	const width = options.dividerWidth ?? defaultWidth;
+	const lineWidth = Math.max(width - label.length - labelGap(label), 0);
+	const line = character.repeat(lineWidth);
+	const output = label === "" ? line : `${label} ${line}`;
+
+	if (options.colour !== true) {
+		return output;
+	}
+
+	if (label === "") {
+		return foreground(line, options.dividerColour ?? defaultColour, options);
+	}
+
+	const renderedLabel = foreground(label, options.labelColour ?? "info", options);
+	const renderedLine = foreground(line, options.dividerColour ?? defaultColour, options);
+
+	return `${renderedLabel} ${renderedLine}`;
+}
+
+/**
+ * Return the label spacing used inside the requested divider width.
+ *
+ * @param  {string}  label
+ *     Divider label.
+ * @returns  {number}
+ *     Width reserved for label gap.
+ */
+function labelGap(label) {
+	return label === "" ? 0 : 1;
+}