src/librustdoc/passes/html_tags.rs

   1 //! Detects invalid HTML (like an unclosed `<span>`) in doc comments.
   2 use super::Pass;
   3 use crate::clean::*;
   4 use crate::core::DocContext;
   5 use crate::html::markdown::main_body_opts;
   6 use crate::visit::DocVisitor;
   7
   8 use pulldown_cmark::{BrokenLink, Event, LinkType, Parser, Tag};
   9
  10 use std::iter::Peekable;
  11 use std::ops::Range;
  12 use std::str::CharIndices;
  13
  14 pub(crate) const CHECK_INVALID_HTML_TAGS: Pass = Pass {
  15     name: "check-invalid-html-tags",
  16     run: check_invalid_html_tags,
  17     description: "detects invalid HTML tags in doc comments",
  18 };
  19
  20 struct InvalidHtmlTagsLinter<'a, 'tcx> {
  21     cx: &'a mut DocContext<'tcx>,
  22 }
  23
  24 pub(crate) fn check_invalid_html_tags(krate: Crate, cx: &mut DocContext<'_>) -> Crate {
  25     let mut coll = InvalidHtmlTagsLinter { cx };
  26     coll.visit_crate(&krate);
  27     krate
  28 }
  29
  30 const ALLOWED_UNCLOSED: &[&str] = &[
  31     "area", "base", "br", "col", "embed", "hr", "img", "input", "keygen", "link", "meta", "param",
  32     "source", "track", "wbr",
  33 ];
  34
  35 fn drop_tag(
  36     tags: &mut Vec<(String, Range<usize>)>,
  37     tag_name: String,
  38     range: Range<usize>,
  39     f: &impl Fn(&str, &Range<usize>, bool),
  40 ) {
  41     let tag_name_low = tag_name.to_lowercase();
  42     if let Some(pos) = tags.iter().rposition(|(t, _)| t.to_lowercase() == tag_name_low) {
  43         // If the tag is nested inside a "<script>" or a "<style>" tag, no warning should
  44         // be emitted.
  45         let should_not_warn = tags.iter().take(pos + 1).any(|(at, _)| {
  46             let at = at.to_lowercase();
  47             at == "script" || at == "style"
  48         });
  49         for (last_tag_name, last_tag_span) in tags.drain(pos + 1..) {
  50             if should_not_warn {
  51                 continue;
  52             }
  53             let last_tag_name_low = last_tag_name.to_lowercase();
  54             if ALLOWED_UNCLOSED.contains(&last_tag_name_low.as_str()) {
  55                 continue;
  56             }
  57             // `tags` is used as a queue, meaning that everything after `pos` is included inside it.
  58             // So `<h2><h3></h2>` will look like `["h2", "h3"]`. So when closing `h2`, we will still
  59             // have `h3`, meaning the tag wasn't closed as it should have.
  60             f(&format!("unclosed HTML tag `{}`", last_tag_name), &last_tag_span, true);
  61         }
  62         // Remove the `tag_name` that was originally closed
  63         tags.pop();
  64     } else {
  65         // It can happen for example in this case: `<h2></script></h2>` (the `h2` tag isn't required
  66         // but it helps for the visualization).
  67         f(&format!("unopened HTML tag `{}`", tag_name), &range, false);
  68     }
  69 }
  70
  71 fn extract_path_backwards(text: &str, end_pos: usize) -> Option<usize> {
  72     use rustc_lexer::{is_id_continue, is_id_start};
  73     let mut current_pos = end_pos;
  74     loop {
  75         if current_pos >= 2 && text[..current_pos].ends_with("::") {
  76             current_pos -= 2;
  77         }
  78         let new_pos = text[..current_pos]
  79             .char_indices()
  80             .rev()
  81             .take_while(|(_, c)| is_id_start(*c) || is_id_continue(*c))
  82             .reduce(|_accum, item| item)
  83             .and_then(|(new_pos, c)| is_id_start(c).then_some(new_pos));
  84         if let Some(new_pos) = new_pos {
  85             if current_pos != new_pos {
  86                 current_pos = new_pos;
  87                 continue;
  88             }
  89         }
  90         break;
  91     }
  92     if current_pos == end_pos { None } else { Some(current_pos) }
  93 }
  94
  95 fn extract_path_forward(text: &str, start_pos: usize) -> Option<usize> {
  96     use rustc_lexer::{is_id_continue, is_id_start};
  97     let mut current_pos = start_pos;
  98     loop {
  99         if current_pos < text.len() && text[current_pos..].starts_with("::") {
 100             current_pos += 2;
 101         } else {
 102             break;
 103         }
 104         let mut chars = text[current_pos..].chars();
 105         if let Some(c) = chars.next() {
 106             if is_id_start(c) {
 107                 current_pos += c.len_utf8();
 108             } else {
 109                 break;
 110             }
 111         }
 112         while let Some(c) = chars.next() {
 113             if is_id_continue(c) {
 114                 current_pos += c.len_utf8();
 115             } else {
 116                 break;
 117             }
 118         }
 119     }
 120     if current_pos == start_pos { None } else { Some(current_pos) }
 121 }
 122
 123 fn is_valid_for_html_tag_name(c: char, is_empty: bool) -> bool {
 124     // https://spec.commonmark.org/0.30/#raw-html
 125     //
 126     // > A tag name consists of an ASCII letter followed by zero or more ASCII letters, digits, or
 127     // > hyphens (-).
 128     c.is_ascii_alphabetic() || !is_empty && (c == '-' || c.is_ascii_digit())
 129 }
 130
 131 fn extract_html_tag(
 132     tags: &mut Vec<(String, Range<usize>)>,
 133     text: &str,
 134     range: &Range<usize>,
 135     start_pos: usize,
 136     iter: &mut Peekable<CharIndices<'_>>,
 137     f: &impl Fn(&str, &Range<usize>, bool),
 138 ) {
 139     let mut tag_name = String::new();
 140     let mut is_closing = false;
 141     let mut prev_pos = start_pos;
 142
 143     loop {
 144         let (pos, c) = match iter.peek() {
 145             Some((pos, c)) => (*pos, *c),
 146             // In case we reached the of the doc comment, we want to check that it's an
 147             // unclosed HTML tag. For example "/// <h3".
 148             None => (prev_pos, '\0'),
 149         };
 150         prev_pos = pos;
 151         // Checking if this is a closing tag (like `</a>` for `<a>`).
 152         if c == '/' && tag_name.is_empty() {
 153             is_closing = true;
 154         } else if is_valid_for_html_tag_name(c, tag_name.is_empty()) {
 155             tag_name.push(c);
 156         } else {
 157             if !tag_name.is_empty() {
 158                 let mut r = Range { start: range.start + start_pos, end: range.start + pos };
 159                 if c == '>' {
 160                     // In case we have a tag without attribute, we can consider the span to
 161                     // refer to it fully.
 162                     r.end += 1;
 163                 }
 164                 if is_closing {
 165                     // In case we have "</div >" or even "</div         >".
 166                     if c != '>' {
 167                         if !c.is_whitespace() {
 168                             // It seems like it's not a valid HTML tag.
 169                             break;
 170                         }
 171                         let mut found = false;
 172                         for (new_pos, c) in text[pos..].char_indices() {
 173                             if !c.is_whitespace() {
 174                                 if c == '>' {
 175                                     r.end = range.start + new_pos + 1;
 176                                     found = true;
 177                                 }
 178                                 break;
 179                             }
 180                         }
 181                         if !found {
 182                             break;
 183                         }
 184                     }
 185                     drop_tag(tags, tag_name, r, f);
 186                 } else {
 187                     tags.push((tag_name, r));
 188                 }
 189             }
 190             break;
 191         }
 192         iter.next();
 193     }
 194 }
 195
 196 fn extract_tags(
 197     tags: &mut Vec<(String, Range<usize>)>,
 198     text: &str,
 199     range: Range<usize>,
 200     is_in_comment: &mut Option<Range<usize>>,
 201     f: &impl Fn(&str, &Range<usize>, bool),
 202 ) {
 203     let mut iter = text.char_indices().peekable();
 204
 205     while let Some((start_pos, c)) = iter.next() {
 206         if is_in_comment.is_some() {
 207             if text[start_pos..].starts_with("-->") {
 208                 *is_in_comment = None;
 209             }
 210         } else if c == '<' {
 211             if text[start_pos..].starts_with("<!--") {
 212                 // We skip the "!--" part. (Once `advance_by` is stable, might be nice to use it!)
 213                 iter.next();
 214                 iter.next();
 215                 iter.next();
 216                 *is_in_comment = Some(Range {
 217                     start: range.start + start_pos,
 218                     end: range.start + start_pos + 3,
 219                 });
 220             } else {
 221                 extract_html_tag(tags, text, &range, start_pos, &mut iter, f);
 222             }
 223         }
 224     }
 225 }
 226
 227 impl<'a, 'tcx> DocVisitor for InvalidHtmlTagsLinter<'a, 'tcx> {
 228     fn visit_item(&mut self, item: &Item) {
 229         let tcx = self.cx.tcx;
 230         let Some(hir_id) = DocContext::as_local_hir_id(tcx, item.item_id)
 231         // If non-local, no need to check anything.
 232         else { return };
 233         let dox = item.attrs.collapsed_doc_value().unwrap_or_default();
 234         if !dox.is_empty() {
 235             let report_diag = |msg: &str, range: &Range<usize>, is_open_tag: bool| {
 236                 let sp = match super::source_span_for_markdown_range(tcx, &dox, range, &item.attrs)
 237                 {
 238                     Some(sp) => sp,
 239                     None => item.attr_span(tcx),
 240                 };
 241                 tcx.struct_span_lint_hir(crate::lint::INVALID_HTML_TAGS, hir_id, sp, msg, |lint| {
 242                     use rustc_lint_defs::Applicability;
 243                     // If a tag looks like `<this>`, it might actually be a generic.
 244                     // We don't try to detect stuff `<like, this>` because that's not valid HTML,
 245                     // and we don't try to detect stuff `<like this>` because that's not valid Rust.
 246                     let mut generics_end = range.end;
 247                     if let Some(Some(mut generics_start)) = (is_open_tag
 248                         && dox[..generics_end].ends_with('>'))
 249                     .then(|| extract_path_backwards(&dox, range.start))
 250                     {
 251                         while generics_start != 0
 252                             && generics_end < dox.len()
 253                             && dox.as_bytes()[generics_start - 1] == b'<'
 254                             && dox.as_bytes()[generics_end] == b'>'
 255                         {
 256                             generics_end += 1;
 257                             generics_start -= 1;
 258                             if let Some(new_start) = extract_path_backwards(&dox, generics_start) {
 259                                 generics_start = new_start;
 260                             }
 261                             if let Some(new_end) = extract_path_forward(&dox, generics_end) {
 262                                 generics_end = new_end;
 263                             }
 264                         }
 265                         if let Some(new_end) = extract_path_forward(&dox, generics_end) {
 266                             generics_end = new_end;
 267                         }
 268                         let generics_sp = match super::source_span_for_markdown_range(
 269                             tcx,
 270                             &dox,
 271                             &(generics_start..generics_end),
 272                             &item.attrs,
 273                         ) {
 274                             Some(sp) => sp,
 275                             None => item.attr_span(tcx),
 276                         };
 277                         // Sometimes, we only extract part of a path. For example, consider this:
 278                         //
 279                         //     <[u32] as IntoIter<u32>>::Item
 280                         //                       ^^^^^ unclosed HTML tag `u32`
 281                         //
 282                         // We don't have any code for parsing fully-qualified trait paths.
 283                         // In theory, we could add it, but doing it correctly would require
 284                         // parsing the entire path grammar, which is problematic because of
 285                         // overlap between the path grammar and Markdown.
 286                         //
 287                         // The example above shows that ambiguity. Is `[u32]` intended to be an
 288                         // intra-doc link to the u32 primitive, or is it intended to be a slice?
 289                         //
 290                         // If the below conditional were removed, we would suggest this, which is
 291                         // not what the user probably wants.
 292                         //
 293                         //     <[u32] as `IntoIter<u32>`>::Item
 294                         //
 295                         // We know that the user actually wants to wrap the whole thing in a code
 296                         // block, but the only reason we know that is because `u32` does not, in
 297                         // fact, implement IntoIter. If the example looks like this:
 298                         //
 299                         //     <[Vec<i32>] as IntoIter<i32>::Item
 300                         //
 301                         // The ideal fix would be significantly different.
 302                         if (generics_start > 0 && dox.as_bytes()[generics_start - 1] == b'<')
 303                             || (generics_end < dox.len() && dox.as_bytes()[generics_end] == b'>')
 304                         {
 305                             return lint;
 306                         }
 307                         // multipart form is chosen here because ``Vec<i32>`` would be confusing.
 308                         lint.multipart_suggestion(
 309                             "try marking as source code",
 310                             vec![
 311                                 (generics_sp.shrink_to_lo(), String::from("`")),
 312                                 (generics_sp.shrink_to_hi(), String::from("`")),
 313                             ],
 314                             Applicability::MaybeIncorrect,
 315                         );
 316                     }
 317
 318                     lint
 319                 });
 320             };
 321
 322             let mut tags = Vec::new();
 323             let mut is_in_comment = None;
 324             let mut in_code_block = false;
 325
 326             let link_names = item.link_names(&self.cx.cache);
 327
 328             let mut replacer = |broken_link: BrokenLink<'_>| {
 329                 if let Some(link) =
 330                     link_names.iter().find(|link| *link.original_text == *broken_link.reference)
 331                 {
 332                     Some((link.href.as_str().into(), link.new_text.as_str().into()))
 333                 } else if matches!(
 334                     &broken_link.link_type,
 335                     LinkType::Reference | LinkType::ReferenceUnknown
 336                 ) {
 337                     // If the link is shaped [like][this], suppress any broken HTML in the [this] part.
 338                     // The `broken_intra_doc_links` will report typos in there anyway.
 339                     Some((
 340                         broken_link.reference.to_string().into(),
 341                         broken_link.reference.to_string().into(),
 342                     ))
 343                 } else {
 344                     None
 345                 }
 346             };
 347
 348             let p =
 349                 Parser::new_with_broken_link_callback(&dox, main_body_opts(), Some(&mut replacer))
 350                     .into_offset_iter();
 351
 352             for (event, range) in p {
 353                 match event {
 354                     Event::Start(Tag::CodeBlock(_)) => in_code_block = true,
 355                     Event::Html(text) if !in_code_block => {
 356                         extract_tags(&mut tags, &text, range, &mut is_in_comment, &report_diag)
 357                     }
 358                     Event::End(Tag::CodeBlock(_)) => in_code_block = false,
 359                     _ => {}
 360                 }
 361             }
 362
 363             for (tag, range) in tags.iter().filter(|(t, _)| {
 364                 let t = t.to_lowercase();
 365                 !ALLOWED_UNCLOSED.contains(&t.as_str())
 366             }) {
 367                 report_diag(&format!("unclosed HTML tag `{}`", tag), range, true);
 368             }
 369
 370             if let Some(range) = is_in_comment {
 371                 report_diag("Unclosed HTML comment", &range, false);
 372             }
 373         }
 374
 375         self.visit_item_recur(item)
 376     }
 377 }