feat(packages/run): add elideNodeDebuggerStringsFromStderr option

Author: Xunnamius

packages/run/package.json

@@ -67,10 +67,15 @@
     "test:packages:all": "symbiote test --env NODE_NO_WARNINGS=1 --tests all-local --scope unlimited --coverage"
   },
   "dependencies": {
+    "core-js": "^3.40.0",
     "execa": "^9.5.2",
     "rejoinder": "^1.2.4",
+    "strip-final-newline": "^4.0.0",
     "type-fest": "^4.34.1"
   },
+  "devDependencies": {
+    "@-xun/fs": "^1.0.0"
+  },
   "engines": {
     "node": "^18.20.0 || ^20.18.0 || ^22.12.0 || >=23.3.0"
   },

packages/run/src/index.ts

@@ -13,6 +13,13 @@ import type {
 let runCounter = 0;
 const debug = createDebugLogger({ namespace: globalDebuggerNamespace });
 
+const nodejsDebugStringRegExps = [
+  /^Debugger attached\.(\n|$)/gm,
+  /^Debugger listening on .+(\n|$)/gm,
+  /^For help, see: https:\/\/nodejs\.org\/en\/docs\/inspector(\n|$)/gm,
+  /^Waiting for the debugger to disconnect\.\.\.(\n|$)/gm
+];
+
 export type { Subprocess } from 'execa' with { 'resolution-mode': 'import' };
 export type * from 'universe+run:types.ts';
 
@@ -27,6 +34,9 @@ export type * from 'universe+run:types.ts';
  *
  * 2. Coerces output to a string. Set `coerceOutputToString: false` (or `lines:
  *    true`) to override this.
+ *
+ * 3. Elides Node.js debugger strings. Set `elideNodeDebuggerStringsFromStderr:
+ *    false` to override this.
  */
 export async function run(
   file: string,
@@ -48,6 +58,7 @@ export async function run<OptionsType extends RunOptions = DefaultRunOptions>(
   const {
     useIntermediate,
     coerceOutputToString = true,
+    elideNodeDebuggerStringsFromStderr = true,
     ...execaOptions
   } = options || ({} as RunOptions);
 
@@ -57,7 +68,9 @@ export async function run<OptionsType extends RunOptions = DefaultRunOptions>(
 
   const shouldCoerceOutputToString = coerceOutputToString && !execaOptions.lines;
   runDebug('output coercion: %O', shouldCoerceOutputToString);
+  runDebug('debug elision: %O', elideNodeDebuggerStringsFromStderr);
 
+  const stripFinalNewline = (await import('strip-final-newline')).default;
   const intermediateResult = (await import('execa')).execa(file, args, execaOptions);
 
   await useIntermediate?.(intermediateResult);
@@ -70,6 +83,25 @@ export async function run<OptionsType extends RunOptions = DefaultRunOptions>(
     finalResult.stderr = finalResult.stderr?.toString() ?? '';
   }
 
+  if (elideNodeDebuggerStringsFromStderr) {
+    /* istanbul ignore else */
+    if (typeof finalResult.stderr === 'string') {
+      let { stderr } = finalResult;
+
+      nodejsDebugStringRegExps.forEach((regExp) => {
+        stderr = stderr.replaceAll(regExp, '');
+      });
+
+      finalResult.stderr =
+        execaOptions.stripFinalNewline === false ? stderr : stripFinalNewline(stderr);
+    } else if (Array.isArray(finalResult.stderr)) {
+      finalResult.stderr = finalResult.stderr.filter((filterTarget_) => {
+        const filterTarget = String(filterTarget_);
+        return nodejsDebugStringRegExps.every((regExp) => !filterTarget.match(regExp));
+      });
+    }
+  }
+
   runDebug('execution result: %O', finalResult);
   return finalResult;
 }
@@ -94,6 +126,7 @@ export async function runWithInheritedIo(
   return run(file, args, {
     ...options,
     coerceOutputToString: false,
+    elideNodeDebuggerStringsFromStderr: false,
     stdio: 'inherit'
   }) as Promise<Omit<RunReturnType, 'all' | 'stdout' | 'stderr' | 'stdio'>>;
 }
@@ -108,6 +141,9 @@ export async function runWithInheritedIo(
  *
  * 2. Coerces output to a string. Set `coerceOutputToString: false` (or `lines:
  *    true`) to override this.
+ *
+ * 3. Elides Node.js debugger strings. Set `elideNodeDebuggerStringsFromStderr:
+ *    false` to override this.
  */
 export async function runNoRejectOnBadExit(
   file: string,
@@ -142,6 +178,9 @@ export async function runNoRejectOnBadExit<
  *
  * 2. Coerces output to a string. Set `coerceOutputToString: false` (or
  *    `lines: true`) to override this.
+ *
+ * 3. Elides Node.js debugger strings. Set `elideNodeDebuggerStringsFromStderr:
+ *    false` to override this.
  */
 export function runnerFactory<FactoryOptionsType extends RunOptions = DefaultRunOptions>(
   file: string,

packages/run/src/types.ts

@@ -24,6 +24,16 @@ export type RunOptions = ExecaOptions & {
    * output will be coerced to an array of strings regardless of this option.
    */
   coerceOutputToString?: boolean;
+  /**
+   * When attaching a debugger to a Node.js process, such as when using the
+   * `--inspect*` flags, Node will add it's own "debugger attached" lines to
+   * stderr. Set `elideNodeDebuggerStringsFromStderr` to `true` to remove them
+   * automatically, or `false` to do nothing.
+   *
+   * @default true
+   * @see https://github.com/nodejs/node/issues/34799
+   */
+  elideNodeDebuggerStringsFromStderr?: boolean;
 };
 
 /**
@@ -32,6 +42,7 @@ export type RunOptions = ExecaOptions & {
 export type DefaultRunOptions = RunOptions & {
   lines: false;
   coerceOutputToString: true;
+  elideNodeDebuggerStringsFromStderr: true;
   all: false;
 };
 

packages/run/test/unit.test.ts

@@ -69,6 +69,61 @@ describe('::run', () => {
       expect(result.all).toStrictEqual(testOutput.split('\n'));
     }
   });
+
+  it('elides Node.js inspector debug strings from stderr by default', async () => {
+    expect.hasAssertions();
+
+    const testScriptString = /* js */ `
+    console.error('Waiting for the debugger to disconnect...');
+    console.error('Debugger listening on ws://127.0.0.1:9229/4dad5ead-6482-44b3-9c2c-8e880788863f');
+    console.error('For help, see: https://nodejs.org/en/docs/inspector');
+    console.error('Debugger attached.');
+    console.error('test');
+    console.error('Debugger attached.');
+    console.error('Debugger attached.');
+    console.error('Waiting for the debugger to disconnect...');
+    console.error('Waiting for the debugger to disconnect...');
+`;
+
+    {
+      const result = await run('node', ['-e', testScriptString]);
+
+      expect(result.stdout).toBeEmpty();
+      expect(result.stderr).toBe('test');
+      expect(result.exitCode).toBe(0);
+    }
+
+    {
+      const result = await run('node', ['-e', testScriptString], {
+        lines: true
+      });
+
+      expect(result.stdout).toBeEmpty();
+      expect(result.stderr).toStrictEqual(['test']);
+      expect(result.exitCode).toBe(0);
+    }
+
+    {
+      const result = await run('node', ['-e', testScriptString], {
+        elideNodeDebuggerStringsFromStderr: false
+      });
+
+      expect(result.stdout).toBeEmpty();
+      expect(result.stderr).not.toBe('test');
+      expect(result.exitCode).toBe(0);
+    }
+
+    {
+      const result = await run('node', ['-e', testScriptString], {
+        lines: true,
+        elideNodeDebuggerStringsFromStderr: false
+      });
+
+      expect(result.stdout).toBeEmpty();
+      expect(result.stderr).not.toStrictEqual(['test']);
+      expect(result.exitCode).toBe(0);
+    }
+  });
 });
 
 describe('::runWithInheritedIo', () => {