dialekt 0.1.0

package/src/cli/format.ts

@@ -0,0 +1,205 @@
+/**
+ * Terminal formatting core utilities for the dialekt CLI output.
+ *
+ * Two output modes:
+ *   - `pretty` — lush human-readable output with colours and grouping (TTY only)
+ *   - `json`   — single compact JSON document for AI agents / machines
+ *
+ * stdout is the data contract in every mode; status / banners go to stderr.
+ * All decoration is gated behind `isTTY` so the output is never mojibake-prone
+ * when piped or consumed by another process.
+ */
+
+// ─── Output format ──────────────────────────────────────────────────────────
+
+export type OutputFormat = 'pretty' | 'json';
+
+/**
+ * Environment variables that signal dialekt is running inside an AI agent.
+ * When any is set (truthy), or stdout is not a TTY, JSON mode is the default.
+ */
+export const AGENT_ENV_VARS = [
+  'CLAUDE_CODE',
+  'CLAUDECODE',
+  'CURSOR',
+  'CURSOR_TRACE_ID',
+  'DEVIN',
+  'GEMINI_CLI',
+  'AGENT_TASK_ID',
+  'AIDER_CHAT',
+] as const;
+
+/**
+ * Resolves the output format from explicit flag and environment.
+ * Precedence: explicit `--format` > auto-detection.
+ *
+ * Auto-detection picks `json` when stdout is not a TTY or an agent env var
+ * is present; otherwise `pretty`.
+ */
+export function detectFormat(explicit?: OutputFormat | undefined): OutputFormat {
+  if (explicit !== undefined) return explicit;
+  if (!process.stdout.isTTY) return 'json';
+  if (AGENT_ENV_VARS.some((k) => process.env[k])) return 'json';
+  return 'pretty';
+}
+
+// ─── ANSI colours ────────────────────────────────────────────────────────────
+
+const C = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+} as const;
+
+function isTty(): boolean {
+  return process.stdout.isTTY === true;
+}
+
+/** Wraps text in ANSI codes only when stdout is a TTY; otherwise returns it bare. */
+export function color(text: string, ...codes: string[]): string {
+  if (!isTty()) return text;
+  return `${codes.join('')}${text}${C.reset}`;
+}
+
+// ─── Box-drawing glyphs ──────────────────────────────────────────────────────
+
+interface Glyphs {
+  hLine: string;
+  vLine: string;
+  cornerTL: string;
+  cornerTR: string;
+  cornerBL: string;
+  cornerBR: string;
+  teeRight: string;
+  teeLeft: string;
+  teeDown: string;
+  teeUp: string;
+  cross: string;
+  bullet: string;
+  arrow: string;
+  check: string;
+  crossMark: string;
+  warn: string;
+}
+
+const PRETTY_GLYPHS: Glyphs = {
+  hLine: String.fromCharCode(0x2500),
+  vLine: String.fromCharCode(0x2502),
+  cornerTL: String.fromCharCode(0x250C),
+  cornerTR: String.fromCharCode(0x2510),
+  cornerBL: String.fromCharCode(0x2514),
+  cornerBR: String.fromCharCode(0x2518),
+  teeRight: String.fromCharCode(0x251C),
+  teeLeft: String.fromCharCode(0x2524),
+  teeDown: String.fromCharCode(0x252C),
+  teeUp: String.fromCharCode(0x2534),
+  cross: String.fromCharCode(0x253C),
+  bullet: String.fromCharCode(0x2022),
+  arrow: String.fromCharCode(0x2192),
+  check: String.fromCharCode(0x2713),
+  crossMark: String.fromCharCode(0x2717),
+  warn: String.fromCharCode(0x26A0),
+};
+
+const ASCII_GLYPHS: Glyphs = {
+  hLine: '-',
+  vLine: '|',
+  cornerTL: '+',
+  cornerTR: '+',
+  cornerBL: '+',
+  cornerBR: '+',
+  teeRight: '+',
+  teeLeft: '+',
+  teeDown: '+',
+  teeUp: '+',
+  cross: '+',
+  bullet: '*',
+  arrow: '>',
+  check: '+',
+  crossMark: 'x',
+  warn: '!',
+};
+
+export function glyphs(): Glyphs {
+  return isTty() ? PRETTY_GLYPHS : ASCII_GLYPHS;
+}
+
+// ─── Table helpers ───────────────────────────────────────────────────────────
+
+export function drawTable(
+  headers: readonly string[],
+  rows: readonly (readonly string[])[]
+): string {
+  const g = glyphs();
+  const colWidths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length))
+  );
+
+  const pad = (text: string, width: number) => text.padEnd(width);
+
+  const hLine = g.cornerTL +
+    colWidths.map((w) => g.hLine.repeat(w + 2)).join(g.teeDown) +
+    g.cornerTR;
+
+  const headerRow = g.vLine +
+    headers.map((h, i) => ` ${color(pad(h, colWidths[i]!), C.bold)} `).join(g.vLine) +
+    g.vLine;
+
+  const separator = g.teeRight +
+    colWidths.map((w) => g.hLine.repeat(w + 2)).join(g.cross) +
+    g.teeLeft;
+
+  const dataRows = rows.map((row) =>
+    g.vLine +
+    row.map((cell, i) => ` ${pad(cell, colWidths[i]!)} `).join(g.vLine) +
+    g.vLine
+  );
+
+  const bottomLine = g.cornerBL +
+    colWidths.map((w) => g.hLine.repeat(w + 2)).join(g.teeUp) +
+    g.cornerBR;
+
+  return [hLine, headerRow, separator, ...dataRows, bottomLine].join('\n');
+}
+
+// ─── Banner / header helpers ─────────────────────────────────────────────────
+
+export function banner(title: string): string {
+  const g = glyphs();
+  const line = g.hLine.repeat(Math.max(title.length + 4, 40));
+  return `${color(line, C.dim)}\n  ${color(title, C.bold + C.cyan)}\n${color(line, C.dim)}`;
+}
+
+export function sectionHeader(label: string): string {
+  const g = glyphs();
+  return `\n${color(`${g.arrow} ${label}`, C.bold + C.cyan)}`;
+}
+
+export function success(text: string): string {
+  const g = glyphs();
+  return `${color(`${g.check} ${text}`, C.green)}`;
+}
+
+export function failure(text: string): string {
+  const g = glyphs();
+  return `${color(`${g.crossMark} ${text}`, C.red)}`;
+}
+
+export function warning(text: string): string {
+  const g = glyphs();
+  return `${color(`${g.warn} ${text}`, C.yellow)}`;
+}
+
+export function info(text: string): string {
+  return color(text, C.dim);
+}
+
+export function keyValue(key: string, value: string): string {
+  return `  ${color(key, C.bold)} ${value}`;
+}

package/src/cli/formatters.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from 'vitest';
+import {
+  formatMissingKeys,
+  formatUnusedKeys,
+  formatValidate,
+  formatLanguages,
+  formatTranslate,
+  formatAdd,
+  formatBenchmark,
+  formatError,
+} from './formatters.js';
+
+describe('formatMissingKeys', () => {
+  it('returns JSON array in json mode', () => {
+    const entries = [{ adapter: 'a', locale: 'de', resource: 'r', key: 'k' }];
+    const result = formatMissingKeys(entries, 'json');
+    expect(JSON.parse(result)).toEqual(entries);
+  });
+
+  it('returns success message when empty in pretty mode', () => {
+    const result = formatMissingKeys([], 'pretty');
+    expect(result).toContain('complete');
+  });
+
+  it('groups by adapter, locale, resource in pretty mode', () => {
+    const entries = [
+      { adapter: 'a1', locale: 'de', resource: 'auth', key: 'k1' },
+      { adapter: 'a1', locale: 'de', resource: 'auth', key: 'k2' },
+      { adapter: 'a1', locale: 'fr', resource: 'auth', key: 'k3' },
+    ];
+    const result = formatMissingKeys(entries, 'pretty');
+    expect(result).toContain('a1');
+    expect(result).toContain('de');
+    expect(result).toContain('fr');
+    expect(result).toContain('auth');
+    expect(result).toContain('k1');
+    expect(result).toContain('k2');
+    expect(result).toContain('k3');
+  });
+});
+
+describe('formatUnusedKeys', () => {
+  it('returns JSON array in json mode', () => {
+    const entries = [{ adapter: 'a', locale: 'en', resource: 'r', key: 'old' }];
+    const result = formatUnusedKeys(entries, 'json');
+    expect(JSON.parse(result)).toEqual(entries);
+  });
+
+  it('returns success message when empty in pretty mode', () => {
+    const result = formatUnusedKeys([], 'pretty');
+    expect(result).toContain('referenced');
+  });
+
+  it('groups entries in pretty mode', () => {
+    const entries = [{ adapter: 'a', locale: 'en', resource: 'r', key: 'old' }];
+    const result = formatUnusedKeys(entries, 'pretty');
+    expect(result).toContain('a');
+    expect(result).toContain('old');
+  });
+});
+
+describe('formatValidate', () => {
+  it('returns JSON in json mode', () => {
+    const result = formatValidate({ passing: true, entries: [] }, 'json');
+    const parsed = JSON.parse(result);
+    expect(parsed.passing).toBe(true);
+  });
+
+  it('returns success message when passing in pretty mode', () => {
+    const result = formatValidate({ passing: true, entries: [] }, 'pretty');
+    expect(result).toContain('up to date');
+  });
+
+  it('returns table when failing in pretty mode', () => {
+    const result = formatValidate(
+      { passing: false, entries: [{ adapter: 'a', locale: 'de', resource: 'r', count: 3 }] },
+      'pretty',
+    );
+    expect(result).toContain('Missing');
+    expect(result).toContain('a');
+    expect(result).toContain('de');
+    expect(result).toContain('3');
+  });
+});
+
+describe('formatLanguages', () => {
+  it('returns JSON in json mode', () => {
+    const result = formatLanguages([{ adapter: 'a', locales: ['en', 'de'] }], 'json');
+    expect(JSON.parse(result)).toEqual([{ adapter: 'a', locales: ['en', 'de'] }]);
+  });
+
+  it('returns warning when empty in pretty mode', () => {
+    const result = formatLanguages([], 'pretty');
+    expect(result).toContain('No adapters');
+  });
+
+  it('lists adapters and locales in pretty mode', () => {
+    const result = formatLanguages([{ adapter: 'laravel', locales: ['en', 'de'] }], 'pretty');
+    expect(result).toContain('laravel');
+    expect(result).toContain('en');
+    expect(result).toContain('de');
+  });
+});
+
+describe('formatTranslate', () => {
+  it('returns JSON in json mode', () => {
+    const result = formatTranslate({ success: true, message: 'Done' }, 'json');
+    expect(JSON.parse(result)).toEqual({ success: true, message: 'Done' });
+  });
+
+  it('returns success text in pretty mode', () => {
+    const result = formatTranslate({ success: true, message: 'Done' }, 'pretty');
+    expect(result).toContain('Done');
+  });
+
+  it('includes stats in pretty mode', () => {
+    const result = formatTranslate(
+      { success: true, message: 'Done', stats: { adaptersProcessed: 1, localesTranslated: 2, keysTranslated: 5 } },
+      'pretty',
+    );
+    expect(result).toContain('Adapters:');
+    expect(result).toContain('1');
+    expect(result).toContain('Locales:');
+    expect(result).toContain('2');
+  });
+
+  it('returns failure text in pretty mode', () => {
+    const result = formatTranslate({ success: false, message: 'Failed' }, 'pretty');
+    expect(result).toContain('Failed');
+  });
+});
+
+describe('formatAdd', () => {
+  it('returns JSON in json mode', () => {
+    const result = formatAdd({ success: true, message: 'Done' }, 'json');
+    expect(JSON.parse(result)).toEqual({ success: true, message: 'Done' });
+  });
+
+  it('returns success text in pretty mode', () => {
+    const result = formatAdd({ success: true, message: 'Done' }, 'pretty');
+    expect(result).toContain('Done');
+  });
+
+  it('lists added resources in pretty mode', () => {
+    const result = formatAdd(
+      { success: true, message: 'Done', addedResources: ['a/en/messages'] },
+      'pretty',
+    );
+    expect(result).toContain('a/en/messages');
+  });
+});
+
+describe('formatBenchmark', () => {
+  it('returns JSON in json mode', () => {
+    const entries = [{ strategyName: 's', totalChunks: 1, succeededChunks: 1, failedChunks: 0, totalDurationMs: 100, averageDurationMsPerChunk: 100, totalAttempts: 1 }];
+    const result = formatBenchmark(entries, 'json');
+    expect(JSON.parse(result)).toEqual(entries);
+  });
+
+  it('returns warning when empty in pretty mode', () => {
+    const result = formatBenchmark([], 'pretty');
+    expect(result).toContain('No benchmark');
+  });
+
+  it('renders table in pretty mode', () => {
+    const entries = [
+      { strategyName: 'one-shot', totalChunks: 2, succeededChunks: 2, failedChunks: 0, totalDurationMs: 200, averageDurationMsPerChunk: 100, totalAttempts: 2 },
+    ];
+    const result = formatBenchmark(entries, 'pretty');
+    expect(result).toContain('Benchmark');
+    expect(result).toContain('one-shot');
+    expect(result).toContain('2/2');
+  });
+});
+
+describe('formatError', () => {
+  it('returns JSON in json mode', () => {
+    const result = formatError('Something broke', 'json');
+    expect(JSON.parse(result)).toEqual({ error: 'Something broke' });
+  });
+
+  it('returns failure text in pretty mode', () => {
+    const result = formatError('Something broke', 'pretty');
+    expect(result).toContain('Something broke');
+  });
+});