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

CapturedDrain

Detailed drain result. Carries the entries plus a dropped count for emissions silently evicted by the bounded buffer since the previous drain, so the consumer can surface a “(N earlier entries dropped)” line instead of letting the loss go unnoticed.

CapturedEntry

One captured emission, tagged with the Instant it landed at the sink. Consumers that display the buffer over time (the TUI warnings panel once v0.2 background plugins can emit between draws) compute relative age against Instant::now() at render time; the monotonic clock means a host suspending mid-session doesn’t show negative ages or jump backwards.

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

CAPTURED_SINK_DEFAULT_CAP

Default cap for the CapturedSink inter-frame ring. Sized for a chatty render (one warn per segment across a multi-line config) plus burst headroom from future background emitters. Each entry is a short formatted string, so the worst-case memory at the cap is on the order of tens of KiB — small enough to be permanently allocated for the alt-screen lifetime.

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.