[.github/shared] Add async backpressure-aware log() helper to console.js (#40568)

* Initial plan

* Add async backpressure-aware log() helper to .github/shared/src/console.js

Co-authored-by: mikeharder <9459391+mikeharder@users.noreply.github.com>

* make arg types exactly match

* simplify, improve typings

* improve backpressure test

* comments

* comment

* Apply suggestion from @mikeharder

* Remove duplicate exports in package.json

Removed duplicate entries for console and error-reporting in exports.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: mikeharder <9459391+mikeharder@users.noreply.github.com>
Co-authored-by: Mike Harder <mharder@microsoft.com>

Author: Copilot

.github/shared/package.json

@@ -6,6 +6,7 @@
     "./array": "./src/array.js",
     "./breaking-change": "./src/breaking-change.js",
     "./changed-files": "./src/changed-files.js",
+    "./console": "./src/console.js",
     "./error-reporting": "./src/error-reporting.js",
     "./eslint-base-config": "./eslint.base.config.js",
     "./exec": "./src/exec.js",

.github/shared/src/console.js

@@ -0,0 +1,48 @@
+import { once } from "node:events";
+import { format } from "node:util";
+
+/**
+ * Async, backpressure-aware console.log() replacement.  console.log() can silently drop messages under backpressure.
+ *
+ * Use when you need to log a lot of text, and the console reader may be applying backpressure.
+ *
+ * Examples: `node app.js | tee out.txt`, GitHub Actions console log reader
+ *
+ * @type {(...args: Parameters<typeof console.log>) => Promise<void>}
+ */
+export async function log(...args) {
+  const line = format(...args) + "\n";
+
+  if (!process.stdout.write(line)) {
+    await once(process.stdout, "drain");
+  }
+}
+
+// ## Future Improvement
+//
+// The log() function currently handles backpressure per call, but concurrent callers
+// can still invoke `process.stdout.write()` before a prior `drain` completes
+// (eg callers using Promise.all()).  If we ever need strict global backpressure control,
+// add a shared write queue (promise chain/mutex) to serialize all writes across calls.
+//
+// /** @type {Promise<void>} */
+// let writeQueue = Promise.resolve();
+//
+// /**
+//  * Async, backpressure-aware console.log replacement.
+//  *
+//  * @type {(...args: Parameters<typeof console.log>) => Promise<void>}
+//  */
+// export function log(...args) {
+//   const line = format(...args) + "\n";
+//
+//   const writeOnce = async () => {
+//     if (!process.stdout.write(line)) {
+//       await once(process.stdout, "drain");
+//     }
+//   };
+//
+//   const next = writeQueue.then(writeOnce, writeOnce);
+//   writeQueue = next.catch(() => {});
+//   return next;
+// }

.github/shared/test/console.test.js

@@ -0,0 +1,51 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { log } from "../src/console.js";
+
+describe("console", () => {
+  describe("log", () => {
+    /** @type {import("vitest").MockInstance<typeof process.stdout.write>} */
+    let writeSpy;
+
+    beforeEach(() => {
+      writeSpy = vi.spyOn(process.stdout, "write").mockReturnValue(true);
+    });
+
+    afterEach(() => {
+      writeSpy.mockRestore();
+    });
+
+    it("writes a formatted line to stdout", async () => {
+      await log("hello %s", "world");
+      expect(writeSpy).toBeCalledWith("hello world\n");
+    });
+
+    it("formats multiple arguments like console.log", async () => {
+      await log("a", "b", "c");
+      expect(writeSpy).toBeCalledWith("a b c\n");
+    });
+
+    it("works with no arguments", async () => {
+      await log();
+      expect(writeSpy).toBeCalledWith("\n");
+    });
+
+    it("awaits drain when stdout has backpressure", async () => {
+      writeSpy.mockReturnValueOnce(false);
+
+      let resolved = false;
+      const promise = log("backpressure test").then(() => {
+        resolved = true;
+      });
+
+      // Should still be pending before drain
+      expect(resolved).toBe(false);
+      expect(writeSpy).toBeCalledWith("backpressure test\n");
+
+      // Unblock backpressure
+      process.stdout.emit("drain");
+      await promise;
+
+      expect(resolved).toBe(true);
+    });
+  });
+});