@kgdiff/cli 0.0.0-stage → 0.1.0

package/src/style.ts

@@ -0,0 +1,164 @@
+/**
+ * Terminal colors: support detection (`--color`, TTY, `NO_COLOR`, `FORCE_COLOR`, `COLORTERM`,
+ * `TERM`) and a tiny painter for the meaning families of docs/visual-language.md.
+ *
+ * Colors are the visual-language family colors: the dark ("night") base colors on dark or
+ * unknown backgrounds, the light ("paper") strong colors when `COLORFGBG` reports a light
+ * background. Truecolor terminals get the exact values, 256-color terminals the nearest xterm
+ * palette entry, others the closest of the 16 basic colors.
+ */
+
+export type ColorMode = 'auto' | 'always' | 'never';
+
+/** 0 = no color, 1 = 16 colors, 2 = 256 colors, 3 = truecolor. */
+export type ColorLevel = 0 | 1 | 2 | 3;
+
+export type Env = Readonly<Record<string, string | undefined>>;
+
+/** Color tones used by the CLI: the five meaning families plus UI accents. */
+export type Tone = 'added' | 'removed' | 'content' | 'structure' | 'identity' | 'accent';
+
+/**
+ * `FORCE_COLOR`: `0` / `false` → 0, `1` / `2` / `3` → exactly that level, `''` / `true` /
+ * anything else → `'depth'` (on, at the terminal's depth); unset → `undefined`.
+ */
+function forceColorLevel(value: string | undefined): ColorLevel | 'depth' | undefined {
+  if (value === undefined) return undefined;
+  const v = value.trim().toLowerCase();
+  if (v === 'false' || v === '0') return 0;
+  if (v === '1') return 1;
+  if (v === '2') return 2;
+  if (v === '3') return 3;
+  return 'depth';
+}
+
+/** Color depth the terminal supports, assuming color is wanted at all. */
+export function terminalDepth(env: Env): ColorLevel {
+  const colorterm = (env.COLORTERM ?? '').toLowerCase();
+  if (colorterm === 'truecolor' || colorterm === '24bit') return 3;
+  const term = (env.TERM ?? '').toLowerCase();
+  if (env.WT_SESSION || term === 'xterm-kitty' || term === 'xterm-ghostty' || term === 'wezterm') {
+    return 3;
+  }
+  if (env.GITHUB_ACTIONS === 'true') return 3;
+  if (/-256(colou?r)?$/.test(term) || env.TERM_PROGRAM === 'Apple_Terminal') return 2;
+  return 1;
+}
+
+/**
+ * Resolve the color level.
+ *
+ * - `never` → 0.
+ * - `always` → the level `FORCE_COLOR` names (1–3), else the terminal depth (at least 16
+ *   colors), even when `NO_COLOR` is set.
+ * - `auto`: `FORCE_COLOR` wins (`0`/`false` disables, `1`–`3` force exactly that level, other
+ *   values the terminal depth), then a non-empty `NO_COLOR` disables, then color only when the
+ *   stream is a TTY and `TERM` is not `dumb`.
+ */
+export function resolveColorLevel(mode: ColorMode, env: Env, isTTY: boolean): ColorLevel {
+  if (mode === 'never') return 0;
+  const forced = forceColorLevel(env.FORCE_COLOR);
+  const depth = (): ColorLevel => {
+    const d = terminalDepth(env);
+    return d === 0 ? 1 : d;
+  };
+  if (mode === 'always') return typeof forced === 'number' && forced > 0 ? forced : depth();
+  if (forced !== undefined) return forced === 'depth' ? depth() : forced;
+  if (env.NO_COLOR !== undefined && env.NO_COLOR !== '') return 0;
+  if (!isTTY || env.TERM === 'dumb') return 0;
+  return terminalDepth(env);
+}
+
+/** True when `COLORFGBG` (rxvt, Konsole, iTerm2…) reports a light background. */
+export function isLightBackground(env: Env): boolean {
+  const parts = (env.COLORFGBG ?? '').split(';');
+  const bg = Number(parts[parts.length - 1]);
+  return bg === 7 || bg === 15;
+}
+
+type Rgb = readonly [number, number, number];
+
+interface ToneColors {
+  readonly dark: Rgb;
+  readonly light: Rgb;
+  /** SGR foreground code of the nearest basic color. */
+  readonly basic: number;
+}
+
+const hex = (value: string): Rgb => {
+  const n = Number.parseInt(value.slice(1), 16);
+  return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
+};
+
+/** docs/visual-language.md: dark `family.*.base`, light `family.*.strong`. */
+const TONES: Readonly<Record<Tone, ToneColors>> = {
+  added: { dark: hex('#34D399'), light: hex('#15803D'), basic: 32 },
+  removed: { dark: hex('#F87171'), light: hex('#B91C1C'), basic: 31 },
+  content: { dark: hex('#FBBF24'), light: hex('#B45309'), basic: 33 },
+  structure: { dark: hex('#38BDF8'), light: hex('#0369A1'), basic: 36 },
+  identity: { dark: hex('#A78BFA'), light: hex('#6D28D9'), basic: 35 },
+  accent: { dark: hex('#7C9CFF'), light: hex('#2F49B5'), basic: 34 },
+};
+
+const CUBE = [0, 95, 135, 175, 215, 255] as const;
+
+function nearestCube(v: number): number {
+  let best = 0;
+  for (let i = 1; i < CUBE.length; i++) {
+    if (Math.abs((CUBE[i] as number) - v) < Math.abs((CUBE[best] as number) - v)) best = i;
+  }
+  return best;
+}
+
+/** Nearest xterm-256 palette index (6×6×6 cube or gray ramp) by squared RGB distance. */
+export function ansi256([r, g, b]: Rgb): number {
+  const ri = nearestCube(r);
+  const gi = nearestCube(g);
+  const bi = nearestCube(b);
+  const cube: Rgb = [CUBE[ri] as number, CUBE[gi] as number, CUBE[bi] as number];
+  const grayLevel = Math.min(23, Math.max(0, Math.round(((r + g + b) / 3 - 8) / 10)));
+  const gray = 8 + grayLevel * 10;
+  const dist = (c: Rgb): number => (c[0] - r) ** 2 + (c[1] - g) ** 2 + (c[2] - b) ** 2;
+  return dist([gray, gray, gray]) < dist(cube) ? 232 + grayLevel : 16 + 36 * ri + 6 * gi + bi;
+}
+
+/** Applies colors and text attributes; every method is the identity at level 0. */
+export interface Painter {
+  readonly level: ColorLevel;
+  tone(tone: Tone, text: string): string;
+  bold(text: string): string;
+  dim(text: string): string;
+}
+
+/** Create a painter for `level`. `light` picks colors that read on light backgrounds. */
+export function createPainter(level: ColorLevel, light = false): Painter {
+  if (level === 0) {
+    const id = (text: string): string => text;
+    return { level, tone: (_tone, text) => text, bold: id, dim: id };
+  }
+  const open: Record<Tone, string> = {} as Record<Tone, string>;
+  for (const [name, colors] of Object.entries(TONES) as [Tone, ToneColors][]) {
+    const rgb = light ? colors.light : colors.dark;
+    open[name] =
+      level === 3
+        ? `\x1b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m`
+        : level === 2
+          ? `\x1b[38;5;${ansi256(rgb)}m`
+          : `\x1b[${colors.basic}m`;
+  }
+  const wrap = (start: string, end: string) => (text: string) =>
+    text === '' ? '' : `${start}${text}${end}`;
+  return {
+    level,
+    tone: (tone, text) => (text === '' ? '' : `${open[tone]}${text}\x1b[39m`),
+    // SGR 22 ends both bold and dim; the CLI never nests the two.
+    bold: wrap('\x1b[1m', '\x1b[22m'),
+    dim: wrap('\x1b[2m', '\x1b[22m'),
+  };
+}
+
+/** Remove SGR escape sequences (for measuring or comparing painted text). */
+export function stripAnsi(text: string): string {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: ESC is the point.
+  return text.replace(/\x1b\[[0-9;]*m/g, '');
+}

package/src/summary.ts

@@ -0,0 +1,440 @@
+/**
+ * Terminal outputs: the default summary (header, counters, diffstat bar, hunk list), `--stat`
+ * and `--name-status` (docs/cli.md §Terminal summary).
+ *
+ * Every line is laid out on plain text first (measured with `stringWidth`, truncated with an
+ * ellipsis) and painted last, so alignment holds with and without color and with CJK labels.
+ */
+import { type DiffResult, formatHunk, type Hunk, type Locale } from '@kgdiff/core';
+import { formatInt, type Messages, messages } from './locale.js';
+import {
+  apportion,
+  COUNTER_PHASES,
+  groupByPhase,
+  hunkFamily,
+  hunkGlyph,
+  nameStatus,
+  type Overview,
+  overview,
+  PHASE_FAMILY,
+  PHASE_GLYPH,
+} from './model.js';
+import type { Painter } from './style.js';
+import { padEnd, padStart, sanitize, stringWidth, truncate, wrap } from './width.js';
+
+export interface TextContext {
+  readonly paint: Painter;
+  readonly locale: Locale;
+  /** Maximum line width in columns. */
+  readonly width: number;
+  /** Maximum hunks listed in the summary; 0 lists all. */
+  readonly limit: number;
+}
+
+const INDENT = '  ';
+const BRAND = 'kgdiff';
+/** The layout never stretches beyond what it needs, nor below this width. */
+const COMFORT_WIDTH = 72;
+const MAX_BAR = 50;
+const COLUMN_GAP = 3;
+/** Narrowest title column worth keeping a family column for. */
+const MIN_TITLE = 16;
+/**
+ * Room kept for the summary after the family label before titles are truncated (at most a
+ * quarter of the line).
+ */
+const MIN_SUMMARY = 22;
+
+/** `179 → 184 nodes · 351 → 353 edges` (single numbers when a count did not change). */
+export function totalsText(diff: DiffResult, m: Messages): string {
+  const { before, after } = diff.stats;
+  return m.totals([before.nodes, after.nodes], [before.edges, after.edges]);
+}
+
+/** Left and right text on one line, right-aligned to `width`; wraps the right part if needed. */
+function spread(
+  left: { plain: string; painted: string },
+  right: { plain: string; painted: string },
+  width: number,
+): string[] {
+  const gap = width - stringWidth(left.plain) - stringWidth(right.plain);
+  if (!right.plain) return [left.painted];
+  if (gap >= COLUMN_GAP) return [left.painted + ' '.repeat(gap) + right.painted];
+  const room = width - INDENT.length;
+  return [
+    left.painted,
+    INDENT + (stringWidth(right.plain) <= room ? right.painted : truncate(right.plain, room)),
+  ];
+}
+
+function headerLines(diff: DiffResult, title: string, ctx: TextContext, width: number): string[] {
+  const m = messages(ctx.locale);
+  const { paint } = ctx;
+  const right = totalsText(diff, m);
+  const fixed = BRAND.length + 2;
+  const fitsBeside = width - fixed - COLUMN_GAP - stringWidth(right) >= 12;
+  const titleRoom = fitsBeside ? width - fixed - COLUMN_GAP - stringWidth(right) : width - fixed;
+  const shown = truncate(sanitize(title), titleRoom);
+  const left = {
+    plain: `${BRAND}  ${shown}`,
+    painted: `${paint.bold(paint.tone('accent', BRAND))}  ${paint.bold(shown)}`,
+  };
+  return spread(left, { plain: right, painted: paint.dim(right) }, width);
+}
+
+interface Painted {
+  readonly plain: string;
+  readonly painted: string;
+}
+
+function counterItems(ov: Overview, m: Messages, paint: Painter): Painted[] {
+  const items: Painted[] = [];
+  for (const phase of COUNTER_PHASES) {
+    const n = ov.phases[phase].hunks;
+    if (n === 0) continue;
+    const count = `${PHASE_GLYPH[phase]}${formatInt(n)}`;
+    items.push({
+      plain: `${count} ${m.counter[phase]}`,
+      painted: `${paint.bold(paint.tone(PHASE_FAMILY[phase], count))} ${m.counter[phase]}`,
+    });
+  }
+  return items;
+}
+
+const COUNTER_GAP = '   ';
+
+/** Counter items joined on one line, or wrapped over several lines to fit `room`. */
+function counterLines(items: readonly Painted[], room: number): Painted[] {
+  const lines: { plain: string[]; painted: string[] }[] = [];
+  for (const item of items) {
+    const line = lines[lines.length - 1];
+    const width = line ? stringWidth(line.plain.join(COUNTER_GAP)) + COUNTER_GAP.length : 0;
+    if (line && width + stringWidth(item.plain) <= room) {
+      line.plain.push(item.plain);
+      line.painted.push(item.painted);
+    } else lines.push({ plain: [item.plain], painted: [item.painted] });
+  }
+  return lines.map((l) => ({
+    plain: l.plain.join(COUNTER_GAP),
+    painted: l.painted.join(COUNTER_GAP),
+  }));
+}
+
+/** Proportional diffstat bar: one segment per phase, sized by changed elements. */
+export function diffstatBar(ov: Overview, width: number, paint: Painter): string {
+  const cells = apportion(
+    COUNTER_PHASES.map((p) => ov.phases[p].changes),
+    Math.min(ov.changes, Math.max(10, Math.min(MAX_BAR, width - INDENT.length * 2))),
+  );
+  return COUNTER_PHASES.map((phase, i) => {
+    const n = cells[i] as number;
+    if (n === 0) return '';
+    return paint.level === 0
+      ? PHASE_GLYPH[phase].repeat(n)
+      : paint.tone(PHASE_FAMILY[phase], '█'.repeat(n));
+  }).join('');
+}
+
+function statLines(ov: Overview, ctx: TextContext, width: number): string[] {
+  const m = messages(ctx.locale);
+  const right = m.changes(ov.changes, ov.hunks);
+  const rows = counterLines(counterItems(ov, m, ctx.paint), width - INDENT.length);
+  const lines = rows.slice(0, -1).map((r) => INDENT + r.painted);
+  const last = rows[rows.length - 1] ?? { plain: '', painted: '' };
+  lines.push(
+    ...spread(
+      { plain: INDENT + last.plain, painted: INDENT + last.painted },
+      { plain: right, painted: ctx.paint.dim(right) },
+      width,
+    ),
+  );
+  lines.push(INDENT + diffstatBar(ov, width, ctx.paint));
+  return lines;
+}
+
+function identicalLines(diff: DiffResult, ctx: TextContext, width: number): string[] {
+  const m = messages(ctx.locale);
+  const { paint } = ctx;
+  const detail = m.identicalDetail(diff.stats.after.nodes, diff.stats.after.edges);
+  const head = `✓ ${m.identical}`;
+  const room = width - INDENT.length;
+  if (stringWidth(head) + 2 + stringWidth(detail) <= room) {
+    return [
+      `${INDENT}${paint.tone('added', '✓')} ${paint.bold(m.identical)}  ${paint.dim(detail)}`,
+    ];
+  }
+  return [
+    `${INDENT}${paint.tone('added', '✓')} ${paint.bold(m.identical)}`,
+    ...wrap(detail, room).map((line) => INDENT + paint.dim(line)),
+  ];
+}
+
+interface Row {
+  readonly hunk: Hunk;
+  readonly glyph: string;
+  readonly title: string;
+  readonly family: string;
+  readonly subtitle: string;
+}
+
+function rowsOf(diff: DiffResult, hunks: readonly Hunk[], ctx: TextContext): Row[] {
+  const m = messages(ctx.locale);
+  return hunks.map((hunk) => {
+    const { title, subtitle } = formatHunk(hunk, diff, ctx.locale);
+    return {
+      hunk,
+      glyph: hunkGlyph(hunk),
+      title: sanitize(title),
+      family: m.family[hunkFamily(hunk)],
+      subtitle: sanitize(subtitle),
+    };
+  });
+}
+
+const rightText = (row: Row): string =>
+  row.subtitle ? `${row.family} · ${row.subtitle}` : row.family;
+
+/** Natural width of the hunk list (before any truncation). */
+function listWidth(rows: readonly Row[]): number {
+  let title = 0;
+  let right = 0;
+  for (const row of rows) {
+    title = Math.max(title, stringWidth(row.title));
+    right = Math.max(right, stringWidth(rightText(row)));
+  }
+  return INDENT.length + 2 + title + COLUMN_GAP + right;
+}
+
+/**
+ * Column widths for the hunk list. Titles come first: they get all the room they need as long
+ * as the family column keeps its family label plus a short summary; the summaries take the rest.
+ * Below ~40 columns the family column is dropped.
+ */
+function listColumns(rows: readonly Row[], width: number): { title: number; right: number } {
+  const room = width - INDENT.length - 2 - COLUMN_GAP;
+  let maxTitle = 0;
+  let maxRight = 0;
+  let maxFamily = 0;
+  for (const row of rows) {
+    maxTitle = Math.max(maxTitle, stringWidth(row.title));
+    maxRight = Math.max(maxRight, stringWidth(rightText(row)));
+    maxFamily = Math.max(maxFamily, stringWidth(row.family));
+  }
+  if (maxTitle + maxRight <= room) return { title: maxTitle, right: maxRight };
+  if (room - maxFamily < MIN_TITLE) return { title: width - INDENT.length - 2, right: 0 };
+  const minRight = Math.min(maxRight, maxFamily + Math.min(MIN_SUMMARY, Math.floor(room / 4)));
+  const title = Math.max(MIN_TITLE, Math.min(maxTitle, room - minRight));
+  return { title, right: Math.max(maxFamily, Math.min(maxRight, room - title)) };
+}
+
+function renderRow(row: Row, cols: { title: number; right: number }, ctx: TextContext): string {
+  const { paint } = ctx;
+  const tone = hunkFamily(row.hunk);
+  const glyph = paint.tone(tone, row.glyph);
+  if (cols.right === 0) return `${INDENT}${glyph} ${truncate(row.title, cols.title)}`;
+  const title = padEnd(truncate(row.title, cols.title), cols.title);
+  const familyWidth = stringWidth(row.family);
+  const restRoom = cols.right - familyWidth;
+  const rest = row.subtitle && restRoom >= 6 ? truncate(` · ${row.subtitle}`, restRoom) : '';
+  return (
+    `${INDENT}${glyph} ${title}${' '.repeat(COLUMN_GAP)}` +
+    `${paint.tone(tone, row.family)}${paint.dim(rest)}`
+  );
+}
+
+/** Line width for a layout whose content naturally needs `natural` columns. */
+function layoutWidth(natural: number, available: number): number {
+  return Math.min(available, Math.max(natural, COMFORT_WIDTH));
+}
+
+function headerNatural(diff: DiffResult, title: string, ctx: TextContext, ov: Overview): number {
+  const m = messages(ctx.locale);
+  const header = BRAND.length + 2 + stringWidth(sanitize(title)) + COLUMN_GAP;
+  const counters =
+    INDENT.length +
+    stringWidth(
+      counterItems(ov, m, ctx.paint)
+        .map((i) => i.plain)
+        .join(COUNTER_GAP),
+    ) +
+    COLUMN_GAP;
+  return Math.max(
+    header + stringWidth(totalsText(diff, m)),
+    counters + stringWidth(m.changes(ov.changes, ov.hunks)),
+  );
+}
+
+/**
+ * The default terminal output: header (title, node and edge totals), per-phase counters, a
+ * proportional diffstat bar, then the hunks grouped by phase with glyph, title and a family /
+ * summary column. At most `ctx.limit` hunks are listed (0 = all), then "… and N more".
+ */
+export function renderSummary(diff: DiffResult, title: string, ctx: TextContext): string {
+  const ov = overview(diff);
+  if (ov.hunks === 0) {
+    const width = layoutWidth(headerNatural(diff, title, ctx, ov), ctx.width);
+    return `${[...headerLines(diff, title, ctx, width), '', ...identicalLines(diff, ctx, width)].join('\n')}\n`;
+  }
+  const m = messages(ctx.locale);
+  const groups = groupByPhase(diff.hunks);
+  let shown = 0;
+  const budget = ctx.limit > 0 ? ctx.limit : Number.POSITIVE_INFINITY;
+  const listed = groups.map((g) => {
+    const take = g.hunks.slice(0, Math.max(0, budget - shown));
+    shown += take.length;
+    return { phase: g.phase, total: g.hunks.length, rows: rowsOf(diff, take, ctx) };
+  });
+  const allRows = listed.flatMap((g) => g.rows);
+  const width = layoutWidth(
+    Math.max(headerNatural(diff, title, ctx, ov), listWidth(allRows)),
+    ctx.width,
+  );
+  const cols = listColumns(allRows, width);
+  const lines = [...headerLines(diff, title, ctx, width), '', ...statLines(ov, ctx, width), ''];
+  for (const group of listed) {
+    if (group.rows.length === 0) continue;
+    lines.push(
+      `${INDENT}${ctx.paint.bold(m.phase[group.phase])} ${ctx.paint.dim(formatInt(group.total))}`,
+    );
+    for (const row of group.rows) lines.push(renderRow(row, cols, ctx));
+  }
+  const hidden = ov.hunks - shown;
+  if (hidden > 0) {
+    const more = `${m.more(hidden)} · ${m.moreHint}`;
+    lines.push(INDENT + ctx.paint.dim(truncate(more, width - INDENT.length)));
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+const MAX_TYPE_ROWS = 12;
+const MAX_TYPE_NAME = 28;
+
+/**
+ * `--stat`: header, counters and bar, a nodes / edges × added / removed / modified / unchanged
+ * table, and a git-style per-type breakdown (`+` added, `−` removed, `~` modified nodes).
+ */
+export function renderStat(diff: DiffResult, title: string, ctx: TextContext): string {
+  const ov = overview(diff);
+  const width = layoutWidth(headerNatural(diff, title, ctx, ov), ctx.width);
+  const lines = [...headerLines(diff, title, ctx, width), ''];
+  if (ov.hunks === 0) return `${[...lines, ...identicalLines(diff, ctx, width)].join('\n')}\n`;
+  lines.push(...statLines(ov, ctx, width), '');
+  lines.push(...countsTable(diff, ctx, width), '');
+  lines.push(...typeLines(diff, ctx, width));
+  return `${lines.join('\n')}\n`;
+}
+
+/** Node / edge counts; columns are dropped from the right when the line is too narrow. */
+function countsTable(diff: DiffResult, ctx: TextContext, width: number): string[] {
+  const m = messages(ctx.locale);
+  const { paint } = ctx;
+  const { nodes, edges } = diff.stats;
+  const all = [
+    { label: m.table.added, key: 'added', tone: 'added' },
+    { label: m.table.removed, key: 'removed', tone: 'removed' },
+    { label: m.table.modified, key: 'modified', tone: 'content' },
+    { label: m.table.unchanged, key: 'unchanged', tone: undefined },
+  ] as const;
+  const rows = [
+    { label: m.table.nodes, counts: nodes },
+    { label: m.table.edges, counts: edges },
+  ];
+  const labelWidth = Math.max(...rows.map((r) => stringWidth(r.label)));
+  const widthOf = (c: (typeof all)[number]): number =>
+    Math.max(stringWidth(c.label), ...rows.map((r) => formatInt(r.counts[c.key]).length));
+  const columns: (typeof all)[number][] = [...all];
+  while (
+    columns.length > 1 &&
+    INDENT.length + labelWidth + columns.reduce((sum, c) => sum + 2 + widthOf(c), 0) > width
+  ) {
+    columns.pop();
+  }
+  const widths = columns.map(widthOf);
+  const head =
+    INDENT +
+    ' '.repeat(labelWidth) +
+    columns.map((c, i) => `  ${padStart(c.label, widths[i] as number)}`).join('');
+  const body = rows.map(
+    (r) =>
+      INDENT +
+      padEnd(r.label, labelWidth) +
+      columns
+        .map((c, i) => {
+          const n = r.counts[c.key];
+          const cell = padStart(formatInt(n), widths[i] as number);
+          return `  ${c.tone && n > 0 ? paint.tone(c.tone, cell) : cell}`;
+        })
+        .join(''),
+  );
+  return [paint.dim(head), ...body];
+}
+
+function typeLines(diff: DiffResult, ctx: TextContext, width: number): string[] {
+  const m = messages(ctx.locale);
+  const { paint } = ctx;
+  const changed = diff.stats.byType.filter((t) => t.added + t.removed + t.modified > 0);
+  if (changed.length === 0) return [];
+  const shown = changed.slice(0, MAX_TYPE_ROWS);
+  const totals = shown.map((t) => t.added + t.removed + t.modified);
+  const countRoom = Math.max(...totals.map((n) => formatInt(n).length));
+  // Names give way first on narrow lines: indent, two spaces, count, space, ≥ 4 bar cells.
+  const nameRoom = Math.max(
+    4,
+    Math.min(MAX_TYPE_NAME, width - INDENT.length - 2 - countRoom - 1 - 4),
+  );
+  const names = shown.map((t) => truncate(sanitize(t.type) || m.untyped, nameRoom));
+  const nameWidth = Math.max(...names.map(stringWidth));
+  const countWidth = Math.max(...totals.map((n) => formatInt(n).length));
+  const maxTotal = Math.max(...totals);
+  const barRoom = Math.max(1, Math.min(30, width - INDENT.length - nameWidth - countWidth - 3));
+  const lines = [INDENT + paint.bold(m.byType)];
+  shown.forEach((t, i) => {
+    const total = totals[i] as number;
+    const size =
+      maxTotal <= barRoom ? total : Math.max(1, Math.round((total / maxTotal) * barRoom));
+    const [a, r, mod] = apportion([t.added, t.removed, t.modified], size);
+    const bar =
+      paint.tone('added', '+'.repeat(a ?? 0)) +
+      paint.tone('removed', '−'.repeat(r ?? 0)) +
+      paint.tone('content', '~'.repeat(mod ?? 0));
+    lines.push(
+      `${INDENT}${padEnd(names[i] as string, nameWidth)}  ${padStart(formatInt(total), countWidth)} ${bar}`,
+    );
+  });
+  if (changed.length > shown.length) {
+    lines.push(
+      INDENT +
+        paint.dim(truncate(m.moreTypes(changed.length - shown.length), width - INDENT.length)),
+    );
+  }
+  return lines;
+}
+
+/**
+ * `--name-status`: one line per hunk in review order: status letter, anchor id, title.
+ * Tab-separated (scriptable) unless `aligned`, which pads the columns for a terminal.
+ */
+export function renderNameStatus(diff: DiffResult, ctx: TextContext, aligned: boolean): string {
+  if (diff.hunks.length === 0) return '';
+  const rows = diff.hunks.map((hunk) => ({
+    hunk,
+    letter: nameStatus(hunk, diff),
+    id: sanitize(hunk.anchor),
+    title: sanitize(formatHunk(hunk, diff, ctx.locale).title),
+  }));
+  const { paint } = ctx;
+  if (!aligned) {
+    return `${rows.map((r) => `${paint.tone(hunkFamily(r.hunk), r.letter)}\t${r.id}\t${r.title}`).join('\n')}\n`;
+  }
+  const idWidth = Math.min(
+    rows.reduce((max, r) => Math.max(max, stringWidth(r.id)), 0),
+    Math.max(8, Math.floor(ctx.width / 3)),
+  );
+  const titleRoom = Math.max(1, ctx.width - 1 - 2 - idWidth - 2);
+  return `${rows
+    .map((r) => {
+      const id = padEnd(truncate(r.id, idWidth), idWidth);
+      return `${paint.bold(paint.tone(hunkFamily(r.hunk), r.letter))}  ${paint.dim(id)}  ${truncate(r.title, titleRoom)}`;
+    })
+    .join('\n')}\n`;
+}

package/src/version.ts

@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs';
+
+let cached: string | undefined;
+
+/**
+ * The CLI version from its package.json (one directory above both `src/` and `dist/`).
+ * Read lazily and once.
+ */
+export function cliVersion(): string {
+  if (cached === undefined) {
+    try {
+      const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as {
+        version?: unknown;
+      };
+      cached = typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+    } catch {
+      cached = '0.0.0';
+    }
+  }
+  return cached;
+}