reporter updates to simplify things a bit

Author: JasonVMo

incubator/reporter/eslint.config.js

@@ -1,4 +1 @@
-import config from "@rnx-kit/eslint-config";
-
-// eslint-disable-next-line no-restricted-exports
-export default config;
+module.exports = require("@rnx-kit/eslint-config");

incubator/reporter/package.json

@@ -4,6 +4,8 @@
   "description": "EXPERIMENTAL - USE WITH CAUTION - reporter",
   "homepage": "https://github.com/microsoft/rnx-kit/tree/main/incubator/reporter#readme",
   "license": "MIT",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "author": {
     "name": "Microsoft Open Source",
     "email": "microsoftopensource@users.noreply.github.com"

incubator/reporter/src/events.ts

@@ -0,0 +1,62 @@
+import { channel, subscribe, unsubscribe } from "node:diagnostics_channel";
+import type { ErrorEvent, SessionData } from "./types";
+
+/** @internal */
+export const errorEvent = createEventHandler<ErrorEvent>("rnx-reporter:errors");
+
+/** @internal */
+export const startEvent = createEventHandler<SessionData>("rnx-reporter:start");
+
+/** @internal */
+export const finishEvent = createEventHandler<SessionData>("rnx-reporter:end");
+
+/**
+ * Typed wrapper around managing events sent through node's diagnostics channel
+ * @param name friendly name of the event, will be turned into a symbol for containment
+ * @returns a set of functions that can be used to listen for and send events
+ */
+export function createEventHandler<T>(name: string) {
+  const eventName = Symbol(name);
+  const eventChannel = channel(eventName);
+
+  return {
+    subscribe: (callback: (event: T) => void) => {
+      const handler = (event: unknown, name: symbol | string) => {
+        if (name === eventName) {
+          callback(event as T);
+        }
+      };
+      subscribe(eventName, handler);
+      return () => unsubscribe(eventName, handler);
+    },
+    hasSubscribers: () => eventChannel.hasSubscribers,
+    publish: (event: T) => eventChannel.publish(event),
+  };
+}
+
+/**
+ * Listen for reporter start events, sent when reporters or tasks are initiated
+ * @param callback called when an error event is sent
+ * @returns a function to unsubscribe from the event
+ */
+export function subscribeToStart(callback: (event: SessionData) => void) {
+  return startEvent.subscribe(callback);
+}
+
+/**
+ * Listen for reporter finish events, sent when reporters or tasks are completed
+ * @param callback called when an error event is sent
+ * @returns a function to unsubscribe from the event
+ */
+export function subscribeToFinish(callback: (event: SessionData) => void) {
+  return finishEvent.subscribe(callback);
+}
+
+/**
+ * Listen for reporter error events
+ * @param callback called when an error event is sent
+ * @returns a function to unsubscribe from the event
+ */
+export function subscribeToError(callback: (event: ErrorEvent) => void) {
+  return errorEvent.subscribe(callback);
+}

incubator/reporter/src/formatting.ts

@@ -1,81 +1,153 @@
-import { stripVTControlCharacters } from "node:util";
+import chalk from "chalk";
+import {
+  inspect,
+  type InspectOptions,
+  stripVTControlCharacters,
+} from "node:util";
+import { allLogLevels } from "./levels.ts";
 import type {
   ColorSettings,
   DeepPartial,
   FormatHelper,
-  ReporterSettings,
+  FormattingOptions,
+  FormattingSettings,
 } from "./types.ts";
 
 export function noChange<T>(arg: T) {
   return arg;
 }
 
-function asObject<T extends object>(item: unknown): T | undefined {
-  if (item && typeof item === "object" && !Array.isArray(item)) {
-    return item as T;
+export type Formatting = FormattingSettings & {
+  format: FormatHelper;
+};
+
+const defaultFormatSettings: FormattingSettings = {
+  inspectOptions: {
+    colors: true,
+    depth: 2,
+    compact: true,
+  },
+  colors: {
+    error: { prefix: chalk.red.bold },
+    warn: { prefix: chalk.yellowBright.bold },
+    log: {},
+    verbose: { text: chalk.dim },
+    labels: chalk.bold,
+    pkgName: chalk.bold.cyan,
+    pkgScope: chalk.bold.blue,
+    path: chalk.blue,
+    duration: chalk.green,
+    durationUnits: chalk.greenBright,
+  },
+  prefixes: {
+    error: "ERROR: ⛔",
+    warn: "WARNING: ⚠️",
+  },
+};
+
+const defaultFormatting: Formatting = {
+  ...defaultFormatSettings,
+  format: createFormatHelper(defaultFormatSettings),
+};
+
+export function getFormatting(
+  overrides?: FormattingOptions,
+  baseline: Formatting = defaultFormatting
+): Formatting {
+  if (overrides) {
+    const { colors, inspectOptions, prefixes } = overrides;
+    const rebuildFormat = colors || inspectOptions;
+
+    // if settings have changed, create a new formatting object
+    if (rebuildFormat || prefixes) {
+      const result = {
+        colors: mergeColors(baseline.colors, colors),
+        inspectOptions: mergeInspectOptions(
+          baseline.inspectOptions,
+          inspectOptions
+        ),
+        prefixes: mergePrefixes(baseline.prefixes, prefixes),
+        format: baseline.format,
+      };
+      // update the format helper if needed, otherwise carry it forward
+      if (rebuildFormat) {
+        result.format = createFormatHelper(result);
+      }
+      return result;
+    }
   }
-  return undefined;
+  return baseline;
 }
 
-/**
- * Deep merges two objects, applying the source object properties to the target object.
- * @param target the object to merge into
- * @param source the object to merge from
- * @param immutable if true, the target object will not be modified, instead a new object will be returned
- * @returns either target with applied updates (if !immutable) or a new object with the merged settings
- */
-export function mergeSettings<T extends object>(
-  target: T,
-  source?: DeepPartial<T>,
-  immutable?: boolean
-): T {
-  if (!source) {
-    return target;
-  }
-  if (immutable) {
-    target = { ...target };
+export function updateDefaultFormatting(options?: FormattingOptions) {
+  const newDefault = getFormatting(options);
+  if (newDefault !== defaultFormatting) {
+    defaultFormatting.colors = newDefault.colors;
+    defaultFormatting.inspectOptions = newDefault.inspectOptions;
+    defaultFormatting.prefixes = newDefault.prefixes;
+    defaultFormatting.format = newDefault.format;
   }
-  for (const key in source) {
-    if (source[key] !== undefined) {
-      const objValue = asObject(source[key]);
-      const objTarget = asObject(target[key]);
-      if (objValue && objTarget) {
-        target[key] = mergeSettings(
-          objTarget,
-          objValue,
-          immutable
-        ) as T[Extract<keyof T, string>];
-      } else {
-        target[key] = source[key] as T[Extract<keyof T, string>];
+}
+
+export function disableColors() {
+  const disableMsgType = { text: stripVTControlCharacters };
+  updateDefaultFormatting({
+    inspectOptions: { colors: false },
+    colors: {
+      error: disableMsgType,
+      warn: disableMsgType,
+      log: disableMsgType,
+      verbose: disableMsgType,
+    },
+  });
+}
+
+export function defaultColors(): Readonly<ColorSettings> {
+  return defaultFormatting.colors;
+}
+
+export function defaultFormat(): Readonly<FormatHelper> {
+  return defaultFormatting.format;
+}
+
+function mergePrefixes(
+  base: FormattingSettings["prefixes"],
+  override?: Partial<FormattingSettings["prefixes"]>
+) {
+  return override ? { ...base, ...override } : base;
+}
+
+function mergeInspectOptions(
+  base: InspectOptions,
+  overrides?: Partial<InspectOptions>
+): InspectOptions {
+  return overrides ? { ...base, ...overrides } : base;
+}
+
+function mergeColors(
+  base: ColorSettings,
+  overrides?: DeepPartial<ColorSettings>
+): ColorSettings {
+  if (overrides) {
+    const result = { ...base, ...overrides };
+    for (const level of allLogLevels) {
+      if (overrides[level]) {
+        result[level] = { ...base[level], ...overrides[level] };
       }
     }
   }
-  return target;
+  return base;
 }
 
-const emptyMsgColors = { text: stripVTControlCharacters };
-
-export const disableColorOptions: DeepPartial<ReporterSettings> = {
-  inspectOptions: { colors: false },
-  color: {
-    message: {
-      default: emptyMsgColors,
-      error: emptyMsgColors,
-      warn: emptyMsgColors,
-      log: emptyMsgColors,
-      verbose: emptyMsgColors,
-    },
-  },
-};
-
-export function createFormatHelper(colorSettings: ColorSettings): FormatHelper {
-  const { path: colorPath } = colorSettings;
+export function createFormatHelper(settings: FormattingSettings): FormatHelper {
+  const { colors, inspectOptions } = settings;
   return {
-    packageFull: (pkg: string) => formatPackageName(colorSettings, pkg),
+    packageFull: (pkg: string) => formatPackageName(colors, pkg),
     packageParts: (name: string, scope?: string) =>
-      formatPackageParts(colorSettings, name, scope),
-    path: (pathValue: string) => colorPath(pathValue),
-    duration: (time: number) => formatDuration(colorSettings, time),
+      formatPackageParts(colors, name, scope),
+    path: (pathValue: string) => colors.path(pathValue),
+    duration: (time: number) => formatDuration(colors, time),
+    serialize: (args: unknown[]) => serializeArgs(inspectOptions, args),
   };
 }
 
@@ -123,3 +195,21 @@ function formatPackageParts(
   const { pkgName = noChange, pkgScope = noChange } = colors;
   return scope ? `${pkgScope(scope)}/${pkgName(name)}` : pkgName(name);
 }
+
+/**
+ * @param inspectOptions options for node:util.inspect, used to format the arguments, same as console.log
+ * @param args args list to serialize
+ * @returns a single string with arguments joined together with spaces, terminated with a newline
+ */
+export function serializeArgs(
+  inspectOptions: InspectOptions,
+  args: unknown[]
+): string {
+  let msg = args
+    .map((arg) =>
+      typeof arg === "string" ? arg : inspect(arg, inspectOptions)
+    )
+    .join(" ");
+  msg += "\n";
+  return msg;
+}

incubator/reporter/src/index.ts

@@ -1,35 +1,31 @@
 import { checkPerformanceEnv } from "./performance.ts";
 import { ReporterImpl } from "./reporter.ts";
-import type {
-  DeepPartial,
-  Reporter,
-  ReporterOptions,
-  ReporterSettings,
-} from "./types.ts";
+import type { CustomData, Reporter, ReporterOptions } from "./types.ts";
 
+export {
+  subscribeToError,
+  subscribeToFinish,
+  subscribeToStart,
+} from "./events.ts";
+export {
+  defaultColors,
+  defaultFormat,
+  disableColors,
+  updateDefaultFormatting,
+} from "./formatting.ts";
 export { enablePerformanceTracing } from "./performance.ts";
-export { onCompleteEvent, onErrorEvent, onStartEvent } from "./reporter.ts";
 export type {
-  CompleteEvent,
   ErrorEvent,
-  EventSource,
+  LogLevel,
   Reporter,
   ReporterOptions,
-  ReporterSettings,
+  SessionData,
   TaskOptions,
 } from "./types.ts";
 
-export function createReporter(options: ReporterOptions): Reporter {
+export function createReporter<T extends CustomData = CustomData>(
+  options: ReporterOptions<T>
+): Reporter<T> {
   checkPerformanceEnv();
-  return new ReporterImpl(options);
-}
-
-export function updateDefaultReporterSettings(
-  options: DeepPartial<ReporterSettings>
-): void {
-  ReporterImpl.updateDefaults(options);
-}
-
-export function disableColors(): void {
-  ReporterImpl.disableColors();
+  return new ReporterImpl<T>(options);
 }