src/librustdoc/passes/html_tags.rs

   1 use super::{span_of_attrs, Pass};
   2 use crate::clean::*;
   3 use crate::core::DocContext;
   4 use crate::fold::DocFolder;
   5 use crate::html::markdown::opts;
   6 use core::ops::Range;
   7 use pulldown_cmark::{Event, Parser, Tag};
   8 use rustc_session::lint;
   9 use std::iter::Peekable;
  10 use std::str::CharIndices;
  11
  12 crate const CHECK_INVALID_HTML_TAGS: Pass = Pass {
  13     name: "check-invalid-html-tags",
  14     run: check_invalid_html_tags,
  15     description: "detects invalid HTML tags in doc comments",
  16 };
  17
  18 struct InvalidHtmlTagsLinter<'a, 'tcx> {
  19     cx: &'a DocContext<'tcx>,
  20 }
  21
  22 impl<'a, 'tcx> InvalidHtmlTagsLinter<'a, 'tcx> {
  23     fn new(cx: &'a DocContext<'tcx>) -> Self {
  24         InvalidHtmlTagsLinter { cx }
  25     }
  26 }
  27
  28 crate fn check_invalid_html_tags(krate: Crate, cx: &DocContext<'_>) -> Crate {
  29     if !cx.tcx.sess.is_nightly_build() {
  30         krate
  31     } else {
  32         let mut coll = InvalidHtmlTagsLinter::new(cx);
  33
  34         coll.fold_crate(krate)
  35     }
  36 }
  37
  38 const ALLOWED_UNCLOSED: &[&str] = &[
  39     "area", "base", "br", "col", "embed", "hr", "img", "input", "keygen", "link", "meta", "param",
  40     "source", "track", "wbr",
  41 ];
  42
  43 fn drop_tag(
  44     tags: &mut Vec<(String, Range<usize>)>,
  45     tag_name: String,
  46     range: Range<usize>,
  47     f: &impl Fn(&str, &Range<usize>),
  48 ) {
  49     let tag_name_low = tag_name.to_lowercase();
  50     if let Some(pos) = tags.iter().rposition(|(t, _)| t.to_lowercase() == tag_name_low) {
  51         // If the tag is nested inside a "<script>" or a "<style>" tag, no warning should
  52         // be emitted.
  53         let should_not_warn = tags.iter().take(pos + 1).any(|(at, _)| {
  54             let at = at.to_lowercase();
  55             at == "script" || at == "style"
  56         });
  57         for (last_tag_name, last_tag_span) in tags.drain(pos + 1..) {
  58             if should_not_warn {
  59                 continue;
  60             }
  61             let last_tag_name_low = last_tag_name.to_lowercase();
  62             if ALLOWED_UNCLOSED.iter().any(|&at| at == &last_tag_name_low) {
  63                 continue;
  64             }
  65             // `tags` is used as a queue, meaning that everything after `pos` is included inside it.
  66             // So `<h2><h3></h2>` will look like `["h2", "h3"]`. So when closing `h2`, we will still
  67             // have `h3`, meaning the tag wasn't closed as it should have.
  68             f(&format!("unclosed HTML tag `{}`", last_tag_name), &last_tag_span);
  69         }
  70         // Remove the `tag_name` that was originally closed
  71         tags.pop();
  72     } else {
  73         // It can happen for example in this case: `<h2></script></h2>` (the `h2` tag isn't required
  74         // but it helps for the visualization).
  75         f(&format!("unopened HTML tag `{}`", tag_name), &range);
  76     }
  77 }
  78
  79 fn extract_html_tag(
  80     tags: &mut Vec<(String, Range<usize>)>,
  81     text: &str,
  82     range: &Range<usize>,
  83     start_pos: usize,
  84     iter: &mut Peekable<CharIndices<'_>>,
  85     f: &impl Fn(&str, &Range<usize>),
  86 ) {
  87     let mut tag_name = String::new();
  88     let mut is_closing = false;
  89     let mut prev_pos = start_pos;
  90
  91     loop {
  92         let (pos, c) = match iter.peek() {
  93             Some((pos, c)) => (*pos, *c),
  94             // In case we reached the of the doc comment, we want to check that it's an
  95             // unclosed HTML tag. For example "/// <h3".
  96             None => (prev_pos, '\0'),
  97         };
  98         prev_pos = pos;
  99         // Checking if this is a closing tag (like `</a>` for `<a>`).
 100         if c == '/' && tag_name.is_empty() {
 101             is_closing = true;
 102         } else if c.is_ascii_alphanumeric() {
 103             tag_name.push(c);
 104         } else {
 105             if !tag_name.is_empty() {
 106                 let mut r = Range { start: range.start + start_pos, end: range.start + pos };
 107                 if c == '>' {
 108                     // In case we have a tag without attribute, we can consider the span to
 109                     // refer to it fully.
 110                     r.end += 1;
 111                 }
 112                 if is_closing {
 113                     // In case we have "</div >" or even "</div         >".
 114                     if c != '>' {
 115                         if !c.is_whitespace() {
 116                             // It seems like it's not a valid HTML tag.
 117                             break;
 118                         }
 119                         let mut found = false;
 120                         for (new_pos, c) in text[pos..].char_indices() {
 121                             if !c.is_whitespace() {
 122                                 if c == '>' {
 123                                     r.end = range.start + new_pos + 1;
 124                                     found = true;
 125                                 }
 126                                 break;
 127                             }
 128                         }
 129                         if !found {
 130                             break;
 131                         }
 132                     }
 133                     drop_tag(tags, tag_name, r, f);
 134                 } else {
 135                     tags.push((tag_name, r));
 136                 }
 137             }
 138             break;
 139         }
 140         iter.next();
 141     }
 142 }
 143
 144 fn extract_tags(
 145     tags: &mut Vec<(String, Range<usize>)>,
 146     text: &str,
 147     range: Range<usize>,
 148     is_in_comment: &mut Option<Range<usize>>,
 149     f: &impl Fn(&str, &Range<usize>),
 150 ) {
 151     let mut iter = text.char_indices().peekable();
 152
 153     while let Some((start_pos, c)) = iter.next() {
 154         if is_in_comment.is_some() {
 155             if text[start_pos..].starts_with("-->") {
 156                 *is_in_comment = None;
 157             }
 158         } else if c == '<' {
 159             if text[start_pos..].starts_with("<!--") {
 160                 // We skip the "!--" part. (Once `advance_by` is stable, might be nice to use it!)
 161                 iter.next();
 162                 iter.next();
 163                 iter.next();
 164                 *is_in_comment = Some(Range {
 165                     start: range.start + start_pos,
 166                     end: range.start + start_pos + 3,
 167                 });
 168             } else {
 169                 extract_html_tag(tags, text, &range, start_pos, &mut iter, f);
 170             }
 171         }
 172     }
 173 }
 174
 175 impl<'a, 'tcx> DocFolder for InvalidHtmlTagsLinter<'a, 'tcx> {
 176     fn fold_item(&mut self, item: Item) -> Option<Item> {
 177         let hir_id = match self.cx.as_local_hir_id(item.def_id) {
 178             Some(hir_id) => hir_id,
 179             None => {
 180                 // If non-local, no need to check anything.
 181                 return Some(self.fold_item_recur(item));
 182             }
 183         };
 184         let dox = item.attrs.collapsed_doc_value().unwrap_or_default();
 185         if !dox.is_empty() {
 186             let cx = &self.cx;
 187             let report_diag = |msg: &str, range: &Range<usize>| {
 188                 let sp = match super::source_span_for_markdown_range(cx, &dox, range, &item.attrs) {
 189                     Some(sp) => sp,
 190                     None => span_of_attrs(&item.attrs).unwrap_or(item.source.span()),
 191                 };
 192                 cx.tcx.struct_span_lint_hir(lint::builtin::INVALID_HTML_TAGS, hir_id, sp, |lint| {
 193                     lint.build(msg).emit()
 194                 });
 195             };
 196
 197             let mut tags = Vec::new();
 198             let mut is_in_comment = None;
 199             let mut in_code_block = false;
 200
 201             let p = Parser::new_ext(&dox, opts()).into_offset_iter();
 202
 203             for (event, range) in p {
 204                 match event {
 205                     Event::Start(Tag::CodeBlock(_)) => in_code_block = true,
 206                     Event::Html(text) | Event::Text(text) if !in_code_block => {
 207                         extract_tags(&mut tags, &text, range, &mut is_in_comment, &report_diag)
 208                     }
 209                     Event::End(Tag::CodeBlock(_)) => in_code_block = false,
 210                     _ => {}
 211                 }
 212             }
 213
 214             for (tag, range) in tags.iter().filter(|(t, _)| {
 215                 let t = t.to_lowercase();
 216                 ALLOWED_UNCLOSED.iter().find(|&&at| at == t).is_none()
 217             }) {
 218                 report_diag(&format!("unclosed HTML tag `{}`", tag), range);
 219             }
 220
 221             if let Some(range) = is_in_comment {
 222                 report_diag("Unclosed HTML comment", &range);
 223             }
 224         }
 225
 226         Some(self.fold_item_recur(item))
 227     }
 228 }