//! Focus and layering diagnostics, off unless asked for at launch (`--diag` or the environment //! variable `WAYBETTER_DIAG=1`). While on, native code and the shell append one timestamped line per //! event to `diag.log` in the app's log folder: menu open requests and every close with its reason, //! overlays and `shell_raise` calls with their results, native focus calls, and the shell document's //! focus, blur and visibility changes. A line is an event name and a few words: never a URL, a //! query, page text or anything about an account ([`clean`] keeps plain printable ASCII only and //! caps the length). Each launch with diagnostics on starts a new file; the one before it is kept as `diag.prev.log`. use std::io::Write; use std::path::PathBuf; use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::Mutex; use std::time::Instant; pub const ARG: &str = "--diag"; pub const ENV: &str = "WAYBETTER_DIAG"; pub const FILE: &str = "diag.log"; pub const PREVIOUS: &str = "diag.prev.log"; const MAX_LINE: usize = 300; static ON: AtomicBool = AtomicBool::new(false); static SINK: Mutex> = Mutex::new(None); /// Whether this launch asks for diagnostics (the first argument is the program itself). pub fn asked(args: I, env: Option<&str>) -> bool where I: IntoIterator, S: AsRef, { env.is_some_and(|value| value == "1") || args.into_iter().skip(1).any(|arg| arg.as_ref() == ARG) } /// A line as it is written: printable ASCII only (anything else becomes `?`), one line, capped. pub fn clean(line: &str) -> String { line.chars().take(MAX_LINE).map(|ch| if (' '..='~').contains(&ch) { ch } else { '?' }).collect() } /// Starts writing to `dir/diag.log` (created, truncated); the previous run's log is kept as `diag.prev.log`. /// Nothing happens without a folder. pub fn start(dir: Option) { let Some(dir) = dir else { return }; let _ = std::fs::create_dir_all(&dir); // A run that went wrong is usually relaunched at once: keep its log. let _ = std::fs::rename(dir.join(FILE), dir.join(PREVIOUS)); if let Ok(file) = std::fs::File::create(dir.join(FILE)) { if let Ok(mut sink) = SINK.lock() { *sink = Some((file, Instant::now())); ON.store(true, Ordering::SeqCst); } } log("host", "diagnostics on"); } pub fn active() -> bool { ON.load(Ordering::SeqCst) } /// One event from `source` (`host` or `shell`), with milliseconds since the start. pub fn log(source: &str, line: &str) { if !active() { return; } if let Ok(mut sink) = SINK.lock() { if let Some((file, started)) = sink.as_mut() { let _ = writeln!(file, "{:>9} {:<5} {}", started.elapsed().as_millis(), clean(source), clean(line)); let _ = file.flush(); } } } #[cfg(test)] mod tests { use super::*; #[test] fn asked_by_the_argument_or_the_environment_only() { assert!(asked(["app", "--diag"], None)); assert!(asked(["app"], Some("1"))); assert!(!asked(["app"], Some("yes"))); assert!(!asked(["--diag"], None), "the first argument is the program"); assert!(!asked(["app", "--diag=1", "diag"], None)); } #[test] fn a_line_is_plain_short_ascii() { assert_eq!(clean("menu close: blur (hasFocus=false)"), "menu close: blur (hasFocus=false)"); assert_eq!(clean("two\nlines\ttab é"), "two?lines?tab ?"); assert_eq!(clean(&"x".repeat(1000)).len(), MAX_LINE); // Off by default: nothing is written. assert!(!active()); log("shell", "ignored"); } }