feat: comprehensive logging across parser, app, persistence, runtime (X1)

Completes the X1 full sweep started in a8ad0c6 (db.rs). Closes X1 -> [x].

- persistence/mod.rs: debug! on every yaml/CSV/history write -- the
  silent-failure-prone disk paths (write_schema, write_table_data incl.
  the empty->delete branch, append_history/_failure).
- runtime.rs: debug! on execute_command_typed dispatch (one per executed
  command, complements the db.rs executor logs).
- app.rs: debug! on submit (route + submission mode), dispatch_app_command,
  and the ADR-0044 diagram-vs-prose render-mode choice.
- dsl/parser.rs: trace! on parse begin/outcome at the parse_command_inner
  choke point -- trace, not debug, because the live overlay/completion
  re-parse per keystroke (hot path).
- logging.rs: documented level discipline (error/warn/info/debug/trace) so
  the convention survives across sessions.

Levels verified end-to-end through the real worker thread + logging::init.
~75 -> 135 tracing sites total. Tests: 2207 pass / 0 fail / 1 ignored.
Clippy clean.
This commit is contained in:
claude@clouddev1
2026-06-10 11:38:22 +00:00
parent a8ad0c6cc3
commit 0a7612efe2
6 changed files with 87 additions and 12 deletions
+32
View File
@@ -6,6 +6,38 @@
//! environment variable; if neither is set we default to
//! `~/.rdbms-playground/playground.log` and create directories as
//! needed.
//!
//! ## Level conventions (X1 — `requirements.md`)
//!
//! Instrumentation across the tree follows a consistent level
//! discipline so the default `info` filter stays quiet and
//! `RDBMS_PLAYGROUND_LOG=debug` (or `=trace`) is a rich, layered
//! diagnostic stream. The env filter (`RDBMS_PLAYGROUND_LOG`,
//! full `EnvFilter` syntax) controls this independently of the
//! file path above; the default is `info`.
//!
//! - **`error!`** — unrecoverable failure (fatal persistence, a
//! panic-equivalent). The process is going down or a command is
//! hard-failing.
//! - **`warn!`** — recoverable failure or a fallback taken (a
//! snapshot couldn't be staged, a `PRAGMA` couldn't be restored,
//! an integrity check rolled a rebuild back).
//! - **`info!`** — low-volume lifecycle, visible by default: db
//! worker start/exit, project create/open, "logging initialised".
//! - **`debug!`** — the bulk of instrumentation, one line per
//! *executed* command and the decision points within it (executor
//! entry with key params, autofill/cascade summaries, the
//! rebuild-table primitive, persistence writes, render-mode
//! choice). Off by default.
//! - **`trace!`** — hot paths only: per-keystroke parsing
//! (`dsl::parser`), per-key input handling (`app`), per-refresh
//! table reads. A firehose; never on except when debugging that
//! specific layer.
//!
//! Rule of thumb for new code: a loop logs a single summary count,
//! never per-iteration at `debug`/`info`. Logs are developer-facing,
//! so naming the engine (SQLite/PRAGMA) is fine here even though the
//! "no engine name" rule (ADR-0002) forbids it in user-facing strings.
use std::fs::{File, OpenOptions, create_dir_all};
use std::path::{Path, PathBuf};