@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/eval/report.ts

@@ -0,0 +1,234 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
+import type { EvalRunArtifact, EvalSummary } from "./types.js";
+
+export function renderEvalReport(artifact: EvalRunArtifact, artifactPath?: string): string {
+	const lines = [
+		`eval: ${artifact.evalId}`,
+		`task file: ${artifact.taskFile}`,
+		`repeat: ${artifact.repeat}`,
+		...renderSummaryLines(artifact.summary),
+	];
+	if (artifactPath !== undefined) lines.splice(2, 0, `artifact: ${artifactPath}`);
+	lines.splice(
+		2,
+		0,
+		`clio: ${artifact.clio.version} commit=${artifact.clio.commit ?? "unknown"} entry=${artifact.clio.entry}`,
+	);
+	lines.splice(3, 0, `environment: ${artifact.environment.platform} node=${artifact.environment.node}`);
+	const evidenceIds = uniqueEvidenceIds(artifact);
+	if (evidenceIds.length > 0) {
+		const insertAt = artifactPath === undefined ? 4 : 5;
+		lines.splice(insertAt, 0, `evidence: ${evidenceIds.join(", ")}`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+export function renderSummaryLines(summary: EvalSummary): string[] {
+	return [
+		`runs: ${summary.runs}`,
+		`passed: ${summary.passed}`,
+		`failed: ${summary.failed}`,
+		`pass rate: ${formatPercent(summary.passRate)}`,
+		`tokens: ${summary.tokens}`,
+		`cost USD: ${formatCost(summary.costUsd)}`,
+		`wall time ms: ${summary.wallTimeMs}`,
+		`receipt-backed runs: ${summary.harness.receiptCount}`,
+		`tool calls: ${summary.harness.toolCalls}`,
+		`retries: ${summary.harness.retries}`,
+		`safety blocks: ${summary.harness.safetyBlocks}`,
+		`correction latency ms: ${summary.harness.correctionLatencyMs}`,
+		`validation evidence: ${summary.harness.validationEvidence}`,
+		`failure classes: ${formatFailureClasses(summary)}`,
+	];
+}
+
+function formatPercent(value: number): string {
+	return `${(value * 100).toFixed(2)}%`;
+}
+
+function formatCost(value: number): string {
+	return value.toFixed(6);
+}
+
+function formatFailureClasses(summary: EvalSummary): string {
+	if (summary.failureClasses.length === 0) return "none";
+	return summary.failureClasses.map((entry) => `${entry.failureClass}=${entry.count}`).join(", ");
+}
+
+function uniqueEvidenceIds(artifact: EvalRunArtifact): string[] {
+	return [
+		...new Set(artifact.results.flatMap((result) => (result.evidenceId === undefined ? [] : [result.evidenceId]))),
+	].sort((left, right) => left.localeCompare(right));
+}
+
+export function renderSweJsonl(artifact: EvalRunArtifact): string {
+	const lines: string[] = [];
+	for (const run of artifact.results) {
+		const entry = {
+			instance_id: run.taskId,
+			model_patch: modelPatchForRun(artifact, run), // Local eval artifacts store no patch unless a linked receipt or evidence file provides one.
+			model_name_or_path: artifact.evalId,
+			status: run.pass ? "pass" : "fail",
+			pass: run.pass,
+			tokens: run.tokens,
+			wall_time_ms: run.wallTimeMs,
+			cost_usd: run.costUsd,
+		};
+		lines.push(JSON.stringify(entry));
+	}
+	return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
+}
+
+type EvalResultLike = EvalRunArtifact["results"][number];
+
+function modelPatchForRun(artifact: EvalRunArtifact, run: EvalResultLike): string {
+	const embeddedPatch = patchFromUnknown(run);
+	if (embeddedPatch !== undefined) return embeddedPatch;
+	const linkedPatch = patchFromLinkedFiles(run, process.cwd());
+	if (linkedPatch !== undefined) return linkedPatch;
+	const receiptPatch = patchFromReceipt(run);
+	if (receiptPatch !== undefined) return receiptPatch;
+	const evidencePatch = patchFromEvidence(artifact, run);
+	return evidencePatch ?? "";
+}
+
+function patchFromReceipt(run: EvalResultLike): string | undefined {
+	if (run.receiptPath === undefined) return undefined;
+	const receipt = readJsonIfExists(run.receiptPath);
+	const direct = patchFromUnknown(receipt);
+	if (direct !== undefined) return direct;
+	const linkedPatch = patchFromLinkedFiles(receipt, dirname(run.receiptPath));
+	if (linkedPatch !== undefined) return linkedPatch;
+	const base = basename(run.receiptPath, extname(run.receiptPath));
+	for (const candidate of [`${base}.patch`, `${base}.diff`, `${run.runId}.patch`, `${run.runId}.diff`]) {
+		const text = readNonEmptyText(join(dirname(run.receiptPath), candidate));
+		if (text !== undefined) return text;
+	}
+	return undefined;
+}
+
+function patchFromEvidence(artifact: EvalRunArtifact, run: EvalResultLike): string | undefined {
+	for (const directory of evidenceDirectories(artifact, run)) {
+		for (const candidate of [
+			"model.patch",
+			"model.diff",
+			"model_patch.txt",
+			"patch.diff",
+			"patch.json",
+			"receipt.json",
+			"eval-result.json",
+		]) {
+			const path = join(directory, candidate);
+			if (candidate.endsWith(".json")) {
+				const patch = patchFromUnknown(readJsonIfExists(path));
+				if (patch !== undefined) return patch;
+				continue;
+			}
+			const text = readNonEmptyText(path);
+			if (text !== undefined) return text;
+		}
+	}
+	return undefined;
+}
+
+function evidenceDirectories(artifact: EvalRunArtifact, run: EvalResultLike): string[] {
+	const directories: string[] = [];
+	const rawRun = asRecord(run) ?? {};
+	for (const field of ["evidencePath", "evidenceDirectory", "evidence_dir"]) {
+		const value = stringField(rawRun, field);
+		if (value !== undefined) directories.push(resolve(value));
+	}
+	const evidenceId = run.evidenceId;
+	if (evidenceId !== undefined) {
+		if (isAbsolute(evidenceId)) directories.push(evidenceId);
+		if (run.receiptPath !== undefined) {
+			const stateDir = dirname(dirname(run.receiptPath));
+			directories.push(join(stateDir, "evidence", evidenceId));
+			directories.push(join(dirname(stateDir), "data", "evidence", evidenceId));
+		}
+		const artifactRecord = asRecord(artifact) ?? {};
+		for (const field of ["artifactPath", "path"]) {
+			const path = stringField(artifactRecord, field);
+			if (path !== undefined) directories.push(join(dirname(path), "..", "evidence", evidenceId));
+		}
+	}
+	return [...new Set(directories)];
+}
+
+function patchFromLinkedFiles(value: unknown, baseDir: string): string | undefined {
+	for (const patchPath of patchPathsFromUnknown(value)) {
+		const expanded = expandRedactedHomePath(patchPath);
+		const target = isAbsolute(expanded) ? expanded : resolve(baseDir, expanded);
+		const text = readNonEmptyText(target);
+		if (text !== undefined) return text;
+	}
+	return undefined;
+}
+
+function patchFromUnknown(value: unknown): string | undefined {
+	const record = asRecord(value);
+	if (record === undefined) return undefined;
+	for (const field of ["model_patch", "modelPatch", "patch", "diff", "gitDiff"]) {
+		const patch = stringField(record, field);
+		if (patch !== undefined && patch.trim().length > 0) return patch;
+	}
+	for (const field of ["evidence", "artifact", "result"]) {
+		const patch = patchFromUnknown(record[field]);
+		if (patch !== undefined) return patch;
+	}
+	return undefined;
+}
+
+function patchPathsFromUnknown(value: unknown): string[] {
+	const record = asRecord(value);
+	if (record === undefined) return [];
+	const paths: string[] = [];
+	for (const field of ["modelPatchPath", "model_patch_path", "patchPath", "patch_path", "diffPath", "diff_path"]) {
+		const path = stringField(record, field);
+		if (path !== undefined && path.trim().length > 0) paths.push(path);
+	}
+	for (const field of ["evidence", "artifact", "result"]) {
+		paths.push(...patchPathsFromUnknown(record[field]));
+	}
+	return paths;
+}
+
+function readJsonIfExists(path: string): unknown {
+	const text = readNonEmptyText(expandRedactedHomePath(path));
+	if (text === undefined) return undefined;
+	try {
+		return JSON.parse(text) as unknown;
+	} catch {
+		return undefined;
+	}
+}
+
+function readNonEmptyText(path: string): string | undefined {
+	try {
+		const expanded = expandRedactedHomePath(path);
+		if (!existsSync(expanded)) return undefined;
+		const text = readFileSync(expanded, "utf8");
+		return text.trim().length > 0 ? text : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: undefined;
+}
+
+function stringField(record: Record<string, unknown>, field: string): string | undefined {
+	const value = record[field];
+	return typeof value === "string" ? value : undefined;
+}
+
+function expandRedactedHomePath(path: string): string {
+	if (path === "$HOME") return homedir();
+	if (path.startsWith("$HOME/")) return join(homedir(), path.slice("$HOME/".length));
+	return path;
+}

package/src/domains/eval/reports/json.ts

@@ -0,0 +1,5 @@
+import type { EvalArtifactV4 } from "../schema/artifact.js";
+
+export function renderEvalJsonReportV4(artifact: EvalArtifactV4): string {
+	return `${JSON.stringify(artifact, null, 2)}\n`;
+}

package/src/domains/eval/reports/junit.ts

@@ -0,0 +1,23 @@
+import type { EvalArtifactV4 } from "../schema/artifact.js";
+
+export function renderEvalJunitReportV4(artifact: EvalArtifactV4): string {
+	const cases = artifact.results
+		.map((result) => {
+			const name = escapeXml(
+				`${result.taskId}[${result.target.id}:${result.target.model ?? "default"}:${result.repeatIndex}]`,
+			);
+			if (result.pass) return `  <testcase name="${name}" />`;
+			return `  <testcase name="${name}"><failure message="${escapeXml(result.failureClass ?? "failed")}" /></testcase>`;
+		})
+		.join("\n");
+	return [
+		`<testsuite name="${escapeXml(artifact.suite.id)}" tests="${artifact.summary.runs}" failures="${artifact.summary.failed}">`,
+		cases,
+		"</testsuite>",
+		"",
+	].join("\n");
+}
+
+function escapeXml(value: string): string {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+}

package/src/domains/eval/reports/markdown.ts

@@ -0,0 +1,20 @@
+import type { EvalArtifactV4 } from "../schema/artifact.js";
+
+export function renderEvalMarkdownReportV4(artifact: EvalArtifactV4): string {
+	const lines = [
+		`# Eval ${artifact.evalId}`,
+		"",
+		`Suite: ${artifact.suite.id}`,
+		`Target: ${artifact.matrix.target}`,
+		`Pass rate: ${(artifact.summary.passRate * 100).toFixed(2)}%`,
+		"",
+		"| Task | Target | Model | Repeat | Pass | Failure |",
+		"|---|---|---|---:|---|---|",
+		...artifact.results.map(
+			(result) =>
+				`| ${result.taskId} | ${result.target.id} | ${result.target.model ?? ""} | ${result.repeatIndex} | ${result.pass ? "pass" : "fail"} | ${result.failureClass ?? ""} |`,
+		),
+		"",
+	];
+	return `${lines.join("\n")}`;
+}

package/src/domains/eval/reports/swe-jsonl.ts

@@ -0,0 +1,16 @@
+import type { EvalArtifactV4 } from "../schema/artifact.js";
+
+export function renderEvalSweJsonlReportV4(artifact: EvalArtifactV4): string {
+	return artifact.results
+		.map((result) =>
+			JSON.stringify({
+				instance_id: result.taskId,
+				model_name_or_path: artifact.matrix.model ?? artifact.matrix.target,
+				model_patch: typeof result.artifacts.patch === "string" ? result.artifacts.patch : "",
+				status: result.pass ? "pass" : "fail",
+				pass: result.pass,
+			}),
+		)
+		.join("\n")
+		.concat(artifact.results.length === 0 ? "" : "\n");
+}

package/src/domains/eval/reports/text.ts

@@ -0,0 +1,25 @@
+import type { EvalArtifactV4 } from "../schema/artifact.js";
+
+export function renderEvalTextReportV4(artifact: EvalArtifactV4): string {
+	const tokens = artifact.summary.tokens;
+	return [
+		`eval: ${artifact.evalId}`,
+		`suite: ${artifact.suite.id}`,
+		`target: ${artifact.matrix.target}`,
+		`model: ${artifact.matrix.model ?? "none"}`,
+		`runs: ${artifact.summary.runs}`,
+		`passed: ${artifact.summary.passed}`,
+		`failed: ${artifact.summary.failed}`,
+		`pass rate: ${(artifact.summary.passRate * 100).toFixed(2)}%`,
+		// A run whose child Clio work is out of the harness's sight has no token
+		// count. Saying "0" would claim it cost nothing, so the count is
+		// reported next to how many runs it actually covers.
+		!tokens.measured
+			? `tokens total: unmeasured (0 of ${tokens.runs} runs reported usage)`
+			: tokens.measuredRuns === tokens.runs
+				? `tokens total: ${tokens.total}`
+				: `tokens total: ${tokens.total} (measured in ${tokens.measuredRuns} of ${tokens.runs} runs)`,
+		`wall time ms: ${artifact.summary.wallTimeMs}`,
+		"",
+	].join("\n");
+}

package/src/domains/eval/run-compare.ts

@@ -0,0 +1,274 @@
+import { subtractEvalHarnessMetrics } from "./harness-metrics.js";
+import type { EvalFailureClass, EvalHarnessMetrics, EvalRunArtifact, EvalRunRecord, EvalSummary } from "./types.js";
+
+export const EVAL_COMPARE_MATCHING_RULE = "taskId+repeatIndex";
+
+export interface EvalCompareTotals {
+	passed: number;
+	failed: number;
+	passRate: number;
+	tokens: number;
+	costUsd: number;
+	wallTimeMs: number;
+	harness: EvalHarnessMetrics;
+}
+
+export interface EvalCompareDeltas {
+	passRate: number;
+	tokens: number;
+	costUsd: number;
+	wallTimeMs: number;
+	harness: EvalHarnessMetrics;
+}
+
+export interface EvalCompareResultRef {
+	taskId: string;
+	repeatIndex: number;
+	runId: string;
+	pass: boolean;
+	failureClass: EvalFailureClass | null;
+}
+
+export interface EvalCompareMatchedChange {
+	taskId: string;
+	repeatIndex: number;
+	baselineRunId: string;
+	candidateRunId: string;
+	baselineFailureClass: EvalFailureClass | null;
+	candidateFailureClass: EvalFailureClass | null;
+}
+
+export interface EvalComparisonSummary {
+	version: 1;
+	baselineEvalId: string;
+	candidateEvalId: string;
+	matchingRule: typeof EVAL_COMPARE_MATCHING_RULE;
+	matchedCount: number;
+	addedCount: number;
+	missingCount: number;
+	baseline: EvalCompareTotals;
+	candidate: EvalCompareTotals;
+	deltas: EvalCompareDeltas;
+	regressions: EvalCompareMatchedChange[];
+	improvements: EvalCompareMatchedChange[];
+	unchangedPassCount: number;
+	unchangedFailCount: number;
+	failureClassChanges: EvalCompareMatchedChange[];
+	added: EvalCompareResultRef[];
+	missing: EvalCompareResultRef[];
+}
+
+export function compareEvalArtifacts(baseline: EvalRunArtifact, candidate: EvalRunArtifact): EvalComparisonSummary {
+	const baselineIndex = indexRecords(baseline.results, "baseline", baseline.evalId);
+	const candidateIndex = indexRecords(candidate.results, "candidate", candidate.evalId);
+	const regressions: EvalCompareMatchedChange[] = [];
+	const improvements: EvalCompareMatchedChange[] = [];
+	const failureClassChanges: EvalCompareMatchedChange[] = [];
+	const missing: EvalCompareResultRef[] = [];
+	let matchedCount = 0;
+	let unchangedPassCount = 0;
+	let unchangedFailCount = 0;
+
+	for (const baselineRecord of sortedRecords(baselineIndex)) {
+		const candidateRecord = candidateIndex.get(resultKey(baselineRecord));
+		if (candidateRecord === undefined) {
+			missing.push(resultRef(baselineRecord));
+			continue;
+		}
+		matchedCount += 1;
+		const change = matchedChange(baselineRecord, candidateRecord);
+		if (baselineRecord.pass && !candidateRecord.pass) {
+			regressions.push(change);
+			continue;
+		}
+		if (!baselineRecord.pass && candidateRecord.pass) {
+			improvements.push(change);
+			continue;
+		}
+		if (baselineRecord.pass && candidateRecord.pass) {
+			unchangedPassCount += 1;
+			continue;
+		}
+		unchangedFailCount += 1;
+		if ((baselineRecord.failureClass ?? null) !== (candidateRecord.failureClass ?? null)) {
+			failureClassChanges.push(change);
+		}
+	}
+
+	const added = sortedRecords(candidateIndex)
+		.filter((candidateRecord) => !baselineIndex.has(resultKey(candidateRecord)))
+		.map(resultRef);
+	const baselineTotals = summaryTotals(baseline.summary);
+	const candidateTotals = summaryTotals(candidate.summary);
+
+	return {
+		version: 1,
+		baselineEvalId: baseline.evalId,
+		candidateEvalId: candidate.evalId,
+		matchingRule: EVAL_COMPARE_MATCHING_RULE,
+		matchedCount,
+		addedCount: added.length,
+		missingCount: missing.length,
+		baseline: baselineTotals,
+		candidate: candidateTotals,
+		deltas: {
+			passRate: candidateTotals.passRate - baselineTotals.passRate,
+			tokens: candidateTotals.tokens - baselineTotals.tokens,
+			costUsd: candidateTotals.costUsd - baselineTotals.costUsd,
+			wallTimeMs: candidateTotals.wallTimeMs - baselineTotals.wallTimeMs,
+			harness: subtractEvalHarnessMetrics(candidateTotals.harness, baselineTotals.harness),
+		},
+		regressions,
+		improvements,
+		unchangedPassCount,
+		unchangedFailCount,
+		failureClassChanges,
+		added,
+		missing,
+	};
+}
+
+export function renderEvalComparison(summary: EvalComparisonSummary): string {
+	const lines = [
+		`baseline eval: ${summary.baselineEvalId}`,
+		`candidate eval: ${summary.candidateEvalId}`,
+		`matching: ${summary.matchingRule}`,
+		`matched: ${summary.matchedCount}`,
+		`added: ${summary.addedCount}`,
+		`missing: ${summary.missingCount}`,
+		`baseline passed: ${summary.baseline.passed}`,
+		`baseline failed: ${summary.baseline.failed}`,
+		`candidate passed: ${summary.candidate.passed}`,
+		`candidate failed: ${summary.candidate.failed}`,
+		`pass-rate delta: ${formatSignedPercent(summary.deltas.passRate)}`,
+		`token delta: ${formatSignedInteger(summary.deltas.tokens)}`,
+		`cost delta USD: ${formatSignedCost(summary.deltas.costUsd)}`,
+		`wall-time delta ms: ${formatSignedInteger(summary.deltas.wallTimeMs)}`,
+		`tool-call delta: ${formatSignedInteger(summary.deltas.harness.toolCalls)}`,
+		`retry delta: ${formatSignedInteger(summary.deltas.harness.retries)}`,
+		`safety-block delta: ${formatSignedInteger(summary.deltas.harness.safetyBlocks)}`,
+		`correction-latency delta ms: ${formatSignedInteger(summary.deltas.harness.correctionLatencyMs)}`,
+		`validation-evidence delta: ${formatSignedInteger(summary.deltas.harness.validationEvidence)}`,
+		`regressions: ${summary.regressions.length}`,
+		...formatMatchedChanges(summary.regressions),
+		`fixes/improvements: ${summary.improvements.length}`,
+		...formatMatchedChanges(summary.improvements),
+		`unchanged pass: ${summary.unchangedPassCount}`,
+		`unchanged fail: ${summary.unchangedFailCount}`,
+		`failure class changes: ${summary.failureClassChanges.length}`,
+		...formatMatchedChanges(summary.failureClassChanges),
+		`added results: ${summary.added.length}`,
+		...formatResultRefs(summary.added),
+		`missing results: ${summary.missing.length}`,
+		...formatResultRefs(summary.missing),
+	];
+	return `${lines.join("\n")}\n`;
+}
+
+function summaryTotals(summary: EvalSummary): EvalCompareTotals {
+	return {
+		passed: summary.passed,
+		failed: summary.failed,
+		passRate: summary.passRate,
+		tokens: summary.tokens,
+		costUsd: summary.costUsd,
+		wallTimeMs: summary.wallTimeMs,
+		harness: summary.harness,
+	};
+}
+
+function indexRecords(
+	records: ReadonlyArray<EvalRunRecord>,
+	label: "baseline" | "candidate",
+	evalId: string,
+): Map<string, EvalRunRecord> {
+	const index = new Map<string, EvalRunRecord>();
+	for (const record of records) {
+		const key = resultKey(record);
+		if (index.has(key)) {
+			throw new Error(
+				`${label} eval ${evalId} has duplicate result identity: ${formatIdentity(record.taskId, record.repeatIndex)}`,
+			);
+		}
+		index.set(key, record);
+	}
+	return index;
+}
+
+function sortedRecords(index: ReadonlyMap<string, EvalRunRecord>): EvalRunRecord[] {
+	return [...index.values()].sort(compareRecords);
+}
+
+function compareRecords(a: EvalRunRecord, b: EvalRunRecord): number {
+	const byTask = a.taskId.localeCompare(b.taskId);
+	if (byTask !== 0) return byTask;
+	return a.repeatIndex - b.repeatIndex;
+}
+
+function matchedChange(baselineRecord: EvalRunRecord, candidateRecord: EvalRunRecord): EvalCompareMatchedChange {
+	return {
+		taskId: baselineRecord.taskId,
+		repeatIndex: baselineRecord.repeatIndex,
+		baselineRunId: baselineRecord.runId,
+		candidateRunId: candidateRecord.runId,
+		baselineFailureClass: baselineRecord.failureClass ?? null,
+		candidateFailureClass: candidateRecord.failureClass ?? null,
+	};
+}
+
+function resultRef(record: EvalRunRecord): EvalCompareResultRef {
+	return {
+		taskId: record.taskId,
+		repeatIndex: record.repeatIndex,
+		runId: record.runId,
+		pass: record.pass,
+		failureClass: record.failureClass ?? null,
+	};
+}
+
+function resultKey(record: EvalRunRecord): string {
+	return `${record.taskId}\u0000${record.repeatIndex}`;
+}
+
+function formatMatchedChanges(changes: ReadonlyArray<EvalCompareMatchedChange>): string[] {
+	return changes.map(
+		(change) =>
+			`  ${formatIdentity(change.taskId, change.repeatIndex)} baseline=${change.baselineRunId} candidate=${change.candidateRunId} failure=${formatFailureChange(change)}`,
+	);
+}
+
+function formatResultRefs(results: ReadonlyArray<EvalCompareResultRef>): string[] {
+	return results.map(
+		(result) =>
+			`  ${formatIdentity(result.taskId, result.repeatIndex)} run=${result.runId} pass=${String(result.pass)} failure=${formatFailureClass(result.failureClass)}`,
+	);
+}
+
+function formatIdentity(taskId: string, repeatIndex: number): string {
+	return `task=${taskId} repeat=${repeatIndex}`;
+}
+
+function formatFailureChange(change: EvalCompareMatchedChange): string {
+	return `${formatFailureClass(change.baselineFailureClass)}->${formatFailureClass(change.candidateFailureClass)}`;
+}
+
+function formatFailureClass(failureClass: EvalFailureClass | null): string {
+	return failureClass ?? "none";
+}
+
+function formatSignedPercent(value: number): string {
+	return `${formatSignedNumber(value * 100, 2)}pp`;
+}
+
+function formatSignedCost(value: number): string {
+	return formatSignedNumber(value, 6);
+}
+
+function formatSignedInteger(value: number): string {
+	return value > 0 ? `+${value}` : String(value);
+}
+
+function formatSignedNumber(value: number, digits: number): string {
+	const formatted = value.toFixed(digits);
+	return value > 0 ? `+${formatted}` : formatted;
+}