Skip to main content

babbel_yaml/devtools/
debug.rs

1//! Debugging utilities for YAML library development.
2//!
3//! This module provides debug levels, context tracking, and helper functions
4//! for internal development and troubleshooting of the YAML library.
5//!
6//! (c) 2026 YAML Library Developers
7
8use alloc::format;
9use alloc::string::String;
10use alloc::vec::Vec;
11
12use crate::nodes::node::Node;
13
14/// Debug level for controlling output verbosity
15#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
16pub enum DebugLevel {
17    None = 0,
18    Error = 1,
19    Warn = 2,
20    Info = 3,
21    Debug = 4,
22    Trace = 5,
23}
24
25/// Debug context for tracking execution flow
26#[derive(Debug, Clone)]
27pub struct DebugContext {
28    level: DebugLevel,
29    logs: Vec<String>,
30    breakpoints: Vec<String>,
31}
32
33impl DebugContext {
34    /// Create a new debug context
35    pub fn new(level: DebugLevel) -> Self {
36        Self {
37            level,
38            logs: Vec::new(),
39            breakpoints: Vec::new(),
40        }
41    }
42
43    /// Create with info level
44    pub fn with_info() -> Self {
45        Self::new(DebugLevel::Info)
46    }
47
48    /// Create with debug level
49    pub fn with_debug() -> Self {
50        Self::new(DebugLevel::Debug)
51    }
52
53    /// Create with trace level
54    pub fn with_trace() -> Self {
55        Self::new(DebugLevel::Trace)
56    }
57
58    /// Set debug level
59    pub fn set_level(&mut self, level: DebugLevel) {
60        self.level = level;
61    }
62
63    /// Get current debug level
64    pub fn level(&self) -> DebugLevel {
65        self.level
66    }
67
68    /// Log a message at the specified level
69    pub fn log(&mut self, level: DebugLevel, message: String) {
70        if level <= self.level {
71            self.logs.push(format!("[{:?}] {}", level, message));
72        }
73    }
74
75    /// Log error message
76    pub fn error(&mut self, message: String) {
77        self.log(DebugLevel::Error, message);
78    }
79
80    /// Log warning message
81    pub fn warn(&mut self, message: String) {
82        self.log(DebugLevel::Warn, message);
83    }
84
85    /// Log info message
86    pub fn info(&mut self, message: String) {
87        self.log(DebugLevel::Info, message);
88    }
89
90    /// Log debug message
91    pub fn debug(&mut self, message: String) {
92        self.log(DebugLevel::Debug, message);
93    }
94
95    /// Log trace message
96    pub fn trace(&mut self, message: String) {
97        self.log(DebugLevel::Trace, message);
98    }
99
100    /// Add a breakpoint
101    pub fn add_breakpoint(&mut self, name: String) {
102        self.breakpoints.push(name);
103    }
104
105    /// Check if a breakpoint exists
106    pub fn has_breakpoint(&self, name: &str) -> bool {
107        self.breakpoints.iter().any(|bp| bp == name)
108    }
109
110    /// Get all logs
111    pub fn logs(&self) -> &[String] {
112        &self.logs
113    }
114
115    /// Get all breakpoints
116    pub fn breakpoints(&self) -> &[String] {
117        &self.breakpoints
118    }
119
120    /// Clear all logs
121    pub fn clear_logs(&mut self) {
122        self.logs.clear();
123    }
124
125    /// Clear all breakpoints
126    pub fn clear_breakpoints(&mut self) {
127        self.breakpoints.clear();
128    }
129
130    /// Format all logs as a string
131    pub fn format_logs(&self) -> String {
132        self.logs.join("\n")
133    }
134}
135
136impl Default for DebugContext {
137    fn default() -> Self {
138        Self::new(DebugLevel::Info)
139    }
140}
141
142/// Node debugger for inspecting node operations
143pub struct NodeDebugger {
144    context: DebugContext,
145    trace_enabled: bool,
146}
147
148impl NodeDebugger {
149    /// Create a new node debugger
150    pub fn new() -> Self {
151        Self {
152            context: DebugContext::with_debug(),
153            trace_enabled: false,
154        }
155    }
156
157    /// Create with tracing enabled
158    pub fn with_trace() -> Self {
159        Self {
160            context: DebugContext::with_trace(),
161            trace_enabled: true,
162        }
163    }
164
165    /// Enable tracing
166    pub fn enable_trace(&mut self) {
167        self.trace_enabled = true;
168        self.context.set_level(DebugLevel::Trace);
169    }
170
171    /// Disable tracing
172    pub fn disable_trace(&mut self) {
173        self.trace_enabled = false;
174    }
175
176    /// Get the debug context
177    pub fn context(&self) -> &DebugContext {
178        &self.context
179    }
180
181    /// Get mutable debug context
182    pub fn context_mut(&mut self) -> &mut DebugContext {
183        &mut self.context
184    }
185
186    /// Debug a node access operation
187    pub fn debug_access(&mut self, path: &str, node: &Node) {
188        let msg = format!(
189            "Access: {} -> {:?}",
190            path,
191            crate::devtools::inspect::node_type(node)
192        );
193        self.context.debug(msg);
194    }
195
196    /// Debug a node creation operation
197    pub fn debug_create(&mut self, node: &Node) {
198        let msg = format!("Create: {:?}", crate::devtools::inspect::node_type(node));
199        self.context.debug(msg);
200    }
201
202    /// Debug a node modification operation
203    pub fn debug_modify(&mut self, path: &str, old: &Node, new: &Node) {
204        let msg = format!(
205            "Modify: {} from {:?} to {:?}",
206            path,
207            crate::devtools::inspect::node_type(old),
208            crate::devtools::inspect::node_type(new)
209        );
210        self.context.debug(msg);
211    }
212
213    /// Trace node traversal
214    pub fn trace_visit(&mut self, depth: usize, node: &Node) {
215        if self.trace_enabled {
216            let indent = "  ".repeat(depth);
217            let msg = format!(
218                "{}Visit: {:?}",
219                indent,
220                crate::devtools::inspect::node_type(node)
221            );
222            self.context.trace(msg);
223        }
224    }
225
226    /// Get formatted logs
227    pub fn logs(&self) -> String {
228        self.context.format_logs()
229    }
230
231    /// Clear all logs
232    pub fn clear(&mut self) {
233        self.context.clear_logs();
234        self.context.clear_breakpoints();
235    }
236}
237
238impl Default for NodeDebugger {
239    fn default() -> Self {
240        Self::new()
241    }
242}
243
244/// Assertion helper for debugging
245pub struct DebugAssert;
246
247impl DebugAssert {
248    /// Assert node type
249    pub fn assert_type(
250        node: &Node,
251        expected: crate::devtools::inspect::NodeType,
252    ) -> Result<(), String> {
253        let actual = crate::devtools::inspect::node_type(node);
254        if actual == expected {
255            Ok(())
256        } else {
257            Err(format!(
258                "Type assertion failed: expected {:?}, got {:?}",
259                expected, actual
260            ))
261        }
262    }
263
264    /// Assert node has specific size
265    pub fn assert_size(node: &Node, expected: usize) -> Result<(), String> {
266        let actual = crate::devtools::inspect::node_size(node);
267        if actual == expected {
268            Ok(())
269        } else {
270            Err(format!(
271                "Size assertion failed: expected {}, got {}",
272                expected, actual
273            ))
274        }
275    }
276
277    /// Assert node has maximum depth
278    pub fn assert_max_depth(node: &Node, max_depth: usize) -> Result<(), String> {
279        let actual = crate::devtools::inspect::node_depth(node);
280        if actual <= max_depth {
281            Ok(())
282        } else {
283            Err(format!(
284                "Depth assertion failed: expected <= {}, got {}",
285                max_depth, actual
286            ))
287        }
288    }
289
290    /// Assert node is scalar
291    pub fn assert_scalar(node: &Node) -> Result<(), String> {
292        let node_type = crate::devtools::inspect::node_type(node);
293        if node_type.is_scalar() {
294            Ok(())
295        } else {
296            Err(format!("Scalar assertion failed: node is {:?}", node_type))
297        }
298    }
299
300    /// Assert node is collection
301    pub fn assert_collection(node: &Node) -> Result<(), String> {
302        let node_type = crate::devtools::inspect::node_type(node);
303        if node_type.is_collection() {
304            Ok(())
305        } else {
306            Err(format!(
307                "Collection assertion failed: node is {:?}",
308                node_type
309            ))
310        }
311    }
312}
313
314#[cfg(test)]
315mod tests {
316    use super::*;
317
318    #[test]
319    fn test_debug_level_ordering() {
320        assert!(DebugLevel::Error < DebugLevel::Warn);
321        assert!(DebugLevel::Warn < DebugLevel::Info);
322        assert!(DebugLevel::Info < DebugLevel::Debug);
323        assert!(DebugLevel::Debug < DebugLevel::Trace);
324    }
325
326    #[test]
327    fn test_debug_context() {
328        let mut ctx = DebugContext::new(DebugLevel::Info);
329
330        ctx.error("Error message".to_string());
331        ctx.info("Info message".to_string());
332        ctx.debug("Debug message".to_string());
333
334        let logs = ctx.logs();
335        assert_eq!(logs.len(), 2); // Error and Info, but not Debug
336        assert!(logs[0].contains("Error"));
337        assert!(logs[1].contains("Info"));
338    }
339
340    #[test]
341    fn test_breakpoints() {
342        let mut ctx = DebugContext::new(DebugLevel::Debug);
343
344        ctx.add_breakpoint("parse_start".to_string());
345        ctx.add_breakpoint("parse_end".to_string());
346
347        assert!(ctx.has_breakpoint("parse_start"));
348        assert!(ctx.has_breakpoint("parse_end"));
349        assert!(!ctx.has_breakpoint("unknown"));
350
351        ctx.clear_breakpoints();
352        assert!(!ctx.has_breakpoint("parse_start"));
353    }
354
355    #[test]
356    fn test_node_debugger() {
357        let mut debugger = NodeDebugger::new();
358        let node = Node::from("test");
359
360        debugger.debug_create(&node);
361        debugger.debug_access("/path/to/node", &node);
362
363        let logs = debugger.logs();
364        assert!(logs.contains("Create"));
365        assert!(logs.contains("Access"));
366    }
367
368    #[test]
369    fn test_debug_assert_type() {
370        use crate::devtools::inspect::NodeType;
371
372        let node = Node::from("test");
373        assert!(DebugAssert::assert_type(&node, NodeType::String).is_ok());
374        assert!(DebugAssert::assert_type(&node, NodeType::Integer).is_err());
375    }
376
377    #[test]
378    fn test_debug_assert_size() {
379        let node = Node::Array(vec![Node::from(1), Node::from(2)]);
380        assert!(DebugAssert::assert_size(&node, 2).is_ok());
381        assert!(DebugAssert::assert_size(&node, 3).is_err());
382    }
383
384    #[test]
385    fn test_debug_assert_scalar() {
386        assert!(DebugAssert::assert_scalar(&Node::from("test")).is_ok());
387        assert!(DebugAssert::assert_scalar(&Node::Array(vec![])).is_err());
388    }
389
390    #[test]
391    fn test_trace_enabled() {
392        let mut debugger = NodeDebugger::with_trace();
393        assert!(debugger.trace_enabled);
394
395        debugger.disable_trace();
396        assert!(!debugger.trace_enabled);
397    }
398
399    #[test]
400    fn test_debug_context_log_levels() {
401        let mut ctx = DebugContext::new(DebugLevel::Trace);
402        ctx.error("Error".to_string());
403        ctx.warn("Warn".to_string());
404        ctx.info("Info".to_string());
405        ctx.debug("Debug".to_string());
406        ctx.trace("Trace".to_string());
407        let logs = ctx.logs();
408        assert_eq!(logs.len(), 5);
409        assert!(logs[0].contains("Error"));
410        assert!(logs[1].contains("Warn"));
411        assert!(logs[2].contains("Info"));
412        assert!(logs[3].contains("Debug"));
413        assert!(logs[4].contains("Trace"));
414    }
415
416    #[test]
417    fn test_debug_context_clear_logs() {
418        let mut ctx = DebugContext::new(DebugLevel::Debug);
419        ctx.info("Info message".to_string());
420        ctx.debug("Debug message".to_string());
421        assert!(!ctx.logs().is_empty());
422        ctx.clear_logs();
423        assert!(ctx.logs().is_empty());
424    }
425
426    #[test]
427    fn test_node_debugger_trace_visit() {
428        let mut debugger = NodeDebugger::with_trace();
429        let node = Node::from("test");
430        debugger.trace_visit(2, &node);
431        let logs = debugger.logs();
432        assert!(logs.contains("Visit"));
433        assert!(logs.contains("  ")); // Indentation for depth
434    }
435
436    #[test]
437    fn test_debug_assert_max_depth() {
438        let node = Node::Array(vec![Node::from(1), Node::Array(vec![Node::from(2)])]);
439        let depth = crate::devtools::inspect::node_depth(&node);
440        println!("Actual depth: {}", depth);
441        assert!(DebugAssert::assert_max_depth(&node, depth).is_ok());
442        assert!(DebugAssert::assert_max_depth(&node, depth - 1).is_err());
443    }
444
445    #[test]
446    fn test_debug_assert_collection() {
447        let node = Node::Array(vec![Node::from(1)]);
448        assert!(DebugAssert::assert_collection(&node).is_ok());
449        assert!(DebugAssert::assert_collection(&Node::from("test")).is_err());
450    }
451}