@mantiq/logging 0.0.1

package/README.md

@@ -0,0 +1,19 @@
+# @mantiq/logging
+
+Channel-based logging for MantiqJS — console, file, daily rotation, and stack drivers.
+
+Part of [MantiqJS](https://github.com/abdullahkhan/mantiq) — a batteries-included TypeScript web framework for Bun.
+
+## Installation
+
+```bash
+bun add @mantiq/logging
+```
+
+## Documentation
+
+See the [MantiqJS repository](https://github.com/abdullahkhan/mantiq) for full documentation.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@mantiq/logging",
+  "version": "0.0.1",
+  "description": "Channel-based logging",
+  "type": "module",
+  "license": "MIT",
+  "author": "Abdullah Khan",
+  "homepage": "https://github.com/abdullahkhan/mantiq/tree/main/packages/logging",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/abdullahkhan/mantiq.git",
+    "directory": "packages/logging"
+  },
+  "bugs": {
+    "url": "https://github.com/abdullahkhan/mantiq/issues"
+  },
+  "keywords": [
+    "mantiq",
+    "mantiqjs",
+    "bun",
+    "typescript",
+    "framework",
+    "logging"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@mantiq/core": "workspace:*"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5.7.0"
+  }
+}

package/src/LogManager.ts

@@ -0,0 +1,133 @@
+import type { DriverManager } from '@mantiq/core'
+import type { LogLevel, LoggerDriver, LogConfig, ChannelConfig, LogFormatter } from './contracts/Logger.ts'
+import { ConsoleDriver } from './drivers/ConsoleDriver.ts'
+import { FileDriver } from './drivers/FileDriver.ts'
+import { DailyDriver } from './drivers/DailyDriver.ts'
+import { StackDriver } from './drivers/StackDriver.ts'
+import { NullDriver } from './drivers/NullDriver.ts'
+import { LineFormatter } from './formatters/LineFormatter.ts'
+import { JsonFormatter } from './formatters/JsonFormatter.ts'
+
+export class LogManager implements DriverManager<LoggerDriver>, LoggerDriver {
+  private readonly config: LogConfig
+  private readonly channels = new Map<string, LoggerDriver>()
+  private readonly customCreators = new Map<string, (config: ChannelConfig) => LoggerDriver>()
+
+  constructor(config?: Partial<LogConfig>) {
+    this.config = {
+      default: config?.default ?? 'console',
+      channels: config?.channels ?? {},
+    }
+  }
+
+  // ── DriverManager ─────────────────────────────────────────────────────────
+
+  driver(name?: string): LoggerDriver {
+    const channelName = name ?? this.getDefaultDriver()
+
+    if (!this.channels.has(channelName)) {
+      this.channels.set(channelName, this.createDriver(channelName))
+    }
+
+    return this.channels.get(channelName)!
+  }
+
+  channel(name?: string): LoggerDriver {
+    return this.driver(name)
+  }
+
+  extend(name: string, factory: (config: ChannelConfig) => LoggerDriver): void {
+    this.customCreators.set(name, factory)
+  }
+
+  getDefaultDriver(): string {
+    return this.config.default
+  }
+
+  forgetChannel(name: string): void {
+    this.channels.delete(name)
+  }
+
+  forgetChannels(): void {
+    this.channels.clear()
+  }
+
+  // ── LoggerDriver (delegates to default channel) ───────────────────────────
+
+  log(level: LogLevel, message: string, context?: Record<string, any>): void {
+    this.driver().log(level, message, context)
+  }
+
+  emergency(message: string, context?: Record<string, any>): void { this.driver().emergency(message, context) }
+  alert(message: string, context?: Record<string, any>): void { this.driver().alert(message, context) }
+  critical(message: string, context?: Record<string, any>): void { this.driver().critical(message, context) }
+  error(message: string, context?: Record<string, any>): void { this.driver().error(message, context) }
+  warning(message: string, context?: Record<string, any>): void { this.driver().warning(message, context) }
+  notice(message: string, context?: Record<string, any>): void { this.driver().notice(message, context) }
+  info(message: string, context?: Record<string, any>): void { this.driver().info(message, context) }
+  debug(message: string, context?: Record<string, any>): void { this.driver().debug(message, context) }
+
+  // ── Internal ──────────────────────────────────────────────────────────────
+
+  private createDriver(name: string): LoggerDriver {
+    const channelConfig = this.config.channels[name]
+    const driverName = channelConfig?.driver ?? name
+
+    const custom = this.customCreators.get(driverName)
+    if (custom) return custom(channelConfig ?? { driver: driverName })
+
+    if (!channelConfig && driverName === 'console') {
+      return new ConsoleDriver('console', 'debug')
+    }
+
+    if (!channelConfig) {
+      throw new Error(`Logging channel "${name}" is not configured. Define it in config/logging.ts or use extend().`)
+    }
+
+    const formatter = this.resolveFormatter(channelConfig)
+
+    switch (driverName) {
+      case 'console':
+        return new ConsoleDriver(
+          name,
+          channelConfig.level ?? 'debug',
+          formatter,
+        )
+
+      case 'file':
+        return new FileDriver(
+          name,
+          channelConfig.path as string ?? 'storage/logs/mantiq.log',
+          channelConfig.level ?? 'debug',
+          formatter,
+        )
+
+      case 'daily':
+        return new DailyDriver(
+          name,
+          channelConfig.path as string ?? 'storage/logs/mantiq.log',
+          channelConfig.level ?? 'debug',
+          (channelConfig.days as number) ?? 14,
+          formatter,
+        )
+
+      case 'stack': {
+        const channelNames = (channelConfig.channels as string[]) ?? []
+        const drivers = channelNames.map((ch) => this.driver(ch))
+        return new StackDriver(drivers)
+      }
+
+      case 'null':
+        return new NullDriver()
+
+      default:
+        throw new Error(`Unsupported logging driver: "${driverName}". Use extend() to register custom drivers.`)
+    }
+  }
+
+  private resolveFormatter(config: ChannelConfig): LogFormatter | undefined {
+    if (config.formatter === 'json') return new JsonFormatter()
+    if (config.formatter === 'line') return new LineFormatter()
+    return undefined
+  }
+}

package/src/LoggingServiceProvider.ts

@@ -0,0 +1,54 @@
+import { ServiceProvider, ConfigRepository } from '@mantiq/core'
+import type { LogConfig } from './contracts/Logger.ts'
+import { LogManager } from './LogManager.ts'
+import { LOGGING_MANAGER } from './helpers/log.ts'
+
+const DEFAULT_CONFIG: LogConfig = {
+  default: 'stack',
+  channels: {
+    stack: {
+      driver: 'stack',
+      channels: ['console', 'daily'],
+    },
+    console: {
+      driver: 'console',
+      level: 'debug',
+    },
+    daily: {
+      driver: 'daily',
+      path: 'storage/logs/mantiq.log',
+      level: 'debug',
+      days: 14,
+    },
+    file: {
+      driver: 'file',
+      path: 'storage/logs/mantiq.log',
+      level: 'debug',
+    },
+    null: {
+      driver: 'null',
+    },
+  },
+}
+
+export class LoggingServiceProvider extends ServiceProvider {
+  override register(): void {
+    this.app.singleton(LogManager, (c) => {
+      const config = c.make(ConfigRepository).get<LogConfig>('logging', DEFAULT_CONFIG)
+
+      // Resolve relative log paths to absolute from app base path
+      const basePath = this.app.basePath_()
+      if (config.channels) {
+        for (const ch of Object.values(config.channels)) {
+          if (typeof ch.path === 'string' && !ch.path.startsWith('/')) {
+            ch.path = `${basePath}/${ch.path}`
+          }
+        }
+      }
+
+      return new LogManager(config)
+    })
+
+    this.app.alias(LogManager, LOGGING_MANAGER)
+  }
+}

package/src/contracts/Logger.ts

@@ -0,0 +1,49 @@
+export type LogLevel = 'emergency' | 'alert' | 'critical' | 'error' | 'warning' | 'notice' | 'info' | 'debug'
+
+export const LOG_LEVELS: Record<LogLevel, number> = {
+  emergency: 0,
+  alert: 1,
+  critical: 2,
+  error: 3,
+  warning: 4,
+  notice: 5,
+  info: 6,
+  debug: 7,
+}
+
+export interface LogEntry {
+  level: LogLevel
+  message: string
+  context: Record<string, any>
+  timestamp: Date
+  channel: string
+}
+
+export interface LogFormatter {
+  format(entry: LogEntry): string
+}
+
+export interface LoggerDriver {
+  log(level: LogLevel, message: string, context?: Record<string, any>): void
+
+  emergency(message: string, context?: Record<string, any>): void
+  alert(message: string, context?: Record<string, any>): void
+  critical(message: string, context?: Record<string, any>): void
+  error(message: string, context?: Record<string, any>): void
+  warning(message: string, context?: Record<string, any>): void
+  notice(message: string, context?: Record<string, any>): void
+  info(message: string, context?: Record<string, any>): void
+  debug(message: string, context?: Record<string, any>): void
+}
+
+export interface ChannelConfig {
+  driver: string
+  level?: LogLevel
+  formatter?: 'line' | 'json'
+  [key: string]: unknown
+}
+
+export interface LogConfig {
+  default: string
+  channels: Record<string, ChannelConfig>
+}

package/src/drivers/ConsoleDriver.ts

@@ -0,0 +1,45 @@
+import type { LogLevel, LogEntry, LogFormatter, LoggerDriver } from '../contracts/Logger.ts'
+import { LOG_LEVELS } from '../contracts/Logger.ts'
+import { LineFormatter } from '../formatters/LineFormatter.ts'
+
+export class ConsoleDriver implements LoggerDriver {
+  private readonly minLevel: number
+  private readonly formatter: LogFormatter
+  private readonly channelName: string
+
+  constructor(channel: string = 'console', minLevel: LogLevel = 'debug', formatter?: LogFormatter) {
+    this.channelName = channel
+    this.minLevel = LOG_LEVELS[minLevel]
+    this.formatter = formatter ?? new LineFormatter()
+  }
+
+  log(level: LogLevel, message: string, context: Record<string, any> = {}): void {
+    if (LOG_LEVELS[level] > this.minLevel) return
+
+    const entry: LogEntry = {
+      level,
+      message,
+      context,
+      timestamp: new Date(),
+      channel: this.channelName,
+    }
+
+    const formatted = this.formatter.format(entry)
+
+    // Use stderr for error-level and above, stdout for the rest
+    if (LOG_LEVELS[level] <= LOG_LEVELS.error) {
+      process.stderr.write(formatted + '\n')
+    } else {
+      process.stdout.write(formatted + '\n')
+    }
+  }
+
+  emergency(message: string, context?: Record<string, any>): void { this.log('emergency', message, context) }
+  alert(message: string, context?: Record<string, any>): void { this.log('alert', message, context) }
+  critical(message: string, context?: Record<string, any>): void { this.log('critical', message, context) }
+  error(message: string, context?: Record<string, any>): void { this.log('error', message, context) }
+  warning(message: string, context?: Record<string, any>): void { this.log('warning', message, context) }
+  notice(message: string, context?: Record<string, any>): void { this.log('notice', message, context) }
+  info(message: string, context?: Record<string, any>): void { this.log('info', message, context) }
+  debug(message: string, context?: Record<string, any>): void { this.log('debug', message, context) }
+}

package/src/drivers/DailyDriver.ts

@@ -0,0 +1,109 @@
+import { appendFile, mkdir, readdir, rm } from 'node:fs/promises'
+import { dirname, join, basename } from 'node:path'
+import type { LogLevel, LogEntry, LogFormatter, LoggerDriver } from '../contracts/Logger.ts'
+import { LOG_LEVELS } from '../contracts/Logger.ts'
+import { LineFormatter } from '../formatters/LineFormatter.ts'
+
+export class DailyDriver implements LoggerDriver {
+  private readonly basePath: string
+  private readonly days: number
+  private readonly minLevel: number
+  private readonly formatter: LogFormatter
+  private readonly channelName: string
+  private _lastDate: string = ''
+  private _currentPath: string = ''
+  private _dirEnsured = false
+  private _pruned = false
+
+  constructor(
+    channel: string,
+    basePath: string,
+    minLevel: LogLevel = 'debug',
+    days: number = 14,
+    formatter?: LogFormatter,
+  ) {
+    this.channelName = channel
+    this.basePath = basePath
+    this.days = days
+    this.minLevel = LOG_LEVELS[minLevel]
+    this.formatter = formatter ?? new LineFormatter()
+  }
+
+  log(level: LogLevel, message: string, context: Record<string, any> = {}): void {
+    if (LOG_LEVELS[level] > this.minLevel) return
+
+    const entry: LogEntry = {
+      level,
+      message,
+      context,
+      timestamp: new Date(),
+      channel: this.channelName,
+    }
+
+    const line = this.formatter.format(entry) + '\n'
+    void this.writeLine(line, entry.timestamp)
+  }
+
+  private async writeLine(line: string, now: Date): Promise<void> {
+    const dateStr = now.toISOString().slice(0, 10) // YYYY-MM-DD
+    if (dateStr !== this._lastDate) {
+      this._lastDate = dateStr
+      this._currentPath = this.pathForDate(dateStr)
+      this._dirEnsured = false
+    }
+
+    if (!this._dirEnsured) {
+      await mkdir(dirname(this._currentPath), { recursive: true })
+      this._dirEnsured = true
+    }
+
+    await appendFile(this._currentPath, line)
+
+    if (!this._pruned) {
+      this._pruned = true
+      void this.pruneOldFiles()
+    }
+  }
+
+  private pathForDate(dateStr: string): string {
+    // e.g., /storage/logs/mantiq-2024-03-19.log
+    const dir = dirname(this.basePath)
+    const name = basename(this.basePath, '.log')
+    return join(dir, `${name}-${dateStr}.log`)
+  }
+
+  private async pruneOldFiles(): Promise<void> {
+    const dir = dirname(this.basePath)
+    const prefix = basename(this.basePath, '.log')
+    const cutoff = Date.now() - this.days * 86400000
+
+    try {
+      const entries = await readdir(dir)
+      for (const entry of entries) {
+        // Match files like mantiq-2024-03-19.log
+        const match = entry.match(new RegExp(`^${escapeRegExp(prefix)}-(\\d{4}-\\d{2}-\\d{2})\\.log$`))
+        if (match) {
+          const fileDate = new Date(match[1]! + 'T00:00:00Z')
+          if (fileDate.getTime() < cutoff) {
+            await rm(join(dir, entry)).catch(() => {})
+          }
+        }
+      }
+    } catch {
+      // Pruning is best-effort
+    }
+  }
+
+  emergency(message: string, context?: Record<string, any>): void { this.log('emergency', message, context) }
+  alert(message: string, context?: Record<string, any>): void { this.log('alert', message, context) }
+  critical(message: string, context?: Record<string, any>): void { this.log('critical', message, context) }
+  error(message: string, context?: Record<string, any>): void { this.log('error', message, context) }
+  warning(message: string, context?: Record<string, any>): void { this.log('warning', message, context) }
+  notice(message: string, context?: Record<string, any>): void { this.log('notice', message, context) }
+  info(message: string, context?: Record<string, any>): void { this.log('info', message, context) }
+  debug(message: string, context?: Record<string, any>): void { this.log('debug', message, context) }
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}

package/src/drivers/FileDriver.ts

@@ -0,0 +1,54 @@
+import { appendFile, mkdir } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import type { LogLevel, LogEntry, LogFormatter, LoggerDriver } from '../contracts/Logger.ts'
+import { LOG_LEVELS } from '../contracts/Logger.ts'
+import { LineFormatter } from '../formatters/LineFormatter.ts'
+
+export class FileDriver implements LoggerDriver {
+  private readonly path: string
+  private readonly minLevel: number
+  private readonly formatter: LogFormatter
+  private readonly channelName: string
+  private _dirEnsured = false
+
+  constructor(channel: string, path: string, minLevel: LogLevel = 'debug', formatter?: LogFormatter) {
+    this.channelName = channel
+    this.path = path
+    this.minLevel = LOG_LEVELS[minLevel]
+    this.formatter = formatter ?? new LineFormatter()
+  }
+
+  log(level: LogLevel, message: string, context: Record<string, any> = {}): void {
+    if (LOG_LEVELS[level] > this.minLevel) return
+
+    const entry: LogEntry = {
+      level,
+      message,
+      context,
+      timestamp: new Date(),
+      channel: this.channelName,
+    }
+
+    const line = this.formatter.format(entry) + '\n'
+
+    // Fire-and-forget — logging should never block the request
+    void this.writeLine(line)
+  }
+
+  private async writeLine(line: string): Promise<void> {
+    if (!this._dirEnsured) {
+      await mkdir(dirname(this.path), { recursive: true })
+      this._dirEnsured = true
+    }
+    await appendFile(this.path, line)
+  }
+
+  emergency(message: string, context?: Record<string, any>): void { this.log('emergency', message, context) }
+  alert(message: string, context?: Record<string, any>): void { this.log('alert', message, context) }
+  critical(message: string, context?: Record<string, any>): void { this.log('critical', message, context) }
+  error(message: string, context?: Record<string, any>): void { this.log('error', message, context) }
+  warning(message: string, context?: Record<string, any>): void { this.log('warning', message, context) }
+  notice(message: string, context?: Record<string, any>): void { this.log('notice', message, context) }
+  info(message: string, context?: Record<string, any>): void { this.log('info', message, context) }
+  debug(message: string, context?: Record<string, any>): void { this.log('debug', message, context) }
+}

package/src/drivers/NullDriver.ts

@@ -0,0 +1,13 @@
+import type { LogLevel, LoggerDriver } from '../contracts/Logger.ts'
+
+export class NullDriver implements LoggerDriver {
+  log(_level: LogLevel, _message: string, _context?: Record<string, any>): void {}
+  emergency(_message: string, _context?: Record<string, any>): void {}
+  alert(_message: string, _context?: Record<string, any>): void {}
+  critical(_message: string, _context?: Record<string, any>): void {}
+  error(_message: string, _context?: Record<string, any>): void {}
+  warning(_message: string, _context?: Record<string, any>): void {}
+  notice(_message: string, _context?: Record<string, any>): void {}
+  info(_message: string, _context?: Record<string, any>): void {}
+  debug(_message: string, _context?: Record<string, any>): void {}
+}

package/src/drivers/StackDriver.ts

@@ -0,0 +1,24 @@
+import type { LogLevel, LoggerDriver } from '../contracts/Logger.ts'
+
+export class StackDriver implements LoggerDriver {
+  private readonly drivers: LoggerDriver[]
+
+  constructor(drivers: LoggerDriver[]) {
+    this.drivers = drivers
+  }
+
+  log(level: LogLevel, message: string, context?: Record<string, any>): void {
+    for (const driver of this.drivers) {
+      driver.log(level, message, context)
+    }
+  }
+
+  emergency(message: string, context?: Record<string, any>): void { this.log('emergency', message, context) }
+  alert(message: string, context?: Record<string, any>): void { this.log('alert', message, context) }
+  critical(message: string, context?: Record<string, any>): void { this.log('critical', message, context) }
+  error(message: string, context?: Record<string, any>): void { this.log('error', message, context) }
+  warning(message: string, context?: Record<string, any>): void { this.log('warning', message, context) }
+  notice(message: string, context?: Record<string, any>): void { this.log('notice', message, context) }
+  info(message: string, context?: Record<string, any>): void { this.log('info', message, context) }
+  debug(message: string, context?: Record<string, any>): void { this.log('debug', message, context) }
+}

package/src/formatters/JsonFormatter.ts

@@ -0,0 +1,13 @@
+import type { LogEntry, LogFormatter } from '../contracts/Logger.ts'
+
+export class JsonFormatter implements LogFormatter {
+  format(entry: LogEntry): string {
+    return JSON.stringify({
+      timestamp: entry.timestamp.toISOString(),
+      channel: entry.channel,
+      level: entry.level,
+      message: entry.message,
+      ...(Object.keys(entry.context).length > 0 ? { context: entry.context } : {}),
+    })
+  }
+}

package/src/formatters/LineFormatter.ts

@@ -0,0 +1,12 @@
+import type { LogEntry, LogFormatter } from '../contracts/Logger.ts'
+
+export class LineFormatter implements LogFormatter {
+  format(entry: LogEntry): string {
+    const ts = entry.timestamp.toISOString()
+    const level = entry.level.toUpperCase().padEnd(9)
+    const ctx = Object.keys(entry.context).length > 0
+      ? ' ' + JSON.stringify(entry.context)
+      : ''
+    return `[${ts}] ${entry.channel}.${level} ${entry.message}${ctx}`
+  }
+}

package/src/helpers/log.ts

@@ -0,0 +1,13 @@
+import { Application } from '@mantiq/core'
+import type { LoggerDriver } from '../contracts/Logger.ts'
+import type { LogManager } from '../LogManager.ts'
+
+export const LOGGING_MANAGER = Symbol('LogManager')
+
+export function log(): LogManager
+export function log(channel: string): LoggerDriver
+export function log(channel?: string): LogManager | LoggerDriver {
+  const manager = Application.getInstance().make<LogManager>(LOGGING_MANAGER)
+  if (channel === undefined) return manager
+  return manager.channel(channel)
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+// ── Contracts ─────────────────────────────────────────────────────────────────
+export type {
+  LogLevel,
+  LogEntry,
+  LogFormatter,
+  LoggerDriver,
+  ChannelConfig,
+  LogConfig,
+} from './contracts/Logger.ts'
+export { LOG_LEVELS } from './contracts/Logger.ts'
+
+// ── Core ──────────────────────────────────────────────────────────────────────
+export { LogManager } from './LogManager.ts'
+export { LoggingServiceProvider } from './LoggingServiceProvider.ts'
+
+// ── Formatters ────────────────────────────────────────────────────────────────
+export { LineFormatter } from './formatters/LineFormatter.ts'
+export { JsonFormatter } from './formatters/JsonFormatter.ts'
+
+// ── Drivers ───────────────────────────────────────────────────────────────────
+export { ConsoleDriver } from './drivers/ConsoleDriver.ts'
+export { FileDriver } from './drivers/FileDriver.ts'
+export { DailyDriver } from './drivers/DailyDriver.ts'
+export { StackDriver } from './drivers/StackDriver.ts'
+export { NullDriver } from './drivers/NullDriver.ts'
+
+// ── Testing ───────────────────────────────────────────────────────────────────
+export { LogFake } from './testing/LogFake.ts'
+export type { LoggedMessage } from './testing/LogFake.ts'
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+export { log, LOGGING_MANAGER } from './helpers/log.ts'

package/src/testing/LogFake.ts

@@ -0,0 +1,96 @@
+import type { LogLevel, LoggerDriver } from '../contracts/Logger.ts'
+import { LOG_LEVELS } from '../contracts/Logger.ts'
+
+export interface LoggedMessage {
+  level: LogLevel
+  message: string
+  context: Record<string, any>
+}
+
+export class LogFake implements LoggerDriver {
+  private readonly logged: LoggedMessage[] = []
+
+  log(level: LogLevel, message: string, context: Record<string, any> = {}): void {
+    this.logged.push({ level, message, context })
+  }
+
+  emergency(message: string, context?: Record<string, any>): void { this.log('emergency', message, context ?? {}) }
+  alert(message: string, context?: Record<string, any>): void { this.log('alert', message, context ?? {}) }
+  critical(message: string, context?: Record<string, any>): void { this.log('critical', message, context ?? {}) }
+  error(message: string, context?: Record<string, any>): void { this.log('error', message, context ?? {}) }
+  warning(message: string, context?: Record<string, any>): void { this.log('warning', message, context ?? {}) }
+  notice(message: string, context?: Record<string, any>): void { this.log('notice', message, context ?? {}) }
+  info(message: string, context?: Record<string, any>): void { this.log('info', message, context ?? {}) }
+  debug(message: string, context?: Record<string, any>): void { this.log('debug', message, context ?? {}) }
+
+  // ── Assertions ────────────────────────────────────────────────────────────
+
+  assertLogged(level: LogLevel, message?: string | RegExp, count?: number): void {
+    const matches = this.matching(level, message)
+    if (matches.length === 0) {
+      throw new Error(
+        `Expected log at level [${level}]${message ? ` matching "${message}"` : ''} but none was found.\n` +
+        `Logged messages: ${JSON.stringify(this.logged, null, 2)}`,
+      )
+    }
+    if (count !== undefined && matches.length !== count) {
+      throw new Error(
+        `Expected ${count} log(s) at level [${level}]${message ? ` matching "${message}"` : ''} but found ${matches.length}.`,
+      )
+    }
+  }
+
+  assertNotLogged(level: LogLevel, message?: string | RegExp): void {
+    const matches = this.matching(level, message)
+    if (matches.length > 0) {
+      throw new Error(
+        `Unexpected log at level [${level}]${message ? ` matching "${message}"` : ''} was found.\n` +
+        `Match: ${JSON.stringify(matches[0])}`,
+      )
+    }
+  }
+
+  assertNothingLogged(): void {
+    if (this.logged.length > 0) {
+      throw new Error(
+        `Expected no logs but ${this.logged.length} were recorded.\n` +
+        `First: ${JSON.stringify(this.logged[0])}`,
+      )
+    }
+  }
+
+  assertLoggedCount(count: number): void {
+    if (this.logged.length !== count) {
+      throw new Error(`Expected ${count} log(s) but ${this.logged.length} were recorded.`)
+    }
+  }
+
+  // ── Inspection ────────────────────────────────────────────────────────────
+
+  all(): LoggedMessage[] {
+    return [...this.logged]
+  }
+
+  forLevel(level: LogLevel): LoggedMessage[] {
+    return this.logged.filter((m) => m.level === level)
+  }
+
+  hasLogged(level: LogLevel, message?: string | RegExp): boolean {
+    return this.matching(level, message).length > 0
+  }
+
+  reset(): void {
+    this.logged.length = 0
+  }
+
+  // ── Internal ──────────────────────────────────────────────────────────────
+
+  private matching(level: LogLevel, message?: string | RegExp): LoggedMessage[] {
+    return this.logged.filter((m) => {
+      if (m.level !== level) return false
+      if (message === undefined) return true
+      if (typeof message === 'string') return m.message === message
+      return message.test(m.message)
+    })
+  }
+}