feat(utils): integrate logger with executeProcess

Author: matejchalk

packages/utils/mocks/logger-demo.ts

@@ -44,7 +44,7 @@ try {
         async () => {
           await sleep(3000);
           if (errorStage === 'plugin') {
-            logger.info('Configuration file not found.');
+            logger.debug('Configuration file not found.', { force: true });
             throw new Error(`Command ${ansis.bold(bin)} exited with code 1`);
           }
           logger.debug('All files pass linting.');

packages/utils/src/lib/execute-process.unit.test.ts renamed to packages/utils/src/lib/execute-process.int.test.ts

@@ -2,6 +2,7 @@ import { ChildProcess } from 'node:child_process';
 import { describe, expect, it, vi } from 'vitest';
 import { getAsyncProcessRunnerConfig } from '@code-pushup/test-utils';
 import { type ProcessObserver, executeProcess } from './execute-process.js';
+import { logger } from './logger.js';
 
 describe('executeProcess', () => {
   const spyObserver: ProcessObserver = {
@@ -12,13 +13,9 @@ describe('executeProcess', () => {
   };
   const errorSpy = vi.fn();
 
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
   it('should work with node command `node -v`', async () => {
     const processResult = await executeProcess({
-      command: `node`,
+      command: 'node',
       args: ['-v'],
       observer: spyObserver,
     });
@@ -32,7 +29,7 @@ describe('executeProcess', () => {
 
   it('should work with npx command `npx --help`', async () => {
     const processResult = await executeProcess({
-      command: `npx`,
+      command: 'npx',
       args: ['--help'],
       observer: spyObserver,
     });
@@ -101,4 +98,42 @@ describe('executeProcess', () => {
     expect(spyObserver.onError).not.toHaveBeenCalled();
     expect(spyObserver.onComplete).toHaveBeenCalledOnce();
   });
+
+  it('should show spinner with serialized command and args', async () => {
+    await executeProcess({ command: 'echo', args: ['hello'] });
+    expect(logger.command).toHaveBeenCalledWith(
+      'echo hello',
+      expect.any(Function),
+    );
+  });
+
+  it('should log stdout and stderr if verbose', async () => {
+    await executeProcess(
+      getAsyncProcessRunnerConfig({ interval: 10, runs: 2, throwError: false }),
+    );
+    expect(logger.debug).toHaveBeenCalledWith(
+      `
+process:start with interval: 10, runs: 2, throwError: false
+process:update
+process:update
+process:complete
+`.trimStart(),
+    );
+  });
+
+  it('should log stdout and stderr if process failed', async () => {
+    await expect(
+      executeProcess(
+        getAsyncProcessRunnerConfig({
+          interval: 10,
+          runs: 1,
+          throwError: true,
+        }),
+      ),
+    ).rejects.toThrow();
+    expect(logger.debug).toHaveBeenCalledWith(
+      expect.stringMatching(/process:start.*Error: dummy-error/s),
+      { force: true },
+    );
+  });
 });

packages/utils/src/lib/execute-process.ts

@@ -1,3 +1,4 @@
+import ansis from 'ansis';
 import {
   type ChildProcess,
   type ChildProcessByStdio,
@@ -6,38 +7,33 @@ import {
   spawn,
 } from 'node:child_process';
 import type { Readable, Writable } from 'node:stream';
-import { isVerbose } from './env.js';
-import { formatCommandLog } from './format-command-log.js';
-import { ui } from './logging.js';
+import { logger } from './logger.js';
 
 /**
  * Represents the process result.
- * @category Types
- * @public
- * @property {number | null} code - The exit code of the process.
- * @property {string} stdout - The stdout of the process.
- * @property {string} stderr - The stderr of the process.
  */
 export type ProcessResult = {
+  /** The full command with args that was executed. */
+  bin: string;
+  /** The exit code of the process (`null` if terminated by signal). */
   code: number | null;
+  /** The signal which terminated the process, if any. */
+  signal: NodeJS.Signals | null;
+  /** The standard output from the process. */
   stdout: string;
+  /** The standard error from the process. */
   stderr: string;
 };
 
 /**
  * Error class for process errors.
  * Contains additional information about the process result.
- * @category Error
- * @public
- * @class
- * @extends Error
  * @example
- * const result = await executeProcess({})
- * .catch((error) => {
+ * const result = await executeProcess({}).catch((error) => {
  *   if (error instanceof ProcessError) {
- *   console.error(error.code);
- *   console.error(error.stderr);
- *   console.error(error.stdout);
+ *     console.error(error.code);
+ *     console.error(error.stderr);
+ *     console.error(error.stdout);
  *   }
  * });
  *
@@ -48,7 +44,10 @@ export class ProcessError extends Error {
   stdout: string;
 
   constructor(result: ProcessResult) {
-    super(result.stderr);
+    const message = result.signal
+      ? `Process ${ansis.bold(result.bin)} terminated by ${result.signal}`
+      : `Process ${ansis.bold(result.bin)} failed with exit code ${result.code}`;
+    super(message);
     this.code = result.code;
     this.stderr = result.stderr;
     this.stdout = result.stdout;
@@ -57,9 +56,7 @@ export class ProcessError extends Error {
 
 /**
  * Process config object. Contains the command, args and observer.
- * @param cfg - process config object with command, args and observer (optional)
- * @category Types
- * @public
+ * @param cfg Process config object with command, args and observer (optional)
  * @property {string} command - The command to execute.
  * @property {string[]} args - The arguments for the command.
  * @property {ProcessObserver} observer - The observer for the process.
@@ -74,15 +71,15 @@ export class ProcessError extends Error {
  *
  * // node command
  * const cfg = {
- * command: 'node',
- * args: ['--version']
+ *  command: 'node',
+ *  args: ['--version']
  * };
  *
  * // npx command
  * const cfg = {
- * command: 'npx',
- * args: ['--version']
- *
+ *   command: 'npx',
+ *   args: ['--version']
+ * };
  */
 export type ProcessConfig = Omit<
   SpawnOptionsWithStdioTuple<StdioPipe, StdioPipe, StdioPipe>,
@@ -95,22 +92,21 @@ export type ProcessConfig = Omit<
 };
 
 /**
- * Process observer object. Contains the onStdout, error and complete function.
- * @category Types
- * @public
- * @property {function} onStdout - The onStdout function of the observer (optional).
- * @property {function} onError - The error function of the observer (optional).
- * @property {function} onComplete - The complete function of the observer (optional).
+ * Process observer object.
  *
  * @example
  * const observer = {
- *  onStdout: (stdout) => console.info(stdout)
- *  }
+ *   onStdout: (stdout) => console.info(stdout)
+ * }
  */
 export type ProcessObserver = {
+  /** Called when the `stdout` stream receives new data (optional). */
   onStdout?: (stdout: string, sourceProcess?: ChildProcess) => void;
+  /** Called when the `stdout` stream receives new data (optional). */
   onStderr?: (stderr: string, sourceProcess?: ChildProcess) => void;
+  /** Called when the process ends in an error (optional). */
   onError?: (error: ProcessError) => void;
+  /** Called when the process ends successfully (optional). */
   onComplete?: () => void;
 };
 
@@ -146,48 +142,59 @@ export function executeProcess(cfg: ProcessConfig): Promise<ProcessResult> {
   const { command, args, observer, ignoreExitCode = false, ...options } = cfg;
   const { onStdout, onStderr, onError, onComplete } = observer ?? {};
 
-  if (isVerbose()) {
-    ui().logger.log(
-      formatCommandLog(command, args, `${cfg.cwd ?? process.cwd()}`),
-    );
-  }
+  const bin = [command, ...(args ?? [])].join(' ');
 
-  return new Promise((resolve, reject) => {
-    // shell:true tells Windows to use shell command for spawning a child process
-    const spawnedProcess = spawn(command, args ?? [], {
-      shell: true,
-      windowsHide: true,
-      ...options,
-    }) as ChildProcessByStdio<Writable, Readable, Readable>;
+  return logger.command(
+    bin,
+    () =>
+      new Promise((resolve, reject) => {
+        const spawnedProcess = spawn(command, args ?? [], {
+          // shell:true tells Windows to use shell command for spawning a child process
+          // https://stackoverflow.com/questions/60386867/node-spawn-child-process-not-working-in-windows
+          shell: true,
+          windowsHide: true,
+          ...options,
+        }) as ChildProcessByStdio<Writable, Readable, Readable>;
 
-    // eslint-disable-next-line functional/no-let
-    let stdout = '';
-    // eslint-disable-next-line functional/no-let
-    let stderr = '';
+        // eslint-disable-next-line functional/no-let
+        let stdout = '';
+        // eslint-disable-next-line functional/no-let
+        let stderr = '';
+        // eslint-disable-next-line functional/no-let
+        let output = ''; // interleaved stdout and stderr
 
-    spawnedProcess.stdout.on('data', data => {
-      stdout += String(data);
-      onStdout?.(String(data), spawnedProcess);
-    });
+        spawnedProcess.stdout.on('data', (data: unknown) => {
+          const message = String(data);
+          stdout += message;
+          output += message;
+          onStdout?.(message, spawnedProcess);
+        });
 
-    spawnedProcess.stderr.on('data', data => {
-      stderr += String(data);
-      onStderr?.(String(data), spawnedProcess);
-    });
+        spawnedProcess.stderr.on('data', (data: unknown) => {
+          const message = String(data);
+          stderr += message;
+          output += message;
+          onStderr?.(message, spawnedProcess);
+        });
 
-    spawnedProcess.on('error', err => {
-      stderr += err.toString();
-    });
+        spawnedProcess.on('error', error => {
+          reject(error);
+        });
 
-    spawnedProcess.on('close', code => {
-      if (code === 0 || ignoreExitCode) {
-        onComplete?.();
-        resolve({ code, stdout, stderr });
-      } else {
-        const errorMsg = new ProcessError({ code, stdout, stderr });
-        onError?.(errorMsg);
-        reject(errorMsg);
-      }
-    });
-  });
+        spawnedProcess.on('close', (code, signal) => {
+          const result: ProcessResult = { bin, code, signal, stdout, stderr };
+          if (code === 0 || ignoreExitCode) {
+            logger.debug(output);
+            onComplete?.();
+            resolve(result);
+          } else {
+            // ensure stdout and stderr are logged to help debug failure
+            logger.debug(output, { force: true });
+            const error = new ProcessError(result);
+            onError?.(error);
+            reject(error);
+          }
+        });
+      }),
+  );
 }