feat(with-watch): use WW_LOG and default diagnostic logs to off (#374)

kdy1 · web-flow · commit 0501ad35e57c · 2026-04-10T22:11:27.000+02:00
## Summary
- switch with-watch diagnostic tracing configuration from `RUST_LOG` to
`WW_LOG`
- default with-watch diagnostic logging to `with_watch=off` while
keeping fatal user-facing errors unchanged
- document the new logging contract in the crate README, public docs,
and canonical docs

## Testing
- pnpm --filter public-docs test
- cargo test -p with-watch
- cargo test
diff --git a/apps/public-docs/with-watch.mdx b/apps/public-docs/with-watch.mdx
@@ -124,6 +124,15 @@ with-watch exec --input 'src/**/*.rs' -- cargo test -p with-watch
 - Self-mutating commands such as `sed -i.bak -e 's/old/new/' config.txt` refresh their baseline after each run so they do not loop on their own writes.
 - Replace-style writers remain watchable because path inputs subscribe from the nearest existing directory anchor.
 
+## Logging
+
+- `with-watch` reads diagnostic `tracing` filters only from `WW_LOG`.
+- Diagnostic logs are off by default.
+- Set `WW_LOG=with_watch=info` for normal watcher diagnostics or `WW_LOG=with_watch=debug` for deeper troubleshooting.
+- `RUST_LOG` does not affect `with-watch` logging.
+- `WITH_WATCH_LOG_COLOR` and `NO_COLOR` still control ANSI log coloring.
+- Fatal user-facing errors still print to stderr even when diagnostic logging is off.
+
 ## Related pages
 
 - [Projects Overview](projects-overview)
diff --git a/crates/with-watch/README.md b/crates/with-watch/README.md
@@ -111,6 +111,14 @@ with-watch exec --input 'src/**/*.rs' -- cargo test -p with-watch
 - Commands that mutate watched inputs directly, such as `sed -i.bak -e 's/old/new/' config.txt`, refresh their baseline after each run so they do not loop on their own writes.
 - Path-based inputs anchor the watcher at the nearest existing directory so replace-style writers keep producing later external change events.
 
+## Logging
+
+- `with-watch` reads `tracing` filter directives only from `WW_LOG`.
+- Diagnostic logs are off by default. Set `WW_LOG=with_watch=info` or `WW_LOG=with_watch=debug` when you want planner and watcher details.
+- `RUST_LOG` does not configure `with-watch` logging.
+- `WITH_WATCH_LOG_COLOR` and `NO_COLOR` continue to control ANSI log coloring.
+- Fatal user-facing errors still print to stderr even when diagnostic logging is off.
+
 ## Troubleshooting
 
 - `No watch inputs could be inferred from the delegated command`: switch to `with-watch exec --input ... -- <command>`.
diff --git a/crates/with-watch/src/logging.rs b/crates/with-watch/src/logging.rs
@@ -1,11 +1,12 @@
 use tracing_subscriber::EnvFilter;
 
+const WW_LOG_ENV: &str = "WW_LOG";
 const WITH_WATCH_LOG_COLOR_ENV: &str = "WITH_WATCH_LOG_COLOR";
 const NO_COLOR_ENV: &str = "NO_COLOR";
+const DEFAULT_LOG_FILTER: &str = "with_watch=off";
 
 pub fn init_logging() {
-    let env_filter =
-        EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("with_watch=info"));
+    let env_filter = resolve_env_filter_from_environment();
     let _ = tracing_subscriber::fmt()
         .with_env_filter(env_filter)
         .with_ansi(log_color_enabled())
@@ -15,6 +16,19 @@ pub fn init_logging() {
         .try_init();
 }
 
+fn resolve_env_filter_from_environment() -> EnvFilter {
+    resolve_env_filter(std::env::var(WW_LOG_ENV).ok().as_deref())
+}
+
+fn resolve_env_filter(ww_log: Option<&str>) -> EnvFilter {
+    let filter = ww_log
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .unwrap_or(DEFAULT_LOG_FILTER);
+
+    EnvFilter::try_new(filter).unwrap_or_else(|_| EnvFilter::new(DEFAULT_LOG_FILTER))
+}
+
 fn log_color_enabled() -> bool {
     resolve_log_color_enabled(
         std::env::var(WITH_WATCH_LOG_COLOR_ENV).ok().as_deref(),
@@ -54,7 +68,19 @@ fn parse_log_color_mode(raw: &str) -> Option<LogColorMode> {
 
 #[cfg(test)]
 mod tests {
-    use super::resolve_log_color_enabled;
+    use std::{
+        io::{self, Write},
+        sync::{Arc, Mutex, OnceLock},
+    };
+
+    use tracing::{debug, info};
+
+    use super::{
+        resolve_env_filter, resolve_env_filter_from_environment, resolve_log_color_enabled,
+        EnvFilter, DEFAULT_LOG_FILTER, WW_LOG_ENV,
+    };
+
+    const RUST_LOG_ENV: &str = "RUST_LOG";
 
     #[test]
     fn default_enables_colored_logs() {
@@ -70,4 +96,151 @@ mod tests {
     fn no_color_disables_logs_without_override() {
         assert!(!resolve_log_color_enabled(None, Some("1")));
     }
+
+    #[test]
+    fn default_filter_disables_info_logs() {
+        let output = capture_logs(resolve_env_filter(None), || {
+            info!("hidden");
+        });
+
+        assert!(output.is_empty());
+    }
+
+    #[test]
+    fn blank_ww_log_uses_default_filter() {
+        let output = capture_logs(resolve_env_filter(Some("   ")), || {
+            info!("hidden");
+        });
+
+        assert!(
+            output.is_empty(),
+            "blank WW_LOG should fall back to {DEFAULT_LOG_FILTER}"
+        );
+    }
+
+    #[test]
+    fn ww_log_can_enable_info_logs() {
+        let output = capture_logs(resolve_env_filter(Some("with_watch=info")), || {
+            info!("visible");
+            debug!("still hidden");
+        });
+
+        assert!(output.contains("visible"));
+        assert!(!output.contains("still hidden"));
+    }
+
+    #[test]
+    fn ww_log_can_enable_debug_logs() {
+        let output = capture_logs(resolve_env_filter(Some("with_watch=debug")), || {
+            debug!("visible");
+        });
+
+        assert!(output.contains("visible"));
+    }
+
+    #[test]
+    fn invalid_ww_log_falls_back_to_default_filter() {
+        let output = capture_logs(resolve_env_filter(Some("not a valid filter[")), || {
+            info!("hidden");
+        });
+
+        assert!(output.is_empty());
+    }
+
+    #[test]
+    fn rust_log_is_ignored_when_resolving_environment_filter() {
+        with_logging_environment(None, Some("with_watch=debug"), || {
+            let output = capture_logs(resolve_env_filter_from_environment(), || {
+                info!("hidden");
+            });
+
+            assert!(output.is_empty());
+        });
+    }
+
+    #[test]
+    fn ww_log_from_environment_overrides_default_off() {
+        with_logging_environment(Some("with_watch=info"), Some("with_watch=off"), || {
+            let output = capture_logs(resolve_env_filter_from_environment(), || {
+                info!("visible");
+            });
+
+            assert!(output.contains("visible"));
+        });
+    }
+
+    fn capture_logs(env_filter: EnvFilter, callback: impl FnOnce()) -> String {
+        let buffer = Arc::new(Mutex::new(Vec::new()));
+        let writer = SharedWriter(buffer.clone());
+        let subscriber = tracing_subscriber::fmt()
+            .with_env_filter(env_filter)
+            .with_ansi(false)
+            .with_target(false)
+            .with_level(false)
+            .without_time()
+            .with_writer(move || writer.clone())
+            .finish();
+
+        tracing::subscriber::with_default(subscriber, callback);
+
+        let output = buffer.lock().expect("lock log buffer").clone();
+        String::from_utf8(output).expect("utf8 log output")
+    }
+
+    fn with_logging_environment<T>(
+        ww_log: Option<&str>,
+        rust_log: Option<&str>,
+        callback: impl FnOnce() -> T,
+    ) -> T {
+        let _guard = environment_lock().lock().expect("lock logging env");
+
+        let original_ww_log = std::env::var_os(WW_LOG_ENV);
+        let original_rust_log = std::env::var_os(RUST_LOG_ENV);
+
+        set_optional_env(WW_LOG_ENV, ww_log);
+        set_optional_env(RUST_LOG_ENV, rust_log);
+
+        let result = callback();
+
+        restore_optional_env(WW_LOG_ENV, original_ww_log);
+        restore_optional_env(RUST_LOG_ENV, original_rust_log);
+
+        result
+    }
+
+    fn environment_lock() -> &'static Mutex<()> {
+        static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+        LOCK.get_or_init(|| Mutex::new(()))
+    }
+
+    fn set_optional_env(key: &str, value: Option<&str>) {
+        match value {
+            Some(value) => std::env::set_var(key, value),
+            None => std::env::remove_var(key),
+        }
+    }
+
+    fn restore_optional_env(key: &str, value: Option<std::ffi::OsString>) {
+        match value {
+            Some(value) => std::env::set_var(key, value),
+            None => std::env::remove_var(key),
+        }
+    }
+
+    #[derive(Clone)]
+    struct SharedWriter(Arc<Mutex<Vec<u8>>>);
+
+    impl Write for SharedWriter {
+        fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+            self.0
+                .lock()
+                .expect("lock log buffer")
+                .extend_from_slice(buf);
+            Ok(buf.len())
+        }
+
+        fn flush(&mut self) -> io::Result<()> {
+            Ok(())
+        }
+    }
 }
diff --git a/crates/with-watch/tests/cli.rs b/crates/with-watch/tests/cli.rs
@@ -51,6 +51,66 @@ fn short_help_stays_compact() {
         .stdout(predicate::str::contains("Recognized but not auto-watchable commands:").not());
 }
 
+#[cfg(unix)]
+#[test]
+fn tracing_logs_are_off_by_default() {
+    let temp_dir = tempfile::tempdir().expect("create tempdir");
+    let input_path = temp_dir.path().join("input.txt");
+    fs::write(&input_path, "hello\n").expect("write input");
+
+    with_watch_command()
+        .env_remove("WW_LOG")
+        .env_remove("RUST_LOG")
+        .env("WITH_WATCH_LOG_COLOR", "never")
+        .env("WITH_WATCH_TEST_MAX_RUNS", "1")
+        .arg("cat")
+        .arg(&input_path)
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("hello"))
+        .stdout(predicate::str::contains("Starting with-watch run loop").not());
+}
+
+#[cfg(unix)]
+#[test]
+fn ww_log_can_enable_startup_logs() {
+    let temp_dir = tempfile::tempdir().expect("create tempdir");
+    let input_path = temp_dir.path().join("input.txt");
+    fs::write(&input_path, "hello\n").expect("write input");
+
+    with_watch_command()
+        .env("WW_LOG", "with_watch=info")
+        .env_remove("RUST_LOG")
+        .env("WITH_WATCH_LOG_COLOR", "never")
+        .env("WITH_WATCH_TEST_MAX_RUNS", "1")
+        .arg("cat")
+        .arg(&input_path)
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("hello"))
+        .stdout(predicate::str::contains("Starting with-watch run loop"));
+}
+
+#[cfg(unix)]
+#[test]
+fn rust_log_does_not_enable_startup_logs() {
+    let temp_dir = tempfile::tempdir().expect("create tempdir");
+    let input_path = temp_dir.path().join("input.txt");
+    fs::write(&input_path, "hello\n").expect("write input");
+
+    with_watch_command()
+        .env_remove("WW_LOG")
+        .env("RUST_LOG", "with_watch=info")
+        .env("WITH_WATCH_LOG_COLOR", "never")
+        .env("WITH_WATCH_TEST_MAX_RUNS", "1")
+        .arg("cat")
+        .arg(&input_path)
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("hello"))
+        .stdout(predicate::str::contains("Starting with-watch run loop").not());
+}
+
 #[test]
 fn commands_without_filesystem_inputs_guide_users_to_exec_input() {
     with_watch_command()
diff --git a/docs/crates-with-watch-foundation.md b/docs/crates-with-watch-foundation.md
@@ -22,6 +22,8 @@
 - After watch input inference, watcher setup, and baseline snapshot capture succeed, all command modes must execute the delegated command immediately once before waiting for the first filesystem change event.
 - `exec --input` must accept repeatable explicit glob/path values, keep the delegated command unchanged, and remain the canonical fallback for otherwise ambiguous or pathless commands.
 - `--no-hash` must remain a global flag that switches rerun filtering from content hashes to metadata-only comparison.
+- `WW_LOG` must remain the only supported environment variable for configuring `with-watch` diagnostic `tracing` filters.
+- The default diagnostic log filter must remain `with_watch=off`, and `RUST_LOG` must not affect `with-watch` logging behavior.
 - Public crate installation must remain `cargo install with-watch`.
 - Publish tag naming must remain `with-watch@v<version>`.
 - Stable internal enums must remain aligned with the current v1 contract:
@@ -61,6 +63,7 @@
 
 ## Logging
 - Use structured `tracing` logs for command planning, watcher setup, snapshot capture, debounce decisions, and rerun causes.
+- Diagnostic `tracing` logs are operator opt-in: they are disabled by default and enabled via `WW_LOG`.
 - Logs must include `command_source`, `detection_mode`, input counts, `adapter_id`, `fallback_used`, `default_watch_root_used`, `filtered_output_count`, `side_effect_profile`, snapshot modes, snapshot entry counts, snapshot capture elapsed time, and rerun suppression outcomes.
 
 ## Build and Test
diff --git a/docs/project-with-watch.md b/docs/project-with-watch.md
@@ -20,6 +20,8 @@ Provide a Rust-based CLI wrapper that reruns delegated shell utilities and arbit
 - The public CLI surface must keep exactly one delegated-command entrypoint per invocation: passthrough argv, `--shell`, or `exec --input`.
 - After watch input inference, watcher setup, and baseline snapshot capture succeed, `with-watch` must execute the delegated command immediately once before waiting for the first filesystem change event.
 - Default change detection must prefer content hashing, while `--no-hash` must switch the rerun filter to metadata-only comparison.
+- `WW_LOG` must remain the only supported environment variable for configuring `with-watch` diagnostic `tracing` logs, and the default diagnostic filter must remain `with_watch=off`.
+- `RUST_LOG` must not affect `with-watch` diagnostic logging.
 - `exec --input` reruns the delegated command unchanged and must not inject changed paths into argv or environment variables.
 - Commands without safe inferred filesystem inputs must fail clearly and direct operators to `with-watch exec --input ...`.
 - Passthrough and shell modes must use adapter-driven input inference that excludes known outputs, scripts, and pattern operands from the watch set.
