package logging

import "context"

// Logger is the interface for structured, leveled logging.
// All Einherjar starters accept Logger at their constructors and pass it
// to sub-components — never the concrete implementation.
// Implementations must be safe for concurrent use.
type Logger interface {
	// Debug logs a message at DEBUG level.
	Debug(msg string, args ...any)
	// Info logs a message at INFO level.
	Info(msg string, args ...any)
	// Warn logs a message at WARN level.
	Warn(msg string, args ...any)
	// Error logs a message at ERROR level. err may be nil.
	// Implementations should detect errs.CodedError and errs.ContextualError
	// and append their fields automatically to the log record.
	Error(msg string, err error, args ...any)
	// With returns a new Logger with the given key-value attributes pre-attached
	// to every subsequent log record produced by the returned logger.
	With(args ...any) Logger
	// WithContext returns a new Logger enriched with request-scoped fields stored
	// in ctx. Safe to call with a nil context — returns the receiver unchanged.
	WithContext(ctx context.Context) Logger
}