ctor debug state setup via shared atomic in core

syncdoc-core/Cargo.toml

@@ -23,6 +23,7 @@ unsynn.workspace = true
 
 [dev-dependencies]
 braces = "0.2.6"
+ctor = "0.6.1"
 duct = "1.1.1"
 insta.workspace = true
 itertools = "0.14.0"

syncdoc-core/src/debug.rs

@@ -0,0 +1,46 @@
+//! Debug printer control for syncdoc.
+//!
+//! Provides a thread-safe atomic flag for debug logging via STDERR and a function
+//! to enable it programmatically (runs automatically if compiled in `cfg(test)`).
+
+use std::env;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+/// Atomic flag indicating whether debug output is enabled.
+static DEBUG_ENABLED: AtomicBool = AtomicBool::new(false);
+
+/// Initialise the debug atomic from the `SYNCDOC_DEBUG` environment variable.
+///
+/// - Treats `"0"`, `"false"`, `"no"`, `"off"` as false.
+/// - Any other value is true.
+/// - If the variable is unset, defaults to true for tests, false otherwise.
+pub fn init_from_env() {
+    let enabled = match env::var("SYNCDOC_DEBUG") {
+        Ok(val) => {
+            let val = val.trim();
+            !(val == "0"
+                || val.eq_ignore_ascii_case("false")
+                || val.eq_ignore_ascii_case("no")
+                || val.eq_ignore_ascii_case("off"))
+        }
+        Err(_) => cfg!(test),
+    };
+    set_debug(enabled);
+}
+
+/// Enable or disable debug output programmatically.
+pub fn set_debug(enabled: bool) {
+    DEBUG_ENABLED.store(enabled, Ordering::Relaxed);
+}
+
+/// Check whether debug output is enabled.
+pub fn is_enabled() -> bool {
+    DEBUG_ENABLED.load(Ordering::Relaxed)
+}
+
+/// Automatically enable debug output for tests, respecting the env var.
+#[cfg(test)]
+#[ctor::ctor]
+fn init_debug_for_tests() {
+    init_from_env();
+}

syncdoc-core/src/lib.rs

@@ -1,5 +1,6 @@
 /// syncdoc-core: documentation injection helper macros
 pub mod config;
+pub mod debug;
 mod doc_injector;
 mod omnibus;
 pub mod parse;
@@ -9,10 +10,14 @@ pub mod token_processors;
 pub use doc_injector::{module_doc_impl, omnidoc_impl};
 pub use omnibus::inject_all_docs_impl;
 
+/// Macro for debug output in syncdoc.
+///
+/// Prints to stderr only if debug output is enabled via the atomic flag (tests do this using ctor)
+/// or the `SYNCDOC_DEBUG` environment variable at startup.
 #[macro_export]
 macro_rules! syncdoc_debug {
     ($($arg:tt)*) => {
-        if std::env::var("SYNCDOC_DEBUG").is_ok() {
+        if $crate::debug::is_enabled() {
             eprintln!("[SYNCDOC DEBUG] {}", format!($($arg)*));
         }
     };

syncdoc-core/tests/helpers.rs

@@ -11,6 +11,11 @@ use std::path::PathBuf;
 use std::process::Command;
 use tempfile::TempDir;
 
+#[ctor::ctor]
+fn init_debug() {
+    syncdoc_core::debug::init_from_env();
+}
+
 pub struct TestCrate {
     _temp_dir: TempDir,
     root: PathBuf,

syncdoc-migrate/Cargo.toml

@@ -22,6 +22,7 @@ unsynn.workspace = true
 
 [dev-dependencies]
 braces = "0.2.1"
+ctor = "0.6.1"
 insta.workspace = true
 rust-format.workspace = true
 tempfile.workspace = true

syncdoc-migrate/src/lib.rs

@@ -8,6 +8,9 @@ pub mod restore;
 pub mod rewrite;
 pub mod write;
 
+// Re-export core's macro
+pub use syncdoc_core::syncdoc_debug;
+
 pub use config::DocsPathMode;
 pub use discover::{discover_rust_files, get_or_create_docs_path, parse_file, ParsedFile};
 pub use extract::{extract_doc_content, has_doc_attrs};
@@ -17,14 +20,5 @@ pub use write::{
     extract_all_docs, find_expected_doc_paths, write_extractions, DocExtraction, WriteReport,
 };
 
-#[macro_export]
-macro_rules! syncdoc_debug {
-    ($($arg:tt)*) => {
-        if std::env::var("SYNCDOC_DEBUG").is_ok() {
-            eprintln!("[SYNCDOC DEBUG] {}", format!($($arg)*));
-        }
-    };
-}
-
 #[cfg(test)]
 mod tests;

syncdoc-migrate/src/tests/mod.rs

@@ -9,3 +9,9 @@ mod restore;
 mod rewrite;
 mod strip;
 mod write;
+
+/// Automatically enable debug output for all tests
+#[ctor::ctor]
+fn init_debug() {
+    syncdoc_core::debug::set_debug(true);
+}

syncdoc-migrate/tests/helpers.rs

@@ -10,6 +10,11 @@ use syncdoc_migrate::{
 };
 use tempfile::TempDir;
 
+#[ctor::ctor]
+fn init_debug() {
+    syncdoc_core::debug::set_debug(true);
+}
+
 pub fn setup_test_file(source: &str, filename: &str) -> (TempDir, PathBuf) {
     let temp_dir = TempDir::new().unwrap();
     let file_path = temp_dir.path().join(filename);

syncdoc/Cargo.toml

@@ -47,6 +47,7 @@ syncdoc-migrate = { optional = true, workspace = true }
 [dev-dependencies]
 assert_cmd.workspace = true
 braces = "0.2.6"
+ctor = "0.6.1"
 insta.workspace = true
 regex = "1.12.2"
 rust-format.workspace = true

syncdoc/tests/cli_integration.rs

@@ -6,6 +6,11 @@ use std::fs;
 use std::path::Path;
 use tempfile::TempDir;
 
+#[ctor::ctor]
+fn init_debug() {
+    syncdoc_core::debug::set_debug(true);
+}
+
 fn to_braces(paths: &[&str]) -> String {
     let braces_config = BraceConfig::default();
     brace_paths(paths, &braces_config).expect("Brace error")

syncdoc/tests/roundtrip/helpers.rs

@@ -7,6 +7,11 @@ use std::path::{Path, PathBuf};
 use std::process::Command;
 use tempfile::TempDir;
 
+#[ctor::ctor]
+fn init_debug() {
+    syncdoc_core::debug::set_debug(true);
+}
+
 /// Module configuration for test setup
 #[derive(Debug, Clone)]
 pub struct ModuleConfig {