@monochromatic-dev/module-logger 0.1.0

package/src/startup.unit.test.ts

@@ -0,0 +1,232 @@
+import { spawn, } from 'node:child_process';
+import { once, } from 'node:events';
+import {
+  mkdir,
+  mkdtemp,
+  readFile,
+  readdir,
+  rm,
+  writeFile,
+} from 'node:fs/promises';
+import { tmpdir, } from 'node:os';
+import { join, } from 'node:path';
+import { text, } from 'node:stream/consumers';
+
+import {
+  describe,
+  expect,
+  it,
+} from '@monochromatic-dev/module-test/ts';
+
+/** Built package entry used by the subprocess probe. */
+const BUILT_INDEX_PATH = join(
+  import.meta.dirname,
+  '..',
+  'dist',
+  'final',
+  'node',
+  'index.mjs',
+);
+
+/** Message logged before the probe awaits anything from the logger package. */
+const STARTUP_MESSAGE = 'startup before consumer init await';
+
+/** JSONL fragment proving the startup message reached the file sink. */
+const STARTUP_MESSAGE_FRAGMENT = `"message":${JSON.stringify(STARTUP_MESSAGE,)}`;
+
+/** Debug message used by the process-stream startup probe. */
+const DEBUG_MESSAGE = 'debug before consumer init await';
+
+/** Async-disposable temporary project for file-sink startup probes. */
+type TempProject = {
+  readonly path: string;
+  readonly scriptPath: string;
+  readonly [Symbol.asyncDispose]: () => Promise<void>;
+};
+
+/** Result captured from the probe subprocess. */
+type ProbeResult = {
+  readonly exitCode: number;
+  readonly stderr: string;
+  readonly stdout: string;
+};
+
+/**
+ * Builds a throwaway project root with `node_modules` so the file sink chooses
+ * an isolated `node_modules/.monochromatic` log directory.
+ *
+ * @param logLine - Logger call that the generated probe should execute.
+ *
+ * @returns Temporary project handle removed by `await using`.
+ */
+async function createTempProject(
+  { logLine, }: { readonly logLine: string; },
+): Promise<TempProject> {
+  const path = await mkdtemp(join(tmpdir(), 'logger-startup-',),);
+  await mkdir(
+    join(
+      path,
+      'node_modules',
+    ),
+    { recursive: true, },
+  );
+
+  /** Probe script that never imports or awaits `initPromise`. */
+  const scriptPath = join(
+    path,
+    'probe.ts',
+  );
+  /** Probe source assembled as separate lines so generated syntax stays readable. */
+  const script = [
+    `import { logger, } from ${JSON.stringify(BUILT_INDEX_PATH,)};`,
+    '',
+    logLine,
+    'await logger.flush();',
+    '',
+  ].join('\n',);
+  await writeFile(
+    scriptPath,
+    script,
+  );
+
+  return {
+    path,
+    scriptPath,
+    async [Symbol.asyncDispose](): Promise<void> {
+      await rm(path, { recursive: true, force: true, },);
+    },
+  };
+}
+
+/**
+ * Runs a probe script in its temporary project root.
+ *
+ * @param cwd - Project root used as `process.cwd()` by the file sink.
+ * @param env - Environment overrides applied to the probe process.
+ * @param scriptPath - Absolute path to the probe script.
+ *
+ * @returns Captured stdout, stderr, and exit code.
+ */
+async function runProbe(
+  {
+    cwd,
+    env = {},
+    scriptPath,
+  }: {
+    readonly cwd: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly scriptPath: string;
+  },
+): Promise<ProbeResult> {
+  // Default stdio is 'pipe', which yields a ChildProcessWithoutNullStreams so
+  // stdout/stderr are non-null Readables. The probe is a `.ts` file, so it runs
+  // through the same Node runtime used by mise test tasks.
+  const subprocess = spawn(
+    'node',
+    [scriptPath,],
+    {
+      cwd,
+      env: {
+        ...process.env,
+        ...env,
+      },
+    },
+  );
+
+  const [
+    stdout,
+    stderr,
+  ] = await Promise.all([
+    text(subprocess.stdout,),
+    text(subprocess.stderr,),
+    once(subprocess, 'close',),
+  ],);
+
+  return {
+    // After 'close' the exit code is populated; null means killed by signal.
+    exitCode: subprocess.exitCode ?? (-1),
+    stderr,
+    stdout,
+  };
+}
+
+/**
+ * Reads the single JSONL file created by the probe's file sink.
+ *
+ * @param projectPath - Temporary project root containing `node_modules`.
+ *
+ * @returns Log file contents.
+ */
+async function readOnlyLogContent({ projectPath, }: { readonly projectPath: string; },): Promise<string> {
+  const logDir = join(
+    projectPath,
+    'node_modules',
+    '.monochromatic',
+  );
+  const logFiles = await readdir(logDir,);
+  expect(logFiles.length,)
+    .toBe(1,);
+
+  /** Single log file emitted by one probe process. */
+  const [logFile,] = logFiles;
+  if (logFile === undefined)
+    throw new Error('Expected logger to create a log file.',);
+
+  return await readFile(
+    join(
+      logDir,
+      logFile,
+    ),
+    'utf8',
+  );
+}
+
+await describe({
+  name: 'logger startup initialization',
+  children: [
+    it({
+      name: 'delivers startup records to file sink without awaiting initPromise',
+      fn: async () => {
+        await using project = await createTempProject({
+          logLine: `logger.info(${JSON.stringify(STARTUP_MESSAGE,)},);`,
+        },);
+
+        const result = await runProbe({
+          cwd: project.path,
+          scriptPath: project.scriptPath,
+        },);
+        expect(result.exitCode,)
+          .toBe(0,);
+        expect(result.stderr,)
+          .toBe('',);
+        expect(result.stdout,)
+          .toContain(STARTUP_MESSAGE,);
+
+        const content = await readOnlyLogContent({ projectPath: project.path, },);
+        expect(content,)
+          .toContain(STARTUP_MESSAGE_FRAGMENT,);
+      },
+    },),
+
+    it({
+      name: 'writes debug startup records to stderr when process stderr is available',
+      fn: async () => {
+        await using project = await createTempProject({
+          logLine: `logger.debug(${JSON.stringify(DEBUG_MESSAGE,)},);`,
+        },);
+
+        const result = await runProbe({
+          cwd: project.path,
+          env: { MONOCHROMATIC_VERBOSE: 'true', },
+          scriptPath: project.scriptPath,
+        },);
+        expect(result.exitCode,)
+          .toBe(0,);
+        expect(result.stdout,)
+          .toBe('',);
+        expect(result.stderr,)
+          .toContain(DEBUG_MESSAGE,);
+      },
+    },),
+  ],
+},);

package/src/tagged.ts

@@ -0,0 +1,74 @@
+import { logger as defaultLogger, } from './logger.ts';
+import type { Logger, } from './types.ts';
+
+/**
+ * Wraps a logger so every message is prefixed with `[tag] `.
+ * Callers typically pass `myFn.name` as tag to keep prefixes
+ * in sync with refactors.
+ *
+ * @param tag - Prefix string inserted before each message
+ *
+ * @param l - Base logger to wrap; defaults to the module-level {@link logger}
+ *   singleton
+ *
+ * @returns Logger whose methods prepend `[tag] ` to every message
+ *
+ * @example
+ * ```ts
+ * import { tagged } from '\@monochromatic-dev/module-logger/tagged';
+ *
+ * function handleRequest({ l }: { l: Logger }): void {
+ *   l.info('received');
+ * }
+ *
+ * handleRequest({ l: tagged({ tag: handleRequest.name }) });
+ * // logs: [handleRequest] received
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Composing tags: the outermost wrap (`l2` here) prepends to the message
+ * // last, so its tag ends up rightmost. The innermost wrap (`l1`) hits the
+ * // underlying logger first, so its tag is leftmost. The chain reads
+ * // root-first: outer wrap = inner tag position.
+ * const l1 = tagged({ tag: 'http' });
+ * const l2 = tagged({ tag: 'retry', l: l1 });
+ * l2.info('attempt 3');
+ * // logs: [http] [retry] attempt 3
+ * ```
+ */
+export function tagged({
+  tag,
+  l = defaultLogger,
+}: {
+  readonly l?: Logger;
+  readonly tag: string;
+},): Logger {
+  /**
+   * Bracketed tag prepended to every message; built once so each log call does one concatenation.
+   */
+  const prefix = `[${tag}] `;
+  return {
+    debug: function debug(message: string,): void {
+      l.debug(`${prefix}${message}`,);
+    },
+    error: function error(message: string,): void {
+      l.error(`${prefix}${message}`,);
+    },
+    fatal: function fatal(message: string,): void {
+      l.fatal(`${prefix}${message}`,);
+    },
+    flush: function flush(): Promise<void> {
+      return l.flush();
+    },
+    info: function info(message: string,): void {
+      l.info(`${prefix}${message}`,);
+    },
+    trace: function trace(message: string,): void {
+      l.trace(`${prefix}${message}`,);
+    },
+    warn: function warn(message: string,): void {
+      l.warn(`${prefix}${message}`,);
+    },
+  };
+}

package/src/tagged.unit.test.ts

@@ -0,0 +1,211 @@
+import {
+  describe,
+  expect,
+  it,
+} from '@monochromatic-dev/module-test/ts';
+import {
+  tagged,
+  type Level,
+  type Logger,
+} from '@monochromatic-dev/module-logger';
+
+/**
+ * Every log level paired with the message body the all-levels test sends
+ * through each, so the assertion can be built from one source of truth.
+ */
+const LEVEL_MESSAGES: readonly { readonly level: Level; readonly message: string; }[] = [
+  {
+    level: 'trace',
+    message: 'a',
+  },
+  {
+    level: 'debug',
+    message: 'b',
+  },
+  {
+    level: 'info',
+    message: 'c',
+  },
+  {
+    level: 'warn',
+    message: 'd',
+  },
+  {
+    level: 'error',
+    message: 'e',
+  },
+  {
+    level: 'fatal',
+    message: 'f',
+  },
+];
+
+/**
+ * Builds a stub logger whose methods record the messages they receive
+ * and whose `flush` is a trivial resolved promise. Used to verify the
+ * tagged wrapper's message prefixing and `flush` forwarding without
+ * touching the default multi-sink singleton.
+ *
+ * @returns Object containing the stub logger and the recorded message list.
+ */
+function createStubLogger(): {
+  l: Logger;
+  messages: { level: string; message: string; }[];
+  flushCalls: number;
+} {
+  const messages: { level: string; message: string; }[] = [];
+  const counters: { flushCalls: number; } = { flushCalls: 0, };
+  const l: Logger = {
+    debug: function debug(message: string,): void {
+      messages.push({ level: 'debug', message, },);
+    },
+    error: function error(message: string,): void {
+      messages.push({ level: 'error', message, },);
+    },
+    fatal: function fatal(message: string,): void {
+      messages.push({ level: 'fatal', message, },);
+    },
+    flush: function flush(): Promise<void> {
+      counters.flushCalls++;
+      return Promise.resolve();
+    },
+    info: function info(message: string,): void {
+      messages.push({ level: 'info', message, },);
+    },
+    trace: function trace(message: string,): void {
+      messages.push({ level: 'trace', message, },);
+    },
+    warn: function warn(message: string,): void {
+      messages.push({ level: 'warn', message, },);
+    },
+  };
+  return {
+    get flushCalls() {
+      return counters.flushCalls;
+    },
+    l,
+    messages,
+  };
+}
+
+await describe({
+  name: 'tagged logger wrapper',
+  children: [
+    it({
+      name: 'prepends [tag] to each level method',
+      fn: async () => {
+        const stub = createStubLogger();
+        const wrapped = tagged({
+          tag: 'scope',
+          l: stub.l,
+        },);
+
+        wrapped.info('hello',);
+        wrapped.warn('careful',);
+
+        expect(stub.messages,)
+          .toEqual([
+            { level: 'info', message: '[scope] hello', },
+            { level: 'warn', message: '[scope] careful', },
+          ],);
+      },
+    },),
+
+    it({
+      name: 'flush delegates to the inner logger without tagging',
+      fn: async () => {
+        const stub = createStubLogger();
+        const wrapped = tagged({
+          tag: 'scope',
+          l: stub.l,
+        },);
+
+        expect(stub.flushCalls,)
+          .toBe(0,);
+        await wrapped.flush();
+        expect(stub.flushCalls,)
+          .toBe(1,);
+        // flush must not leak into the message stream
+        expect(stub.messages.length,)
+          .toBe(0,);
+      },
+    },),
+
+    it({
+      name: 'prepends [tag] across all six level methods',
+      fn: async () => {
+        const stub = createStubLogger();
+        const wrapped = tagged({
+          tag: 'svc',
+          l: stub.l,
+        },);
+
+        LEVEL_MESSAGES.forEach(function logAtLevel({
+          level,
+          message,
+        },) {
+          wrapped[level](message,);
+        },);
+
+        expect(stub.messages,)
+          .toEqual(LEVEL_MESSAGES.map(function toTagged({
+            level,
+            message,
+          },) {
+            return {
+              level,
+              message: `[svc] ${message}`,
+            };
+          },),);
+      },
+    },),
+
+    it({
+      name: 'composes nested tags root-first',
+      fn: async () => {
+        const stub = createStubLogger();
+        // Inner wrap hits the underlying logger first (leftmost tag); outer
+        // wrap prepends last (rightmost tag), so the stub sees them root-first.
+        const inner = tagged({
+          tag: 'http',
+          l: stub.l,
+        },);
+        const outer = tagged({
+          tag: 'retry',
+          l: inner,
+        },);
+
+        outer.info('attempt 3',);
+
+        expect(stub.messages,)
+          .toEqual([
+            {
+              level: 'info',
+              message: '[http] [retry] attempt 3',
+            },
+          ],);
+      },
+    },),
+
+    it({
+      name: 'wraps the default singleton logger when no parent is given',
+      fn: async () => {
+        // Exercises the `l = defaultLogger` parameter default: a tag with no
+        // explicit parent returns a usable wrapper whose calls reach the
+        // singleton without throwing and whose flush delegates to it.
+        const wrapped = tagged({ tag: 'standalone', },);
+
+        expect(typeof wrapped.info,)
+          .toBe('function',);
+        expect(function logThroughDefault() {
+          wrapped.info('via default logger',);
+        },)
+          .not
+          .toThrow();
+        await expect(wrapped.flush(),)
+          .resolves
+          .toBeUndefined();
+      },
+    },),
+  ],
+},);

package/src/types.ts

@@ -0,0 +1,78 @@
+/**
+ * Log severity levels ordered from least to most severe.
+ */
+export type Level = 'debug' | 'error' | 'fatal' | 'info' | 'trace' | 'warn';
+
+/**
+ * Structured log record written to sinks.
+ */
+export type LogRecord = {
+  readonly level: Level;
+  readonly message: string;
+  readonly timestamp: number;
+};
+
+/**
+ * Optional drain hook for sinks that buffer records internally.
+ * Called via logger-level {@link Logger.flush} to force buffered work
+ * through before a process exit, critical error boundary, or assertion.
+ *
+ * Always async: sinks whose drain is synchronous return an
+ * already-resolved promise so callers `await` uniformly. A `void` arm is
+ * not used; under the `no-optional-escape` rule `T | void` is a banned
+ * fake-optional encoding, and there is no real synchronous value to carry.
+ */
+export type SinkFlush = () => Promise<void>;
+
+/**
+ * Verification function that checks if a sink backend is available.
+ * May run setup side effects (resolving a log path, opening a writable
+ * stream) and reports whether the backend is usable. A sink whose
+ * verification resolves `false` (or rejects) is dropped by the logger and
+ * receives no further records.
+ *
+ * Always async, matching `write` and `flush`: a synchronous check returns an
+ * already-resolved promise (`Promise.resolve(check)`) so the logger awaits
+ * verification uniformly with no sync/async branch.
+ */
+export type Verify = () => Promise<boolean>;
+
+/**
+ * Sink that receives log records. A sink is a self-describing adapter: it
+ * carries everything the logger must know to use it, namely how to
+ * `verify` its backend is available, how to `write` a record, and
+ * optionally how to `flush` buffered work. Holding `verify` on the sink
+ * (rather than as a sibling export the logger pairs by hand) lets the
+ * logger treat a registry as a plain `Sink[]` and lets a test supply one
+ * self-contained fake.
+ *
+ * Sinks that buffer records (e.g. microtask-batched console) may
+ * expose a `flush` hook so callers can force emission on demand.
+ *
+ * `write` is always async: a synchronous sink does its work eagerly and
+ * returns an already-resolved promise, so the logger observes a uniform
+ * `Promise<void>`. A rejected write is handled per sink and does not
+ * disable the backend; only a failed `verify` drops a sink. A `void` arm
+ * is not used, for the reason stated on {@link SinkFlush}.
+ */
+export type Sink = {
+  readonly flush?: SinkFlush;
+  readonly verify: Verify;
+  readonly write: (record: LogRecord,) => Promise<void>;
+};
+
+/**
+ * Logger interface with 6 log levels plus `flush` for startup and sink drains.
+ * `flush()` resolves once startup verification has completed, tracked sink
+ * writes have settled, and every available sink's own {@link SinkFlush} hook
+ * has settled. Safe to call even when no sink buffers.
+ */
+export type Logger = {
+  readonly debug: (message: string,) => void;
+  readonly error: (message: string,) => void;
+  readonly fatal: (message: string,) => void;
+  readonly flush: () => Promise<void>;
+  readonly info: (message: string,) => void;
+  readonly trace: (message: string,) => void;
+  readonly warn: (message: string,) => void;
+};