@quenty/cli-output-helpers 1.9.0 → 1.10.1

package/src/reporting/index.ts

@@ -6,8 +6,20 @@ export {
   type PackageStatus,
   type PackageResult,
   type BatchSummary,
+  type ProgressSummary,
+  type TestCountProgress,
+  type ByteProgress,
+  type StepProgress,
 } from './reporter.js';
 
+// Progress formatting helpers
+export {
+  formatProgressInline,
+  formatProgressResult,
+  isEmptyTestRun,
+  summarizeFailure,
+} from './progress-format.js';
+
 // State tracking
 export {
   type IStateTracker,

package/src/reporting/progress-format.ts

@@ -0,0 +1,97 @@
+/**
+ * Formatting helpers for ProgressSummary values.
+ */
+
+import { type ProgressSummary, type JobPhase } from './reporter.js';
+
+/**
+ * Format progress for inline display in spinners and running status.
+ * Returns empty string when progress is undefined.
+ *
+ * - test-counts: "(5/23)"
+ * - bytes: "12.3 MB" or "45%"
+ * - steps: "(3/10)"
+ */
+export function formatProgressInline(progress?: ProgressSummary): string {
+  if (!progress) return '';
+
+  switch (progress.kind) {
+    case 'test-counts':
+      return `(${progress.passed}/${progress.total})`;
+    case 'bytes':
+      if (progress.totalBytes > 0 && progress.transferredBytes > 0) {
+        return `(${_formatBytes(progress.transferredBytes)}/${_formatBytes(progress.totalBytes)})`;
+      }
+      return `(${_formatBytes(progress.totalBytes)})`;
+    case 'steps':
+      if (progress.total > 0) {
+        return `(${progress.completed}/${progress.total})`;
+      }
+      // Indeterminate: show label or just the count
+      return progress.label ? `(${progress.label})` : `(${progress.completed})`;
+  }
+}
+
+/**
+ * Format progress for final result display (passed/failed lines).
+ * Returns empty string when progress is undefined.
+ *
+ * - test-counts: "(23/100)" or "(0/0)"
+ * - bytes: "(12.3 MB)"
+ * - steps: "(3/10)"
+ */
+export function formatProgressResult(progress?: ProgressSummary): string {
+  if (!progress) return '';
+
+  switch (progress.kind) {
+    case 'test-counts':
+      return `(${progress.passed}/${progress.total})`;
+    case 'bytes':
+      return `(${_formatBytes(progress.totalBytes)})`;
+    case 'steps':
+      return `(${progress.completed}/${progress.total})`;
+  }
+}
+
+/** True when progress is test-counts with total === 0. */
+export function isEmptyTestRun(progress?: ProgressSummary): boolean {
+  return progress?.kind === 'test-counts' && progress.total === 0;
+}
+
+/**
+ * Condense a raw error string and optional failedPhase into a short one-liner.
+ *
+ * Examples:
+ *   summarizeFailure("Upload failed: 409 Conflict: {...}", "uploading")
+ *     → "at uploading: Upload failed (409)"
+ *   summarizeFailure("timeout after 120s", "executing")
+ *     → "at executing: timeout after 120s"
+ */
+export function summarizeFailure(
+  error?: string,
+  failedPhase?: JobPhase
+): string {
+  const parts: string[] = [];
+
+  if (failedPhase) {
+    parts.push(`at ${failedPhase}`);
+  }
+
+  if (error) {
+    const firstLine = error.split('\n')[0];
+    const short = firstLine.length > 60 ? firstLine.slice(0, 57) + '...' : firstLine;
+    if (parts.length > 0) {
+      parts.push(`: ${short}`);
+    } else {
+      parts.push(short);
+    }
+  }
+
+  return parts.join('');
+}
+
+function _formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

package/src/reporting/reporter.ts

@@ -6,11 +6,38 @@
  */
 
 /** Execution phases a package can move through. */
-export type JobPhase = 'building' | 'downloading' | 'merging' | 'uploading' | 'scheduling' | 'launching' | 'connecting' | 'executing';
+export type JobPhase = 'waiting' | 'building' | 'downloading' | 'merging' | 'combining' | 'uploading' | 'scheduling' | 'launching' | 'connecting' | 'executing';
 
 /** Unified status for a package moving through the job lifecycle. */
 export type PackageStatus = 'pending' | JobPhase | 'passed' | 'failed';
 
+// ── Progress summary types ─────────────────────────────────────────────────
+
+/** Test count progress: "23/100 passed" */
+export interface TestCountProgress {
+  kind: 'test-counts';
+  passed: number;
+  failed: number;
+  total: number;
+}
+
+/** Byte-level transfer progress: "45% of 12.3 MB" */
+export interface ByteProgress {
+  kind: 'bytes';
+  transferredBytes: number;
+  totalBytes: number;
+}
+
+/** Generic step progress: "3/10 packages" */
+export interface StepProgress {
+  kind: 'steps';
+  completed: number;
+  total: number;
+  label?: string;
+}
+
+export type ProgressSummary = TestCountProgress | ByteProgress | StepProgress;
+
 /** Result for a single package in a batch run. */
 export interface PackageResult {
   packageName: string;
@@ -18,6 +45,8 @@ export interface PackageResult {
   logs: string;
   durationMs: number;
   error?: string;
+  progressSummary?: ProgressSummary;
+  failedPhase?: JobPhase;
 }
 
 /** Summary of a complete batch run. */
@@ -47,6 +76,9 @@ export interface Reporter {
   /** Called when a package transitions phases (building, uploading, executing, etc). */
   onPackagePhaseChange(packageName: string, phase: JobPhase): void;
 
+  /** Called when a package's in-progress metrics update (high-frequency). */
+  onPackageProgressUpdate(packageName: string, progress: ProgressSummary): void;
+
   /** Called when a single package job completes. */
   onPackageResult(result: PackageResult, bufferedOutput?: string[]): void;
 
@@ -62,6 +94,7 @@ export class BaseReporter implements Reporter {
   async startAsync(): Promise<void> {}
   onPackageStart(_packageName: string): void {}
   onPackagePhaseChange(_packageName: string, _phase: JobPhase): void {}
+  onPackageProgressUpdate(_packageName: string, _progress: ProgressSummary): void {}
   onPackageResult(_result: PackageResult, _bufferedOutput?: string[]): void {}
   async stopAsync(): Promise<void> {}
 }

package/src/reporting/simple-reporter.ts

@@ -1,6 +1,7 @@
 import { OutputHelper } from '../outputHelper.js';
 import { type PackageResult, BaseReporter } from './reporter.js';
 import { type IStateTracker } from './state/state-tracker.js';
+import { formatProgressResult } from './progress-format.js';
 
 export interface SimpleReporterOptions {
   alwaysShowLogs: boolean;
@@ -37,8 +38,10 @@ export class SimpleReporter extends BaseReporter {
       OutputHelper.info('(no output)');
     }
 
+    const progressText = formatProgressResult(result.progressSummary);
     if (result.success) {
-      OutputHelper.info(this._successMessage);
+      const msg = progressText ? `${this._successMessage} ${progressText}` : this._successMessage;
+      OutputHelper.info(msg);
     } else {
       OutputHelper.error(this._failureMessage);
     }

package/src/reporting/spinner-reporter.ts

@@ -2,6 +2,7 @@ import { OutputHelper } from '../outputHelper.js';
 import { formatDurationMs } from '../cli-utils.js';
 import { type PackageResult, BaseReporter } from './reporter.js';
 import { type IStateTracker } from './state/state-tracker.js';
+import { formatProgressInline, formatProgressResult, isEmptyTestRun } from './progress-format.js';
 
 export interface SpinnerReporterOptions {
   showLogs: boolean;
@@ -17,7 +18,9 @@ const SPINNER_FRAMES = ['◐', '◓', '◑', '◒'];
 
 /** Emoji + label for each active phase in the spinner. */
 const PHASE_LABELS: Record<string, string> = {
+  waiting: '◇ Waiting',
   building: '⚙ Building',
+  combining: '🔗 Combining',
   uploading: '▲ Uploading',
   scheduling: '◇ Scheduling',
   launching: '🚀 Launching',
@@ -164,22 +167,31 @@ export class SpinnerReporter extends BaseReporter {
         )} ${statusText}`;
       } else if (phaseLabel) {
         const icon = OutputHelper.formatInfo(spinner);
-        const statusText = OutputHelper.formatInfo(phaseLabel);
-        line = `  ${icon} ${state.name.padEnd(30)} ${statusText.padEnd(
-          22
-        )} ${OutputHelper.formatDim(time)}`;
+        const progressText = formatProgressInline(state.progress);
+        const plain = progressText
+          ? `${phaseLabel} ${progressText}`
+          : phaseLabel;
+        const statusText = OutputHelper.formatInfo(plain.padEnd(22));
+        line = `  ${icon} ${state.name.padEnd(30)} ${statusText} ${OutputHelper.formatDim(time)}`;
       } else if (state.status === 'passed') {
         const icon = OutputHelper.formatSuccess('✓');
-        const statusText = OutputHelper.formatSuccess(this._options.successLabel ?? 'Passed');
-        line = `  ${icon} ${state.name.padEnd(30)} ${statusText.padEnd(
-          20
-        )} ${OutputHelper.formatDim(time)}`;
+        const progressText = formatProgressResult(state.result?.progressSummary);
+        const label = this._options.successLabel ?? 'Passed';
+        const empty = isEmptyTestRun(state.result?.progressSummary);
+        let plain = progressText ? `${label} ${progressText}` : label;
+        if (empty) plain += ' ⚠';
+        const statusText = empty
+          ? OutputHelper.formatWarning(plain.padEnd(22))
+          : OutputHelper.formatSuccess(plain.padEnd(22));
+        line = `  ${icon} ${state.name.padEnd(30)} ${statusText} ${OutputHelper.formatDim(time)}`;
       } else {
         const icon = OutputHelper.formatError('✗');
-        const statusText = OutputHelper.formatError(this._options.failureLabel ?? 'FAILED');
-        line = `  ${icon} ${state.name.padEnd(30)} ${statusText.padEnd(
-          20
-        )} ${OutputHelper.formatDim(time)}`;
+        const failedPhase = state.result?.failedPhase;
+        const plain = failedPhase
+          ? `${this._options.failureLabel ?? 'FAILED'} at ${failedPhase}`
+          : (this._options.failureLabel ?? 'FAILED');
+        const statusText = OutputHelper.formatError(plain.padEnd(22));
+        line = `  ${icon} ${state.name.padEnd(30)} ${statusText} ${OutputHelper.formatDim(time)}`;
       }
 
       lines.push(line);

package/src/reporting/state/live-state-tracker.ts

@@ -1,4 +1,4 @@
-import { type PackageResult, type JobPhase, BaseReporter } from '../reporter.js';
+import { type PackageResult, type PackageStatus, type JobPhase, type ProgressSummary, BaseReporter } from '../reporter.js';
 import { type IStateTracker, type PackageState } from './state-tracker.js';
 
 export type { PackageState } from './state-tracker.js';
@@ -54,6 +54,10 @@ export class LiveStateTracker
     return this._failures;
   }
 
+  getCurrentPhase(name: string): PackageStatus | undefined {
+    return this._packages.get(name)?.status;
+  }
+
   override async startAsync(): Promise<void> {
     this._startTimeMs = Date.now();
   }
@@ -68,7 +72,15 @@ export class LiveStateTracker
   override onPackagePhaseChange(name: string, phase: JobPhase): void {
     const state = this._packages.get(name);
     if (!state) return;
+    if (state.status === 'passed' || state.status === 'failed') return; // don't regress terminal states
     state.status = phase;
+    state.progress = undefined; // clear progress on phase transition
+  }
+
+  override onPackageProgressUpdate(name: string, progress: ProgressSummary): void {
+    const state = this._packages.get(name);
+    if (!state) return;
+    state.progress = progress;
   }
 
   override onPackageResult(
@@ -82,6 +94,9 @@ export class LiveStateTracker
     state.durationMs = result.durationMs;
     state.result = result;
     state.bufferedOutput = bufferedOutput;
+    if (result.progressSummary) {
+      state.progress = result.progressSummary;
+    }
     this._completed++;
 
     this._allResults.push(result);

package/src/reporting/state/loaded-state-tracker.ts

@@ -1,6 +1,7 @@
 import * as fs from 'fs/promises';
 import {
   type PackageResult,
+  type PackageStatus,
   type BatchSummary,
 } from '../reporter.js';
 import {
@@ -48,6 +49,7 @@ export class LoadedStateTracker implements IStateTracker {
         status: result.success ? 'passed' : 'failed',
         durationMs: result.durationMs,
         result,
+        progress: result.progressSummary,
       });
       if (!result.success) {
         failures.push(result);
@@ -92,4 +94,8 @@ export class LoadedStateTracker implements IStateTracker {
   getFailures(): PackageResult[] {
     return this._failures;
   }
+
+  getCurrentPhase(name: string): PackageStatus | undefined {
+    return this._packages.get(name)?.status;
+  }
 }

package/src/reporting/state/state-tracker.ts

@@ -1,4 +1,4 @@
-import { type PackageResult, type PackageStatus } from '../reporter.js';
+import { type PackageResult, type PackageStatus, type ProgressSummary } from '../reporter.js';
 
 export interface PackageState {
   name: string;
@@ -7,6 +7,7 @@ export interface PackageState {
   durationMs?: number;
   result?: PackageResult;
   bufferedOutput?: string[];
+  progress?: ProgressSummary;
 }
 
 /**
@@ -21,4 +22,5 @@ export interface IStateTracker {
   getAllPackages(): PackageState[];
   getResults(): PackageResult[];
   getFailures(): PackageResult[];
+  getCurrentPhase(name: string): PackageStatus | undefined;
 }

package/src/reporting/summary-table-reporter.ts

@@ -2,6 +2,7 @@ import { OutputHelper } from '../outputHelper.js';
 import { formatDurationMs } from '../cli-utils.js';
 import { BaseReporter } from './reporter.js';
 import { type IStateTracker } from './state/state-tracker.js';
+import { formatProgressResult, isEmptyTestRun } from './progress-format.js';
 
 export interface SummaryTableReporterOptions {
   /** Label for successful results in the table. Default: "Passed" */
@@ -38,18 +39,43 @@ export class SummaryTableReporter extends BaseReporter {
     const passed = results.length - failures.length;
     const durationMs = Date.now() - this._state.startTimeMs;
 
+    const STATUS_WIDTH = 26;
+
     console.log('');
-    console.log('Package'.padEnd(40) + 'Status'.padEnd(10) + 'Duration');
-    console.log('-'.repeat(60));
+    console.log('Package'.padEnd(40) + 'Status'.padEnd(STATUS_WIDTH) + 'Duration');
+    console.log('─'.repeat(40 + STATUS_WIDTH + 8));
 
+    let emptyRunCount = 0;
     for (const result of results) {
-      const status = result.success
-        ? OutputHelper.formatSuccess(this._successLabel)
-        : OutputHelper.formatError(this._failureLabel);
+      const progressText = formatProgressResult(result.progressSummary);
+      const empty = isEmptyTestRun(result.progressSummary);
+      if (empty) emptyRunCount++;
+
+      let label: string;
+      if (result.success) {
+        label = progressText ? `${this._successLabel} ${progressText}` : this._successLabel;
+      } else {
+        const failedPhase = result.failedPhase;
+        label = failedPhase
+          ? `${this._failureLabel} at ${failedPhase}`
+          : this._failureLabel;
+      }
+
+      // Pad the plain text BEFORE wrapping in ANSI so padEnd counts visible chars
+      const paddedLabel = label.padEnd(STATUS_WIDTH);
+      let status: string;
+      if (result.success) {
+        status = empty
+          ? OutputHelper.formatWarning(paddedLabel)
+          : OutputHelper.formatSuccess(paddedLabel);
+      } else {
+        status = OutputHelper.formatError(paddedLabel);
+      }
+
       const duration = OutputHelper.formatDim(
         formatDurationMs(result.durationMs)
       );
-      console.log(result.packageName.padEnd(40) + status.padEnd(20) + duration);
+      console.log(result.packageName.padEnd(40) + status + duration);
     }
 
     console.log('');
@@ -64,5 +90,13 @@ export class SummaryTableReporter extends BaseReporter {
     console.log(
       `${results.length} ${this._summaryVerb}, ${passedText}, ${failedText} ${totalTime}`
     );
+
+    if (emptyRunCount > 0) {
+      console.log(
+        OutputHelper.formatWarning(
+          `⚠ ${emptyRunCount} package(s) ran 0 tests — check test discovery`
+        )
+      );
+    }
   }
 }