@warlock.js/logger 5.24.0 → 5.26.0

package/skills/test-logging-code/SKILL.md

@@ -1,177 +1,177 @@
----
-name: test-logging-code
-description: 'Test code that touches the logger — silence globally via log.setChannels([]) in setupFiles, assert specific log lines via a capturing LogChannel subclass (prefer it over vi.spyOn — it asserts on delivered entries, not just method calls, and isolates the shared singleton cleanly). Triggers: `log.setChannels`, `LogChannel`, `LoggingData`, `Logger`, `log.channels`; "silence logger in vitest", "assert a log line was emitted", "capture log output in tests", "test code that logs"; typical import `import { log, Logger, LogChannel, type LoggingData } from "@warlock.js/logger"`. Skip: custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing `vi.spyOn(console)`, `jest.spyOn`.'
----
-
-# Testing — code that logs, and asserting on log output
-
-Two scenarios: **silencing the logger during tests** (most common) and **asserting that a specific log line was emitted**.
-
-## Silence the logger during tests
-
-Clear every channel once, globally. No output, no file handles, no noise.
-
-```ts title="src/setupTests.ts"
-import { log } from "@warlock.js/logger";
-
-log.setChannels([]);
-```
-
-Wire it in Vitest:
-
-```ts title="vitest.config.ts"
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: {
-    setupFiles: ["src/setupTests.ts"],
-  },
-});
-```
-
-## Assert on log output — use a capturing channel
-
-Don't spy on `console.log` and don't mock `log.info` — assert on what a channel actually received instead (see "Why not spy on `log.info`?" below). The cleanest pattern is a tiny channel that records what it sees:
-
-```ts
-import { LogChannel } from "@warlock.js/logger";
-import type { LoggingData } from "@warlock.js/logger";
-
-class CapturingChannel extends LogChannel {
-  public name = "capture";
-  public terminal = false;
-  public received: LoggingData[] = [];
-  public log(data: LoggingData) { this.received.push({ ...data }); }
-}
-```
-
-### Test against the singleton
-
-```ts
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { log } from "@warlock.js/logger";
-import { createUser } from "./users";
-
-describe("createUser", () => {
-  let capture: CapturingChannel;
-  let originalChannels: typeof log.channels;
-
-  beforeEach(() => {
-    capture = new CapturingChannel();
-    originalChannels = log.channels;
-    log.channels = [capture];
-  });
-
-  afterEach(() => {
-    log.channels = originalChannels;
-  });
-
-  it("logs a success entry when the user is created", async () => {
-    await createUser({ email: "a@b.com" });
-
-    expect(capture.received).toContainEqual(
-      expect.objectContaining({
-        type: "success",
-        module: "users",
-        action: "create",
-      }),
-    );
-  });
-});
-```
-
-### Test an isolated logger (avoid touching the singleton)
-
-If the code under test accepts a logger via injection, create one per test:
-
-```ts
-import { Logger } from "@warlock.js/logger";
-
-const testLogger = new Logger();
-const capture = new CapturingChannel();
-testLogger.addChannel(capture);
-
-await createUser({ email: "a@b.com" }, testLogger);
-
-expect(capture.received[0]!.type).toBe("success");
-```
-
-No cleanup needed — the local `Logger` is garbage-collected.
-
-## Why not spy on `log.info`?
-
-`log` is a plain `Logger` instance (`export const log = new Logger()`) and every level method lives on the prototype, so `vi.spyOn(log, "info")` *does* technically work. Prefer the capturing channel anyway:
-
-- A spy on `log.info` proves the method was **called**, not that an entry was **delivered** — it skips the whole pipeline (`minLevel` floor, redaction, per-channel `levels` / `filter`). A capturing channel asserts on the entry your code under test actually produced after all of that ran.
-- The `log` singleton is shared global state. A spy you forget to `mockRestore()` leaks into the next test; swapping `log.channels` and restoring it in `afterEach` is the same amount of code and isolates cleanly.
-- Code that logs through `log.error(...)` and the bare object form `log.log({ type, ... })` both land in channels, but only the level shortcut goes through `log.info` — a channel catches both.
-
-So capture through a channel as shown above; reach for a method spy only when you specifically want to assert "this exact shortcut was invoked".
-
-## Testing a custom channel
-
-Write specs against the channel directly; don't route through `Logger`:
-
-```ts
-import { describe, it, expect, vi } from "vitest";
-import { SlackLog } from "./slack-log";
-
-describe("SlackLog", () => {
-  it("skips non-error levels", async () => {
-    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response());
-
-    const channel = new SlackLog({ webhookUrl: "https://test", levels: ["error"] });
-    await channel.log({ type: "info", module: "x", action: "y", message: "z" });
-
-    expect(fetchSpy).not.toHaveBeenCalled();
-  });
-});
-```
-
-## Testing `FileLog` and `JSONFileLog`
-
-Use real temp directories — it's the only way to exercise file IO, rotation, chunking, and JSON I/O with fidelity:
-
-```ts
-import fs from "fs";
-import os from "os";
-import path from "path";
-import { randomUUID } from "node:crypto";
-
-function tempDir() {
-  const dir = path.join(os.tmpdir(), "logger-test", randomUUID());
-  fs.mkdirSync(dir, { recursive: true });
-  return dir;
-}
-```
-
-Clean up in `afterEach(() => fs.rmSync(dir, { recursive: true, force: true }))`.
-
-## Waiting for async init
-
-`LogChannel.init()` runs inside a `setTimeout(0)`. Before asserting on post-init behavior, yield once:
-
-```ts
-const channel = new FileLog({ storagePath: tempDir() });
-await new Promise((r) => setTimeout(r, 10));
-// Now `channel.isInitialized` is true and it's safe to call `channel.log(...)` for real I/O.
-```
-
-## Testing `captureAnyUnhandledRejection`
-
-Don't actually throw unhandled rejections in tests — emit the listener directly:
-
-```ts
-captureAnyUnhandledRejection();
-process.emit("unhandledRejection", new Error("test"), Promise.resolve());
-```
-
-The `uncaughtException` path additionally calls `process.exit(1)`, so stub it (or pass `{ exitOnUncaughtException: false }`) before emitting — otherwise the emitted exception tears the test runner down:
-
-```ts
-vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
-captureAnyUnhandledRejection();
-process.emit("uncaughtException", new Error("test"), "uncaughtException");
-```
-
-See [`@warlock.js/logger/capture-unhandled-errors/SKILL.md`](@warlock.js/logger/capture-unhandled-errors/SKILL.md) for a full example.
+---
+name: test-logging-code
+description: 'Test code that touches the logger — silence globally via log.setChannels([]) in setupFiles, assert specific log lines via a capturing LogChannel subclass (prefer it over vi.spyOn — it asserts on delivered entries, not just method calls, and isolates the shared singleton cleanly). Triggers: `log.setChannels`, `LogChannel`, `LoggingData`, `Logger`, `log.channels`; "silence logger in vitest", "assert a log line was emitted", "capture log output in tests", "test code that logs"; typical import `import { log, Logger, LogChannel, type LoggingData } from "@warlock.js/logger"`. Skip: custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing `vi.spyOn(console)`, `jest.spyOn`.'
+---
+
+# Testing — code that logs, and asserting on log output
+
+Two scenarios: **silencing the logger during tests** (most common) and **asserting that a specific log line was emitted**.
+
+## Silence the logger during tests
+
+Clear every channel once, globally. No output, no file handles, no noise.
+
+```ts title="src/setupTests.ts"
+import { log } from "@warlock.js/logger";
+
+log.setChannels([]);
+```
+
+Wire it in Vitest:
+
+```ts title="vitest.config.ts"
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    setupFiles: ["src/setupTests.ts"],
+  },
+});
+```
+
+## Assert on log output — use a capturing channel
+
+Don't spy on `console.log` and don't mock `log.info` — assert on what a channel actually received instead (see "Why not spy on `log.info`?" below). The cleanest pattern is a tiny channel that records what it sees:
+
+```ts
+import { LogChannel } from "@warlock.js/logger";
+import type { LoggingData } from "@warlock.js/logger";
+
+class CapturingChannel extends LogChannel {
+  public name = "capture";
+  public terminal = false;
+  public received: LoggingData[] = [];
+  public log(data: LoggingData) { this.received.push({ ...data }); }
+}
+```
+
+### Test against the singleton
+
+```ts
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { log } from "@warlock.js/logger";
+import { createUser } from "./users";
+
+describe("createUser", () => {
+  let capture: CapturingChannel;
+  let originalChannels: typeof log.channels;
+
+  beforeEach(() => {
+    capture = new CapturingChannel();
+    originalChannels = log.channels;
+    log.channels = [capture];
+  });
+
+  afterEach(() => {
+    log.channels = originalChannels;
+  });
+
+  it("logs a success entry when the user is created", async () => {
+    await createUser({ email: "a@b.com" });
+
+    expect(capture.received).toContainEqual(
+      expect.objectContaining({
+        type: "success",
+        module: "users",
+        action: "create",
+      }),
+    );
+  });
+});
+```
+
+### Test an isolated logger (avoid touching the singleton)
+
+If the code under test accepts a logger via injection, create one per test:
+
+```ts
+import { Logger } from "@warlock.js/logger";
+
+const testLogger = new Logger();
+const capture = new CapturingChannel();
+testLogger.addChannel(capture);
+
+await createUser({ email: "a@b.com" }, testLogger);
+
+expect(capture.received[0]!.type).toBe("success");
+```
+
+No cleanup needed — the local `Logger` is garbage-collected.
+
+## Why not spy on `log.info`?
+
+`log` is a plain `Logger` instance (`export const log = new Logger()`) and every level method lives on the prototype, so `vi.spyOn(log, "info")` *does* technically work. Prefer the capturing channel anyway:
+
+- A spy on `log.info` proves the method was **called**, not that an entry was **delivered** — it skips the whole pipeline (`minLevel` floor, redaction, per-channel `levels` / `filter`). A capturing channel asserts on the entry your code under test actually produced after all of that ran.
+- The `log` singleton is shared global state. A spy you forget to `mockRestore()` leaks into the next test; swapping `log.channels` and restoring it in `afterEach` is the same amount of code and isolates cleanly.
+- Code that logs through `log.error(...)` and the bare object form `log.log({ type, ... })` both land in channels, but only the level shortcut goes through `log.info` — a channel catches both.
+
+So capture through a channel as shown above; reach for a method spy only when you specifically want to assert "this exact shortcut was invoked".
+
+## Testing a custom channel
+
+Write specs against the channel directly; don't route through `Logger`:
+
+```ts
+import { describe, it, expect, vi } from "vitest";
+import { SlackLog } from "./slack-log";
+
+describe("SlackLog", () => {
+  it("skips non-error levels", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response());
+
+    const channel = new SlackLog({ webhookUrl: "https://test", levels: ["error"] });
+    await channel.log({ type: "info", module: "x", action: "y", message: "z" });
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});
+```
+
+## Testing `FileLog` and `JSONFileLog`
+
+Use real temp directories — it's the only way to exercise file IO, rotation, chunking, and JSON I/O with fidelity:
+
+```ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { randomUUID } from "node:crypto";
+
+function tempDir() {
+  const dir = path.join(os.tmpdir(), "logger-test", randomUUID());
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+```
+
+Clean up in `afterEach(() => fs.rmSync(dir, { recursive: true, force: true }))`.
+
+## Waiting for async init
+
+`LogChannel.init()` runs inside a `setTimeout(0)`. Before asserting on post-init behavior, yield once:
+
+```ts
+const channel = new FileLog({ storagePath: tempDir() });
+await new Promise((r) => setTimeout(r, 10));
+// Now `channel.isInitialized` is true and it's safe to call `channel.log(...)` for real I/O.
+```
+
+## Testing `captureAnyUnhandledRejection`
+
+Don't actually throw unhandled rejections in tests — emit the listener directly:
+
+```ts
+captureAnyUnhandledRejection();
+process.emit("unhandledRejection", new Error("test"), Promise.resolve());
+```
+
+The `uncaughtException` path additionally calls `process.exit(1)`, so stub it (or pass `{ exitOnUncaughtException: false }`) before emitting — otherwise the emitted exception tears the test runner down:
+
+```ts
+vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
+captureAnyUnhandledRejection();
+process.emit("uncaughtException", new Error("test"), "uncaughtException");
+```
+
+See [`@warlock.js/logger/capture-unhandled-errors/SKILL.md`](@warlock.js/logger/capture-unhandled-errors/SKILL.md) for a full example.

package/skills/use-log-helpers/SKILL.md

@@ -1,66 +1,66 @@
----
-name: use-log-helpers
-description: 'Two DX shortcuts on every Logger — log.assert(condition, module, action, message, context?) logs an error when condition is falsy (free on the happy path), log.timer(module, action) returns an end-function emitting an info entry with measured duration. Triggers: `log.assert`, `log.timer`, `durationMs`; "assert an invariant via logger", "measure how long an operation took", "time a request", "log operation duration"; typical import `import { log } from "@warlock.js/logger"`. Skip: basics — `@warlock.js/logger/logger-basics/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing `console.assert`, `console.time`, `console.timeEnd`, `perf_hooks.performance.now`.'
----
-
-# Helpers — `assert`, `timer`
-
-Two small DX shortcuts on every `Logger` (and the bound `log` helper). They route through the normal log pipeline — every channel sees what they emit.
-
-## `log.assert(condition, module, action, message, context?)`
-
-Logs an `error` entry when `condition` is falsy. Genuinely free in the happy path: when the condition is truthy, the entry is never built and channels are never invoked.
-
-```ts
-log.assert(user !== null, "auth", "session", "user vanished mid-flight", {
-  sessionId,
-});
-
-// truthy → no log call
-// falsy  → equivalent to log.error("auth", "session", "user vanished...", { sessionId })
-```
-
-The level is implicitly `error` — assertions express failures, not warnings. If you need a non-error level, use `log.error` / `log.warn` directly with your own `if`.
-
-### Why not `console.assert`?
-
-`console.assert` writes to stderr only and bypasses your file/JSON channels. `log.assert` runs through the logger pipeline, so a failed assertion is captured by every persistent channel you've configured. See [`@warlock.js/logger/pick-log-channel/SKILL.md`](@warlock.js/logger/pick-log-channel/SKILL.md).
-
-## `log.timer(module, action)`
-
-Returns an end-function. Calling it emits an `info` entry with `completed in <ms>ms` and a `durationMs` field in `context`.
-
-```ts
-const end = log.timer("db", "users.findById");
-const user = await usersRepo.findById(id);
-end({ id, found: !!user });
-// ℹ info [db] [users.findById] completed in 12ms
-//   ↳ { durationMs: 12, id: "abc", found: true } (when ConsoleLog has showContext: true)
-```
-
-Common patterns:
-
-```ts
-// Around an HTTP handler
-async function handle(req) {
-  const end = log.timer("http", `${req.method} ${req.url}`);
-  try {
-    return await runHandler(req);
-  } finally {
-    end({ status: res.statusCode });
-  }
-}
-
-// Around a job
-const end = log.timer("jobs", "nightly-report");
-await report.run();
-end({ rowsProcessed: report.rowCount });
-```
-
-`end()` can be called more than once if you want intermediate checkpoints — each call emits a fresh entry with the duration measured from the original `timer()` call.
-
-### Caveats
-
-- The duration is `Date.now()` based — millisecond resolution. For sub-millisecond profiling, reach for `performance.now()` directly.
-- The end-function captures `this` at construction; calling it after the logger is reconfigured still routes through the same `Logger` instance.
-- `log.timer` shorthand binds to the singleton — see [`@warlock.js/logger/test-logging-code/SKILL.md`](@warlock.js/logger/test-logging-code/SKILL.md) for how to swap channels per test.
+---
+name: use-log-helpers
+description: 'Two DX shortcuts on every Logger — log.assert(condition, module, action, message, context?) logs an error when condition is falsy (free on the happy path), log.timer(module, action) returns an end-function emitting an info entry with measured duration. Triggers: `log.assert`, `log.timer`, `durationMs`; "assert an invariant via logger", "measure how long an operation took", "time a request", "log operation duration"; typical import `import { log } from "@warlock.js/logger"`. Skip: basics — `@warlock.js/logger/logger-basics/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing `console.assert`, `console.time`, `console.timeEnd`, `perf_hooks.performance.now`.'
+---
+
+# Helpers — `assert`, `timer`
+
+Two small DX shortcuts on every `Logger` (and the bound `log` helper). They route through the normal log pipeline — every channel sees what they emit.
+
+## `log.assert(condition, module, action, message, context?)`
+
+Logs an `error` entry when `condition` is falsy. Genuinely free in the happy path: when the condition is truthy, the entry is never built and channels are never invoked.
+
+```ts
+log.assert(user !== null, "auth", "session", "user vanished mid-flight", {
+  sessionId,
+});
+
+// truthy → no log call
+// falsy  → equivalent to log.error("auth", "session", "user vanished...", { sessionId })
+```
+
+The level is implicitly `error` — assertions express failures, not warnings. If you need a non-error level, use `log.error` / `log.warn` directly with your own `if`.
+
+### Why not `console.assert`?
+
+`console.assert` writes to stderr only and bypasses your file/JSON channels. `log.assert` runs through the logger pipeline, so a failed assertion is captured by every persistent channel you've configured. See [`@warlock.js/logger/pick-log-channel/SKILL.md`](@warlock.js/logger/pick-log-channel/SKILL.md).
+
+## `log.timer(module, action)`
+
+Returns an end-function. Calling it emits an `info` entry with `completed in <ms>ms` and a `durationMs` field in `context`.
+
+```ts
+const end = log.timer("db", "users.findById");
+const user = await usersRepo.findById(id);
+end({ id, found: !!user });
+// ℹ info [db] [users.findById] completed in 12ms
+//   ↳ { durationMs: 12, id: "abc", found: true } (when ConsoleLog has showContext: true)
+```
+
+Common patterns:
+
+```ts
+// Around an HTTP handler
+async function handle(req) {
+  const end = log.timer("http", `${req.method} ${req.url}`);
+  try {
+    return await runHandler(req);
+  } finally {
+    end({ status: res.statusCode });
+  }
+}
+
+// Around a job
+const end = log.timer("jobs", "nightly-report");
+await report.run();
+end({ rowsProcessed: report.rowCount });
+```
+
+`end()` can be called more than once if you want intermediate checkpoints — each call emits a fresh entry with the duration measured from the original `timer()` call.
+
+### Caveats
+
+- The duration is `Date.now()` based — millisecond resolution. For sub-millisecond profiling, reach for `performance.now()` directly.
+- The end-function captures `this` at construction; calling it after the logger is reconfigured still routes through the same `Logger` instance.
+- `log.timer` shorthand binds to the singleton — see [`@warlock.js/logger/test-logging-code/SKILL.md`](@warlock.js/logger/test-logging-code/SKILL.md) for how to swap channels per test.