@reporters/mux 1.0.0

package/README.md

@@ -0,0 +1,97 @@
+![tests](https://github.com/MoLow/reporters/actions/workflows/test.yaml/badge.svg?branch=main) [![codecov](https://codecov.io/gh/MoLow/reporters/branch/main/graph/badge.svg?token=0LFVC8SCQV)](https://codecov.io/gh/MoLow/reporters)
+
+# Reporter Multiplexer
+
+One `--test-reporter` flag, every environment covered.
+
+`@reporters/mux` is environment-aware routing for `node:test` reporters.
+Register it once; it reads a `mux.config` file, picks the active **profile**
+(`ci` vs `local`, auto-detected), tees the test-event stream to every configured
+**reporter**, and pipes each reporter's output into its **sink** —
+`stdout`/`stderr`, a file, a local HTTP viewer, or a remote upload with a
+shareable report URL.
+
+The same command gives you a live interactive tree at your desk, and a CI log
+plus a browsable report link on the build server:
+
+![the same mux command rendering a live tree locally and a CI log with a report link under REPORTERS_PROFILE=ci](https://raw.githubusercontent.com/MoLow/reporters/5393ed7b104f42d90bb930ad89854d8fdff6785b/packages/mux/assets/cli.gif)
+
+That `report at` link is [`@reporters/web`](https://github.com/MoLow/reporters/tree/main/packages/web)'s
+run being delivered through a sink — it opens as an interactive tree in the
+browser (**[live demo](https://molow.github.io/reporters/?src=https://raw.githubusercontent.com/MoLow/reporters/5393ed7b104f42d90bb930ad89854d8fdff6785b/packages/web/assets/demo-run.ndjson)**):
+
+[![the browser viewer rendering the delivered run](https://raw.githubusercontent.com/MoLow/reporters/5393ed7b104f42d90bb930ad89854d8fdff6785b/packages/web/assets/viewer.png)](https://molow.github.io/reporters/?src=https://raw.githubusercontent.com/MoLow/reporters/5393ed7b104f42d90bb930ad89854d8fdff6785b/packages/web/assets/demo-run.ndjson)
+
+## Usage
+
+```bash
+node --test-reporter=@reporters/mux --test
+```
+
+## Config
+
+Create a `mux.config.js` (or `.mjs`/`.ts`), discovered by walking up from the
+current directory. It default-exports a map of profile name → routes:
+
+```js
+import { httpServer } from '@reporters/web/sink';
+import { gist } from '@reporters/sink';
+import live from '@reporters/live';
+
+export default {
+  local: [
+    { reporter: live,             sink: 'stdout' },
+    { reporter: '@reporters/web', sink: httpServer() }, // serves localhost, opens the browser
+  ],
+  ci: [
+    { reporter: '@reporters/gh',  sink: 'stdout' },
+    { reporter: '@reporters/web', sink: gist() }, // uploads the run, links the hosted viewer
+  ],
+};
+```
+
+Both async-generator reporters (like `@reporters/live`, `@reporters/web`) and
+Transform-stream reporters (like `@reporters/gh`) are supported as route reporters.
+
+### Route fields
+
+- `reporter` — a reporter function, a Transform/Duplex stream, or a module specifier `mux` will `import()`.
+- `options` — optional 2nd-arg object passed to the reporter (e.g.
+  `@reporters/web` accepts `{ open: boolean }`); most reporters need none.
+- `sink` — `'stdout'`, `'stderr'`, a file path, or a `Sink` object.
+- `open` — open the sink's viewer URL in a browser. Defaults to on locally, off
+  in CI. `open: false` opts out; `REPORTERS_OPEN=1|0` forces it.
+
+### Profile resolution
+
+`REPORTERS_PROFILE` if set; otherwise `ci` when a CI environment is detected
+(`CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, `BUILDKITE`, …), else `local`. Profile
+names are yours — add a `nightly` or `benchmark` profile and select it with
+`REPORTERS_PROFILE=nightly`.
+
+## Sinks
+
+A sink decides where a reporter's bytes go — and, for viewers, where a human
+looks:
+
+```ts
+interface Sink {
+  start?(): Promise<void>;
+  write(chunk: string | Buffer): void | Promise<void>;
+  flush?(): Promise<void>;
+  close(): Promise<void>;
+  viewerUrl?(): string | undefined;
+}
+```
+
+Built in: `'stdout'`, `'stderr'`, and file paths. Beyond those:
+
+- [`@reporters/web`](https://github.com/MoLow/reporters/tree/main/packages/web)
+  ships `httpServer()` — serves the viewer on localhost over the growing run.
+- [`@reporters/sink`](https://github.com/MoLow/reporters/tree/main/packages/sink)
+  ships `gist()` and `s3()` — upload the run where a browser can fetch it, so
+  the hosted viewer can render CI runs — plus `remoteSink()` to bring your own
+  transport.
+
+When a sink exposes a `viewerUrl`, mux prints `report at <url>` to stderr and —
+on GitHub Actions — adds a **View report** link to the job summary.

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { Duplex } from 'node:stream';
+
+type DiagnosticLevel = 'info' | 'warn' | 'error';
+/** The fields of a `node:test` reporter event that the store consumes. */
+interface TestEventData {
+    name?: string;
+    nesting?: number;
+    file?: string;
+    testId?: number;
+    parentId?: number;
+    line?: number;
+    column?: number;
+    tags?: string[];
+    todo?: boolean | string;
+    skip?: boolean | string;
+    message?: string;
+    level?: DiagnosticLevel;
+    count?: number;
+    type?: 'suite' | 'test';
+    details?: {
+        duration_ms?: number;
+        error?: unknown;
+        type?: string;
+        passed?: boolean;
+    };
+    counts?: Record<string, number>;
+    duration_ms?: number;
+    success?: boolean;
+}
+interface TestEvent {
+    type: string;
+    data: TestEventData;
+}
+
+interface Sink {
+    /** Start servers/streams; resolves once ready to receive writes. */
+    start?(): Promise<void>;
+    write(chunk: string | Buffer): void | Promise<void>;
+    /** Periodic durability hook (e.g. a future s3 re-PUT). */
+    flush?(): Promise<void>;
+    /** The run ended; release resources. */
+    close(): Promise<void>;
+    /** How a human views what was written, if anything. */
+    viewerUrl?(): string | undefined;
+}
+type SinkSpec = string | Sink;
+
+/** A `node:test` reporter: pure transform from events to output bytes. */
+type Reporter = (source: AsyncIterable<TestEvent>, options?: unknown) => AsyncGenerator<string>;
+interface Route {
+    /** A reporter: a generator function, a Duplex/Transform stream instance, or a
+     *  module specifier `mux` will `import()` to either shape. */
+    reporter: Reporter | Duplex | string;
+    /** Optional 2nd-arg passed to the reporter (only for output-format variants). */
+    options?: unknown;
+    /** Where the reporter's bytes go: 'stdout' | 'stderr' | a file path | a Sink. */
+    sink: SinkSpec;
+    /** Open the sink's viewer URL in a browser. Defaults to on locally, off in CI. */
+    open?: boolean;
+}
+/** Map of profile name -> the routes active under that profile. */
+type MuxConfig = Record<string, Route[]>;
+
+/** A reporter function, a stream instance, or a module specifier to `import()`. */
+declare function resolveReporter(reporter: Reporter | Duplex | string): Promise<Reporter | Duplex>;
+/**
+ * Run every route in `config`'s active profile against `source`: tee the events,
+ * run each route's reporter, pipe its bytes into the route's sink, and open the
+ * sink's viewer URL when the gate allows. `open` is injected for testability.
+ */
+declare function runRoutes(source: AsyncIterable<TestEvent>, config: MuxConfig, env?: NodeJS.ProcessEnv, open?: (url: string) => void): Promise<void>;
+/**
+ * The routing reporter. Reads `mux.config`, resolves the active profile, and
+ * fans the event stream out to each route's reporter + sink. It yields nothing
+ * to Node — all output flows through the sinks it drives directly.
+ */
+declare function mux(source: AsyncIterable<TestEvent>): AsyncGenerator<string>;
+
+export { type MuxConfig, type Reporter, type Route, type Sink, type SinkSpec, mux as default, resolveReporter, runRoutes };

package/dist/index.js

@@ -0,0 +1,226 @@
+// src/index.ts
+import { Readable } from "stream";
+
+// src/config.ts
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+import { pathToFileURL } from "url";
+var CONFIG_NAMES = ["mux.config.js", "mux.config.mjs", "mux.config.ts"];
+function findConfigFile(startDir = process.cwd()) {
+  let dir = startDir;
+  for (; ; ) {
+    for (const name of CONFIG_NAMES) {
+      const candidate = join(dir, name);
+      if (existsSync(candidate)) return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+async function loadConfig(startDir = process.cwd()) {
+  const file = findConfigFile(startDir);
+  if (!file) throw new Error(`mux: no mux.config.{js,mjs,ts} found (searched up from ${startDir})`);
+  const mod = await import(pathToFileURL(file).href);
+  return mod.default ?? mod;
+}
+
+// src/profile.ts
+function isCI(env = process.env) {
+  return Boolean(
+    env.CI || env.CONTINUOUS_INTEGRATION || env.GITHUB_ACTIONS || env.GITLAB_CI || env.BUILDKITE
+  );
+}
+function resolveProfileName(env = process.env) {
+  return env.REPORTERS_PROFILE || (isCI(env) ? "ci" : "local");
+}
+function resolveProfile(config, env = process.env) {
+  const name = resolveProfileName(env);
+  const routes = config[name];
+  if (!routes) {
+    const available = Object.keys(config).join(", ") || "none";
+    throw new Error(`mux: no profile "${name}" in config (available: ${available})`);
+  }
+  return routes;
+}
+
+// src/broadcast.ts
+var AsyncQueue = class {
+  values = [];
+  waiters = [];
+  done = false;
+  failed = false;
+  error;
+  push(value) {
+    const waiter = this.waiters.shift();
+    if (waiter) waiter.resolve({ value, done: false });
+    else this.values.push(value);
+  }
+  close() {
+    this.done = true;
+    let waiter = this.waiters.shift();
+    while (waiter) {
+      waiter.resolve({ value: void 0, done: true });
+      waiter = this.waiters.shift();
+    }
+  }
+  /** Surface `err` to consumers once their buffered values have drained. */
+  fail(err) {
+    this.failed = true;
+    this.error = err;
+    let waiter = this.waiters.shift();
+    while (waiter) {
+      waiter.reject(err);
+      waiter = this.waiters.shift();
+    }
+  }
+  [Symbol.asyncIterator]() {
+    return {
+      next: () => {
+        if (this.values.length) return Promise.resolve({ value: this.values.shift(), done: false });
+        if (this.failed) return Promise.reject(this.error);
+        if (this.done) return Promise.resolve({ value: void 0, done: true });
+        return new Promise((resolve2, reject) => {
+          this.waiters.push({ resolve: resolve2, reject });
+        });
+      }
+    };
+  }
+};
+function broadcast(source, n) {
+  if (n === 0) return [];
+  const queues = Array.from({ length: n }, () => new AsyncQueue());
+  (async () => {
+    try {
+      for await (const item of source) for (const q of queues) q.push(item);
+      for (const q of queues) q.close();
+    } catch (err) {
+      for (const q of queues) q.fail(err);
+    }
+  })();
+  return queues;
+}
+
+// src/sink.ts
+import { createWriteStream } from "fs";
+import { resolve } from "path";
+function streamSink(stream) {
+  return {
+    write(chunk) {
+      stream.write(chunk);
+    },
+    async close() {
+    }
+  };
+}
+function fileSink(path) {
+  const full = resolve(path);
+  let stream;
+  return {
+    async start() {
+      stream = createWriteStream(full);
+    },
+    write(chunk) {
+      (stream ?? (stream = createWriteStream(full))).write(chunk);
+    },
+    async close() {
+      const s = stream;
+      if (!s) return;
+      await new Promise((res, rej) => {
+        s.end((err) => {
+          if (err) return rej(err);
+          return res();
+        });
+      });
+    }
+  };
+}
+function resolveSink(spec) {
+  if (typeof spec !== "string") return spec;
+  if (spec === "stdout") return streamSink(process.stdout);
+  if (spec === "stderr") return streamSink(process.stderr);
+  return fileSink(spec);
+}
+
+// src/open.ts
+import { spawn } from "child_process";
+import { appendFileSync } from "fs";
+function shouldOpen(routeOpen, env = process.env) {
+  const flag = env.REPORTERS_OPEN;
+  if (flag === "1" || flag === "true") return true;
+  if (flag === "0" || flag === "false") return false;
+  if (routeOpen === false) return false;
+  return !isCI(env);
+}
+function openCommand(url, platform = process.platform) {
+  if (platform === "darwin") return ["open", [url]];
+  if (platform === "win32") return ["cmd", ["/c", "start", "", url]];
+  return ["xdg-open", [url]];
+}
+function openInBrowser(url) {
+  const [cmd, args] = openCommand(url);
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+function announce(url, env = process.env) {
+  process.stderr.write(`
+@reporters/mux: report at ${url}
+`);
+  if (env.GITHUB_STEP_SUMMARY) {
+    try {
+      appendFileSync(env.GITHUB_STEP_SUMMARY, `
+[View report](${url})
+`);
+    } catch {
+    }
+  }
+}
+var internals = { openInBrowser, announce };
+
+// src/index.ts
+function isStreamReporter(value) {
+  return typeof value === "object" && value !== null && typeof value.pipe === "function";
+}
+async function resolveReporter(reporter) {
+  if (typeof reporter === "function" || isStreamReporter(reporter)) return reporter;
+  const mod = await import(reporter);
+  const resolved = mod.default;
+  if (typeof resolved === "function" || isStreamReporter(resolved)) return resolved;
+  throw new Error(`mux: reporter "${reporter}" must default-export a generator function or a stream`);
+}
+async function runRoutes(source, config, env = process.env, open = internals.openInBrowser) {
+  const routes = resolveProfile(config, env);
+  const streams = broadcast(source, routes.length);
+  await Promise.all(routes.map(async (route, i) => {
+    const reporter = await resolveReporter(route.reporter);
+    const sink = resolveSink(route.sink);
+    const stage = typeof reporter === "function" ? (src) => reporter(src, route.options) : reporter;
+    try {
+      if (sink.start) await sink.start();
+      const url = sink.viewerUrl?.();
+      if (url) {
+        internals.announce(url, env);
+        if (shouldOpen(route.open, env)) open(url);
+      }
+      const output = Readable.from(streams[i]).compose(stage);
+      for await (const chunk of output) await sink.write(chunk);
+      if (sink.flush) await sink.flush();
+    } finally {
+      await sink.close();
+    }
+  }));
+}
+async function* mux(source) {
+  const config = await loadConfig();
+  await runRoutes(source, config);
+}
+export {
+  mux as default,
+  resolveReporter,
+  runRoutes
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@reporters/mux",
+  "version": "1.0.0",
+  "description": "Environment-aware routing reporter for `node:test`: tee the event stream to multiple reporters and sinks",
+  "type": "module",
+  "keywords": [
+    "node:test",
+    "test",
+    "reporter",
+    "reporters",
+    "routing",
+    "multiplexer"
+  ],
+  "files": [
+    "./dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "rm -rf dist && tsup",
+    "prepack": "rm -rf dist && tsup",
+    "pretest": "rm -rf dist && tsup",
+    "test": "node --test-reporter=@reporters/mux --test"
+  },
+  "devDependencies": {
+    "@reporters/tree-core": "workspace:^",
+    "tsup": "^8.5.0",
+    "typescript": "^5.7.0"
+  },
+  "bugs": {
+    "url": "https://github.com/MoLow/reporters/issues"
+  },
+  "homepage": "https://github.com/MoLow/reporters/tree/main/packages/mux",
+  "repository": "https://github.com/MoLow/reporters.git",
+  "author": "Moshe Atlow",
+  "license": "MIT"
+}