@c9up/spectrum 0.1.3

package/src/testing/FakeLogger.ts

@@ -0,0 +1,140 @@
+/**
+ * In-memory `LogChannel` for tests — captures every `write(entry)`
+ * and exposes Adonis/Laravel-style `assertLogged` /
+ * `assertNotLogged` helpers in the same shape as Rover's
+ * `FakeMail` and Bay's `FakeQueue`.
+ *
+ * Not re-exported from the main barrel; reach via
+ * `@c9up/spectrum/testing`.
+ */
+
+import type { LogChannel, LogEntry, LogLevel } from "../types.js";
+
+export interface FakeLoggerPredicate {
+	/** Substring match against `entry.message`. */
+	containing?: string;
+	/** Custom predicate against `entry.data`. */
+	dataMatches?: (data: Record<string, unknown> | undefined) => boolean;
+}
+
+export type FakeLoggerPredicateArg =
+	| FakeLoggerPredicate
+	| ((entry: LogEntry) => boolean);
+
+export class FakeLogger implements LogChannel {
+	readonly name = "fake";
+	#captured: LogEntry[] = [];
+
+	write(entry: LogEntry): void {
+		// Deep-clone via `structuredClone` so nested objects in `data`
+		// are isolated — a shallow `{ ...entry.data }` would leak
+		// mutations of nested fields back into the captured entry.
+		this.#captured.push({
+			...entry,
+			data: entry.data ? deepClone(entry.data) : undefined,
+		});
+	}
+
+	/** Defensive snapshot of every captured entry. */
+	getLogged(): LogEntry[] {
+		return this.#captured.map((e) => ({
+			...e,
+			data: e.data ? deepClone(e.data) : undefined,
+		}));
+	}
+
+	reset(): void {
+		this.#captured = [];
+	}
+
+	assertLogged(level: LogLevel, predicate?: FakeLoggerPredicateArg): void {
+		const match = makeMatcher(level, predicate);
+		if (this.#captured.some(match)) return;
+		throw new Error(
+			`logger.assertLogged('${level}'${describePredicate(predicate)}) failed — no captured entry matches.\n${describeCaptured(this.#captured)}`,
+		);
+	}
+
+	assertNotLogged(level: LogLevel, predicate?: FakeLoggerPredicateArg): void {
+		const match = makeMatcher(level, predicate);
+		if (!this.#captured.some(match)) return;
+		throw new Error(
+			`logger.assertNotLogged('${level}'${describePredicate(predicate)}) failed — at least one captured entry matches.\n${describeCaptured(this.#captured)}`,
+		);
+	}
+}
+
+function makeMatcher(
+	level: LogLevel,
+	predicate: FakeLoggerPredicateArg | undefined,
+): (e: LogEntry) => boolean {
+	if (typeof predicate === "function") {
+		return (e) => e.level === level && predicate(e);
+	}
+	if (predicate === undefined) {
+		return (e) => e.level === level;
+	}
+	// Validate the predicate AT CONSTRUCTION, not inside the closure —
+	// Array.some short-circuits on an empty array, so a check inside
+	// the matcher would silently pass when nothing was captured.
+	if (predicate.containing === "") {
+		throw new Error(
+			"FakeLogger: `containing` predicate cannot be an empty string — it would match every captured message.",
+		);
+	}
+	return (e) => {
+		if (e.level !== level) return false;
+		if (
+			predicate.containing !== undefined &&
+			!e.message.includes(predicate.containing)
+		) {
+			return false;
+		}
+		if (predicate.dataMatches && !predicate.dataMatches(e.data)) {
+			return false;
+		}
+		return true;
+	};
+}
+
+function describePredicate(
+	predicate: FakeLoggerPredicateArg | undefined,
+): string {
+	if (predicate === undefined) return "";
+	if (typeof predicate === "function") return ", <function predicate>";
+	if (Object.keys(predicate).length === 0)
+		return ", <empty predicate (level-only)>";
+	return `, ${safeStringify(predicate)}`;
+}
+
+function describeCaptured(captured: LogEntry[]): string {
+	if (captured.length === 0) return "Captured: (none)";
+	const lines = captured.map(
+		(e, i) => `  [${i}] ${e.level} module="${e.module}" message="${e.message}"`,
+	);
+	return `Captured (${captured.length}):\n${lines.join("\n")}`;
+}
+
+/** `JSON.stringify` with circular-ref + function-field handling.
+ *  Functions render as `<function>`, circular refs as `<circular>`,
+ *  unstringifiable values as `<unstringifiable>` — so an assertion
+ *  failure message never gets eaten by a JSON throw. */
+function safeStringify(value: unknown): string {
+	const seen = new WeakSet<object>();
+	try {
+		return JSON.stringify(value, (_key, v: unknown) => {
+			if (typeof v === "function") return "<function>";
+			if (typeof v === "object" && v !== null) {
+				if (seen.has(v)) return "<circular>";
+				seen.add(v);
+			}
+			return v;
+		});
+	} catch {
+		return "<unstringifiable>";
+	}
+}
+
+function deepClone<T>(value: T): T {
+	return structuredClone(value);
+}

package/src/types.ts

@@ -0,0 +1,36 @@
+/**
+ * Spectrum types.
+ * @implements FR54, FR57
+ */
+
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+
+export const LOG_LEVEL_ORDER: Record<LogLevel, number> = {
+	trace: 0,
+	debug: 1,
+	info: 2,
+	warn: 3,
+	error: 4,
+	fatal: 5,
+};
+
+export interface LogEntry {
+	level: LogLevel;
+	message: string;
+	module: string;
+	correlationId?: string;
+	timestamp: string;
+	data?: Record<string, unknown>;
+}
+
+export interface LogChannel {
+	name: string;
+	write(entry: LogEntry): void;
+}
+
+export interface LogConfig {
+	level: LogLevel;
+	channels: LogChannel[];
+	/** Per-module log level overrides */
+	modules?: Record<string, LogLevel>;
+}