nginx_lint_common/
linter.rs

1//! Core types for the lint engine: rule definitions, error reporting, and fix proposals.
2//!
3//! This module contains the fundamental abstractions used by both native Rust
4//! rules (in `src/rules/`) and WASM plugin rules:
5//!
6//! - [`LintRule`] — trait that every rule implements
7//! - [`LintError`] — a single diagnostic produced by a rule
8//! - [`Severity`] — error vs. warning classification
9//! - [`Fix`] — an auto-fix action attached to a diagnostic
10//! - [`Linter`] — collects rules and runs them against a parsed config
11
12use crate::parser::ast::Config;
13use serde::Serialize;
14use std::path::Path;
15
16/// Display-ordered list of rule categories for UI output.
17///
18/// Used by the CLI and documentation generator to group rules consistently.
19pub const RULE_CATEGORIES: &[&str] = &[
20    "style",
21    "syntax",
22    "security",
23    "best-practices",
24    "deprecation",
25];
26
27/// Severity level of a lint diagnostic.
28///
29/// # Variants
30///
31/// - `Error` — the configuration is broken or has a critical security issue.
32/// - `Warning` — the configuration works but uses discouraged settings or could be improved.
33#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
34pub enum Severity {
35    /// The configuration will not work correctly, or there is a critical security issue.
36    Error,
37    /// A discouraged setting, potential problem, or improvement suggestion.
38    Warning,
39}
40
41impl std::fmt::Display for Severity {
42    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
43        match self {
44            Severity::Error => write!(f, "ERROR"),
45            Severity::Warning => write!(f, "WARNING"),
46        }
47    }
48}
49
50/// Represents a fix that can be applied to resolve a lint error
51#[derive(Debug, Clone, Serialize)]
52pub struct Fix {
53    /// Line number where the fix should be applied (1-indexed)
54    pub line: usize,
55    /// The original text to replace (if None and new_text is empty, delete the line)
56    pub old_text: Option<String>,
57    /// The new text to insert (empty string with old_text=None means delete)
58    pub new_text: String,
59    /// Whether to delete the entire line
60    #[serde(skip_serializing_if = "std::ops::Not::not")]
61    pub delete_line: bool,
62    /// Whether to insert new_text as a new line after the specified line
63    #[serde(skip_serializing_if = "std::ops::Not::not")]
64    pub insert_after: bool,
65    /// Start byte offset for range-based fix (0-indexed, inclusive)
66    #[serde(skip_serializing_if = "Option::is_none")]
67    pub start_offset: Option<usize>,
68    /// End byte offset for range-based fix (0-indexed, exclusive)
69    #[serde(skip_serializing_if = "Option::is_none")]
70    pub end_offset: Option<usize>,
71}
72
73impl Fix {
74    /// Create a fix that replaces text on a specific line
75    #[deprecated(note = "Use Fix::replace_range() for offset-based fixes instead")]
76    pub fn replace(line: usize, old_text: &str, new_text: &str) -> Self {
77        Self {
78            line,
79            old_text: Some(old_text.to_string()),
80            new_text: new_text.to_string(),
81            delete_line: false,
82            insert_after: false,
83            start_offset: None,
84            end_offset: None,
85        }
86    }
87
88    /// Create a fix that replaces an entire line
89    #[deprecated(note = "Use Fix::replace_range() for offset-based fixes instead")]
90    pub fn replace_line(line: usize, new_text: &str) -> Self {
91        Self {
92            line,
93            old_text: None,
94            new_text: new_text.to_string(),
95            delete_line: false,
96            insert_after: false,
97            start_offset: None,
98            end_offset: None,
99        }
100    }
101
102    /// Create a fix that deletes an entire line
103    #[deprecated(note = "Use Fix::replace_range() for offset-based fixes instead")]
104    pub fn delete(line: usize) -> Self {
105        Self {
106            line,
107            old_text: None,
108            new_text: String::new(),
109            delete_line: true,
110            insert_after: false,
111            start_offset: None,
112            end_offset: None,
113        }
114    }
115
116    /// Create a fix that inserts a new line after the specified line
117    #[deprecated(note = "Use Fix::replace_range() for offset-based fixes instead")]
118    pub fn insert_after(line: usize, new_text: &str) -> Self {
119        Self {
120            line,
121            old_text: None,
122            new_text: new_text.to_string(),
123            delete_line: false,
124            insert_after: true,
125            start_offset: None,
126            end_offset: None,
127        }
128    }
129
130    /// Create a range-based fix that replaces bytes from start to end offset
131    ///
132    /// This allows multiple fixes on the same line as long as their ranges don't overlap.
133    pub fn replace_range(start_offset: usize, end_offset: usize, new_text: &str) -> Self {
134        Self {
135            line: 0, // Not used for range-based fixes
136            old_text: None,
137            new_text: new_text.to_string(),
138            delete_line: false,
139            insert_after: false,
140            start_offset: Some(start_offset),
141            end_offset: Some(end_offset),
142        }
143    }
144
145    /// Check if this is a range-based fix
146    pub fn is_range_based(&self) -> bool {
147        self.start_offset.is_some() && self.end_offset.is_some()
148    }
149}
150
151/// A single lint diagnostic produced by a rule.
152///
153/// Every [`LintRule::check`] call returns a `Vec<LintError>`. Each error
154/// carries the rule name, category, a human-readable message, severity, an
155/// optional source location, and zero or more [`Fix`] proposals.
156///
157/// # Building errors
158///
159/// ```
160/// use nginx_lint_common::linter::{LintError, Severity, Fix};
161///
162/// let error = LintError::new("my-rule", "style", "trailing whitespace", Severity::Warning)
163///     .with_location(10, 1)
164///     .with_fix(Fix::replace(10, "value  ", "value"));
165/// ```
166#[derive(Debug, Clone, Serialize)]
167pub struct LintError {
168    /// Rule identifier (e.g. `"server-tokens-enabled"`).
169    pub rule: String,
170    /// Category the rule belongs to (e.g. `"security"`, `"style"`).
171    pub category: String,
172    /// Human-readable description of the problem.
173    pub message: String,
174    /// Whether this is an error or a warning.
175    pub severity: Severity,
176    /// 1-indexed line number where the problem was detected.
177    pub line: Option<usize>,
178    /// 1-indexed column number where the problem was detected.
179    pub column: Option<usize>,
180    /// Auto-fix proposals that can resolve this diagnostic.
181    #[serde(default, skip_serializing_if = "Vec::is_empty")]
182    pub fixes: Vec<Fix>,
183}
184
185impl LintError {
186    /// Create a new lint error without a source location.
187    ///
188    /// Use [`with_location`](Self::with_location) to attach line/column info
189    /// and [`with_fix`](Self::with_fix) to attach auto-fix proposals.
190    pub fn new(rule: &str, category: &str, message: &str, severity: Severity) -> Self {
191        Self {
192            rule: rule.to_string(),
193            category: category.to_string(),
194            message: message.to_string(),
195            severity,
196            line: None,
197            column: None,
198            fixes: Vec::new(),
199        }
200    }
201
202    /// Attach a source location (1-indexed line and column) to this error.
203    pub fn with_location(mut self, line: usize, column: usize) -> Self {
204        self.line = Some(line);
205        self.column = Some(column);
206        self
207    }
208
209    /// Append a single [`Fix`] proposal to this error.
210    pub fn with_fix(mut self, fix: Fix) -> Self {
211        self.fixes.push(fix);
212        self
213    }
214
215    /// Append multiple [`Fix`] proposals to this error.
216    pub fn with_fixes(mut self, fixes: Vec<Fix>) -> Self {
217        self.fixes.extend(fixes);
218        self
219    }
220}
221
222/// A lint rule that can be checked against a parsed nginx configuration.
223///
224/// Every rule — whether implemented as a native Rust struct or as a WASM
225/// plugin — implements this trait. The four required methods supply metadata
226/// and the check logic; the optional methods provide documentation and
227/// plugin-specific overrides.
228///
229/// # Required methods
230///
231/// | Method | Purpose |
232/// |--------|---------|
233/// | [`name`](Self::name) | Unique rule identifier (e.g. `"server-tokens-enabled"`) |
234/// | [`category`](Self::category) | Category for grouping (e.g. `"security"`) |
235/// | [`description`](Self::description) | One-line human-readable summary |
236/// | [`check`](Self::check) | Run the rule and return diagnostics |
237pub trait LintRule: Send + Sync {
238    /// Unique identifier for this rule (e.g. `"server-tokens-enabled"`).
239    fn name(&self) -> &'static str;
240    /// Category this rule belongs to (e.g. `"security"`, `"style"`).
241    fn category(&self) -> &'static str;
242    /// One-line human-readable description of what this rule checks.
243    fn description(&self) -> &'static str;
244    /// Run the rule against `config` (parsed from `path`) and return diagnostics.
245    fn check(&self, config: &Config, path: &Path) -> Vec<LintError>;
246
247    /// Check with pre-serialized config JSON (optimization for WASM plugins)
248    ///
249    /// This method allows passing a pre-serialized config JSON to avoid
250    /// repeated serialization when running multiple plugins.
251    /// Default implementation ignores the serialized config and calls check().
252    fn check_with_serialized_config(
253        &self,
254        config: &Config,
255        path: &Path,
256        _serialized_config: &str,
257    ) -> Vec<LintError> {
258        self.check(config, path)
259    }
260
261    /// Get detailed explanation of why this rule exists
262    fn why(&self) -> Option<&str> {
263        None
264    }
265
266    /// Get example of bad configuration
267    fn bad_example(&self) -> Option<&str> {
268        None
269    }
270
271    /// Get example of good configuration
272    fn good_example(&self) -> Option<&str> {
273        None
274    }
275
276    /// Get reference URLs
277    fn references(&self) -> Option<Vec<String>> {
278        None
279    }
280
281    /// Get severity level (for plugins)
282    fn severity(&self) -> Option<&str> {
283        None
284    }
285}
286
287/// Container that holds [`LintRule`]s and runs them against a parsed config.
288///
289/// Create a `Linter`, register rules with [`add_rule`](Self::add_rule), then
290/// call [`lint`](Self::lint) to collect all diagnostics.
291pub struct Linter {
292    rules: Vec<Box<dyn LintRule>>,
293}
294
295impl Linter {
296    /// Create an empty linter with no rules registered.
297    pub fn new() -> Self {
298        Self { rules: Vec::new() }
299    }
300
301    /// Register a lint rule. Rules are executed in registration order.
302    pub fn add_rule(&mut self, rule: Box<dyn LintRule>) {
303        self.rules.push(rule);
304    }
305
306    /// Remove rules that match the predicate
307    pub fn remove_rules_by_name<F>(&mut self, should_remove: F)
308    where
309        F: Fn(&str) -> bool,
310    {
311        self.rules.retain(|rule| !should_remove(rule.name()));
312    }
313
314    /// Get a reference to all rules
315    pub fn rules(&self) -> &[Box<dyn LintRule>] {
316        &self.rules
317    }
318
319    /// Run all lint rules and collect errors (sequential version)
320    pub fn lint(&self, config: &Config, path: &Path) -> Vec<LintError> {
321        // Pre-serialize config once for all rules (optimization for WASM plugins)
322        let serialized_config = serde_json::to_string(config).unwrap_or_default();
323
324        self.rules
325            .iter()
326            .flat_map(|rule| rule.check_with_serialized_config(config, path, &serialized_config))
327            .collect()
328    }
329}
330
331impl Default for Linter {
332    fn default() -> Self {
333        Self::new()
334    }
335}
336
337/// Compute the byte offset of the start of each line (1-indexed).
338///
339/// Returns a vector where `line_starts[0]` is always `0` (start of line 1),
340/// `line_starts[1]` is the byte offset of line 2, etc.
341/// An extra entry at the end equals `content.len()` for convenience.
342pub fn compute_line_starts(content: &str) -> Vec<usize> {
343    let mut starts = vec![0];
344    for (i, b) in content.bytes().enumerate() {
345        if b == b'\n' {
346            starts.push(i + 1);
347        }
348    }
349    starts.push(content.len());
350    starts
351}
352
353/// Convert a line-based [`Fix`] into an offset-based one using precomputed line starts.
354///
355/// Line-based fixes (created via deprecated `Fix::replace`, `Fix::delete`, etc.) are
356/// normalized to `Fix::replace_range` using the provided `line_starts` offsets.
357///
358/// Returns `None` if the fix references an out-of-range line or the `old_text` is not found.
359pub fn normalize_line_fix(fix: &Fix, content: &str, line_starts: &[usize]) -> Option<Fix> {
360    if fix.line == 0 {
361        return None;
362    }
363
364    let num_lines = line_starts.len() - 1; // last entry is content.len()
365
366    if fix.delete_line {
367        if fix.line > num_lines {
368            return None;
369        }
370        let start = line_starts[fix.line - 1];
371        let end = if fix.line < num_lines {
372            line_starts[fix.line] // includes the trailing \n
373        } else {
374            // Last line: also remove the preceding \n if there is one
375            let end = line_starts[fix.line]; // == content.len()
376            if start > 0 && content.as_bytes().get(start - 1) == Some(&b'\n') {
377                return Some(Fix::replace_range(start - 1, end, ""));
378            }
379            end
380        };
381        return Some(Fix::replace_range(start, end, ""));
382    }
383
384    if fix.insert_after {
385        if fix.line > num_lines {
386            return None;
387        }
388        // Insert point: right after the \n at end of the target line
389        let insert_offset = if fix.line < num_lines {
390            line_starts[fix.line]
391        } else {
392            content.len()
393        };
394        let new_text = if insert_offset == content.len() && !content.ends_with('\n') {
395            format!("\n{}", fix.new_text)
396        } else {
397            format!("{}\n", fix.new_text)
398        };
399        return Some(Fix::replace_range(insert_offset, insert_offset, &new_text));
400    }
401
402    if fix.line > num_lines {
403        return None;
404    }
405
406    let line_start = line_starts[fix.line - 1];
407    let line_end_with_newline = line_starts[fix.line];
408    // Line content without trailing newline
409    let line_end = if line_end_with_newline > line_start
410        && content.as_bytes().get(line_end_with_newline - 1) == Some(&b'\n')
411    {
412        line_end_with_newline - 1
413    } else {
414        line_end_with_newline
415    };
416
417    if let Some(ref old_text) = fix.old_text {
418        // Replace first occurrence of old_text within the line
419        let line_content = &content[line_start..line_end];
420        if let Some(pos) = line_content.find(old_text.as_str()) {
421            let start = line_start + pos;
422            let end = start + old_text.len();
423            return Some(Fix::replace_range(start, end, &fix.new_text));
424        }
425        return None;
426    }
427
428    // Replace entire line content (not including newline)
429    Some(Fix::replace_range(line_start, line_end, &fix.new_text))
430}
431
432/// Apply fixes to content string.
433///
434/// All fixes (both line-based and offset-based) are normalized to offset-based,
435/// then applied in reverse order to avoid index shifts. Overlapping fixes are skipped.
436///
437/// Returns `(modified_content, number_of_fixes_applied)`.
438pub fn apply_fixes_to_content(content: &str, fixes: &[&Fix]) -> (String, usize) {
439    let line_starts = compute_line_starts(content);
440
441    // Normalize all fixes to range-based
442    let mut range_fixes: Vec<Fix> = Vec::with_capacity(fixes.len());
443    for fix in fixes {
444        if fix.is_range_based() {
445            range_fixes.push((*fix).clone());
446        } else if let Some(normalized) = normalize_line_fix(fix, content, &line_starts) {
447            range_fixes.push(normalized);
448        }
449    }
450
451    // Sort by start_offset descending to avoid index shifts.
452    // For same-offset insertions (start == end), sort by indent ascending so that
453    // the more-indented text is processed last and ends up first in the file.
454    range_fixes.sort_by(|a, b| {
455        let a_start = a.start_offset.unwrap();
456        let b_start = b.start_offset.unwrap();
457        match b_start.cmp(&a_start) {
458            std::cmp::Ordering::Equal => {
459                let a_is_insert = a.end_offset.unwrap() == a_start;
460                let b_is_insert = b.end_offset.unwrap() == b_start;
461                if a_is_insert && b_is_insert {
462                    // For insertions at the same point: ascending indent order
463                    // so more-indented text is processed last (appears first in output)
464                    let a_indent = a.new_text.len() - a.new_text.trim_start().len();
465                    let b_indent = b.new_text.len() - b.new_text.trim_start().len();
466                    a_indent.cmp(&b_indent)
467                } else {
468                    std::cmp::Ordering::Equal
469                }
470            }
471            other => other,
472        }
473    });
474
475    let mut fix_count = 0;
476    let mut result = content.to_string();
477    let mut applied_ranges: Vec<(usize, usize)> = Vec::new();
478
479    for fix in &range_fixes {
480        let start = fix.start_offset.unwrap();
481        let end = fix.end_offset.unwrap();
482
483        // Check if this range overlaps with any already applied range
484        let overlaps = applied_ranges.iter().any(|(s, e)| start < *e && end > *s);
485        if overlaps {
486            continue;
487        }
488
489        if start <= result.len() && end <= result.len() && start <= end {
490            result.replace_range(start..end, &fix.new_text);
491            applied_ranges.push((start, start + fix.new_text.len()));
492            fix_count += 1;
493        }
494    }
495
496    // Ensure trailing newline
497    if !result.ends_with('\n') {
498        result.push('\n');
499    }
500
501    (result, fix_count)
502}
503
504#[cfg(test)]
505mod fix_tests {
506    use super::*;
507
508    #[test]
509    fn test_compute_line_starts() {
510        let starts = compute_line_starts("abc\ndef\nghi");
511        // line 1 starts at 0, line 2 at 4, line 3 at 8, sentinel at 11
512        assert_eq!(starts, vec![0, 4, 8, 11]);
513    }
514
515    #[test]
516    fn test_compute_line_starts_trailing_newline() {
517        let starts = compute_line_starts("abc\n");
518        // line 1 at 0, line 2 at 4 (empty), sentinel at 4
519        assert_eq!(starts, vec![0, 4, 4]);
520    }
521
522    #[test]
523    #[allow(deprecated)]
524    fn test_normalize_replace() {
525        let content = "listen 80;\nserver_name example.com;\n";
526        let line_starts = compute_line_starts(content);
527        let fix = Fix::replace(1, "80", "8080");
528        let normalized = normalize_line_fix(&fix, content, &line_starts).unwrap();
529        assert!(normalized.is_range_based());
530        assert_eq!(normalized.start_offset, Some(7));
531        assert_eq!(normalized.end_offset, Some(9));
532        assert_eq!(normalized.new_text, "8080");
533    }
534
535    #[test]
536    #[allow(deprecated)]
537    fn test_normalize_delete() {
538        let content = "line1\nline2\nline3\n";
539        let line_starts = compute_line_starts(content);
540        let fix = Fix::delete(2);
541        let normalized = normalize_line_fix(&fix, content, &line_starts).unwrap();
542        assert!(normalized.is_range_based());
543        // Should delete "line2\n" (offset 6..12)
544        assert_eq!(normalized.start_offset, Some(6));
545        assert_eq!(normalized.end_offset, Some(12));
546    }
547
548    #[test]
549    #[allow(deprecated)]
550    fn test_normalize_insert_after() {
551        let content = "line1\nline2\n";
552        let line_starts = compute_line_starts(content);
553        let fix = Fix::insert_after(1, "inserted");
554        let normalized = normalize_line_fix(&fix, content, &line_starts).unwrap();
555        assert!(normalized.is_range_based());
556        // Insert at offset 6 (start of line 2)
557        assert_eq!(normalized.start_offset, Some(6));
558        assert_eq!(normalized.end_offset, Some(6));
559        assert_eq!(normalized.new_text, "inserted\n");
560    }
561
562    #[test]
563    #[allow(deprecated)]
564    fn test_normalize_out_of_range() {
565        let content = "line1\n";
566        let line_starts = compute_line_starts(content);
567        let fix = Fix::delete(99);
568        assert!(normalize_line_fix(&fix, content, &line_starts).is_none());
569    }
570
571    #[test]
572    #[allow(deprecated)]
573    fn test_normalize_replace_not_found() {
574        let content = "listen 80;\n";
575        let line_starts = compute_line_starts(content);
576        let fix = Fix::replace(1, "nonexistent", "new");
577        assert!(normalize_line_fix(&fix, content, &line_starts).is_none());
578    }
579
580    #[test]
581    fn test_apply_range_fix() {
582        let content = "listen 80;\n";
583        let fix = Fix::replace_range(7, 9, "8080");
584        let fixes: Vec<&Fix> = vec![&fix];
585        let (result, count) = apply_fixes_to_content(content, &fixes);
586        assert_eq!(result, "listen 8080;\n");
587        assert_eq!(count, 1);
588    }
589
590    #[test]
591    fn test_apply_multiple_fixes_same_line() {
592        // Two fixes on the same line should both apply
593        let content = "proxy_set_header Host $host;\n";
594        let fix1 = Fix::replace_range(17, 21, "X-Real-IP");
595        let fix2 = Fix::replace_range(22, 27, "$remote_addr");
596        let fixes: Vec<&Fix> = vec![&fix1, &fix2];
597        let (result, count) = apply_fixes_to_content(content, &fixes);
598        assert_eq!(result, "proxy_set_header X-Real-IP $remote_addr;\n");
599        assert_eq!(count, 2);
600    }
601
602    #[test]
603    fn test_apply_overlapping_fixes_skips() {
604        let content = "abcdef\n";
605        let fix1 = Fix::replace_range(0, 3, "XYZ"); // replace "abc"
606        let fix2 = Fix::replace_range(2, 5, "QQQ"); // overlaps with fix1
607        let fixes: Vec<&Fix> = vec![&fix1, &fix2];
608        let (_, count) = apply_fixes_to_content(content, &fixes);
609        // Only one fix should apply (the other is skipped due to overlap)
610        assert_eq!(count, 1);
611    }
612
613    #[test]
614    #[allow(deprecated)]
615    fn test_apply_deprecated_fix_via_normalization() {
616        let content = "listen 80;\nserver_name old;\n";
617        let fix = Fix::replace(2, "old", "new");
618        let fixes: Vec<&Fix> = vec![&fix];
619        let (result, count) = apply_fixes_to_content(content, &fixes);
620        assert_eq!(result, "listen 80;\nserver_name new;\n");
621        assert_eq!(count, 1);
622    }
623}
nginx_lint_common/linter.rs

nginx_lint_common/
linter.rs
