kaish_kernel/validator/
scope_tracker.rs

1//! Variable scope tracking for validation.
2//!
3//! Tracks which variables are bound in each scope without caring about values.
4//! Used to detect possibly undefined variable references.
5
6use std::collections::HashSet;
7
8/// Tracks variable bindings across nested scopes.
9///
10/// Unlike the interpreter's Scope which holds values, this only tracks names
11/// for static validation purposes.
12pub struct ScopeTracker {
13    /// Stack of scope frames, each containing bound variable names.
14    frames: Vec<HashSet<String>>,
15}
16
17impl Default for ScopeTracker {
18    fn default() -> Self {
19        Self::new()
20    }
21}
22
23impl ScopeTracker {
24    /// Create a new scope tracker with built-in special variables.
25    pub fn new() -> Self {
26        let mut tracker = Self {
27            frames: vec![HashSet::new()],
28        };
29
30        // Register built-in special variables
31        tracker.bind_builtins();
32
33        tracker
34    }
35
36    /// Register all built-in and special shell variables.
37    fn bind_builtins(&mut self) {
38        let builtins = [
39            // Exit status
40            "?",
41            // Positional parameters
42            "0", "1", "2", "3", "4", "5", "6", "7", "8", "9",
43            // Special arrays
44            "@", "#", "*",
45            // Environment defaults
46            "HOME", "PATH", "PWD", "OLDPWD", "USER", "SHELL", "TERM",
47            // Script info
48            "LINENO", "FUNCNAME", "BASH_SOURCE",
49            // IFS for word splitting
50            "IFS",
51            // Random
52            "RANDOM",
53            // Process info
54            "PID", "PPID", "UID", "EUID",
55        ];
56
57        for name in builtins {
58            self.bind(name);
59        }
60    }
61
62    /// Push a new scope frame.
63    ///
64    /// Variables bound after this call are local to the new frame
65    /// until `pop_frame` is called.
66    pub fn push_frame(&mut self) {
67        self.frames.push(HashSet::new());
68    }
69
70    /// Pop the current scope frame.
71    ///
72    /// Variables bound in this frame are forgotten.
73    /// Panics if trying to pop the global frame.
74    pub fn pop_frame(&mut self) {
75        if self.frames.len() > 1 {
76            self.frames.pop();
77        }
78    }
79
80    /// Bind a variable name in the current scope.
81    pub fn bind(&mut self, name: impl Into<String>) {
82        if let Some(frame) = self.frames.last_mut() {
83            frame.insert(name.into());
84        }
85    }
86
87    /// Check if a variable is bound in any scope.
88    ///
89    /// Searches from innermost to outermost scope.
90    pub fn is_bound(&self, name: &str) -> bool {
91        self.frames.iter().rev().any(|frame| frame.contains(name))
92    }
93
94    /// Check if a variable name should skip undefined warnings.
95    ///
96    /// Variables starting with underscore are conventionally external
97    /// or intentionally unchecked.
98    pub fn should_skip_undefined_check(name: &str) -> bool {
99        name.starts_with('_')
100    }
101
102    /// Get the current nesting depth.
103    pub fn depth(&self) -> usize {
104        self.frames.len()
105    }
106
107}
108
109#[cfg(test)]
110mod tests {
111    use super::*;
112
113    #[test]
114    fn new_has_builtins() {
115        let tracker = ScopeTracker::new();
116        assert!(tracker.is_bound("?"));
117        assert!(tracker.is_bound("HOME"));
118        assert!(tracker.is_bound("PATH"));
119        assert!(tracker.is_bound("0"));
120        assert!(tracker.is_bound("@"));
121    }
122
123    #[test]
124    fn bind_and_lookup() {
125        let mut tracker = ScopeTracker::new();
126        assert!(!tracker.is_bound("MY_VAR"));
127        tracker.bind("MY_VAR");
128        assert!(tracker.is_bound("MY_VAR"));
129    }
130
131    #[test]
132    fn nested_scopes() {
133        let mut tracker = ScopeTracker::new();
134
135        tracker.bind("OUTER");
136        assert!(tracker.is_bound("OUTER"));
137
138        tracker.push_frame();
139        tracker.bind("INNER");
140        assert!(tracker.is_bound("INNER"));
141        assert!(tracker.is_bound("OUTER")); // Still visible from outer scope
142
143        tracker.pop_frame();
144        assert!(!tracker.is_bound("INNER")); // Gone
145        assert!(tracker.is_bound("OUTER")); // Still there
146    }
147
148    #[test]
149    fn underscore_convention() {
150        assert!(ScopeTracker::should_skip_undefined_check("_EXTERNAL"));
151        assert!(ScopeTracker::should_skip_undefined_check("__private"));
152        assert!(!ScopeTracker::should_skip_undefined_check("NORMAL"));
153    }
154
155    #[test]
156    fn depth_tracking() {
157        let mut tracker = ScopeTracker::new();
158        assert_eq!(tracker.depth(), 1);
159
160        tracker.push_frame();
161        assert_eq!(tracker.depth(), 2);
162
163        tracker.push_frame();
164        assert_eq!(tracker.depth(), 3);
165
166        tracker.pop_frame();
167        assert_eq!(tracker.depth(), 2);
168
169        tracker.pop_frame();
170        assert_eq!(tracker.depth(), 1);
171
172        // Can't pop the global frame
173        tracker.pop_frame();
174        assert_eq!(tracker.depth(), 1);
175    }
176}
kaish_kernel/validator/scope_tracker.rs

kaish_kernel/validator/
scope_tracker.rs
