Module logging 

In-crate structured-logging facade.

The statusline is a single-shot, stderr-free-by-default process; a full tracing/log stack would bloat the binary for a narrow diagnostic surface. This module exposes level-gated emission through two macros, [lsm_warn!] and [lsm_debug!], controlled by the LINESMITH_LOG env var.

Default level is Level::Warn so genuine drops (cache-write failures, lock-write failures) surface without opt-in. Silent [Ok(None)] hide paths in rate-limit segments log at Level::Debug and require LINESMITH_LOG=debug to appear.

Structural failures that always warrant a user-visible signal (segment render panics, fatal plugin init errors) emit through [lsm_error!], which bypasses the level gate. LINESMITH_LOG=off quiets chatter; it is not a silence-all-signals switch, because a broken statusline needs a stderr line the user can grep. Scripts that want absolute silence can 2>/dev/null.

Output format on stderr: linesmith [<level>]: <message>. The TUI installs a CapturedSink in place of StderrSink for the duration of the alt-screen so macro emissions don’t paint over the rendered frame; captured entries use the compact [<level>] <message> form (no linesmith prefix, no colon) since the surrounding UI provides context.

Not a general-purpose logger: no filtering by target, no structured fields. Add those when a call site needs them.

Structs

CapturedSink

Buffering sink that accumulates formatted entries for an interactive consumer to drain. The TUI installs one for the alt-screen lifetime so lsm_warn! / lsm_error! / lsm_debug! surface in the live-preview warnings panel instead of painting over the rendered frame.

SinkGuard

RAII handle that installs a custom sink and restores the prior one on drop. The TUI uses this so stderr emission resumes after the alt-screen exits in the normal-return path. Note: the workspace’s release profile sets panic = "abort", so on a release-build panic this Drop does not run — the panic hook (in [super::tui]) is what restores the terminal under abort, and stderr is owned by the alt-screen until then. Under the default unwind profile (dev/test), stack unwinding drops the guard normally.

StderrSink

Default sink. Writes linesmith [<tag>]: <msg> lines to io::stderr().lock() and drops the write on a closed pipe / full disk: the statusline has no recovery path, and panicking here would nuke an otherwise-good render.

Enums

Level

Logger severity. Variants are ordered Off < Warn < Debug so a call fires when its own level is <= the configured level.

Constants

ENV_VAR

Traits

LogSink

Pluggable destination for diagnostic emissions. The default StderrSink preserves the linesmith [<level>]: <msg> format external scripts grep for; the TUI swaps in a CapturedSink for the duration of the alt-screen so macro emissions land in the warnings panel instead of corrupting the painted frame.

Functions

apply

Apply raw (the snapshotted LINESMITH_LOG value, None if unset) to the process-wide level. On an unrecognized value the logger resets to [DEFAULT_LEVEL] and writes one line to warn_sink; the driver threads the injected CLI stderr through so tests and embedders don’t see ambient stderr pollution.

emit

Emit msg at lvl through the active LogSink. Production path: the default sink writes to stderr; the TUI’s CapturedSink buffers for in-frame display; the level gate suppresses below the configured threshold.

emit_error

Emit a structural-failure diagnostic. Bypasses the level gate: even LINESMITH_LOG=off does not suppress it, because the only things that reach this function are render failures a user has no other way of seeing.

is_enabled

true when at_least or a more verbose level is active. A call fires when its own level is <= the currently configured level.

level

set_level

Override the process-wide level. Exposed for tests and embedders that want to pick a level without touching the env.