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                     let mut is_self_closing = false;
 188                     let mut quote_pos = None;
 189                     if c != '>' {
 190                         let mut quote = None;
 191                         let mut after_eq = false;
 192                         for (i, c) in text[pos..].char_indices() {
 193                             if !c.is_whitespace() {
 194                                 if let Some(q) = quote {
 195                                     if c == q {
 196                                         quote = None;
 197                                         quote_pos = None;
 198                                         after_eq = false;
 199                                     }
 200                                 } else if c == '>' {
 201                                     break;
 202                                 } else if c == '/' && !after_eq {
 203                                     is_self_closing = true;
 204                                 } else {
 205                                     if is_self_closing {
 206                                         is_self_closing = false;
 207                                     }
 208                                     if (c == '"' || c == '\'') && after_eq {
 209                                         quote = Some(c);
 210                                         quote_pos = Some(pos + i);
 211                                     } else if c == '=' {
 212                                         after_eq = true;
 213                                     }
 214                                 }
 215                             } else if quote.is_none() {
 216                                 after_eq = false;
 217                             }
 218                         }
 219                     }
 220                     if let Some(quote_pos) = quote_pos {
 221                         let qr = Range { start: quote_pos, end: quote_pos };
 222                         f(
 223                             &format!("unclosed quoted HTML attribute on tag `{}`", tag_name),
 224                             &qr,
 225                             false,
 226                         );
 227                     }
 228                     if is_self_closing {
 229                         // https://html.spec.whatwg.org/#parse-error-non-void-html-element-start-tag-with-trailing-solidus
 230                         let valid = ALLOWED_UNCLOSED.contains(&&tag_name[..])
 231                             || tags.iter().take(pos + 1).any(|(at, _)| {
 232                                 let at = at.to_lowercase();
 233                                 at == "svg" || at == "math"
 234                             });
 235                         if !valid {
 236                             f(&format!("invalid self-closing HTML tag `{}`", tag_name), &r, false);
 237                         }
 238                     } else {
 239                         tags.push((tag_name, r));
 240                     }
 241                 }
 242             }
 243             break;
 244         }
 245         iter.next();
 246     }
 247 }
 248
 249 fn extract_tags(
 250     tags: &mut Vec<(String, Range<usize>)>,
 251     text: &str,
 252     range: Range<usize>,
 253     is_in_comment: &mut Option<Range<usize>>,
 254     f: &impl Fn(&str, &Range<usize>, bool),
 255 ) {
 256     let mut iter = text.char_indices().peekable();
 257
 258     while let Some((start_pos, c)) = iter.next() {
 259         if is_in_comment.is_some() {
 260             if text[start_pos..].starts_with("-->") {
 261                 *is_in_comment = None;
 262             }
 263         } else if c == '<' {
 264             if text[start_pos..].starts_with("<!--") {
 265                 // We skip the "!--" part. (Once `advance_by` is stable, might be nice to use it!)
 266                 iter.next();
 267                 iter.next();
 268                 iter.next();
 269                 *is_in_comment = Some(Range {
 270                     start: range.start + start_pos,
 271                     end: range.start + start_pos + 3,
 272                 });
 273             } else {
 274                 extract_html_tag(tags, text, &range, start_pos, &mut iter, f);
 275             }
 276         }
 277     }
 278 }
 279
 280 impl<'a, 'tcx> DocVisitor for InvalidHtmlTagsLinter<'a, 'tcx> {
 281     fn visit_item(&mut self, item: &Item) {
 282         let tcx = self.cx.tcx;
 283         let Some(hir_id) = DocContext::as_local_hir_id(tcx, item.item_id)
 284         // If non-local, no need to check anything.
 285         else { return };
 286         let dox = item.attrs.collapsed_doc_value().unwrap_or_default();
 287         if !dox.is_empty() {
 288             let report_diag = |msg: &str, range: &Range<usize>, is_open_tag: bool| {
 289                 let sp = match super::source_span_for_markdown_range(tcx, &dox, range, &item.attrs)
 290                 {
 291                     Some(sp) => sp,
 292                     None => item.attr_span(tcx),
 293                 };
 294                 tcx.struct_span_lint_hir(crate::lint::INVALID_HTML_TAGS, hir_id, sp, msg, |lint| {
 295                     use rustc_lint_defs::Applicability;
 296                     // If a tag looks like `<this>`, it might actually be a generic.
 297                     // We don't try to detect stuff `<like, this>` because that's not valid HTML,
 298                     // and we don't try to detect stuff `<like this>` because that's not valid Rust.
 299                     let mut generics_end = range.end;
 300                     if let Some(Some(mut generics_start)) = (is_open_tag
 301                         && dox[..generics_end].ends_with('>'))
 302                     .then(|| extract_path_backwards(&dox, range.start))
 303                     {
 304                         while generics_start != 0
 305                             && generics_end < dox.len()
 306                             && dox.as_bytes()[generics_start - 1] == b'<'
 307                             && dox.as_bytes()[generics_end] == b'>'
 308                         {
 309                             generics_end += 1;
 310                             generics_start -= 1;
 311                             if let Some(new_start) = extract_path_backwards(&dox, generics_start) {
 312                                 generics_start = new_start;
 313                             }
 314                             if let Some(new_end) = extract_path_forward(&dox, generics_end) {
 315                                 generics_end = new_end;
 316                             }
 317                         }
 318                         if let Some(new_end) = extract_path_forward(&dox, generics_end) {
 319                             generics_end = new_end;
 320                         }
 321                         let generics_sp = match super::source_span_for_markdown_range(
 322                             tcx,
 323                             &dox,
 324                             &(generics_start..generics_end),
 325                             &item.attrs,
 326                         ) {
 327                             Some(sp) => sp,
 328                             None => item.attr_span(tcx),
 329                         };
 330                         // Sometimes, we only extract part of a path. For example, consider this:
 331                         //
 332                         //     <[u32] as IntoIter<u32>>::Item
 333                         //                       ^^^^^ unclosed HTML tag `u32`
 334                         //
 335                         // We don't have any code for parsing fully-qualified trait paths.
 336                         // In theory, we could add it, but doing it correctly would require
 337                         // parsing the entire path grammar, which is problematic because of
 338                         // overlap between the path grammar and Markdown.
 339                         //
 340                         // The example above shows that ambiguity. Is `[u32]` intended to be an
 341                         // intra-doc link to the u32 primitive, or is it intended to be a slice?
 342                         //
 343                         // If the below conditional were removed, we would suggest this, which is
 344                         // not what the user probably wants.
 345                         //
 346                         //     <[u32] as `IntoIter<u32>`>::Item
 347                         //
 348                         // We know that the user actually wants to wrap the whole thing in a code
 349                         // block, but the only reason we know that is because `u32` does not, in
 350                         // fact, implement IntoIter. If the example looks like this:
 351                         //
 352                         //     <[Vec<i32>] as IntoIter<i32>::Item
 353                         //
 354                         // The ideal fix would be significantly different.
 355                         if (generics_start > 0 && dox.as_bytes()[generics_start - 1] == b'<')
 356                             || (generics_end < dox.len() && dox.as_bytes()[generics_end] == b'>')
 357                         {
 358                             return lint;
 359                         }
 360                         // multipart form is chosen here because ``Vec<i32>`` would be confusing.
 361                         lint.multipart_suggestion(
 362                             "try marking as source code",
 363                             vec![
 364                                 (generics_sp.shrink_to_lo(), String::from("`")),
 365                                 (generics_sp.shrink_to_hi(), String::from("`")),
 366                             ],
 367                             Applicability::MaybeIncorrect,
 368                         );
 369                     }
 370
 371                     lint
 372                 });
 373             };
 374
 375             let mut tags = Vec::new();
 376             let mut is_in_comment = None;
 377             let mut in_code_block = false;
 378
 379             let link_names = item.link_names(&self.cx.cache);
 380
 381             let mut replacer = |broken_link: BrokenLink<'_>| {
 382                 if let Some(link) =
 383                     link_names.iter().find(|link| *link.original_text == *broken_link.reference)
 384                 {
 385                     Some((link.href.as_str().into(), link.new_text.as_str().into()))
 386                 } else if matches!(
 387                     &broken_link.link_type,
 388                     LinkType::Reference | LinkType::ReferenceUnknown
 389                 ) {
 390                     // If the link is shaped [like][this], suppress any broken HTML in the [this] part.
 391                     // The `broken_intra_doc_links` will report typos in there anyway.
 392                     Some((
 393                         broken_link.reference.to_string().into(),
 394                         broken_link.reference.to_string().into(),
 395                     ))
 396                 } else {
 397                     None
 398                 }
 399             };
 400
 401             let p =
 402                 Parser::new_with_broken_link_callback(&dox, main_body_opts(), Some(&mut replacer))
 403                     .into_offset_iter();
 404
 405             for (event, range) in p {
 406                 match event {
 407                     Event::Start(Tag::CodeBlock(_)) => in_code_block = true,
 408                     Event::Html(text) if !in_code_block => {
 409                         extract_tags(&mut tags, &text, range, &mut is_in_comment, &report_diag)
 410                     }
 411                     Event::End(Tag::CodeBlock(_)) => in_code_block = false,
 412                     _ => {}
 413                 }
 414             }
 415
 416             for (tag, range) in tags.iter().filter(|(t, _)| {
 417                 let t = t.to_lowercase();
 418                 !ALLOWED_UNCLOSED.contains(&t.as_str())
 419             }) {
 420                 report_diag(&format!("unclosed HTML tag `{}`", tag), range, true);
 421             }
 422
 423             if let Some(range) = is_in_comment {
 424                 report_diag("Unclosed HTML comment", &range, false);
 425             }
 426         }
 427
 428         self.visit_item_recur(item)
 429     }
 430 }