rumdl_lib/rules/
md026_no_trailing_punctuation.rs

1/// Rule MD026: No trailing punctuation in headings
2///
3/// See [docs/md026.md](../../docs/md026.md) for full documentation, configuration, and examples.
4use crate::rule::{Fix, LintError, LintResult, LintWarning, Rule, RuleCategory, Severity};
5use crate::utils::range_utils::{LineIndex, calculate_match_range};
6use regex::Regex;
7use std::collections::HashMap;
8use std::ops::Range;
9use std::sync::LazyLock;
10use std::sync::RwLock;
11
12mod md026_config;
13use md026_config::{DEFAULT_PUNCTUATION, MD026Config};
14
15// Optimized single regex for all ATX heading types (normal, closed, indented 1-3 spaces)
16static ATX_HEADING_UNIFIED: LazyLock<Regex> =
17    LazyLock::new(|| Regex::new(r"^( {0,3})(#{1,6})(\s+)(.+?)(\s+#{1,6})?$").unwrap());
18
19// Fast check patterns for early returns - match defaults
20static QUICK_PUNCTUATION_CHECK: LazyLock<Regex> =
21    LazyLock::new(|| Regex::new(&format!(r"[{}]", regex::escape(DEFAULT_PUNCTUATION))).unwrap());
22
23// Regex cache for punctuation patterns
24static PUNCTUATION_REGEX_CACHE: LazyLock<RwLock<HashMap<String, Regex>>> =
25    LazyLock::new(|| RwLock::new(HashMap::new()));
26
27/// Rule MD026: Trailing punctuation in heading
28#[derive(Clone, Default)]
29pub struct MD026NoTrailingPunctuation {
30    config: MD026Config,
31}
32
33impl MD026NoTrailingPunctuation {
34    pub fn new(punctuation: Option<String>) -> Self {
35        Self {
36            config: MD026Config {
37                punctuation: punctuation.unwrap_or_else(|| DEFAULT_PUNCTUATION.to_string()),
38            },
39        }
40    }
41
42    pub fn from_config_struct(config: MD026Config) -> Self {
43        Self { config }
44    }
45
46    #[inline]
47    fn get_punctuation_regex(&self) -> Result<Regex, regex::Error> {
48        // Check cache first
49        {
50            let cache = PUNCTUATION_REGEX_CACHE.read().unwrap();
51            if let Some(cached_regex) = cache.get(&self.config.punctuation) {
52                return Ok(cached_regex.clone());
53            }
54        }
55
56        // Compile and cache the regex
57        let pattern = format!(r"([{}]+)$", regex::escape(&self.config.punctuation));
58        let regex = Regex::new(&pattern)?;
59
60        {
61            let mut cache = PUNCTUATION_REGEX_CACHE.write().unwrap();
62            cache.insert(self.config.punctuation.clone(), regex.clone());
63        }
64
65        Ok(regex)
66    }
67
68    #[inline]
69    fn has_trailing_punctuation(&self, text: &str, re: &Regex) -> bool {
70        let trimmed = text.trim();
71        re.is_match(trimmed)
72    }
73
74    #[inline]
75    fn get_line_byte_range(&self, content: &str, line_num: usize, line_index: &LineIndex) -> Range<usize> {
76        let start_pos = line_index.get_line_start_byte(line_num).unwrap_or(content.len());
77
78        // Find the line length
79        let line = content.lines().nth(line_num - 1).unwrap_or("");
80
81        Range {
82            start: start_pos,
83            end: start_pos + line.len(),
84        }
85    }
86
87    // Remove trailing punctuation from text
88    #[inline]
89    fn remove_trailing_punctuation(&self, text: &str, re: &Regex) -> String {
90        re.replace_all(text.trim(), "").to_string()
91    }
92
93    // Optimized ATX heading fix using unified regex
94    #[inline]
95    fn fix_atx_heading(&self, line: &str, re: &Regex) -> String {
96        if let Some(captures) = ATX_HEADING_UNIFIED.captures(line) {
97            let indentation = captures.get(1).unwrap().as_str();
98            let hashes = captures.get(2).unwrap().as_str();
99            let space = captures.get(3).unwrap().as_str();
100            let content = captures.get(4).unwrap().as_str();
101
102            // Check if content ends with a custom header ID like {#my-id}
103            // If so, we need to fix punctuation before the ID
104            let fixed_content = if let Some(id_pos) = content.rfind(" {#") {
105                // Has a custom ID - fix punctuation before it
106                let before_id = &content[..id_pos];
107                let id_part = &content[id_pos..];
108                let fixed_before = self.remove_trailing_punctuation(before_id, re);
109                format!("{fixed_before}{id_part}")
110            } else {
111                // No custom ID - just remove trailing punctuation
112                self.remove_trailing_punctuation(content, re)
113            };
114
115            // Preserve any trailing hashes if present
116            if let Some(trailing) = captures.get(5) {
117                return format!(
118                    "{}{}{}{}{}",
119                    indentation,
120                    hashes,
121                    space,
122                    fixed_content,
123                    trailing.as_str()
124                );
125            }
126
127            return format!("{indentation}{hashes}{space}{fixed_content}");
128        }
129
130        // Fallback if no regex matches
131        line.to_string()
132    }
133
134    // Fix a setext heading by removing trailing punctuation from the content line
135    #[inline]
136    fn fix_setext_heading(&self, content_line: &str, re: &Regex) -> String {
137        let trimmed = content_line.trim_end();
138        let mut whitespace = "";
139
140        // Preserve trailing whitespace
141        if content_line.len() > trimmed.len() {
142            whitespace = &content_line[trimmed.len()..];
143        }
144
145        // Remove punctuation and preserve whitespace
146        format!("{}{}", self.remove_trailing_punctuation(trimmed, re), whitespace)
147    }
148}
149
150impl Rule for MD026NoTrailingPunctuation {
151    fn name(&self) -> &'static str {
152        "MD026"
153    }
154
155    fn description(&self) -> &'static str {
156        "Trailing punctuation in heading"
157    }
158
159    fn category(&self) -> RuleCategory {
160        RuleCategory::Heading
161    }
162
163    fn should_skip(&self, ctx: &crate::lint_context::LintContext) -> bool {
164        // Skip if no heading markers
165        if !ctx.likely_has_headings() {
166            return true;
167        }
168        // Skip if none of the configured punctuation exists
169        let punctuation = &self.config.punctuation;
170        !punctuation.chars().any(|p| ctx.content.contains(p))
171    }
172
173    fn check(&self, ctx: &crate::lint_context::LintContext) -> LintResult {
174        let content = ctx.content;
175
176        // Early returns for performance
177        if content.is_empty() {
178            return Ok(Vec::new());
179        }
180
181        // Quick check for any punctuation we care about
182        // For custom punctuation, we need to check differently
183        if self.config.punctuation == DEFAULT_PUNCTUATION {
184            if !QUICK_PUNCTUATION_CHECK.is_match(content) {
185                return Ok(Vec::new());
186            }
187        } else {
188            // For custom punctuation, check if any of those characters exist
189            let has_custom_punctuation = self.config.punctuation.chars().any(|c| content.contains(c));
190            if !has_custom_punctuation {
191                return Ok(Vec::new());
192            }
193        }
194
195        // Check if we have any headings from pre-computed line info
196        let has_headings = ctx.lines.iter().any(|line| line.heading.is_some());
197        if !has_headings {
198            return Ok(Vec::new());
199        }
200
201        let mut warnings = Vec::new();
202        let re = match self.get_punctuation_regex() {
203            Ok(regex) => regex,
204            Err(_) => return Ok(warnings),
205        };
206
207        // Create LineIndex for correct byte position calculations across all line ending types
208        let line_index = &ctx.line_index;
209
210        // Use pre-computed heading information from LintContext
211        for (line_num, line_info) in ctx.lines.iter().enumerate() {
212            if let Some(heading) = &line_info.heading {
213                // Skip invalid headings (e.g., `#NoSpace` which lacks required space after #)
214                if !heading.is_valid {
215                    continue;
216                }
217
218                // Skip deeply indented headings (they're code blocks)
219                if line_info.visual_indent >= 4 && matches!(heading.style, crate::lint_context::HeadingStyle::ATX) {
220                    continue;
221                }
222
223                // LintContext already strips Kramdown IDs from heading.text
224                // So we just check the heading text directly for trailing punctuation
225                // This correctly flags "# Heading." even if it has {#id}
226                let text_to_check = heading.text.clone();
227
228                if self.has_trailing_punctuation(&text_to_check, &re) {
229                    // Find the trailing punctuation
230                    if let Some(punctuation_match) = re.find(&text_to_check) {
231                        let line = line_info.content(ctx.content);
232
233                        // For ATX headings, find the punctuation position in the line
234                        let punctuation_pos_in_text = punctuation_match.start();
235                        let text_pos_in_line = line.find(&heading.text).unwrap_or(heading.content_column);
236                        let punctuation_start_in_line = text_pos_in_line + punctuation_pos_in_text;
237                        let punctuation_len = punctuation_match.len();
238
239                        let (start_line, start_col, end_line, end_col) = calculate_match_range(
240                            line_num + 1, // Convert to 1-indexed
241                            line,
242                            punctuation_start_in_line,
243                            punctuation_len,
244                        );
245
246                        let last_char = text_to_check.chars().last().unwrap_or(' ');
247                        warnings.push(LintWarning {
248                            rule_name: Some(self.name().to_string()),
249                            line: start_line,
250                            column: start_col,
251                            end_line,
252                            end_column: end_col,
253                            message: format!("Heading '{text_to_check}' ends with punctuation '{last_char}'"),
254                            severity: Severity::Warning,
255                            fix: Some(Fix {
256                                range: self.get_line_byte_range(content, line_num + 1, line_index),
257                                replacement: if matches!(heading.style, crate::lint_context::HeadingStyle::ATX) {
258                                    self.fix_atx_heading(line, &re)
259                                } else {
260                                    self.fix_setext_heading(line, &re)
261                                },
262                            }),
263                        });
264                    }
265                }
266            }
267        }
268
269        Ok(warnings)
270    }
271
272    fn fix(&self, ctx: &crate::lint_context::LintContext) -> Result<String, LintError> {
273        let content = ctx.content;
274
275        // Fast path optimizations
276        if content.is_empty() {
277            return Ok(content.to_string());
278        }
279
280        // Quick check for punctuation
281        // For custom punctuation, we need to check differently
282        if self.config.punctuation == DEFAULT_PUNCTUATION {
283            if !QUICK_PUNCTUATION_CHECK.is_match(content) {
284                return Ok(content.to_string());
285            }
286        } else {
287            // For custom punctuation, check if any of those characters exist
288            let has_custom_punctuation = self.config.punctuation.chars().any(|c| content.contains(c));
289            if !has_custom_punctuation {
290                return Ok(content.to_string());
291            }
292        }
293
294        // Check if we have any headings from pre-computed line info
295        let has_headings = ctx.lines.iter().any(|line| line.heading.is_some());
296        if !has_headings {
297            return Ok(content.to_string());
298        }
299
300        let re = match self.get_punctuation_regex() {
301            Ok(regex) => regex,
302            Err(_) => return Ok(content.to_string()),
303        };
304
305        let lines = ctx.raw_lines();
306        let mut fixed_lines: Vec<String> = lines.iter().map(|&s| s.to_string()).collect();
307
308        // Use pre-computed heading information from LintContext
309        for (line_num, line_info) in ctx.lines.iter().enumerate() {
310            // Skip lines where this rule is disabled by inline config
311            if ctx.inline_config().is_rule_disabled(self.name(), line_num + 1) {
312                continue;
313            }
314
315            if let Some(heading) = &line_info.heading {
316                // Skip invalid headings (e.g., `#NoSpace` which lacks required space after #)
317                if !heading.is_valid {
318                    continue;
319                }
320
321                // Skip deeply indented headings (they're code blocks)
322                if line_info.visual_indent >= 4 && matches!(heading.style, crate::lint_context::HeadingStyle::ATX) {
323                    continue;
324                }
325
326                // LintContext already strips custom header IDs from heading.text
327                // So we just check the heading text directly for trailing punctuation
328                let text_to_check = heading.text.clone();
329
330                // Check and fix trailing punctuation
331                if self.has_trailing_punctuation(&text_to_check, &re) {
332                    fixed_lines[line_num] = if matches!(heading.style, crate::lint_context::HeadingStyle::ATX) {
333                        self.fix_atx_heading(line_info.content(ctx.content), &re)
334                    } else {
335                        self.fix_setext_heading(line_info.content(ctx.content), &re)
336                    };
337                }
338            }
339        }
340
341        // Reconstruct content preserving line endings
342        let mut result = String::with_capacity(content.len());
343        for (i, line) in fixed_lines.iter().enumerate() {
344            result.push_str(line);
345            if i < fixed_lines.len() - 1 || content.ends_with('\n') {
346                result.push('\n');
347            }
348        }
349
350        Ok(result)
351    }
352
353    fn as_any(&self) -> &dyn std::any::Any {
354        self
355    }
356
357    fn default_config_section(&self) -> Option<(String, toml::Value)> {
358        let json_value = serde_json::to_value(&self.config).ok()?;
359        Some((
360            self.name().to_string(),
361            crate::rule_config_serde::json_to_toml_value(&json_value)?,
362        ))
363    }
364
365    fn from_config(config: &crate::config::Config) -> Box<dyn Rule>
366    where
367        Self: Sized,
368    {
369        let rule_config = crate::rule_config_serde::load_rule_config::<MD026Config>(config);
370        Box::new(Self::from_config_struct(rule_config))
371    }
372}
373
374#[cfg(test)]
375mod tests {
376    use super::*;
377    use crate::lint_context::LintContext;
378
379    #[test]
380    fn test_no_trailing_punctuation() {
381        let rule = MD026NoTrailingPunctuation::new(None);
382        let content = "# This is a heading\n\n## Another heading";
383        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
384        let result = rule.check(&ctx).unwrap();
385        assert!(result.is_empty(), "Headings without punctuation should not be flagged");
386    }
387
388    #[test]
389    fn test_trailing_period() {
390        let rule = MD026NoTrailingPunctuation::new(None);
391        let content = "# This is a heading.\n\n## Another one.";
392        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
393        let result = rule.check(&ctx).unwrap();
394        assert_eq!(result.len(), 2);
395        assert_eq!(result[0].line, 1);
396        assert_eq!(result[0].column, 20);
397        assert!(result[0].message.contains("ends with punctuation '.'"));
398        assert_eq!(result[1].line, 3);
399        assert_eq!(result[1].column, 15);
400    }
401
402    #[test]
403    fn test_trailing_comma() {
404        let rule = MD026NoTrailingPunctuation::new(None);
405        let content = "# Heading,\n## Sub-heading,";
406        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
407        let result = rule.check(&ctx).unwrap();
408        assert_eq!(result.len(), 2);
409        assert!(result[0].message.contains("ends with punctuation ','"));
410    }
411
412    #[test]
413    fn test_trailing_semicolon() {
414        let rule = MD026NoTrailingPunctuation::new(None);
415        let content = "# Title;\n## Subtitle;";
416        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
417        let result = rule.check(&ctx).unwrap();
418        assert_eq!(result.len(), 2);
419        assert!(result[0].message.contains("ends with punctuation ';'"));
420    }
421
422    #[test]
423    fn test_custom_punctuation() {
424        let rule = MD026NoTrailingPunctuation::new(Some("!".to_string()));
425        let content = "# Important!\n## Regular heading.";
426        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
427        let result = rule.check(&ctx).unwrap();
428        assert_eq!(result.len(), 1, "Only exclamation should be flagged with custom config");
429        assert_eq!(result[0].line, 1);
430        assert!(result[0].message.contains("ends with punctuation '!'"));
431    }
432
433    #[test]
434    fn test_legitimate_question_mark() {
435        let rule = MD026NoTrailingPunctuation::new(Some(".,;?".to_string()));
436        let content = "# What is this?\n# This is bad.";
437        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
438        let result = rule.check(&ctx).unwrap();
439        // With custom punctuation, legitimate punctuation exceptions don't apply
440        assert_eq!(result.len(), 2, "Both should be flagged with custom punctuation");
441    }
442
443    #[test]
444    fn test_question_marks_not_in_default() {
445        let rule = MD026NoTrailingPunctuation::new(None);
446        let content = "# What is Rust?\n# How does it work?\n# Is it fast?";
447        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
448        let result = rule.check(&ctx).unwrap();
449        assert!(result.is_empty(), "Question marks are not in default punctuation list");
450    }
451
452    #[test]
453    fn test_colons_in_default() {
454        let rule = MD026NoTrailingPunctuation::new(None);
455        let content = "# FAQ:\n# API Reference:\n# Step 1:\n# Version 2.0:";
456        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
457        let result = rule.check(&ctx).unwrap();
458        assert_eq!(
459            result.len(),
460            4,
461            "Colons are in default punctuation list and should be flagged"
462        );
463    }
464
465    #[test]
466    fn test_fix_atx_headings() {
467        let rule = MD026NoTrailingPunctuation::new(None);
468        let content = "# Title.\n## Subtitle,\n### Sub-subtitle;";
469        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
470        let fixed = rule.fix(&ctx).unwrap();
471        assert_eq!(fixed, "# Title\n## Subtitle\n### Sub-subtitle");
472    }
473
474    #[test]
475    fn test_fix_setext_headings() {
476        let rule = MD026NoTrailingPunctuation::new(None);
477        let content = "Title.\n======\n\nSubtitle,\n---------";
478        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
479        let fixed = rule.fix(&ctx).unwrap();
480        assert_eq!(fixed, "Title\n======\n\nSubtitle\n---------");
481    }
482
483    #[test]
484    fn test_fix_preserves_trailing_hashes() {
485        let rule = MD026NoTrailingPunctuation::new(None);
486        let content = "# Title. #\n## Subtitle, ##";
487        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
488        let fixed = rule.fix(&ctx).unwrap();
489        assert_eq!(fixed, "# Title #\n## Subtitle ##");
490    }
491
492    #[test]
493    fn test_indented_headings() {
494        let rule = MD026NoTrailingPunctuation::new(None);
495        let content = "   # Title.\n  ## Subtitle.";
496        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
497        let result = rule.check(&ctx).unwrap();
498        assert_eq!(result.len(), 2, "Indented headings (< 4 spaces) should be checked");
499    }
500
501    #[test]
502    fn test_deeply_indented_ignored() {
503        let rule = MD026NoTrailingPunctuation::new(None);
504        let content = "    # This is code.";
505        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
506        let result = rule.check(&ctx).unwrap();
507        assert!(result.is_empty(), "Deeply indented lines (4+ spaces) should be ignored");
508    }
509
510    #[test]
511    fn test_multiple_punctuation() {
512        let rule = MD026NoTrailingPunctuation::new(None);
513        let content = "# Title...";
514        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
515        let result = rule.check(&ctx).unwrap();
516        assert_eq!(result.len(), 1);
517        assert_eq!(result[0].column, 8); // Points to first period
518    }
519
520    #[test]
521    fn test_empty_content() {
522        let rule = MD026NoTrailingPunctuation::new(None);
523        let content = "";
524        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
525        let result = rule.check(&ctx).unwrap();
526        assert!(result.is_empty());
527    }
528
529    #[test]
530    fn test_no_headings() {
531        let rule = MD026NoTrailingPunctuation::new(None);
532        let content = "This is just text.\nMore text with punctuation.";
533        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
534        let result = rule.check(&ctx).unwrap();
535        assert!(result.is_empty(), "Non-heading lines should not be checked");
536    }
537
538    #[test]
539    fn test_get_punctuation_regex() {
540        let rule = MD026NoTrailingPunctuation::new(Some("!?".to_string()));
541        let regex = rule.get_punctuation_regex().unwrap();
542        assert!(regex.is_match("text!"));
543        assert!(regex.is_match("text?"));
544        assert!(!regex.is_match("text."));
545    }
546
547    #[test]
548    fn test_regex_caching() {
549        let rule1 = MD026NoTrailingPunctuation::new(Some("!".to_string()));
550        let rule2 = MD026NoTrailingPunctuation::new(Some("!".to_string()));
551
552        // Both should get the same cached regex
553        let _regex1 = rule1.get_punctuation_regex().unwrap();
554        let _regex2 = rule2.get_punctuation_regex().unwrap();
555
556        // Check cache has the entry
557        let cache = PUNCTUATION_REGEX_CACHE.read().unwrap();
558        assert!(cache.contains_key("!"));
559    }
560
561    #[test]
562    fn test_config_from_toml() {
563        let mut config = crate::config::Config::default();
564        let mut rule_config = crate::config::RuleConfig::default();
565        rule_config
566            .values
567            .insert("punctuation".to_string(), toml::Value::String("!?".to_string()));
568        config.rules.insert("MD026".to_string(), rule_config);
569
570        let rule = MD026NoTrailingPunctuation::from_config(&config);
571        let content = "# Title!\n# Another?";
572        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
573        let result = rule.check(&ctx).unwrap();
574        assert_eq!(result.len(), 2, "Custom punctuation from config should be used");
575    }
576
577    #[test]
578    fn test_fix_removes_punctuation() {
579        let rule = MD026NoTrailingPunctuation::new(None);
580        let content = "# Title.   \n## Subtitle,  ";
581        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
582        let fixed = rule.fix(&ctx).unwrap();
583        // The current implementation doesn't preserve trailing whitespace after punctuation removal
584        assert_eq!(fixed, "# Title\n## Subtitle");
585    }
586
587    #[test]
588    fn test_final_newline_preservation() {
589        let rule = MD026NoTrailingPunctuation::new(None);
590        let content = "# Title.\n";
591        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
592        let fixed = rule.fix(&ctx).unwrap();
593        assert_eq!(fixed, "# Title\n");
594
595        let content_no_newline = "# Title.";
596        let ctx2 = LintContext::new(content_no_newline, crate::config::MarkdownFlavor::Standard, None);
597        let fixed2 = rule.fix(&ctx2).unwrap();
598        assert_eq!(fixed2, "# Title");
599    }
600}
rumdl_lib/rules/md026_no_trailing_punctuation.rs

rumdl_lib/rules/
md026_no_trailing_punctuation.rs
