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    /// Minimum nginx version this rule applies to (inclusive).
287    ///
288    /// `None` means the rule applies regardless of how old the nginx version is.
289    /// Used by the linter's version-based rule filter to decide whether to
290    /// run this rule against a config whose
291    /// [`target_nginx_version`](crate::config::LintConfig::target_nginx_version)
292    /// is set.
293    fn min_nginx_version(&self) -> Option<&str> {
294        None
295    }
296
297    /// Maximum nginx version this rule applies to (inclusive).
298    ///
299    /// `None` means the rule applies regardless of how new the nginx version is.
300    fn max_nginx_version(&self) -> Option<&str> {
301        None
302    }
303}
304
305/// Container that holds [`LintRule`]s and runs them against a parsed config.
306///
307/// Create a `Linter`, register rules with [`add_rule`](Self::add_rule), then
308/// call [`lint`](Self::lint) to collect all diagnostics.
309pub struct Linter {
310    rules: Vec<Box<dyn LintRule>>,
311}
312
313impl Linter {
314    /// Create an empty linter with no rules registered.
315    pub fn new() -> Self {
316        Self { rules: Vec::new() }
317    }
318
319    /// Register a lint rule. Rules are executed in registration order.
320    pub fn add_rule(&mut self, rule: Box<dyn LintRule>) {
321        self.rules.push(rule);
322    }
323
324    /// Remove rules that match the predicate
325    pub fn remove_rules_by_name<F>(&mut self, should_remove: F)
326    where
327        F: Fn(&str) -> bool,
328    {
329        self.rules.retain(|rule| !should_remove(rule.name()));
330    }
331
332    /// Get a reference to all rules
333    pub fn rules(&self) -> &[Box<dyn LintRule>] {
334        &self.rules
335    }
336
337    /// Run all lint rules and collect errors (sequential version)
338    pub fn lint(&self, config: &Config, path: &Path) -> Vec<LintError> {
339        // Pre-serialize config once for all rules (optimization for WASM plugins)
340        let serialized_config = serde_json::to_string(config).unwrap_or_default();
341
342        self.rules
343            .iter()
344            .flat_map(|rule| rule.check_with_serialized_config(config, path, &serialized_config))
345            .collect()
346    }
347}
348
349impl Default for Linter {
350    fn default() -> Self {
351        Self::new()
352    }
353}
354
355/// Compute the byte offset of the start of each line (1-indexed).
356///
357/// Returns a vector where `line_starts[0]` is always `0` (start of line 1),
358/// `line_starts[1]` is the byte offset of line 2, etc.
359/// An extra entry at the end equals `content.len()` for convenience.
360pub fn compute_line_starts(content: &str) -> Vec<usize> {
361    let mut starts = vec![0];
362    for (i, b) in content.bytes().enumerate() {
363        if b == b'\n' {
364            starts.push(i + 1);
365        }
366    }
367    starts.push(content.len());
368    starts
369}
370
371/// Convert a line-based [`Fix`] into an offset-based one using precomputed line starts.
372///
373/// Line-based fixes (created via deprecated `Fix::replace`, `Fix::delete`, etc.) are
374/// normalized to `Fix::replace_range` using the provided `line_starts` offsets.
375///
376/// Returns `None` if the fix references an out-of-range line or the `old_text` is not found.
377pub fn normalize_line_fix(fix: &Fix, content: &str, line_starts: &[usize]) -> Option<Fix> {
378    if fix.line == 0 {
379        return None;
380    }
381
382    let num_lines = line_starts.len() - 1; // last entry is content.len()
383
384    if fix.delete_line {
385        if fix.line > num_lines {
386            return None;
387        }
388        let start = line_starts[fix.line - 1];
389        let end = if fix.line < num_lines {
390            line_starts[fix.line] // includes the trailing \n
391        } else {
392            // Last line: also remove the preceding \n if there is one
393            let end = line_starts[fix.line]; // == content.len()
394            if start > 0 && content.as_bytes().get(start - 1) == Some(&b'\n') {
395                return Some(Fix::replace_range(start - 1, end, ""));
396            }
397            end
398        };
399        return Some(Fix::replace_range(start, end, ""));
400    }
401
402    if fix.insert_after {
403        if fix.line > num_lines {
404            return None;
405        }
406        // Insert point: right after the \n at end of the target line
407        let insert_offset = if fix.line < num_lines {
408            line_starts[fix.line]
409        } else {
410            content.len()
411        };
412        let new_text = if insert_offset == content.len() && !content.ends_with('\n') {
413            format!("\n{}", fix.new_text)
414        } else {
415            format!("{}\n", fix.new_text)
416        };
417        return Some(Fix::replace_range(insert_offset, insert_offset, &new_text));
418    }
419
420    if fix.line > num_lines {
421        return None;
422    }
423
424    let line_start = line_starts[fix.line - 1];
425    let line_end_with_newline = line_starts[fix.line];
426    // Line content without trailing newline
427    let line_end = if line_end_with_newline > line_start
428        && content.as_bytes().get(line_end_with_newline - 1) == Some(&b'\n')
429    {
430        line_end_with_newline - 1
431    } else {
432        line_end_with_newline
433    };
434
435    if let Some(ref old_text) = fix.old_text {
436        // Replace first occurrence of old_text within the line
437        let line_content = &content[line_start..line_end];
438        if let Some(pos) = line_content.find(old_text.as_str()) {
439            let start = line_start + pos;
440            let end = start + old_text.len();
441            return Some(Fix::replace_range(start, end, &fix.new_text));
442        }
443        return None;
444    }
445
446    // Replace entire line content (not including newline)
447    Some(Fix::replace_range(line_start, line_end, &fix.new_text))
448}
449
450/// Apply fixes to content string.
451///
452/// All fixes (both line-based and offset-based) are normalized to offset-based,
453/// then applied in reverse order to avoid index shifts. Overlapping fixes are skipped.
454///
455/// Returns `(modified_content, number_of_fixes_applied)`.
456pub fn apply_fixes_to_content(content: &str, fixes: &[&Fix]) -> (String, usize) {
457    let line_starts = compute_line_starts(content);
458
459    // Normalize all fixes to range-based
460    let mut range_fixes: Vec<Fix> = Vec::with_capacity(fixes.len());
461    for fix in fixes {
462        if fix.is_range_based() {
463            range_fixes.push((*fix).clone());
464        } else if let Some(normalized) = normalize_line_fix(fix, content, &line_starts) {
465            range_fixes.push(normalized);
466        }
467    }
468
469    // Sort by start_offset descending to avoid index shifts.
470    // For same-offset insertions (start == end), sort by indent ascending so that
471    // the more-indented text is processed last and ends up first in the file.
472    range_fixes.sort_by(|a, b| {
473        let a_start = a.start_offset.unwrap();
474        let b_start = b.start_offset.unwrap();
475        match b_start.cmp(&a_start) {
476            std::cmp::Ordering::Equal => {
477                let a_is_insert = a.end_offset.unwrap() == a_start;
478                let b_is_insert = b.end_offset.unwrap() == b_start;
479                if a_is_insert && b_is_insert {
480                    // For insertions at the same point: ascending indent order
481                    // so more-indented text is processed last (appears first in output)
482                    let a_indent = a.new_text.len() - a.new_text.trim_start().len();
483                    let b_indent = b.new_text.len() - b.new_text.trim_start().len();
484                    a_indent.cmp(&b_indent)
485                } else {
486                    std::cmp::Ordering::Equal
487                }
488            }
489            other => other,
490        }
491    });
492
493    let mut fix_count = 0;
494    let mut result = content.to_string();
495    let mut applied_ranges: Vec<(usize, usize)> = Vec::new();
496
497    for fix in &range_fixes {
498        let start = fix.start_offset.unwrap();
499        let end = fix.end_offset.unwrap();
500
501        // Check if this range overlaps with any already applied range
502        let overlaps = applied_ranges.iter().any(|(s, e)| start < *e && end > *s);
503        if overlaps {
504            continue;
505        }
506
507        if start <= result.len() && end <= result.len() && start <= end {
508            result.replace_range(start..end, &fix.new_text);
509            applied_ranges.push((start, start + fix.new_text.len()));
510            fix_count += 1;
511        }
512    }
513
514    // Ensure trailing newline
515    if !result.ends_with('\n') {
516        result.push('\n');
517    }
518
519    (result, fix_count)
520}
521
522#[cfg(test)]
523mod fix_tests {
524    use super::*;
525
526    #[test]
527    fn test_compute_line_starts() {
528        let starts = compute_line_starts("abc\ndef\nghi");
529        // line 1 starts at 0, line 2 at 4, line 3 at 8, sentinel at 11
530        assert_eq!(starts, vec![0, 4, 8, 11]);
531    }
532
533    #[test]
534    fn test_compute_line_starts_trailing_newline() {
535        let starts = compute_line_starts("abc\n");
536        // line 1 at 0, line 2 at 4 (empty), sentinel at 4
537        assert_eq!(starts, vec![0, 4, 4]);
538    }
539
540    #[test]
541    #[allow(deprecated)]
542    fn test_normalize_replace() {
543        let content = "listen 80;\nserver_name example.com;\n";
544        let line_starts = compute_line_starts(content);
545        let fix = Fix::replace(1, "80", "8080");
546        let normalized = normalize_line_fix(&fix, content, &line_starts).unwrap();
547        assert!(normalized.is_range_based());
548        assert_eq!(normalized.start_offset, Some(7));
549        assert_eq!(normalized.end_offset, Some(9));
550        assert_eq!(normalized.new_text, "8080");
551    }
552
553    #[test]
554    #[allow(deprecated)]
555    fn test_normalize_delete() {
556        let content = "line1\nline2\nline3\n";
557        let line_starts = compute_line_starts(content);
558        let fix = Fix::delete(2);
559        let normalized = normalize_line_fix(&fix, content, &line_starts).unwrap();
560        assert!(normalized.is_range_based());
561        // Should delete "line2\n" (offset 6..12)
562        assert_eq!(normalized.start_offset, Some(6));
563        assert_eq!(normalized.end_offset, Some(12));
564    }
565
566    #[test]
567    #[allow(deprecated)]
568    fn test_normalize_insert_after() {
569        let content = "line1\nline2\n";
570        let line_starts = compute_line_starts(content);
571        let fix = Fix::insert_after(1, "inserted");
572        let normalized = normalize_line_fix(&fix, content, &line_starts).unwrap();
573        assert!(normalized.is_range_based());
574        // Insert at offset 6 (start of line 2)
575        assert_eq!(normalized.start_offset, Some(6));
576        assert_eq!(normalized.end_offset, Some(6));
577        assert_eq!(normalized.new_text, "inserted\n");
578    }
579
580    #[test]
581    #[allow(deprecated)]
582    fn test_normalize_out_of_range() {
583        let content = "line1\n";
584        let line_starts = compute_line_starts(content);
585        let fix = Fix::delete(99);
586        assert!(normalize_line_fix(&fix, content, &line_starts).is_none());
587    }
588
589    #[test]
590    #[allow(deprecated)]
591    fn test_normalize_replace_not_found() {
592        let content = "listen 80;\n";
593        let line_starts = compute_line_starts(content);
594        let fix = Fix::replace(1, "nonexistent", "new");
595        assert!(normalize_line_fix(&fix, content, &line_starts).is_none());
596    }
597
598    #[test]
599    fn test_apply_range_fix() {
600        let content = "listen 80;\n";
601        let fix = Fix::replace_range(7, 9, "8080");
602        let fixes: Vec<&Fix> = vec![&fix];
603        let (result, count) = apply_fixes_to_content(content, &fixes);
604        assert_eq!(result, "listen 8080;\n");
605        assert_eq!(count, 1);
606    }
607
608    #[test]
609    fn test_apply_multiple_fixes_same_line() {
610        // Two fixes on the same line should both apply
611        let content = "proxy_set_header Host $host;\n";
612        let fix1 = Fix::replace_range(17, 21, "X-Real-IP");
613        let fix2 = Fix::replace_range(22, 27, "$remote_addr");
614        let fixes: Vec<&Fix> = vec![&fix1, &fix2];
615        let (result, count) = apply_fixes_to_content(content, &fixes);
616        assert_eq!(result, "proxy_set_header X-Real-IP $remote_addr;\n");
617        assert_eq!(count, 2);
618    }
619
620    #[test]
621    fn test_apply_overlapping_fixes_skips() {
622        let content = "abcdef\n";
623        let fix1 = Fix::replace_range(0, 3, "XYZ"); // replace "abc"
624        let fix2 = Fix::replace_range(2, 5, "QQQ"); // overlaps with fix1
625        let fixes: Vec<&Fix> = vec![&fix1, &fix2];
626        let (_, count) = apply_fixes_to_content(content, &fixes);
627        // Only one fix should apply (the other is skipped due to overlap)
628        assert_eq!(count, 1);
629    }
630
631    #[test]
632    #[allow(deprecated)]
633    fn test_apply_deprecated_fix_via_normalization() {
634        let content = "listen 80;\nserver_name old;\n";
635        let fix = Fix::replace(2, "old", "new");
636        let fixes: Vec<&Fix> = vec![&fix];
637        let (result, count) = apply_fixes_to_content(content, &fixes);
638        assert_eq!(result, "listen 80;\nserver_name new;\n");
639        assert_eq!(count, 1);
640    }
641}
nginx_lint_common/linter.rs

nginx_lint_common/
linter.rs
