@quenty/cli-output-helpers 1.18.0 → 1.19.1

package/src/outputHelper.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, afterEach } from 'vitest';
+import { describe, it, expect, afterEach, vi } from 'vitest';
 import { OutputHelper } from './outputHelper.js';
 
 describe('OutputHelper.formatErrorChain', () => {
@@ -68,3 +68,34 @@ describe('OutputHelper.formatErrorChain', () => {
     expect(out).toContain(err.stack!);
   });
 });
+
+describe('OutputHelper.setDiagnosticsToStderr', () => {
+  afterEach(() => {
+    OutputHelper.setDiagnosticsToStderr(false);
+    vi.restoreAllMocks();
+  });
+
+  it('writes diagnostics to stdout by default', () => {
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    OutputHelper.info('hello');
+
+    expect(log).toHaveBeenCalledTimes(1);
+    expect(error).not.toHaveBeenCalled();
+  });
+
+  it('moves info, warnings, hints and boxes to stderr', () => {
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+    OutputHelper.setDiagnosticsToStderr(true);
+
+    OutputHelper.info('info');
+    OutputHelper.warn('warn');
+    OutputHelper.hint('hint');
+    OutputHelper.box('box');
+
+    expect(log).not.toHaveBeenCalled();
+    expect(error).toHaveBeenCalledTimes(4);
+  });
+});

package/src/outputHelper.ts

@@ -17,6 +17,16 @@ const _outputStorage = new AsyncLocalStorage<OutputBuffer>();
  */
 export class OutputHelper {
   private static _verbose: boolean = true;
+  private static _diagnosticsToStderr: boolean = false;
+
+  private static _writeDiagnostic(text: string): void {
+    if (this._diagnosticsToStderr) {
+      console.error(text);
+    } else {
+      console.log(text);
+    }
+  }
+
   /**
    * Formats the error with markup
    * @param message Message to format
@@ -169,7 +179,9 @@ export class OutputHelper {
    * @param message Message to write
    */
   public static info(message: string): void {
-    console.log(this._hasAnsi(message) ? message : this.formatInfo(message));
+    this._writeDiagnostic(
+      this._hasAnsi(message) ? message : this.formatInfo(message)
+    );
   }
 
   /**
@@ -189,6 +201,14 @@ export class OutputHelper {
     return this._verbose;
   }
 
+  /**
+   * Sends info, warnings, hints, verbose output and boxes to stderr, for CLIs
+   * whose stdout carries only the command result.
+   */
+  public static setDiagnosticsToStderr(toStderr: boolean): void {
+    this._diagnosticsToStderr = toStderr;
+  }
+
   /**
    * Logs a verbose/intermediate message. Suppressed when verbose is false.
    * When running inside a buffered context (see runBuffered), messages are
@@ -206,7 +226,7 @@ export class OutputHelper {
     if (buffer) {
       buffer.lines.push(formatted);
     } else {
-      console.log(formatted);
+      this._writeDiagnostic(formatted);
     }
   }
 
@@ -228,7 +248,9 @@ export class OutputHelper {
    * @param message Message to write
    */
   public static warn(message: string): void {
-    console.log(this._hasAnsi(message) ? message : this.formatWarning(message));
+    this._writeDiagnostic(
+      this._hasAnsi(message) ? message : this.formatWarning(message)
+    );
   }
 
   /**
@@ -240,7 +262,7 @@ export class OutputHelper {
    * after it.
    */
   public static startGroup(title: string, useGroups = isCI()): void {
-    console.log(
+    this._writeDiagnostic(
       useGroups ? `::group::${title}` : this.formatDim(`── ${title} ──`)
     );
   }
@@ -248,7 +270,7 @@ export class OutputHelper {
   /** Close the section opened by {@link startGroup}. */
   public static endGroup(useGroups = isCI()): void {
     if (useGroups) {
-      console.log('::endgroup::');
+      this._writeDiagnostic('::endgroup::');
     }
   }
 
@@ -257,7 +279,9 @@ export class OutputHelper {
    * @param message Message to write
    */
   public static hint(message: string): void {
-    console.log(this._hasAnsi(message) ? message : this.formatHint(message));
+    this._writeDiagnostic(
+      this._hasAnsi(message) ? message : this.formatHint(message)
+    );
   }
 
   /**
@@ -265,6 +289,6 @@ export class OutputHelper {
    * @param message
    */
   public static box(message: string, options?: BoxOptions): void {
-    console.log(this.formatBox(message, options));
+    this._writeDiagnostic(this.formatBox(message, options));
   }
 }

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

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, afterEach } from 'vitest';
 import {
   type Diagnostic,
+  dedupeDiagnostics,
   formatAnnotation,
   emitAnnotations,
   summarizeDiagnostics,
@@ -18,6 +19,24 @@ function makeDiagnostic(overrides: Partial<Diagnostic> = {}): Diagnostic {
 }
 
 describe('formatAnnotation', () => {
+  it('omits file and line when the location is unknown', () => {
+    const result = formatAnnotation(
+      makeDiagnostic({
+        file: undefined,
+        line: undefined,
+        title: 'Runtime error',
+      })
+    );
+    expect(result).toBe('::error title=Runtime error::Something went wrong');
+  });
+
+  it('formats an annotation with no properties at all', () => {
+    const result = formatAnnotation(
+      makeDiagnostic({ file: undefined, line: undefined })
+    );
+    expect(result).toBe('::error::Something went wrong');
+  });
+
   it('formats a basic error annotation', () => {
     const result = formatAnnotation(makeDiagnostic());
     expect(result).toBe(
@@ -116,7 +135,42 @@ describe('summarizeDiagnostics', () => {
   });
 });
 
+describe('dedupeDiagnostics', () => {
+  it('drops identical repeats', () => {
+    const result = dedupeDiagnostics([
+      makeDiagnostic({ title: 'Runtime error' }),
+      makeDiagnostic({ title: 'Runtime error' }),
+      makeDiagnostic({ file: undefined, line: undefined }),
+      makeDiagnostic({ file: undefined, line: undefined }),
+    ]);
+    expect(result).toHaveLength(2);
+  });
+
+  it('keeps distinct errors at the same file, line and title', () => {
+    const result = dedupeDiagnostics([
+      makeDiagnostic({ title: 'Runtime error', message: 'first' }),
+      makeDiagnostic({ title: 'Runtime error', message: 'second' }),
+      makeDiagnostic({ title: 'Runtime error', message: 'first', line: 11 }),
+    ]);
+    expect(result.map((d) => [d.line, d.message])).toEqual([
+      [10, 'first'],
+      [10, 'second'],
+      [11, 'first'],
+    ]);
+  });
+});
+
 describe('formatAnnotationSummaryMarkdown', () => {
+  it('counts only real files and groups file-less diagnostics', () => {
+    const md = formatAnnotationSummaryMarkdown('Test Failures', [
+      makeDiagnostic({ file: 'src/a.lua' }),
+      makeDiagnostic({ file: undefined, line: undefined }),
+    ]);
+    expect(md).toContain('across 1 file:');
+    expect(md).toContain('<summary>No file (1)</summary>');
+    expect(md).not.toContain('undefined');
+  });
+
   it('returns "no issues" for empty diagnostics', () => {
     const md = formatAnnotationSummaryMarkdown('luau-lsp', []);
     expect(md).toContain('### luau-lsp');

package/src/reporting/github/annotations.ts

@@ -16,8 +16,9 @@ import { isCI } from '../../cli-utils.js';
 export type DiagnosticSeverity = 'error' | 'warning' | 'notice';
 
 export interface Diagnostic {
-  file: string;
-  line: number;
+  /** Repo-relative path. Omit when the location is unknown. */
+  file?: string;
+  line?: number;
   endLine?: number;
   column?: number;
   endColumn?: number;
@@ -61,8 +62,12 @@ function _escapeMessage(value: string): string {
 export function formatAnnotation(diagnostic: Diagnostic): string {
   const props: string[] = [];
 
-  props.push(`file=${_escapeProperty(diagnostic.file)}`);
-  props.push(`line=${diagnostic.line}`);
+  if (diagnostic.file !== undefined) {
+    props.push(`file=${_escapeProperty(diagnostic.file)}`);
+  }
+  if (diagnostic.line !== undefined) {
+    props.push(`line=${diagnostic.line}`);
+  }
 
   if (diagnostic.endLine !== undefined) {
     props.push(`endLine=${diagnostic.endLine}`);
@@ -78,7 +83,25 @@ export function formatAnnotation(diagnostic: Diagnostic): string {
   }
 
   const message = _escapeMessage(diagnostic.message);
-  return `::${diagnostic.severity} ${props.join(',')}::${message}`;
+  const properties = props.length > 0 ? ` ${props.join(',')}` : '';
+  return `::${diagnostic.severity}${properties}::${message}`;
+}
+
+/** Drop exact repeats; GitHub shows only 10 error annotations per step. */
+export function dedupeDiagnostics(diagnostics: Diagnostic[]): Diagnostic[] {
+  const seen = new Set<string>();
+  return diagnostics.filter((d) => {
+    const key = JSON.stringify([
+      d.severity,
+      d.file,
+      d.line,
+      d.title,
+      d.message,
+    ]);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
 }
 
 /**
@@ -103,7 +126,9 @@ export function summarizeDiagnostics(
   const files = new Set<string>();
 
   for (const d of diagnostics) {
-    files.add(d.file);
+    if (d.file !== undefined) {
+      files.add(d.file);
+    }
     switch (d.severity) {
       case 'error':
         errors++;
@@ -158,7 +183,7 @@ export function formatAnnotationSummaryMarkdown(
   } file${summary.fileCount !== 1 ? 's' : ''}: ${parts.join(', ')}\n\n`;
 
   // Group diagnostics by file
-  const byFile = new Map<string, Diagnostic[]>();
+  const byFile = new Map<string | undefined, Diagnostic[]>();
   for (const d of diagnostics) {
     const list = byFile.get(d.file) ?? [];
     list.push(d);
@@ -176,7 +201,8 @@ export function formatAnnotationSummaryMarkdown(
       break;
     }
 
-    md += `<details><summary><code>${file}</code> (${diags.length})</summary>\n\n`;
+    const label = file === undefined ? 'No file' : `<code>${file}</code>`;
+    md += `<details><summary>${label} (${diags.length})</summary>\n\n`;
     md += '| Line | Severity | Message |\n';
     md += '|------|----------|---------|\n';
 
@@ -189,7 +215,7 @@ export function formatAnnotationSummaryMarkdown(
           ? '`warning`'
           : '`notice`';
       const escapedMsg = d.message.replace(/\|/g, '\\|').replace(/\n/g, ' ');
-      md += `| ${d.line} | ${sev} | ${escapedMsg} |\n`;
+      md += `| ${d.line ?? ''} | ${sev} | ${escapedMsg} |\n`;
     }
 
     if (diags.length > MAX_PER_FILE) {

package/src/reporting/github/index.ts

@@ -25,6 +25,7 @@ export {
   type Diagnostic,
   type DiagnosticSummary,
   formatAnnotation,
+  dedupeDiagnostics,
   emitAnnotations,
   summarizeDiagnostics,
   formatAnnotationSummaryMarkdown,

package/src/reporting/index.ts

@@ -104,6 +104,7 @@ export {
   type Diagnostic,
   type DiagnosticSummary,
   formatAnnotation,
+  dedupeDiagnostics,
   emitAnnotations,
   summarizeDiagnostics,
   formatAnnotationSummaryMarkdown,

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

@@ -25,6 +25,14 @@ describe('StdoutResultReporter', () => {
     expect(logSpy).toHaveBeenNthCalledWith(2, 'name=second');
   });
 
+  it('prints nothing when the result renders empty', () => {
+    const reporter = new StdoutResultReporter<unknown>({ render: () => '' });
+
+    reporter.onResult({});
+
+    expect(logSpy).not.toHaveBeenCalled();
+  });
+
   it('startAsync and stopAsync are no-ops', async () => {
     const reporter = new StdoutResultReporter<unknown>({ render: () => '' });
     await reporter.startAsync();

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

@@ -18,6 +18,9 @@ export class StdoutResultReporter<T = unknown> extends BaseResultReporter<T> {
   }
 
   override onResult(result: T): void {
-    console.log(this._render(result));
+    const text = this._render(result);
+    if (text !== '') {
+      console.log(text);
+    }
   }
 }