@quenty/cli-output-helpers 1.10.1 → 1.11.0

package/src/reporting/composite-result-reporter.ts

@@ -0,0 +1,58 @@
+/**
+ * Fans out single-result reporting to multiple ResultReporter instances.
+ * Mirrors CompositeReporter (for batch lifecycle) but for single-result
+ * output.
+ */
+
+import type { ResultReporter } from './result-reporter.js';
+
+export class CompositeResultReporter<T = unknown> implements ResultReporter<T> {
+  private _reporters: ResultReporter<T>[];
+
+  constructor(reporters: ResultReporter<T>[]) {
+    this._reporters = reporters;
+  }
+
+  async startAsync(): Promise<void> {
+    const results = await Promise.allSettled(
+      this._reporters.map((r) => r.startAsync())
+    );
+    this._throwFirstRejection(results, 'startAsync');
+  }
+
+  onResult(result: T): void {
+    const errors: unknown[] = [];
+    for (const r of this._reporters) {
+      try {
+        r.onResult(result);
+      } catch (err) {
+        errors.push(err);
+      }
+    }
+    if (errors.length > 0) {
+      throw errors[0];
+    }
+  }
+
+  async stopAsync(): Promise<void> {
+    const results = await Promise.allSettled(
+      this._reporters.map((r) => r.stopAsync())
+    );
+    this._throwFirstRejection(results, 'stopAsync');
+  }
+
+  private _throwFirstRejection(
+    results: PromiseSettledResult<unknown>[],
+    phase: string
+  ): void {
+    const firstRejected = results.find(
+      (r): r is PromiseRejectedResult => r.status === 'rejected'
+    );
+    if (firstRejected) {
+      const reason = firstRejected.reason;
+      throw reason instanceof Error
+        ? reason
+        : new Error(`Reporter ${phase} failed: ${String(reason)}`);
+    }
+  }
+}

package/src/reporting/file-result-reporter.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const { mockWriteFileSync } = vi.hoisted(() => ({
+  mockWriteFileSync: vi.fn(),
+}));
+
+vi.mock('fs', () => ({
+  writeFileSync: mockWriteFileSync,
+}));
+
+vi.mock('child_process', () => ({
+  execSync: vi.fn(),
+}));
+
+import { FileResultReporter } from './file-result-reporter.js';
+
+describe('FileResultReporter', () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let stderrSpy: any;
+
+  beforeEach(() => {
+    mockWriteFileSync.mockReset();
+    stderrSpy = vi
+      .spyOn(process.stderr, 'write')
+      .mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    stderrSpy.mockRestore();
+  });
+
+  it('writes rendered text to the output path with utf-8 encoding', () => {
+    const reporter = new FileResultReporter<{ msg: string }>({
+      outputPath: '/tmp/out.txt',
+      render: (r) => r.msg,
+    });
+
+    reporter.onResult({ msg: 'hello' });
+
+    expect(mockWriteFileSync).toHaveBeenCalledWith(
+      '/tmp/out.txt',
+      'hello',
+      'utf-8'
+    );
+  });
+
+  it('writes a Buffer when binary callback returns one', () => {
+    const buf = Buffer.from([1, 2, 3]);
+    const reporter = new FileResultReporter<{ b: Buffer }>({
+      outputPath: '/tmp/out.bin',
+      render: () => 'fallback',
+      binary: (r) => r.b,
+    });
+
+    reporter.onResult({ b: buf });
+
+    expect(mockWriteFileSync).toHaveBeenCalledWith('/tmp/out.bin', buf);
+  });
+
+  it('reports "binary output" status for binary writes', () => {
+    const reporter = new FileResultReporter<{ b: Buffer }>({
+      outputPath: '/tmp/out.bin',
+      render: () => '',
+      binary: (r) => r.b,
+    });
+
+    reporter.onResult({ b: Buffer.from([0]) });
+
+    expect(stderrSpy).toHaveBeenCalledWith(
+      'Wrote binary output to /tmp/out.bin\n'
+    );
+  });
+
+  it('falls back to text render when binary returns undefined', () => {
+    const reporter = new FileResultReporter<{ b?: Buffer }>({
+      outputPath: '/tmp/out.txt',
+      render: () => 'text',
+      binary: () => undefined,
+    });
+
+    reporter.onResult({});
+
+    expect(mockWriteFileSync).toHaveBeenCalledWith(
+      '/tmp/out.txt',
+      'text',
+      'utf-8'
+    );
+  });
+
+  it('emits a status line to stderr by default', () => {
+    const reporter = new FileResultReporter<unknown>({
+      outputPath: '/tmp/out.txt',
+      render: () => '',
+    });
+
+    reporter.onResult(null);
+
+    expect(stderrSpy).toHaveBeenCalledWith('Wrote output to /tmp/out.txt\n');
+  });
+
+  it('suppresses status when reportPath is false', () => {
+    const reporter = new FileResultReporter<unknown>({
+      outputPath: '/tmp/out.txt',
+      render: () => '',
+      reportPath: false,
+    });
+
+    reporter.onResult(null);
+
+    expect(stderrSpy).not.toHaveBeenCalled();
+  });
+});

package/src/reporting/file-result-reporter.ts

@@ -0,0 +1,75 @@
+/**
+ * Writes a rendered result to a file. Each onResult overwrites the file —
+ * usable for both single writes and watch-mode file rewrites.
+ *
+ * Optional `binary` callback returns a Buffer to write instead of the
+ * rendered text — used for screenshot/binary output.
+ */
+
+import * as fs from 'fs';
+import { execFileSync } from 'child_process';
+import { BaseResultReporter } from './result-reporter.js';
+
+export interface FileResultReporterOptions<T> {
+  outputPath: string;
+  render: (result: T) => string;
+  /** If provided and returns a Buffer, write that instead of the rendered text. */
+  binary?: (result: T) => Buffer | undefined;
+  /** Open the file with the platform's default viewer after the first write. */
+  open?: boolean;
+  /** Print a "Wrote output to <path>" status to stderr after each write. */
+  reportPath?: boolean;
+}
+
+export class FileResultReporter<T = unknown> extends BaseResultReporter<T> {
+  private _outputPath: string;
+  private _render: (result: T) => string;
+  private _binary?: (result: T) => Buffer | undefined;
+  private _open: boolean;
+  private _reportPath: boolean;
+  private _hasOpened = false;
+
+  constructor(options: FileResultReporterOptions<T>) {
+    super();
+    this._outputPath = options.outputPath;
+    this._render = options.render;
+    this._binary = options.binary;
+    this._open = options.open ?? false;
+    this._reportPath = options.reportPath ?? true;
+  }
+
+  override onResult(result: T): void {
+    const buffer = this._binary?.(result);
+    const isBinary = buffer !== undefined;
+    if (isBinary) {
+      fs.writeFileSync(this._outputPath, buffer);
+    } else {
+      fs.writeFileSync(this._outputPath, this._render(result), 'utf-8');
+    }
+
+    if (this._reportPath) {
+      const label = isBinary ? 'binary output' : 'output';
+      process.stderr.write(`Wrote ${label} to ${this._outputPath}\n`);
+    }
+
+    if (this._open && !this._hasOpened) {
+      this._hasOpened = true;
+      tryOpenFile(this._outputPath);
+    }
+  }
+}
+
+/** Best-effort open a file with the platform's default viewer. */
+function tryOpenFile(filePath: string): void {
+  try {
+    if (process.platform === 'win32') {
+      // `start` is a cmd builtin; the empty "" is the window title slot
+      execFileSync('cmd', ['/c', 'start', '""', filePath], { stdio: 'ignore' });
+    } else {
+      const cmd = process.platform === 'darwin' ? 'open' : 'xdg-open';
+      execFileSync(cmd, [filePath], { stdio: 'ignore' });
+    }
+  } catch {
+    // Fire-and-forget — don't fail the command if open doesn't work
+  }
+}

package/src/reporting/format-json.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { formatJson } from './format-json.js';
+
+describe('formatJson', () => {
+  const originalIsTTY = process.stdout.isTTY;
+
+  afterEach(() => {
+    process.stdout.isTTY = originalIsTTY;
+  });
+
+  it('pretty-prints with indentation when pretty: true', () => {
+    const result = formatJson({ a: 1, b: [2, 3] }, { pretty: true });
+    expect(result).toBe(JSON.stringify({ a: 1, b: [2, 3] }, null, 2));
+    expect(result).toContain('\n');
+  });
+
+  it('emits compact single-line JSON when pretty: false', () => {
+    const result = formatJson({ a: 1, b: [2, 3] }, { pretty: false });
+    expect(result).toBe('{"a":1,"b":[2,3]}');
+    expect(result).not.toContain('\n');
+  });
+
+  it('explicit pretty: true overrides non-TTY', () => {
+    process.stdout.isTTY = undefined as any;
+    const result = formatJson({ x: 1 }, { pretty: true });
+    expect(result).toContain('\n');
+  });
+
+  it('explicit pretty: false overrides TTY', () => {
+    process.stdout.isTTY = true;
+    const result = formatJson({ x: 1 }, { pretty: false });
+    expect(result).not.toContain('\n');
+  });
+});

package/src/reporting/format-json.ts

@@ -0,0 +1,16 @@
+/**
+ * JSON output formatter. Pretty-prints when connected to a TTY,
+ * emits compact JSON when piped.
+ */
+
+export interface JsonOutputOptions {
+  pretty?: boolean;
+}
+
+export function formatJson(data: unknown, options?: JsonOutputOptions): string {
+  const pretty = options?.pretty ?? (process.stdout.isTTY ? true : false);
+  if (pretty) {
+    return JSON.stringify(data, null, 2);
+  }
+  return JSON.stringify(data);
+}

package/src/reporting/format-table.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect } from 'vitest';
+import { formatTable, type TableColumn } from './format-table.js';
+
+interface TestRow {
+  name: string;
+  value: number;
+}
+
+const basicColumns: TableColumn<TestRow>[] = [
+  { header: 'Name', value: (r) => r.name },
+  { header: 'Value', value: (r) => String(r.value) },
+];
+
+describe('formatTable', () => {
+  it('renders a basic table with 2 columns and 2 rows', () => {
+    const rows: TestRow[] = [
+      { name: 'alpha', value: 10 },
+      { name: 'beta', value: 200 },
+    ];
+
+    const result = formatTable(rows, basicColumns);
+    const lines = result.split('\n');
+
+    expect(lines).toHaveLength(4); // header + separator + 2 data rows
+    expect(lines[0]).toContain('Name');
+    expect(lines[0]).toContain('Value');
+    expect(lines[1]).toMatch(/^-+\s+-+$/);
+    expect(lines[2]).toContain('alpha');
+    expect(lines[3]).toContain('beta');
+  });
+
+  it('returns empty string for empty rows', () => {
+    expect(formatTable([], basicColumns)).toBe('');
+  });
+
+  it('handles ANSI color codes in values without breaking alignment', () => {
+    const rows = [
+      { name: '\x1b[32mgreen\x1b[0m', value: 1 },
+      { name: 'plain', value: 2 },
+    ];
+
+    const result = formatTable(rows, basicColumns);
+    const lines = result.split('\n');
+
+    // Both data rows should produce the same visible width for the Name column.
+    // The ANSI-colored row should have padding based on visible "green" (5 chars),
+    // not the full escape-code string length.
+    const stripAnsi = (s: string) => s.replace(/\x1b\[[0-9;]*m/g, '');
+    const dataLine0 = stripAnsi(lines[2]);
+    const dataLine1 = stripAnsi(lines[3]);
+
+    // Split by double-space to find column boundary
+    const col0Width0 = dataLine0.indexOf('1');
+    const col0Width1 = dataLine1.indexOf('2');
+    expect(col0Width0).toBe(col0Width1);
+  });
+
+  it('right-aligns by padding on the left', () => {
+    const columns: TableColumn<TestRow>[] = [
+      { header: 'Name', value: (r) => r.name },
+      { header: 'Value', value: (r) => String(r.value), align: 'right' },
+    ];
+    const rows: TestRow[] = [
+      { name: 'a', value: 1 },
+      { name: 'b', value: 200 },
+    ];
+
+    const result = formatTable(rows, columns);
+    const lines = result.split('\n');
+
+    // The header "Value" is 5 chars wide; data "1" should be padded to "    1" or similar
+    // In the first data row, the value column should end with '1' preceded by spaces
+    const dataLine = lines[2];
+    // Right-aligned: the value "1" should appear at the right edge of the value column
+    expect(dataLine).toMatch(/\s+1$/);
+  });
+
+  it('applies custom indent to every line', () => {
+    const rows: TestRow[] = [{ name: 'x', value: 1 }];
+    const result = formatTable(rows, basicColumns, { indent: '    ' });
+    const lines = result.split('\n');
+
+    for (const line of lines) {
+      expect(line.startsWith('    ')).toBe(true);
+    }
+  });
+
+  it('respects minWidth', () => {
+    const columns: TableColumn<TestRow>[] = [
+      { header: 'N', value: (r) => r.name, minWidth: 20 },
+      { header: 'V', value: (r) => String(r.value) },
+    ];
+    const rows: TestRow[] = [{ name: 'a', value: 1 }];
+
+    const result = formatTable(rows, columns);
+    const lines = result.split('\n');
+
+    // The separator dashes for the first column should be at least 20 chars
+    const separatorParts = lines[1].split('  ');
+    expect(separatorParts[0].length).toBeGreaterThanOrEqual(20);
+  });
+
+  it('applies format function to cell values', () => {
+    const columns: TableColumn<TestRow>[] = [
+      { header: 'Name', value: (r) => r.name, format: (v) => `[${v}]` },
+      { header: 'Value', value: (r) => String(r.value) },
+    ];
+    const rows: TestRow[] = [{ name: 'test', value: 42 }];
+
+    const result = formatTable(rows, columns);
+    expect(result).toContain('[test]');
+  });
+});

package/src/reporting/format-table.ts

@@ -0,0 +1,97 @@
+/**
+ * Generic table formatter for CLI output. Computes column widths from data,
+ * handles ANSI color codes in values, and supports left/right alignment.
+ */
+
+export interface TableColumn<T> {
+  header: string;
+  value: (row: T) => string;
+  minWidth?: number;
+  align?: 'left' | 'right';
+  format?: (value: string, row: T) => string;
+}
+
+export interface TableOptions {
+  showHeaders?: boolean;
+  showSeparator?: boolean;
+  indent?: string;
+}
+
+/** Strip ANSI escape codes so width calculations reflect visible characters. */
+function stripAnsi(text: string): string {
+  return text.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+function padCell(text: string, width: number, align: 'left' | 'right'): string {
+  const visibleLength = stripAnsi(text).length;
+  const padding = Math.max(0, width - visibleLength);
+  if (align === 'right') {
+    return ' '.repeat(padding) + text;
+  }
+  return text + ' '.repeat(padding);
+}
+
+export function formatTable<T>(
+  rows: T[],
+  columns: TableColumn<T>[],
+  options?: TableOptions
+): string {
+  if (rows.length === 0) {
+    return '';
+  }
+
+  const showHeaders = options?.showHeaders ?? true;
+  const showSeparator = options?.showSeparator ?? true;
+  const indent = options?.indent ?? '';
+
+  // Pre-compute raw string values for every cell
+  const cellValues: string[][] = rows.map((row) =>
+    columns.map((col) => col.value(row))
+  );
+
+  // Compute column widths
+  const widths = columns.map((col, colIndex) => {
+    const headerWidth = col.header.length;
+    const minWidth = col.minWidth ?? 0;
+    const maxDataWidth = cellValues.reduce(
+      (max, rowValues) => Math.max(max, stripAnsi(rowValues[colIndex]).length),
+      0
+    );
+    return Math.max(headerWidth, minWidth, maxDataWidth);
+  });
+
+  const lines: string[] = [];
+
+  // Header row
+  if (showHeaders) {
+    const headerCells = columns.map((col, i) =>
+      padCell(col.header, widths[i], col.align ?? 'left')
+    );
+    lines.push(headerCells.join('  '));
+  }
+
+  // Separator row
+  if (showSeparator && showHeaders) {
+    const separatorCells = widths.map((w) => '-'.repeat(w));
+    lines.push(separatorCells.join('  '));
+  }
+
+  // Data rows
+  for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
+    const row = rows[rowIndex];
+    const cells = columns.map((col, colIndex) => {
+      let value = cellValues[rowIndex][colIndex];
+      if (col.format) {
+        value = col.format(value, row);
+      }
+      return padCell(value, widths[colIndex], col.align ?? 'left');
+    });
+    lines.push(cells.join('  '));
+  }
+
+  if (indent) {
+    return lines.map((line) => indent + line).join('\n');
+  }
+
+  return lines.join('\n');
+}

package/src/reporting/github/annotations.test.ts

@@ -47,9 +47,7 @@ describe('formatAnnotation', () => {
   });
 
   it('escapes special characters in properties', () => {
-    const result = formatAnnotation(
-      makeDiagnostic({ title: 'a:b,c' })
-    );
+    const result = formatAnnotation(makeDiagnostic({ title: 'a:b,c' }));
     expect(result).toContain('title=a%3Ab%2Cc');
   });
 

package/src/reporting/github/annotations.ts

@@ -52,10 +52,7 @@ function _escapeProperty(value: string): string {
 
 /** Escape a workflow command message (data portion). */
 function _escapeMessage(value: string): string {
-  return value
-    .replace(/%/g, '%25')
-    .replace(/\r/g, '%0D')
-    .replace(/\n/g, '%0A');
+  return value.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
 }
 
 // ── Annotation emission ─────────────────────────────────────────────────────
@@ -153,12 +150,12 @@ export function formatAnnotationSummaryMarkdown(
     );
   }
   if (summary.notices > 0) {
-    parts.push(
-      `${summary.notices} notice${summary.notices !== 1 ? 's' : ''}`
-    );
+    parts.push(`${summary.notices} notice${summary.notices !== 1 ? 's' : ''}`);
   }
 
-  md += `**${summary.total} issue${summary.total !== 1 ? 's' : ''}** across ${summary.fileCount} file${summary.fileCount !== 1 ? 's' : ''}: ${parts.join(', ')}\n\n`;
+  md += `**${summary.total} issue${summary.total !== 1 ? 's' : ''}** across ${
+    summary.fileCount
+  } file${summary.fileCount !== 1 ? 's' : ''}: ${parts.join(', ')}\n\n`;
 
   // Group diagnostics by file
   const byFile = new Map<string, Diagnostic[]>();
@@ -189,14 +186,16 @@ export function formatAnnotationSummaryMarkdown(
         d.severity === 'error'
           ? '`error`'
           : d.severity === 'warning'
-            ? '`warning`'
-            : '`notice`';
+          ? '`warning`'
+          : '`notice`';
       const escapedMsg = d.message.replace(/\|/g, '\\|').replace(/\n/g, ' ');
       md += `| ${d.line} | ${sev} | ${escapedMsg} |\n`;
     }
 
     if (diags.length > MAX_PER_FILE) {
-      md += `\n_... and ${diags.length - MAX_PER_FILE} more issue(s) in this file_\n`;
+      md += `\n_... and ${
+        diags.length - MAX_PER_FILE
+      } more issue(s) in this file_\n`;
     }
 
     md += '\n</details>\n\n';
@@ -226,7 +225,9 @@ export async function writeAnnotationSummaryAsync(
     OutputHelper.info('Written lint results to GitHub job summary.');
   } catch (err) {
     OutputHelper.warn(
-      `Failed to write job summary: ${err instanceof Error ? err.message : String(err)}`
+      `Failed to write job summary: ${
+        err instanceof Error ? err.message : String(err)
+      }`
     );
   }
 }

package/src/reporting/github/comment-table-reporter.ts

@@ -80,14 +80,14 @@ export class GithubCommentTableReporter extends BaseReporter {
     this._scheduleUpdate();
   }
 
-  override onPackagePhaseChange(
-    _name: string,
-    _phase: PackageStatus
-  ): void {
+  override onPackagePhaseChange(_name: string, _phase: PackageStatus): void {
     this._scheduleUpdate();
   }
 
-  override onPackageProgressUpdate(_name: string, _progress: ProgressSummary): void {
+  override onPackageProgressUpdate(
+    _name: string,
+    _progress: ProgressSummary
+  ): void {
     this._scheduleUpdate();
   }
 

package/src/reporting/github/job-summary-reporter.ts

@@ -79,7 +79,9 @@ export class GithubJobSummaryReporter extends BaseReporter {
       OutputHelper.info('Written results to GitHub job summary.');
     } catch (err) {
       OutputHelper.warn(
-        `Failed to write job summary: ${err instanceof Error ? err.message : String(err)}`
+        `Failed to write job summary: ${
+          err instanceof Error ? err.message : String(err)
+        }`
       );
     }
   }

package/src/reporting/grouped-reporter.ts

@@ -77,11 +77,15 @@ export class GroupedReporter extends BaseReporter {
     const empty = isEmptyTestRun(result.progressSummary);
 
     if (result.success) {
-      const label = progressText ? `${successLabel} ${progressText}` : successLabel;
+      const label = progressText
+        ? `${successLabel} ${progressText}`
+        : successLabel;
       const formatted = empty
         ? OutputHelper.formatWarning(`${label} ⚠`)
         : OutputHelper.formatSuccess(label);
-      const icon = empty ? OutputHelper.formatWarning('⚠') : OutputHelper.formatSuccess('✓');
+      const icon = empty
+        ? OutputHelper.formatWarning('⚠')
+        : OutputHelper.formatSuccess('✓');
       console.log(
         `  ${icon} ${formatted} ${OutputHelper.formatDim(`(${duration})`)}`
       );

package/src/reporting/index.ts

@@ -1,4 +1,4 @@
-// Core types and base class
+// Core types and base class — batch lifecycle (multi-package, phases, progress).
 export {
   BaseReporter,
   type Reporter,
@@ -12,6 +12,39 @@ export {
   type StepProgress,
 } from './reporter.js';
 
+// Single-result reporter — for one-shot or polled command output.
+export { BaseResultReporter, type ResultReporter } from './result-reporter.js';
+export {
+  StdoutResultReporter,
+  type StdoutResultReporterOptions,
+} from './stdout-result-reporter.js';
+export {
+  FileResultReporter,
+  type FileResultReporterOptions,
+} from './file-result-reporter.js';
+export {
+  WatchResultReporter,
+  type WatchResultReporterOptions,
+} from './watch-result-reporter.js';
+export { CompositeResultReporter } from './composite-result-reporter.js';
+export {
+  buildResultReporter,
+  type BuildResultReporterOptions,
+} from './build-result-reporter.js';
+
+// Output formatting primitives.
+export {
+  formatTable,
+  type TableColumn,
+  type TableOptions,
+} from './format-table.js';
+export { formatJson, type JsonOutputOptions } from './format-json.js';
+export {
+  createWatchRenderer,
+  type WatchRenderer,
+  type WatchRendererOptions,
+} from './watch-renderer.js';
+
 // Progress formatting helpers
 export {
   formatProgressInline,