refactor(utils): command helper

packages/nx-plugin/src/executors/cli/executor.int.test.ts

@@ -1,17 +1,34 @@
-import { afterEach, expect, vi } from 'vitest';
+import { afterEach, beforeEach, expect, vi } from 'vitest';
 import { executorContext } from '@code-pushup/test-nx-utils';
-import * as executeProcessModule from '../../internal/execute-process.js';
 import runAutorunExecutor from './executor.js';
 import * as utils from './utils.js';
 
+const { executeProcessSpy } = vi.hoisted(() => ({
+ executeProcessSpy: vi.fn().mockResolvedValue({
+ code: 0,
+ stdout: '',
+ stderr: '',
+ date: new Date().toISOString(),
+ duration: 100,
+ }),
+}));
+
+vi.mock('@code-pushup/utils', async () => {
+ const utils = await vi.importActual('@code-pushup/utils');
+ return {
+ ...utils,
+ executeProcess: executeProcessSpy,
+ };
+});
+
 describe('runAutorunExecutor', () => {
  const parseAutorunExecutorOptionsSpy = vi.spyOn(
  utils,
  'parseAutorunExecutorOptions',
  );
- const executeProcessSpy = vi.spyOn(executeProcessModule, 'executeProcess');
 
  beforeEach(() => {
+ executeProcessSpy.mockClear();
  executeProcessSpy.mockResolvedValue({
  bin: 'npx ...',
  code: 0,
@@ -43,10 +60,12 @@ describe('runAutorunExecutor', () => {
  }),
  );
  expect(executeProcessSpy).toHaveBeenCalledTimes(1);
- expect(executeProcessSpy).toHaveBeenCalledWith({
- command: 'npx',
- args: expect.arrayContaining(['@code-pushup/cli']),
- cwd: process.cwd(),
- });
+ expect(executeProcessSpy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ command: 'npx',
+ args: expect.arrayContaining(['@code-pushup/cli']),
+ cwd: expect.any(String),
+ }),
+ );
  });
 });

packages/nx-plugin/src/executors/cli/executor.ts

@@ -1,5 +1,4 @@
 import { type ExecutorContext, logger } from '@nx/devkit';
-import { executeProcess } from '../../internal/execute-process.js';
 import {
  createCliCommandObject,
  createCliCommandString,
@@ -41,6 +40,7 @@ export default async function runAutorunExecutor(
  logger.warn(`DryRun execution of: ${commandString}`);
  } else {
  try {
+ const { executeProcess } = await import('@code-pushup/utils');
  await executeProcess({
  ...createCliCommandObject({ command, args: cliArgumentObject, bin }),
  ...(context.cwd ? { cwd: context.cwd } : {}),

packages/nx-plugin/src/executors/cli/executor.unit.test.ts

@@ -2,16 +2,32 @@ import { logger } from '@nx/devkit';
 import { afterAll, afterEach, beforeEach, expect, vi } from 'vitest';
 import { executorContext } from '@code-pushup/test-nx-utils';
 import { MEMFS_VOLUME } from '@code-pushup/test-utils';
-import * as executeProcessModule from '../../internal/execute-process.js';
 import runAutorunExecutor from './executor.js';
 
+const { executeProcessSpy } = vi.hoisted(() => ({
+ executeProcessSpy: vi.fn().mockResolvedValue({
+ code: 0,
+ stdout: '',
+ stderr: '',
+ date: new Date().toISOString(),
+ duration: 100,
+ }),
+}));
+
+vi.mock('@code-pushup/utils', async () => {
+ const utils = await vi.importActual('@code-pushup/utils');
+ return {
+ ...utils,
+ executeProcess: executeProcessSpy,
+ };
+});
+
 describe('runAutorunExecutor', () => {
  const processEnvCP = Object.fromEntries(
  Object.entries(process.env).filter(([k]) => k.startsWith('CP_')),
  );
  const loggerInfoSpy = vi.spyOn(logger, 'info');
  const loggerWarnSpy = vi.spyOn(logger, 'warn');
- const executeProcessSpy = vi.spyOn(executeProcessModule, 'executeProcess');
 
  beforeAll(() => {
  Object.entries(process.env)
@@ -25,6 +41,7 @@ describe('runAutorunExecutor', () => {
 
  beforeEach(() => {
  vi.unstubAllEnvs();
+ executeProcessSpy.mockClear();
  executeProcessSpy.mockResolvedValue({
  bin: 'npx ...',
  code: 0,

packages/utils/eslint.config.js

@@ -17,7 +17,9 @@ export default tseslint.config(
  rules: {
  '@nx/dependency-checks': [
  'error',
- { ignoredDependencies: ['esbuild'] }, // esbuild is a peer dependency of bundle-require
+ {
+ ignoredDependencies: ['esbuild', 'ora'], // esbuild is a peer dependency of bundle-require, ora has transitive dependencies with different versions
+ },
  ],
  },
  },

packages/utils/src/lib/command.ts

@@ -0,0 +1,167 @@
+import ansis from 'ansis';
+import path from 'node:path';
+
+type ArgumentValue = number | string | boolean | string[] | undefined;
+export type CliArgsObject<T extends object = Record<string, ArgumentValue>> =
+ T extends never
+ ? Record<string, ArgumentValue | undefined> | { _: string }
+ : T;
+
+/**
+ * Escapes command line arguments that contain spaces, quotes, or other special characters.
+ *
+ * @param {string[]} args - Array of command arguments to escape.
+ * @returns {string[]} - Array of escaped arguments suitable for shell execution.
+ */
+export function escapeCliArgs(args: string[]): string[] {
+ return args.map(arg => {
+ if (arg.includes(' ') || arg.includes('"') || arg.includes("'")) {
+ return `"${arg.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+ }
+ return arg;
+ });
+}
+
+/**
+ * Formats environment variable values for display by stripping quotes and then escaping.
+ *
+ * @param {string} value - Environment variable value to format.
+ * @returns {string} - Formatted and escaped value suitable for display.
+ */
+export function formatEnvValue(value: string): string {
+ // Strip quotes from the value for display
+ const cleanValue = value.replace(/"/g, '');
+ return escapeCliArgs([cleanValue])[0] ?? cleanValue;
+}
+
+/**
+ * Builds a command string by escaping arguments that contain spaces, quotes, or other special characters.
+ *
+ * @param {string} command - The base command to execute.
+ * @param {string[]} args - Array of command arguments.
+ * @returns {string} - The complete command string with properly escaped arguments.
+ */
+export function buildCommandString(
+ command: string,
+ args: string[] = [],
+): string {
+ if (args.length === 0) {
+ return command;
+ }
+
+ return `${command} ${escapeCliArgs(args).join(' ')}`;
+}
+
+/**
+ * Options for formatting a command log.
+ */
+export interface FormatCommandLogOptions {
+ command: string;
+ args?: string[];
+ cwd?: string;
+ env?: Record<string, string>;
+}
+
+/**
+ * Formats a command string with optional cwd prefix, environment variables, and ANSI colors.
+ *
+ * @param {FormatCommandLogOptions} options - Command formatting options.
+ * @returns {string} - ANSI-colored formatted command string.
+ *
+ * @example
+ *
+ * formatCommandLog({cwd: 'tools/api', env: {API_KEY='•••' NODE_ENV='prod'}, command: 'node', args: ['cli.js', '--do', 'thing', 'fast']})
+ * ┌─────────────────────────────────────────────────────────────────────────┐
+ * │ tools/api $ API_KEY="•••" NODE_ENV="prod" node cli.js --do thing fast │
+ * │ │ │ │ │ │ │
+ * │ └ cwd │ │ │ └ args. │
+ * │ │ │ └ command │
+ * │ │ └ env variables │
+ * │ └ prompt symbol ($) │
+ * └─────────────────────────────────────────────────────────────────────────┘
+ */
+export function formatCommandLog(options: FormatCommandLogOptions): string {
+ const { command, args = [], cwd = process.cwd(), env } = options;
+ const relativeDir = path.relative(process.cwd(), cwd);
+
+ return [
+ ...(relativeDir && relativeDir !== '.'
+ ? [ansis.italic(ansis.gray(relativeDir))]
+ : []),
+ ansis.yellow('$'),
+ ...(env && Object.keys(env).length > 0
+ ? Object.entries(env).map(([key, value]) => {
+ return ansis.gray(`${key}=${formatEnvValue(value)}`);
+ })
+ : []),
+ ansis.gray(command),
+ ansis.gray(args.join(' ')),
+ ].join(' ');
+}
+
+/**
+ * Converts an object with different types of values into an array of command-line arguments.
+ *
+ * @example
+ * const args = objectToCliArgs({
+ * _: ['node', 'index.js'], // node index.js
+ * name: 'Juanita', // --name=Juanita
+ * formats: ['json', 'md'] // --format=json --format=md
+ * });
+ */
+export function objectToCliArgs<
+ T extends object = Record<string, ArgumentValue>,
+>(params?: CliArgsObject<T>): string[] {
+ if (!params) {
+ return [];
+ }
+
+ return Object.entries(params).flatMap(([key, value]) => {
+ // process/file/script
+ if (key === '_') {
+ return Array.isArray(value) ? value : [`${value}`];
+ }
+ const prefix = key.length === 1 ? '-' : '--';
+ // "-*" arguments (shorthands)
+ if (Array.isArray(value)) {
+ return value.map(v => `${prefix}${key}="${v}"`);
+ }
+ // "--*" arguments ==========
+
+ if (typeof value === 'object') {
+ return Object.entries(value as Record<string, ArgumentValue>).flatMap(
+ // transform nested objects to the dot notation `key.subkey`
+ ([k, v]) => objectToCliArgs({ [`${key}.${k}`]: v }),
+ );
+ }
+
+ if (typeof value === 'string') {
+ return [`${prefix}${key}="${value}"`];
+ }
+
+ if (typeof value === 'number') {
+ return [`${prefix}${key}=${value}`];
+ }
+
+ if (typeof value === 'boolean') {
+ return [`${prefix}${value ? '' : 'no-'}${key}`];
+ }
+
+ if (typeof value === 'undefined') {
+ return [];
+ }
+
+ throw new Error(`Unsupported type ${typeof value} for key ${key}`);
+ });
+}
+
+/**
+ * Converts a file path to a CLI argument by wrapping it in quotes to handle spaces.
+ *
+ * @param {string} filePath - The file path to convert to a CLI argument.
+ * @returns {string} - The quoted file path suitable for CLI usage.
+ */
+export function filePathToCliArg(filePath: string): string {
+ // needs to be escaped if spaces included
+ return `"${filePath}"`;
+}