agm_core/validator/
node.rs

1//! Per-node structural validation (spec S11, S12).
2//!
3//! Pass 2: validates node IDs, summary, dates, status constraints.
4
5use std::collections::{HashMap, HashSet};
6use std::sync::OnceLock;
7
8use regex::Regex;
9
10use crate::error::codes::ErrorCode;
11use crate::error::diagnostic::{AgmError, ErrorLocation, Severity};
12use crate::model::fields::NodeStatus;
13use crate::model::node::Node;
14
15/// Regex pattern for valid node IDs: dot-or-hyphen-separated lowercase segments.
16/// Segments may contain lowercase letters, digits, and underscores.
17/// First character of each segment must be a letter.
18static NODE_ID_PATTERN: OnceLock<Regex> = OnceLock::new();
19
20fn node_id_regex() -> &'static Regex {
21    NODE_ID_PATTERN.get_or_init(|| Regex::new(r"^[a-z][a-z0-9_]*([.\-][a-z][a-z0-9_]*)*$").unwrap())
22}
23
24/// Validates all node IDs for uniqueness (V003) and pattern compliance (V021).
25///
26/// Returns errors for duplicate IDs and invalid ID patterns.
27#[must_use]
28pub fn validate_node_ids(nodes: &[Node], file_name: &str) -> Vec<AgmError> {
29    let mut errors = Vec::new();
30    let mut seen: HashMap<&str, usize> = HashMap::new();
31    let pattern = node_id_regex();
32
33    for node in nodes {
34        let id = node.id.as_str();
35        let line = node.span.start_line;
36
37        // V003 — uniqueness
38        if let Some(&first_line) = seen.get(id) {
39            errors.push(AgmError::new(
40                ErrorCode::V003,
41                format!("Duplicate node ID: `{id}` (first seen at line {first_line})"),
42                ErrorLocation::full(file_name, line, id),
43            ));
44        } else {
45            seen.insert(id, line);
46        }
47
48        // V021 — ID pattern
49        if !pattern.is_match(id) {
50            errors.push(AgmError::new(
51                ErrorCode::V021,
52                format!("Node ID does not match required pattern: `{id}`"),
53                ErrorLocation::full(file_name, line, id),
54            ));
55        }
56    }
57
58    errors
59}
60
61/// Validates a single node's structural fields.
62///
63/// Rules: V002 (missing summary), V007 (valid_from > valid_until),
64/// V011 (empty summary warning), V012 (summary too long warning),
65/// V014 (deprecated/superseded without replaces).
66#[must_use]
67pub fn validate_node(node: &Node, all_ids: &HashSet<String>, file_name: &str) -> Vec<AgmError> {
68    let _ = all_ids; // used by callers building sets; kept in signature for consistency
69    let mut errors = Vec::new();
70    let line = node.span.start_line;
71    let id = node.id.as_str();
72
73    // V002 — summary required (missing entirely, not just empty)
74    // In the model, summary is String (never None). We check for empty here
75    // as defensive validation; parser may produce empty string.
76    if node.summary.is_empty() {
77        errors.push(AgmError::new(
78            ErrorCode::V002,
79            format!("Node `{id}` missing required field: `summary`"),
80            ErrorLocation::full(file_name, line, id),
81        ));
82        // If truly empty, skip the whitespace/length checks
83        return errors;
84    }
85
86    // V011 — summary is whitespace-only (warning)
87    if node.summary.trim().is_empty() {
88        errors.push(AgmError::with_severity(
89            ErrorCode::V011,
90            Severity::Warning,
91            format!("Summary is empty in node `{id}`"),
92            ErrorLocation::full(file_name, line, id),
93        ));
94    }
95
96    // V012 — summary exceeds 200 characters (warning, measured in chars)
97    if node.summary.chars().count() > 200 {
98        errors.push(AgmError::with_severity(
99            ErrorCode::V012,
100            Severity::Warning,
101            format!("Summary exceeds 200 characters in node `{id}`"),
102            ErrorLocation::full(file_name, line, id),
103        ));
104    }
105
106    // V007 — valid_from must not be after valid_until
107    if let (Some(from), Some(until)) = (&node.valid_from, &node.valid_until) {
108        // Compare as strings: ISO 8601 dates and datetimes sort lexicographically
109        // when zero-padded (which is the standard). This handles both date-only
110        // and datetime formats without pulling in a date library.
111        if from.as_str() > until.as_str() {
112            errors.push(AgmError::new(
113                ErrorCode::V007,
114                format!("`valid_from` is after `valid_until` in node `{id}`"),
115                ErrorLocation::full(file_name, line, id),
116            ));
117        }
118    }
119
120    // V014 — deprecated or superseded node missing `replaces` (warning)
121    let needs_replaces = matches!(
122        &node.status,
123        Some(NodeStatus::Deprecated) | Some(NodeStatus::Superseded)
124    );
125    if needs_replaces && node.replaces.is_none() {
126        errors.push(AgmError::with_severity(
127            ErrorCode::V014,
128            Severity::Warning,
129            format!("Deprecated node `{id}` missing `replaces` or `superseded_by`"),
130            ErrorLocation::full(file_name, line, id),
131        ));
132    }
133
134    errors
135}
136
137#[cfg(test)]
138mod tests {
139
140    use super::*;
141    use crate::model::fields::{NodeStatus, NodeType, Span};
142    use crate::model::node::Node;
143
144    fn minimal_node() -> Node {
145        Node {
146            id: "test.node".to_owned(),
147            node_type: NodeType::Facts,
148            summary: "a test node".to_owned(),
149            span: Span::new(5, 7),
150            ..Default::default()
151        }
152    }
153
154    #[test]
155    fn test_validate_node_ids_duplicate_returns_v003() {
156        let mut n1 = minimal_node();
157        let mut n2 = minimal_node();
158        n1.id = "auth.login".to_owned();
159        n2.id = "auth.login".to_owned();
160        n2.span = Span::new(10, 12);
161        let errors = validate_node_ids(&[n1, n2], "test.agm");
162        assert!(errors.iter().any(|e| e.code == ErrorCode::V003));
163    }
164
165    #[test]
166    fn test_validate_node_id_valid_pattern_returns_empty() {
167        let mut node = minimal_node();
168        node.id = "auth.login".to_owned();
169        let errors = validate_node_ids(&[node], "test.agm");
170        assert!(errors.is_empty());
171    }
172
173    #[test]
174    fn test_validate_node_id_single_segment_valid() {
175        let mut node = minimal_node();
176        node.id = "auth".to_owned();
177        let errors = validate_node_ids(&[node], "test.agm");
178        assert!(errors.is_empty());
179    }
180
181    #[test]
182    fn test_validate_node_id_invalid_pattern_uppercase_returns_v021() {
183        let mut node = minimal_node();
184        node.id = "Auth.Login".to_owned();
185        let errors = validate_node_ids(&[node], "test.agm");
186        assert!(errors.iter().any(|e| e.code == ErrorCode::V021));
187    }
188
189    #[test]
190    fn test_validate_node_id_leading_dot_returns_v021() {
191        let mut node = minimal_node();
192        node.id = ".auth.login".to_owned();
193        let errors = validate_node_ids(&[node], "test.agm");
194        assert!(errors.iter().any(|e| e.code == ErrorCode::V021));
195    }
196
197    #[test]
198    fn test_validate_node_id_trailing_dot_returns_v021() {
199        let mut node = minimal_node();
200        node.id = "auth.login.".to_owned();
201        let errors = validate_node_ids(&[node], "test.agm");
202        assert!(errors.iter().any(|e| e.code == ErrorCode::V021));
203    }
204
205    #[test]
206    fn test_validate_node_id_consecutive_dots_returns_v021() {
207        let mut node = minimal_node();
208        node.id = "auth..login".to_owned();
209        let errors = validate_node_ids(&[node], "test.agm");
210        assert!(errors.iter().any(|e| e.code == ErrorCode::V021));
211    }
212
213    #[test]
214    fn test_validate_node_id_starts_with_digit_returns_v021() {
215        let mut node = minimal_node();
216        node.id = "1auth".to_owned();
217        let errors = validate_node_ids(&[node], "test.agm");
218        assert!(errors.iter().any(|e| e.code == ErrorCode::V021));
219    }
220
221    #[test]
222    fn test_validate_node_empty_summary_returns_v002() {
223        let mut node = minimal_node();
224        node.summary = String::new();
225        let all_ids = HashSet::new();
226        let errors = validate_node(&node, &all_ids, "test.agm");
227        assert!(errors.iter().any(|e| e.code == ErrorCode::V002));
228    }
229
230    #[test]
231    fn test_validate_node_whitespace_only_summary_returns_v011() {
232        let mut node = minimal_node();
233        node.summary = "   ".to_owned();
234        let all_ids = HashSet::new();
235        let errors = validate_node(&node, &all_ids, "test.agm");
236        assert!(errors.iter().any(|e| e.code == ErrorCode::V011));
237    }
238
239    #[test]
240    fn test_validate_node_summary_exactly_200_returns_empty() {
241        let mut node = minimal_node();
242        node.summary = "a".repeat(200);
243        let all_ids = HashSet::new();
244        let errors = validate_node(&node, &all_ids, "test.agm");
245        assert!(errors.is_empty(), "200 chars should not trigger V012");
246    }
247
248    #[test]
249    fn test_validate_node_summary_201_chars_returns_v012() {
250        let mut node = minimal_node();
251        node.summary = "a".repeat(201);
252        let all_ids = HashSet::new();
253        let errors = validate_node(&node, &all_ids, "test.agm");
254        assert!(errors.iter().any(|e| e.code == ErrorCode::V012));
255    }
256
257    #[test]
258    fn test_validate_node_valid_from_after_until_returns_v007() {
259        let mut node = minimal_node();
260        node.valid_from = Some("2025-12-31".to_owned());
261        node.valid_until = Some("2025-01-01".to_owned());
262        let all_ids = HashSet::new();
263        let errors = validate_node(&node, &all_ids, "test.agm");
264        assert!(errors.iter().any(|e| e.code == ErrorCode::V007));
265    }
266
267    #[test]
268    fn test_validate_node_valid_from_equals_until_returns_empty() {
269        let mut node = minimal_node();
270        node.valid_from = Some("2025-06-01".to_owned());
271        node.valid_until = Some("2025-06-01".to_owned());
272        let all_ids = HashSet::new();
273        let errors = validate_node(&node, &all_ids, "test.agm");
274        assert!(errors.is_empty());
275    }
276
277    #[test]
278    fn test_validate_node_valid_from_before_until_returns_empty() {
279        let mut node = minimal_node();
280        node.valid_from = Some("2025-01-01".to_owned());
281        node.valid_until = Some("2025-12-31".to_owned());
282        let all_ids = HashSet::new();
283        let errors = validate_node(&node, &all_ids, "test.agm");
284        assert!(errors.is_empty());
285    }
286
287    #[test]
288    fn test_validate_node_deprecated_no_replaces_returns_v014() {
289        let mut node = minimal_node();
290        node.status = Some(NodeStatus::Deprecated);
291        node.replaces = None;
292        let all_ids = HashSet::new();
293        let errors = validate_node(&node, &all_ids, "test.agm");
294        assert!(errors.iter().any(|e| e.code == ErrorCode::V014));
295    }
296
297    #[test]
298    fn test_validate_node_superseded_no_replaces_returns_v014() {
299        let mut node = minimal_node();
300        node.status = Some(NodeStatus::Superseded);
301        node.replaces = None;
302        let all_ids = HashSet::new();
303        let errors = validate_node(&node, &all_ids, "test.agm");
304        assert!(errors.iter().any(|e| e.code == ErrorCode::V014));
305    }
306
307    #[test]
308    fn test_validate_node_superseded_with_replaces_returns_empty() {
309        let mut node = minimal_node();
310        node.status = Some(NodeStatus::Superseded);
311        node.replaces = Some(vec!["other.node".to_owned()]);
312        let all_ids = HashSet::new();
313        let errors = validate_node(&node, &all_ids, "test.agm");
314        assert!(!errors.iter().any(|e| e.code == ErrorCode::V014));
315    }
316
317    #[test]
318    fn test_validate_node_valid_node_returns_empty() {
319        let node = minimal_node();
320        let all_ids = HashSet::new();
321        let errors = validate_node(&node, &all_ids, "test.agm");
322        assert!(errors.is_empty());
323    }
324}
agm_core/validator/node.rs

agm_core/validator/
node.rs
