@pi-archimedes/diff 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/diff",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "keywords": [
     "pi-package"

package/src/ansi/codes.ts

@@ -0,0 +1,157 @@
+/** ANSI escape codes, constants, and interfaces. */
+
+import { deriveBgFromTheme } from "./colors.js";
+
+// ---------------------------------------------------------------------------
+// ANSI escape codes
+// ---------------------------------------------------------------------------
+
+export const RST = "\x1b[0m";
+export const BOLD = "\x1b[1m";
+export const DIM = "\x1b[2m";
+
+// Diff foregrounds — hardcoded fallbacks
+export const FG_ADD = "\x1b[38;2;100;180;120m"; // desaturated green
+export const FG_DEL = "\x1b[38;2;200;100;100m"; // desaturated red
+export const FG_DIM = "\x1b[38;2;80;80;80m";
+export const FG_LNUM = "\x1b[38;2;100;100;100m";
+export const FG_RULE = "\x1b[38;2;50;50;50m";
+export const FG_SAFE_MUTED = "\x1b[38;2;139;148;158m";
+export const FG_STRIPE = "\x1b[38;2;40;40;40m"; // gray diagonal stripes
+
+export const BORDER_BAR = "▌";
+const BG_DEFAULT = "\x1b[49m"; // reset to terminal default background
+
+// ---------------------------------------------------------------------------
+// DiffBg — instance-scoped background colors derived from a theme
+// ---------------------------------------------------------------------------
+
+/** All background colors needed for diff rendering, derived from a theme. */
+export interface DiffBg {
+	bgAdd: string;
+	bgDel: string;
+	bgAddW: string; // word-level emphasis
+	bgDelW: string;
+	bgGutterAdd: string;
+	bgGutterDel: string;
+	bgEmpty: string;
+	bgBase: string; // tool box base bg
+	rst: string; // reset + base bg
+	divider: string;
+}
+
+/** Hardcoded fallback backgrounds. */
+export const DEFAULT_DIFF_BG: DiffBg = {
+	bgAdd: "\x1b[48;2;22;38;32m",
+	bgDel: "\x1b[48;2;45;25;25m",
+	bgAddW: "\x1b[48;2;35;75;50m",
+	bgDelW: "\x1b[48;2;80;35;35m",
+	bgGutterAdd: "\x1b[48;2;18;32;26m",
+	bgGutterDel: "\x1b[48;2;38;22;22m",
+	bgEmpty: "\x1b[48;2;18;18;18m",
+	bgBase: BG_DEFAULT,
+	rst: "\x1b[0m",
+	divider: `${FG_RULE}│\x1b[0m`,
+};
+
+// Legacy aliases — used by word-diff.ts during transition. Will be removed.
+// These MUST be mutable and live in the same module as the functions that mutate them.
+export let BG_ADD = DEFAULT_DIFF_BG.bgAdd;
+export let BG_DEL = DEFAULT_DIFF_BG.bgDel;
+export let BG_ADD_W = DEFAULT_DIFF_BG.bgAddW;
+export let BG_DEL_W = DEFAULT_DIFF_BG.bgDelW;
+export let BG_GUTTER_ADD = DEFAULT_DIFF_BG.bgGutterAdd;
+export let BG_GUTTER_DEL = DEFAULT_DIFF_BG.bgGutterDel;
+export let BG_EMPTY = DEFAULT_DIFF_BG.bgEmpty;
+export let BG_BASE = DEFAULT_DIFF_BG.bgBase;
+export let DIVIDER = DEFAULT_DIFF_BG.divider;
+
+// Theme cache key state — lives here since it's used by resolveDiffColors.
+let _lastThemeKey: string | undefined;
+
+// ---------------------------------------------------------------------------
+// Regex patterns
+// ---------------------------------------------------------------------------
+
+const ESC_RE = "\u001b";
+export const ANSI_RE = new RegExp(`${ESC_RE}\\[[0-9;]*m`, "g");
+export const ANSI_CAPTURE_RE = new RegExp(`${ESC_RE}\\[([^m]*)m`, "g");
+export const ANSI_PARAM_CAPTURE_RE = new RegExp(`${ESC_RE}\\[([0-9;]*)m`, "g");
+
+// ---------------------------------------------------------------------------
+// DiffColors — foreground colors for diff signs
+// ---------------------------------------------------------------------------
+
+export interface DiffColors {
+	fgAdd: string;
+	fgDel: string;
+	fgCtx: string;
+}
+
+export const DEFAULT_DIFF_COLORS: DiffColors = { fgAdd: FG_ADD, fgDel: FG_DEL, fgCtx: FG_DIM };
+
+// ---------------------------------------------------------------------------
+// Theme-aware color resolution (mutates legacy aliases)
+// ---------------------------------------------------------------------------
+
+/** Reset auto-derived colors — call when theme changes. */
+export function resetDiffColors(): void {
+	_lastThemeKey = undefined;
+	BG_ADD = DEFAULT_DIFF_BG.bgAdd;
+	BG_DEL = DEFAULT_DIFF_BG.bgDel;
+	BG_ADD_W = DEFAULT_DIFF_BG.bgAddW;
+	BG_DEL_W = DEFAULT_DIFF_BG.bgDelW;
+	BG_GUTTER_ADD = DEFAULT_DIFF_BG.bgGutterAdd;
+	BG_GUTTER_DEL = DEFAULT_DIFF_BG.bgGutterDel;
+	BG_EMPTY = DEFAULT_DIFF_BG.bgEmpty;
+	BG_BASE = DEFAULT_DIFF_BG.bgBase;
+	DIVIDER = DEFAULT_DIFF_BG.divider;
+}
+
+export function themeCacheKey(theme?: any): string {
+	if (!theme?.fg) return "no-theme";
+	const fgKeys = [
+		"toolTitle", "accent", "muted", "success", "error",
+		"toolDiffAdded", "toolDiffRemoved", "toolDiffContext",
+	];
+	const bgKeys = ["toolSuccessBg", "toolErrorBg"];
+	const parts: string[] = [];
+	for (const key of fgKeys) {
+		try { parts.push(theme.fg(key, key)); } catch { parts.push(key); }
+	}
+	for (const key of bgKeys) {
+		try { parts.push(theme.bg ? theme.bg(key, key) : key); } catch { parts.push(key); }
+	}
+	return parts.join("|");
+}
+
+export { deriveBgFromTheme };
+
+export function resolveDiffColors(theme?: any): DiffColors {
+	const themeKey = themeCacheKey(theme);
+
+	// Re-derive when theme changes (different key) or first call
+	if (themeKey !== _lastThemeKey && theme?.getFgAnsi) {
+		const dbg = deriveBgFromTheme(theme);
+		BG_ADD = dbg.bgAdd;
+		BG_DEL = dbg.bgDel;
+		BG_ADD_W = dbg.bgAddW;
+		BG_DEL_W = dbg.bgDelW;
+		BG_GUTTER_ADD = dbg.bgGutterAdd;
+		BG_GUTTER_DEL = dbg.bgGutterDel;
+		BG_EMPTY = dbg.bgEmpty;
+		BG_BASE = dbg.bgBase;
+		DIVIDER = dbg.divider;
+		_lastThemeKey = themeKey;
+	}
+	if (!theme?.getFgAnsi) return DEFAULT_DIFF_COLORS;
+	try {
+		return {
+			fgAdd: theme.getFgAnsi("toolDiffAdded") || FG_ADD,
+			fgDel: theme.getFgAnsi("toolDiffRemoved") || FG_DEL,
+			fgCtx: theme.getFgAnsi("toolDiffContext") || FG_DIM,
+		};
+	} catch {
+		return DEFAULT_DIFF_COLORS;
+	}
+}

package/src/ansi/colors.ts

@@ -0,0 +1,80 @@
+/** Diff background color derivation from theme. */
+
+import type { DiffBg } from "./codes.js";
+import { DEFAULT_DIFF_BG, FG_RULE } from "./codes.js";
+
+// ---------------------------------------------------------------------------
+// Color helpers
+// ---------------------------------------------------------------------------
+
+/** Parse 24-bit ANSI color code → RGB. Works for both fg and bg escapes. */
+function parseAnsiRgb(ansi: string): { r: number; g: number; b: number } | null {
+	const esc = "\x1b";
+	const m = ansi.match(new RegExp(`${esc}\\[(?:38|48);2;(\\d+);(\\d+);(\\d+)m`));
+	return m ? { r: +m[1]!, g: +m[2]!, b: +m[3]! } : null;
+}
+
+/** Mix an accent color into a base color at the given intensity (0.0–1.0). */
+function mixBg(
+	base: { r: number; g: number; b: number },
+	accent: { r: number; g: number; b: number },
+	intensity: number,
+): string {
+	const r = Math.round(base.r + (accent.r - base.r) * intensity);
+	const g = Math.round(base.g + (accent.g - base.g) * intensity);
+	const b = Math.round(base.b + (accent.b - base.b) * intensity);
+	return `\x1b[48;2;${r};${g};${b}m`;
+}
+
+// ---------------------------------------------------------------------------
+// Theme-aware diff colors
+// ---------------------------------------------------------------------------
+
+/** Auto-derive diff background colors from the pi theme's fg diff colors. */
+export function deriveBgFromTheme(theme: any): DiffBg {
+	if (!theme?.getFgAnsi) return { ...DEFAULT_DIFF_BG };
+	try {
+		const fgAdd = theme.getFgAnsi("toolDiffAdded");
+		const fgDel = theme.getFgAnsi("toolDiffRemoved");
+		const addRgb = parseAnsiRgb(fgAdd);
+		const delRgb = parseAnsiRgb(fgDel);
+		if (!addRgb || !delRgb) return { ...DEFAULT_DIFF_BG };
+
+		let addBase = { r: 0, g: 0, b: 0 };
+		let delBase = addBase;
+		let bgBase = "\x1b[49m"; // BG_DEFAULT
+
+		if (theme.getBgAnsi) {
+			try {
+				const successBgAnsi = theme.getBgAnsi("toolSuccessBg");
+				const successParsed = parseAnsiRgb(successBgAnsi);
+				if (successParsed) {
+					addBase = successParsed;
+					delBase = successParsed;
+					bgBase = successBgAnsi;
+				}
+			} catch { /* no toolSuccessBg */ }
+
+			try {
+				const errorParsed = parseAnsiRgb(theme.getBgAnsi("toolErrorBg"));
+				if (errorParsed) delBase = errorParsed;
+			} catch { /* no toolErrorBg */ }
+		}
+
+		const rst = bgBase === "\x1b[49m" ? "\x1b[0m" : `\x1b[0m${bgBase}`;
+		return {
+			bgAdd: mixBg(addBase, addRgb, 0.08),
+			bgDel: mixBg(delBase, delRgb, 0.1),
+			bgAddW: mixBg(addBase, addRgb, 0.2),
+			bgDelW: mixBg(delBase, delRgb, 0.22),
+			bgGutterAdd: mixBg(addBase, addRgb, 0.05),
+			bgGutterDel: mixBg(delBase, delRgb, 0.06),
+			bgEmpty: bgBase,
+			bgBase,
+			rst,
+			divider: `${FG_RULE}│${rst}`,
+		};
+	} catch {
+		return { ...DEFAULT_DIFF_BG };
+	}
+}

package/src/ansi/index.ts

@@ -0,0 +1,21 @@
+/** ANSI utilities — barrel re-export. */
+
+export {
+	RST, BOLD, DIM,
+	FG_ADD, FG_DEL, FG_DIM, FG_LNUM, FG_RULE, FG_SAFE_MUTED, FG_STRIPE,
+	BORDER_BAR,
+	DEFAULT_DIFF_BG,
+	BG_ADD, BG_DEL, BG_ADD_W, BG_DEL_W, BG_GUTTER_ADD, BG_GUTTER_DEL, BG_EMPTY, BG_BASE, DIVIDER,
+	ANSI_RE, ANSI_CAPTURE_RE, ANSI_PARAM_CAPTURE_RE,
+	DEFAULT_DIFF_COLORS,
+	resetDiffColors, themeCacheKey, resolveDiffColors,
+	deriveBgFromTheme,
+	type DiffBg,
+	type DiffColors,
+} from "./codes.js";
+
+export {
+	strip, tabs, fit, ansiState,
+	isLowContrastShikiFg, normalizeShikiContrast,
+	stripes, lnum, rule, shortPath, summarize,
+} from "./manip.js";

package/src/ansi/manip.ts

@@ -0,0 +1,113 @@
+/** ANSI string manipulation utilities. */
+
+import { relative } from "node:path";
+import * as C from "./codes.js";
+
+// ---------------------------------------------------------------------------
+// ANSI manipulation
+// ---------------------------------------------------------------------------
+
+const stripSgr = (s: string) => s.replace(/\x1b\[[0-9;]*m/g, "");
+
+/** Strip all ANSI escape codes from a string. */
+export const strip = stripSgr;
+
+/** Replace tabs with 2 spaces. */
+export function tabs(s: string): string {
+	return s.replace(/\t/g, "  ");
+}
+
+/** Pad/truncate `s` to exactly `w` visible chars. ANSI-aware. */
+export function fit(s: string, w: number): string {
+	if (w <= 0) return "";
+	const plain = strip(s);
+	if (plain.length <= w) return s + " ".repeat(w - plain.length);
+	const showW = w > 2 ? w - 1 : w;
+	let vis = 0,
+		i = 0;
+	while (i < s.length && vis < showW) {
+		if (s[i] === "\x1b") {
+			const e = s.indexOf("m", i);
+			if (e !== -1) {
+				i = e + 1;
+				continue;
+			}
+		}
+		vis++;
+		i++;
+	}
+	return w > 2 ? `${s.slice(0, i)}${C.RST}${C.FG_DIM}›${C.RST}` : `${s.slice(0, i)}${C.RST}`;
+}
+
+/** Extract last active fg + bg ANSI codes from a string. Used for wrapping continuations. */
+export function ansiState(s: string): string {
+	let fg = "",
+		bg = "";
+	for (const match of s.matchAll(C.ANSI_CAPTURE_RE)) {
+		const p = match[1] ?? "";
+		const seq = match[0] ?? "";
+		if (p === "0") {
+			fg = "";
+			bg = "";
+		} else if (p === "39") {
+			fg = "";
+		} else if (p.startsWith("38;")) {
+			fg = seq;
+		} else if (p.startsWith("48;")) {
+			bg = seq;
+		}
+	}
+	return bg + fg;
+}
+
+/** Check if a Shiki fg code is too dark to read. */
+export function isLowContrastShikiFg(params: string): boolean {
+	if (params === "30" || params === "90") return true;
+	if (params === "38;5;0" || params === "38;5;8") return true;
+	if (!params.startsWith("38;2;")) return false;
+	const parts = params.split(";").map(Number);
+	if (parts.length !== 5 || parts.some((n) => !Number.isFinite(n))) return false;
+	const [, , r, g, b] = parts as [number, number, number, number, number];
+	const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+	return luminance < 72;
+}
+
+/** Normalize Shiki ANSI output to boost low-contrast fg codes. */
+export function normalizeShikiContrast(ansi: string): string {
+	return ansi.replace(C.ANSI_PARAM_CAPTURE_RE, (seq, params: string) =>
+		isLowContrastShikiFg(params) ? C.FG_SAFE_MUTED : seq,
+	);
+}
+
+/** Generate a dense diagonal stripe fill for empty filler cells. */
+export function stripes(dbg: C.DiffBg, w: number, _rowOffset: number): string {
+	return dbg.bgBase + C.FG_STRIPE + "╱".repeat(w) + dbg.rst;
+}
+
+/** Format a line number, right-padded to width `w`. */
+export function lnum(n: number | null, w: number, fg = C.FG_LNUM): string {
+	if (n === null) return " ".repeat(w);
+	const v = String(n);
+	return `${fg}${" ".repeat(Math.max(0, w - v.length))}${v}${C.RST}`;
+}
+
+/** Horizontal rule line. */
+export function rule(dbg: C.DiffBg, w: number): string {
+	return `${dbg.bgBase}${C.FG_RULE}${"─".repeat(w)}${dbg.rst}`;
+}
+
+/** Shorten a file path relative to cwd or home. */
+export function shortPath(cwd: string, home: string, p: string): string {
+	if (!p) return "";
+	const r = relative(cwd, p);
+	if (!r.startsWith("..") && !r.startsWith("/")) return r;
+	return p.replace(home, "~");
+}
+
+/** Summarize added/removed counts as colored `+N -M` string. */
+export function summarize(a: number, d: number): string {
+	const p: string[] = [];
+	if (a > 0) p.push(`${C.FG_ADD}+${a}${C.RST}`);
+	if (d > 0) p.push(`${C.FG_DEL}-${d}${C.RST}`);
+	return p.length ? p.join(" ") : `${C.FG_DIM}no changes${C.RST}`;
+}

package/src/diff-component.ts

@@ -0,0 +1,139 @@
+/** DiffComponent — proper pi-tui Component for diff rendering. */
+
+import type { BundledLanguage } from "shiki";
+import { Box, type Component } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import * as Ansi from "./ansi/index.js";
+import type { DiffBg, DiffColors } from "./ansi/index.js";
+import { DEFAULT_DIFF_COLORS, DEFAULT_DIFF_BG, deriveBgFromTheme } from "./ansi/index.js";
+import { renderSplitLines, MAX_RENDER_LINES } from "./render/index.js";
+import type { ParsedDiff } from "./core/diff.js";
+
+// ---------------------------------------------------------------------------
+// DiffComponent
+// ---------------------------------------------------------------------------
+
+/**
+ * A pi-tui Component that renders a diff with Shiki syntax highlighting.
+ *
+ * Rendering is lazy: `render(width)` returns an array of lines computed from
+ * the diff data. Shiki highlighting is cached (LRU), so repeated renders at
+ * different widths are cheap after the first call.
+ *
+ * The component wraps its output in a `Box` with the theme-derived base
+ * background, so it is visually self-contained regardless of the tool shell.
+ *
+ * The first render may show a placeholder if Shiki hasn't warmed up yet.
+ * Subsequent renders (triggered by `invalidate()` + TUI re-render cycle)
+ * show the full diff.
+ *
+ * Usage in a tool renderResult:
+ *
+ * ```ts
+ * renderResult(result, options, theme, context) {
+ *   const d = result.details;
+ *   if (d?._type === "diff") {
+ *     const comp = context.lastComponent ?? new DiffComponent(d.diff, d.language, theme);
+ *     return comp;
+ *   }
+ * }
+ * ```
+ */
+export class DiffComponent implements Component {
+	private diff: ParsedDiff;
+	private language: BundledLanguage | undefined;
+	private dc: DiffColors;
+	private dbg: DiffBg;
+	private maxLines: number;
+
+	/** Box wrapper with base background — makes the diff self-contained. */
+	private shell: Box;
+
+	/** Pending render promise — reused across width changes. */
+	private _renderPromise: Promise<string[]> | null = null;
+	/** Resolved raw diff lines (without box wrapping). */
+	private _rawLines: string[] | null = null;
+	/** Width at which output was last computed. */
+	private _cachedWidth: number | undefined;
+	/** Final cached output (box-wrapped). */
+	private _cachedLines: string[] | undefined;
+
+	constructor(
+		diff: ParsedDiff,
+		language: BundledLanguage | undefined,
+		theme: Theme,
+		maxLines: number = MAX_RENDER_LINES,
+	) {
+		this.diff = diff;
+		this.language = language;
+		this.dc = Ansi.resolveDiffColors(theme);
+		this.dbg = deriveBgFromTheme(theme);
+		this.maxLines = maxLines;
+
+		// Box provides base background so the diff is self-contained.
+		this.shell = new Box(0, 0, (s: string) => this.dbg.bgBase + s + this.dbg.rst);
+	}
+
+	render(width: number): string[] {
+		// Use cached output if width unchanged
+		if (this._cachedLines && this._cachedWidth === width) {
+			return this._cachedLines;
+		}
+
+		// If we have resolved raw lines, wrap them in the box
+		if (this._rawLines) {
+			this._updateShell(this._rawLines);
+			const lines = this.shell.render(width);
+			this._cachedWidth = width;
+			this._cachedLines = lines;
+			return lines;
+		}
+
+		// If we have a pending promise, we haven't resolved yet — show placeholder
+		if (this._renderPromise) {
+			this._updateShell([Ansi.FG_DIM + "  rendering diff…" + Ansi.RST]);
+			return this.shell.render(width);
+		}
+
+		// Start async render for this width
+		const promise = renderSplitLines(
+			this.diff,
+			this.language,
+			width,
+			this.maxLines,
+			this.dc,
+			this.dbg,
+		);
+		this._renderPromise = promise;
+
+		// Store resolved lines
+		promise.then((lines) => {
+			this._rawLines = lines;
+			this._renderPromise = null;
+			this.invalidate();
+		}).catch(() => {
+			this._rawLines = [Ansi.FG_DIM + "  diff render failed" + Ansi.RST];
+			this._renderPromise = null;
+			this.invalidate();
+		});
+
+		// Show placeholder while waiting
+		this._updateShell([Ansi.FG_DIM + "  rendering diff…" + Ansi.RST]);
+		return this.shell.render(width);
+	}
+
+	private _updateShell(lines: string[]): void {
+		this.shell.clear();
+		// Join lines into a single text block; each line is a row.
+		const textComponent = new (class implements Component {
+			render(_w: number): string[] { return lines; }
+			invalidate(): void {}
+		})();
+		this.shell.addChild(textComponent);
+	}
+
+	invalidate(): void {
+		this._cachedWidth = undefined;
+		this._cachedLines = undefined;
+	}
+}