// Package logx is the leveled log helper of the v0.116.0 observability pass. It
// prefixes the standard [LEVEL] tag and writes through log.Logger.Output so the
// Lshortfile source (debug mode) attributes to the CALLER, not this file.
//
// Routing is the WRITER's job, not this package's: main.go builds the logger as
// MultiWriter(LevelFilterWriter(stdout, logging.level), LogBuffer) — so a
// logx.Debugf line ALWAYS reaches the debug ring (remote diagnostics) while
// stdout keeps respecting logging.level. Legacy `isDebug()`-gated Printf call
// sites are left as-is (they gate emission entirely); ALL NEW leveled lines use
// these helpers. Conventions (levels, English, no secrets):
// felhom.eu/documentation/runbooks/logging-conventions.md.
package logx

import (
	"fmt"
	"log"
)

// Debugf logs flow detail (phase steps, per-call traces, parsed values).
func Debugf(l *log.Logger, format string, args ...any) { output(l, "DEBUG", format, args...) }

// Infof logs state changes and operations with durations ("X done in Yms").
func Infof(l *log.Logger, format string, args ...any) { output(l, "INFO", format, args...) }

// Warnf logs degraded-but-continuing conditions.
func Warnf(l *log.Logger, format string, args ...any) { output(l, "WARN", format, args...) }

// Errorf logs a failed operation — always include the underlying error.
func Errorf(l *log.Logger, format string, args ...any) { output(l, "ERROR", format, args...) }

func output(l *log.Logger, tag, format string, args ...any) {
	if l == nil {
		return
	}
	// calldepth 3: Output ← output ← Debugf/… ← the caller we want attributed.
	_ = l.Output(3, "["+tag+"] "+fmt.Sprintf(format, args...))
}