go-log/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Test Commands

# Run all tests
go test ./...

# Run a single test
go test -run TestLogger_Levels ./...

# Test coverage
core go cov            # generate report
core go cov --open     # open in browser

# Code quality
core go fmt            # format
core go lint           # lint
core go vet            # vet
core go qa             # fmt + lint + vet + tests
core go qa full        # + race detector, vuln scan, security audit

The core CLI is optional; plain go test and gofmt work without it.

Architecture

Single-package library (package log) split into two files that wire together:

• log.go — Logger type, Level enum (Quiet→Error→Warn→Info→Debug), Security log method (uses Error level with [SEC] prefix), key-value formatting with redaction and injection prevention, Style* function hooks for decoration, RotationWriterFactory injection point, Username() utility, default logger with package-level proxy functions
• errors.go — Err structured error type (Op/Msg/Err/Code), creation helpers (E, Wrap, WrapCode, NewCode, NewError), introspection (Op, ErrCode, Message, Root, AllOps, StackTrace, FormatStackTrace), combined log-and-return helpers (LogError, LogWarn, Must), stdlib wrappers (Is, As, Join)

The logger automatically extracts op and stack from *Err values found in key-value pairs. Wrap propagates error codes upward through the chain.

Zero runtime dependencies. testify is test-only.

Conventions

• UK English in comments and documentation (colour, organisation, centre)
• Test naming: _Good (happy path), _Bad (expected errors), _Ugly (edge cases/panics)
• Commit messages: conventional commits (feat, fix, docs, chore, etc.)
• Dependencies: no new runtime dependencies without justification; use RotationWriterFactory injection point for log rotation
• Requires Go 1.26+ (uses iter.Seq)
• Module path: dappco.re/go/core/log