@sentry/warden 0.0.0

package/src/cli/output/box.ts

@@ -0,0 +1,235 @@
+import chalk from 'chalk';
+import type { OutputMode } from './tty.js';
+
+/**
+ * Unicode box-drawing characters for TTY mode.
+ */
+const BOX = {
+  topLeft: '┌',
+  topRight: '┐',
+  bottomLeft: '└',
+  bottomRight: '┘',
+  horizontal: '─',
+  vertical: '│',
+  leftT: '├',
+  rightT: '┤',
+} as const;
+
+/**
+ * Options for creating a box.
+ */
+export interface BoxOptions {
+  /** Title displayed in the header (left side) */
+  title: string;
+  /** Badge displayed in the header (right side, e.g., duration) */
+  badge?: string;
+  /** Output mode for TTY vs non-TTY rendering */
+  mode: OutputMode;
+  /** Minimum width for the box (default: 50) */
+  minWidth?: number;
+}
+
+/**
+ * Renders box-style containers for terminal output.
+ * Supports TTY mode with Unicode box characters and CI mode with plain text.
+ */
+export class BoxRenderer {
+  private readonly title: string;
+  private readonly badge: string | undefined;
+  private readonly mode: OutputMode;
+  private readonly width: number;
+  private readonly lines: string[] = [];
+
+  constructor(options: BoxOptions) {
+    this.title = options.title;
+    this.badge = options.badge;
+    this.mode = options.mode;
+
+    // Calculate width based on terminal columns, with min/max constraints
+    const minWidth = options.minWidth ?? 50;
+    const maxWidth = Math.min(options.mode.columns - 2, 100);
+    this.width = Math.max(minWidth, maxWidth);
+  }
+
+  /**
+   * Render the top border with title and optional badge.
+   * TTY: ┌─ title ─────────────────────── badge ─┐
+   * CI:  === title (badge) ===
+   */
+  header(): this {
+    if (this.mode.isTTY) {
+      const titlePart = `${BOX.horizontal} ${this.title} `;
+      const badgePart = this.badge ? ` ${this.badge} ${BOX.horizontal}` : BOX.horizontal;
+      const titleLen = this.stripAnsi(titlePart).length;
+      const badgeLen = this.stripAnsi(badgePart).length;
+      const fillLen = Math.max(0, this.width - titleLen - badgeLen - 2);
+      const fill = BOX.horizontal.repeat(fillLen);
+
+      this.lines.push(
+        chalk.dim(BOX.topLeft) +
+          chalk.dim(BOX.horizontal) + ' ' +
+          chalk.bold(this.title) +
+          ' ' + chalk.dim(fill) +
+          (this.badge ? chalk.dim(` ${this.badge} `) : '') +
+          chalk.dim(BOX.horizontal + BOX.topRight)
+      );
+    } else {
+      const badgePart = this.badge ? ` (${this.badge})` : '';
+      this.lines.push(`=== ${this.title}${badgePart} ===`);
+    }
+    return this;
+  }
+
+  /**
+   * Get the available content width (excluding borders and padding).
+   */
+  get contentWidth(): number {
+    return this.width - 4; // 2 for borders + 2 for padding spaces
+  }
+
+  /**
+   * Add content lines with side borders (TTY) or plain (CI).
+   * Long lines are automatically wrapped to fit within the box.
+   */
+  content(contentLines: string | string[]): this {
+    const lines = Array.isArray(contentLines) ? contentLines : [contentLines];
+
+    for (const line of lines) {
+      // Wrap long lines to fit within the box
+      const wrappedLines = this.wrapLine(line);
+
+      for (const wrappedLine of wrappedLines) {
+        if (this.mode.isTTY) {
+          const strippedLen = this.stripAnsi(wrappedLine).length;
+          const padding = Math.max(0, this.width - strippedLen - 4);
+          this.lines.push(
+            chalk.dim(BOX.vertical) + ' ' + wrappedLine + ' '.repeat(padding) + ' ' + chalk.dim(BOX.vertical)
+          );
+        } else {
+          this.lines.push(wrappedLine);
+        }
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Wrap a line to fit within the content width.
+   * Preserves leading indentation on wrapped lines.
+   */
+  private wrapLine(line: string): string[] {
+    const maxWidth = this.contentWidth;
+    const stripped = this.stripAnsi(line);
+
+    // If it fits, return as-is
+    if (stripped.length <= maxWidth) {
+      return [line];
+    }
+
+    // For lines with ANSI codes, we need to be careful.
+    // For simplicity, if the line has ANSI codes and is too long,
+    // we'll wrap the stripped version and lose formatting on continuation lines.
+    const hasAnsi = line !== stripped;
+
+    // Detect leading indentation
+    const indentMatch = stripped.match(/^(\s*)/);
+    const indent = indentMatch?.[1] ?? '';
+    const textToWrap = hasAnsi ? stripped : line;
+
+    const result: string[] = [];
+    let remaining = textToWrap;
+    let isFirstLine = true;
+
+    while (remaining.length > 0) {
+      const currentIndent = isFirstLine ? '' : indent;
+      const availableWidth = maxWidth - currentIndent.length;
+
+      if (this.stripAnsi(remaining).length <= availableWidth) {
+        result.push(currentIndent + remaining);
+        break;
+      }
+
+      // Find a good break point (prefer word boundaries)
+      let breakPoint = availableWidth;
+      const searchStart = Math.max(0, availableWidth - 20);
+
+      for (let i = availableWidth; i >= searchStart; i--) {
+        if (remaining[i] === ' ') {
+          breakPoint = i;
+          break;
+        }
+      }
+
+      // If no space found, hard break at max width
+      if (breakPoint === availableWidth && remaining[availableWidth] !== ' ') {
+        breakPoint = availableWidth;
+      }
+
+      const chunk = remaining.slice(0, breakPoint);
+      result.push(currentIndent + chunk);
+
+      // Skip the space at the break point if there is one
+      remaining = remaining.slice(breakPoint).trimStart();
+      isFirstLine = false;
+    }
+
+    return result;
+  }
+
+  /**
+   * Add an empty content line.
+   */
+  blank(): this {
+    return this.content('');
+  }
+
+  /**
+   * Render a horizontal divider.
+   * TTY: ├─────────────────────────────────────────────┤
+   * CI:  ---
+   */
+  divider(): this {
+    if (this.mode.isTTY) {
+      const fill = BOX.horizontal.repeat(this.width - 2);
+      this.lines.push(chalk.dim(BOX.leftT + fill + BOX.rightT));
+    } else {
+      this.lines.push('---');
+    }
+    return this;
+  }
+
+  /**
+   * Render the bottom border.
+   * TTY: └─────────────────────────────────────────────┘
+   * CI:  (nothing in CI mode - just ends)
+   */
+  footer(): this {
+    if (this.mode.isTTY) {
+      const fill = BOX.horizontal.repeat(this.width - 2);
+      this.lines.push(chalk.dim(BOX.bottomLeft + fill + BOX.bottomRight));
+    }
+    return this;
+  }
+
+  /**
+   * Get all rendered lines.
+   */
+  render(): string[] {
+    return [...this.lines];
+  }
+
+  /**
+   * Get the rendered output as a single string.
+   */
+  toString(): string {
+    return this.lines.join('\n');
+  }
+
+  /**
+   * Strip ANSI escape codes from a string for length calculation.
+   */
+  private stripAnsi(str: string): string {
+    // eslint-disable-next-line no-control-regex
+    return str.replace(/\x1b\[[0-9;]*m/g, '');
+  }
+}

package/src/cli/output/formatters.test.ts

@@ -0,0 +1,187 @@
+import { describe, it, expect } from 'vitest';
+import {
+  formatDuration,
+  formatLocation,
+  formatFindingCountsPlain,
+  formatProgress,
+  truncate,
+  padRight,
+  formatStatsCompact,
+  formatSeverityBadge,
+} from './formatters.js';
+import type { Severity, UsageStats } from '../../types/index.js';
+
+describe('formatDuration', () => {
+  it('formats milliseconds under 1s', () => {
+    expect(formatDuration(50)).toBe('50ms');
+    expect(formatDuration(999)).toBe('999ms');
+  });
+
+  it('formats seconds', () => {
+    expect(formatDuration(1000)).toBe('1.0s');
+    expect(formatDuration(1500)).toBe('1.5s');
+    expect(formatDuration(12345)).toBe('12.3s');
+  });
+
+  it('rounds milliseconds', () => {
+    expect(formatDuration(50.6)).toBe('51ms');
+  });
+});
+
+describe('formatLocation', () => {
+  it('formats path only', () => {
+    expect(formatLocation('src/file.ts')).toBe('src/file.ts');
+  });
+
+  it('formats path with single line', () => {
+    expect(formatLocation('src/file.ts', 10)).toBe('src/file.ts:10');
+  });
+
+  it('formats path with line range', () => {
+    expect(formatLocation('src/file.ts', 10, 20)).toBe('src/file.ts:10-20');
+  });
+
+  it('formats path with same start and end line as single line', () => {
+    expect(formatLocation('src/file.ts', 10, 10)).toBe('src/file.ts:10');
+  });
+});
+
+describe('formatFindingCountsPlain', () => {
+  it('formats zero findings', () => {
+    const counts: Record<Severity, number> = {
+      critical: 0,
+      high: 0,
+      medium: 0,
+      low: 0,
+      info: 0,
+    };
+    expect(formatFindingCountsPlain(counts)).toBe('No findings');
+  });
+
+  it('formats single finding', () => {
+    const counts: Record<Severity, number> = {
+      critical: 0,
+      high: 1,
+      medium: 0,
+      low: 0,
+      info: 0,
+    };
+    expect(formatFindingCountsPlain(counts)).toBe('1 finding (1 high)');
+  });
+
+  it('formats multiple findings', () => {
+    const counts: Record<Severity, number> = {
+      critical: 1,
+      high: 2,
+      medium: 3,
+      low: 0,
+      info: 1,
+    };
+    expect(formatFindingCountsPlain(counts)).toBe('7 findings (1 critical, 2 high, 3 medium, 1 info)');
+  });
+});
+
+describe('formatSeverityBadge', () => {
+  it('includes severity text for each level', () => {
+    expect(formatSeverityBadge('critical')).toContain('critical');
+    expect(formatSeverityBadge('high')).toContain('high');
+    expect(formatSeverityBadge('medium')).toContain('medium');
+    expect(formatSeverityBadge('low')).toContain('low');
+    expect(formatSeverityBadge('info')).toContain('info');
+  });
+});
+
+describe('formatProgress', () => {
+  it('formats progress indicator', () => {
+    // Note: formatProgress uses chalk.dim, so we just check it contains the numbers
+    const result = formatProgress(1, 5);
+    expect(result).toContain('1');
+    expect(result).toContain('5');
+  });
+});
+
+describe('truncate', () => {
+  it('returns string unchanged if shorter than max width', () => {
+    expect(truncate('hello', 10)).toBe('hello');
+  });
+
+  it('returns string unchanged if equal to max width', () => {
+    expect(truncate('hello', 5)).toBe('hello');
+  });
+
+  it('truncates and adds ellipsis if longer than max width', () => {
+    const result = truncate('hello world', 8);
+    expect(result.length).toBe(8);
+    expect(result.endsWith('…') || result.endsWith('...')).toBe(true);
+  });
+
+  it('handles very short max width', () => {
+    expect(truncate('hello', 3).length).toBe(3);
+    expect(truncate('hello', 2).length).toBe(2);
+  });
+});
+
+describe('padRight', () => {
+  it('pads string to reach width', () => {
+    expect(padRight('hi', 5)).toBe('hi   ');
+  });
+
+  it('returns string unchanged if already at width', () => {
+    expect(padRight('hello', 5)).toBe('hello');
+  });
+
+  it('returns string unchanged if longer than width', () => {
+    expect(padRight('hello', 3)).toBe('hello');
+  });
+});
+
+describe('formatStatsCompact', () => {
+  it('formats duration only', () => {
+    expect(formatStatsCompact(15800)).toBe('⏱ 15.8s');
+  });
+
+  it('formats usage only', () => {
+    const usage: UsageStats = {
+      inputTokens: 3000,
+      outputTokens: 680,
+      costUSD: 0.0048,
+    };
+    expect(formatStatsCompact(undefined, usage)).toBe('3.0k in / 680 out · $0.0048');
+  });
+
+  it('formats both duration and usage', () => {
+    const usage: UsageStats = {
+      inputTokens: 3000,
+      outputTokens: 680,
+      costUSD: 0.0048,
+    };
+    expect(formatStatsCompact(15800, usage)).toBe('⏱ 15.8s · 3.0k in / 680 out · $0.0048');
+  });
+
+  it('includes cache read tokens in input total', () => {
+    const usage: UsageStats = {
+      inputTokens: 1000,
+      cacheReadInputTokens: 2000,
+      outputTokens: 500,
+      costUSD: 0.003,
+    };
+    expect(formatStatsCompact(undefined, usage)).toBe('3.0k in / 500 out · $0.0030');
+  });
+
+  it('returns empty string when no stats provided', () => {
+    expect(formatStatsCompact()).toBe('');
+  });
+
+  it('formats milliseconds for short durations', () => {
+    expect(formatStatsCompact(500)).toBe('⏱ 500ms');
+  });
+
+  it('formats large token counts', () => {
+    const usage: UsageStats = {
+      inputTokens: 120000,
+      outputTokens: 3800,
+      costUSD: 0.0892,
+    };
+    expect(formatStatsCompact(45600, usage)).toBe('⏱ 45.6s · 120.0k in / 3.8k out · $0.09');
+  });
+});

package/src/cli/output/formatters.ts

@@ -0,0 +1,269 @@
+import chalk from 'chalk';
+import figures from 'figures';
+import type { Severity, Finding, FileChange, UsageStats } from '../../types/index.js';
+
+/**
+ * Pluralize a word based on count.
+ * @example pluralize(1, 'file') // 'file'
+ * @example pluralize(2, 'file') // 'files'
+ * @example pluralize(1, 'fix', 'fixes') // 'fix'
+ * @example pluralize(2, 'fix', 'fixes') // 'fixes'
+ */
+export function pluralize(count: number, singular: string, plural?: string): string {
+  if (count === 1) return singular;
+  return plural ?? `${singular}s`;
+}
+
+/**
+ * Format a duration in milliseconds to a human-readable string.
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) {
+    return `${Math.round(ms)}ms`;
+  }
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+/**
+ * Format an elapsed time for display (e.g., "+0.8s").
+ */
+export function formatElapsed(ms: number): string {
+  if (ms < 1000) {
+    return `+${Math.round(ms)}ms`;
+  }
+  return `+${(ms / 1000).toFixed(1)}s`;
+}
+
+/**
+ * Severity configuration for display.
+ */
+const SEVERITY_CONFIG: Record<Severity, { color: typeof chalk.red; symbol: string }> = {
+  critical: { color: chalk.red, symbol: figures.bullet },
+  high: { color: chalk.redBright, symbol: figures.bullet },
+  medium: { color: chalk.yellow, symbol: figures.bullet },
+  low: { color: chalk.green, symbol: figures.bullet },
+  info: { color: chalk.blue, symbol: figures.bullet },
+};
+
+/**
+ * Format a severity dot for terminal output.
+ */
+export function formatSeverityDot(severity: Severity): string {
+  const config = SEVERITY_CONFIG[severity];
+  return config.color(config.symbol);
+}
+
+/**
+ * Format a severity badge for terminal output (colored dot + severity text).
+ */
+export function formatSeverityBadge(severity: Severity): string {
+  const config = SEVERITY_CONFIG[severity];
+  return `${config.color(config.symbol)} ${config.color(`(${severity})`)}`;
+}
+
+/**
+ * Format a severity for plain text (CI mode).
+ */
+export function formatSeverityPlain(severity: Severity): string {
+  return `[${severity}]`;
+}
+
+/**
+ * Format a file location string.
+ */
+export function formatLocation(path: string, startLine?: number, endLine?: number): string {
+  if (!startLine) {
+    return path;
+  }
+  if (endLine && endLine !== startLine) {
+    return `${path}:${startLine}-${endLine}`;
+  }
+  return `${path}:${startLine}`;
+}
+
+/**
+ * Format a finding for terminal display.
+ */
+export function formatFindingCompact(finding: Finding): string {
+  const badge = formatSeverityBadge(finding.severity);
+  const location = finding.location
+    ? chalk.dim(formatLocation(finding.location.path, finding.location.startLine, finding.location.endLine))
+    : '';
+
+  return `${badge} ${finding.title}${location ? ` ${location}` : ''}`;
+}
+
+/**
+ * Format finding counts for display (with colored dots).
+ */
+export function formatFindingCounts(counts: Record<Severity, number>): string {
+  const total = Object.values(counts).reduce((a, b) => a + b, 0);
+
+  if (total === 0) {
+    return chalk.green('No findings');
+  }
+
+  const parts: string[] = [];
+  if (counts.critical > 0) parts.push(`${formatSeverityDot('critical')} ${counts.critical} critical`);
+  if (counts.high > 0) parts.push(`${formatSeverityDot('high')} ${counts.high} high`);
+  if (counts.medium > 0) parts.push(`${formatSeverityDot('medium')} ${counts.medium} medium`);
+  if (counts.low > 0) parts.push(`${formatSeverityDot('low')} ${counts.low} low`);
+  if (counts.info > 0) parts.push(`${formatSeverityDot('info')} ${counts.info} info`);
+
+  return `${total} finding${total === 1 ? '' : 's'}: ${parts.join('  ')}`;
+}
+
+/**
+ * Format finding counts for plain text.
+ */
+export function formatFindingCountsPlain(counts: Record<Severity, number>): string {
+  const total = Object.values(counts).reduce((a, b) => a + b, 0);
+
+  if (total === 0) {
+    return 'No findings';
+  }
+
+  const parts: string[] = [];
+  if (counts.critical > 0) parts.push(`${counts.critical} critical`);
+  if (counts.high > 0) parts.push(`${counts.high} high`);
+  if (counts.medium > 0) parts.push(`${counts.medium} medium`);
+  if (counts.low > 0) parts.push(`${counts.low} low`);
+  if (counts.info > 0) parts.push(`${counts.info} info`);
+
+  return `${total} finding${total === 1 ? '' : 's'} (${parts.join(', ')})`;
+}
+
+/**
+ * Format a progress indicator like [1/3].
+ */
+export function formatProgress(current: number, total: number): string {
+  return chalk.dim(`[${current}/${total}]`);
+}
+
+/**
+ * Format file change summary.
+ */
+export function formatFileStats(files: FileChange[]): string {
+  const added = files.filter((f) => f.status === 'added').length;
+  const modified = files.filter((f) => f.status === 'modified').length;
+  const removed = files.filter((f) => f.status === 'removed').length;
+
+  const parts: string[] = [];
+  if (added > 0) parts.push(chalk.green(`+${added}`));
+  if (modified > 0) parts.push(chalk.yellow(`~${modified}`));
+  if (removed > 0) parts.push(chalk.red(`-${removed}`));
+
+  return parts.length > 0 ? parts.join(' ') : '';
+}
+
+/**
+ * Truncate a string to fit within a width, adding ellipsis if needed.
+ */
+export function truncate(str: string, maxWidth: number): string {
+  if (str.length <= maxWidth) {
+    return str;
+  }
+  if (maxWidth <= 3) {
+    return str.slice(0, maxWidth);
+  }
+  return str.slice(0, maxWidth - 1) + figures.ellipsis;
+}
+
+/**
+ * Pad a string on the right to reach a certain width.
+ */
+export function padRight(str: string, width: number): string {
+  if (str.length >= width) {
+    return str;
+  }
+  return str + ' '.repeat(width - str.length);
+}
+
+/**
+ * Count findings by severity.
+ */
+export function countBySeverity(findings: Finding[]): Record<Severity, number> {
+  const counts: Record<Severity, number> = {
+    critical: 0,
+    high: 0,
+    medium: 0,
+    low: 0,
+    info: 0,
+  };
+
+  for (const finding of findings) {
+    counts[finding.severity]++;
+  }
+
+  return counts;
+}
+
+/**
+ * Format a USD cost for display.
+ */
+export function formatCost(costUSD: number): string {
+  if (costUSD < 0.01) {
+    return `$${costUSD.toFixed(4)}`;
+  }
+  return `$${costUSD.toFixed(2)}`;
+}
+
+/**
+ * Format token counts for display.
+ */
+export function formatTokens(tokens: number): string {
+  if (tokens >= 1_000_000) {
+    return `${(tokens / 1_000_000).toFixed(1)}M`;
+  }
+  if (tokens >= 1_000) {
+    return `${(tokens / 1_000).toFixed(1)}k`;
+  }
+  return String(tokens);
+}
+
+/**
+ * Format usage stats for terminal display.
+ */
+export function formatUsage(usage: UsageStats): string {
+  // Total input includes fresh tokens + cache reads
+  const totalInput = usage.inputTokens + (usage.cacheReadInputTokens ?? 0);
+  const inputStr = formatTokens(totalInput);
+  const outputStr = formatTokens(usage.outputTokens);
+  const costStr = formatCost(usage.costUSD);
+  return `${inputStr} in / ${outputStr} out · ${costStr}`;
+}
+
+/**
+ * Format usage stats for plain text display.
+ */
+export function formatUsagePlain(usage: UsageStats): string {
+  // Total input includes fresh tokens + cache reads
+  const totalInput = usage.inputTokens + (usage.cacheReadInputTokens ?? 0);
+  const inputStr = formatTokens(totalInput);
+  const outputStr = formatTokens(usage.outputTokens);
+  const costStr = formatCost(usage.costUSD);
+  return `${inputStr} input, ${outputStr} output, ${costStr}`;
+}
+
+/**
+ * Format stats (duration, tokens, cost) into a compact single-line format.
+ * Used for markdown footers in PR comments and check annotations.
+ *
+ * @example formatStatsCompact(15800, { inputTokens: 3000, outputTokens: 680, costUSD: 0.0048 })
+ * // Returns: "⏱ 15.8s · 3.0k in / 680 out · $0.0048"
+ */
+export function formatStatsCompact(durationMs?: number, usage?: UsageStats): string {
+  const parts: string[] = [];
+
+  if (durationMs !== undefined) {
+    parts.push(`⏱ ${formatDuration(durationMs)}`);
+  }
+
+  if (usage) {
+    const totalInput = usage.inputTokens + (usage.cacheReadInputTokens ?? 0);
+    parts.push(`${formatTokens(totalInput)} in / ${formatTokens(usage.outputTokens)} out`);
+    parts.push(formatCost(usage.costUSD));
+  }
+
+  return parts.join(' · ');
+}

package/src/cli/output/icons.ts

@@ -0,0 +1,13 @@
+/**
+ * Unicode icons for CLI output.
+ * Uses CHECK MARK (U+2713) instead of HEAVY CHECK MARK (U+2714) to avoid emoji rendering.
+ */
+
+/** Check mark for completed/success states */
+export const ICON_CHECK = '✓'; // U+2713 CHECK MARK
+
+/** Down arrow for skipped states */
+export const ICON_SKIPPED = '↓'; // U+2193 DOWNWARDS ARROW
+
+/** Braille spinner frames for loading animation */
+export const SPINNER_FRAMES = ['\u280B', '\u2819', '\u2839', '\u2838', '\u283C', '\u2834', '\u2826', '\u2827', '\u2807', '\u280F'];