1 //! Detects invalid HTML (like an unclosed `<span>`) in doc comments.
3 use crate::core::DocContext;
4 use crate::html::markdown::main_body_opts;
5 use crate::passes::source_span_for_markdown_range;
7 use pulldown_cmark::{BrokenLink, Event, LinkType, Parser, Tag};
9 use std::iter::Peekable;
11 use std::str::CharIndices;
13 pub(crate) fn visit_item(cx: &DocContext<'_>, item: &Item) {
15 let Some(hir_id) = DocContext::as_local_hir_id(tcx, item.item_id)
16 // If non-local, no need to check anything.
18 let dox = item.attrs.collapsed_doc_value().unwrap_or_default();
20 let report_diag = |msg: &str, range: &Range<usize>, is_open_tag: bool| {
21 let sp = match source_span_for_markdown_range(tcx, &dox, range, &item.attrs) {
23 None => item.attr_span(tcx),
25 tcx.struct_span_lint_hir(crate::lint::INVALID_HTML_TAGS, hir_id, sp, msg, |lint| {
26 use rustc_lint_defs::Applicability;
27 // If a tag looks like `<this>`, it might actually be a generic.
28 // We don't try to detect stuff `<like, this>` because that's not valid HTML,
29 // and we don't try to detect stuff `<like this>` because that's not valid Rust.
30 let mut generics_end = range.end;
31 if let Some(Some(mut generics_start)) = (is_open_tag
32 && dox[..generics_end].ends_with('>'))
33 .then(|| extract_path_backwards(&dox, range.start))
35 while generics_start != 0
36 && generics_end < dox.len()
37 && dox.as_bytes()[generics_start - 1] == b'<'
38 && dox.as_bytes()[generics_end] == b'>'
42 if let Some(new_start) = extract_path_backwards(&dox, generics_start) {
43 generics_start = new_start;
45 if let Some(new_end) = extract_path_forward(&dox, generics_end) {
46 generics_end = new_end;
49 if let Some(new_end) = extract_path_forward(&dox, generics_end) {
50 generics_end = new_end;
52 let generics_sp = match source_span_for_markdown_range(
55 &(generics_start..generics_end),
59 None => item.attr_span(tcx),
61 // Sometimes, we only extract part of a path. For example, consider this:
63 // <[u32] as IntoIter<u32>>::Item
64 // ^^^^^ unclosed HTML tag `u32`
66 // We don't have any code for parsing fully-qualified trait paths.
67 // In theory, we could add it, but doing it correctly would require
68 // parsing the entire path grammar, which is problematic because of
69 // overlap between the path grammar and Markdown.
71 // The example above shows that ambiguity. Is `[u32]` intended to be an
72 // intra-doc link to the u32 primitive, or is it intended to be a slice?
74 // If the below conditional were removed, we would suggest this, which is
75 // not what the user probably wants.
77 // <[u32] as `IntoIter<u32>`>::Item
79 // We know that the user actually wants to wrap the whole thing in a code
80 // block, but the only reason we know that is because `u32` does not, in
81 // fact, implement IntoIter. If the example looks like this:
83 // <[Vec<i32>] as IntoIter<i32>::Item
85 // The ideal fix would be significantly different.
86 if (generics_start > 0 && dox.as_bytes()[generics_start - 1] == b'<')
87 || (generics_end < dox.len() && dox.as_bytes()[generics_end] == b'>')
91 // multipart form is chosen here because ``Vec<i32>`` would be confusing.
92 lint.multipart_suggestion(
93 "try marking as source code",
95 (generics_sp.shrink_to_lo(), String::from("`")),
96 (generics_sp.shrink_to_hi(), String::from("`")),
98 Applicability::MaybeIncorrect,
106 let mut tags = Vec::new();
107 let mut is_in_comment = None;
108 let mut in_code_block = false;
110 let link_names = item.link_names(&cx.cache);
112 let mut replacer = |broken_link: BrokenLink<'_>| {
114 link_names.iter().find(|link| *link.original_text == *broken_link.reference)
116 Some((link.href.as_str().into(), link.new_text.as_str().into()))
118 &broken_link.link_type,
119 LinkType::Reference | LinkType::ReferenceUnknown
121 // If the link is shaped [like][this], suppress any broken HTML in the [this] part.
122 // The `broken_intra_doc_links` will report typos in there anyway.
124 broken_link.reference.to_string().into(),
125 broken_link.reference.to_string().into(),
132 let p = Parser::new_with_broken_link_callback(&dox, main_body_opts(), Some(&mut replacer))
135 for (event, range) in p {
137 Event::Start(Tag::CodeBlock(_)) => in_code_block = true,
138 Event::Html(text) if !in_code_block => {
139 extract_tags(&mut tags, &text, range, &mut is_in_comment, &report_diag)
141 Event::End(Tag::CodeBlock(_)) => in_code_block = false,
146 for (tag, range) in tags.iter().filter(|(t, _)| {
147 let t = t.to_lowercase();
148 !ALLOWED_UNCLOSED.contains(&t.as_str())
150 report_diag(&format!("unclosed HTML tag `{}`", tag), range, true);
153 if let Some(range) = is_in_comment {
154 report_diag("Unclosed HTML comment", &range, false);
159 const ALLOWED_UNCLOSED: &[&str] = &[
160 "area", "base", "br", "col", "embed", "hr", "img", "input", "keygen", "link", "meta", "param",
161 "source", "track", "wbr",
165 tags: &mut Vec<(String, Range<usize>)>,
168 f: &impl Fn(&str, &Range<usize>, bool),
170 let tag_name_low = tag_name.to_lowercase();
171 if let Some(pos) = tags.iter().rposition(|(t, _)| t.to_lowercase() == tag_name_low) {
172 // If the tag is nested inside a "<script>" or a "<style>" tag, no warning should
174 let should_not_warn = tags.iter().take(pos + 1).any(|(at, _)| {
175 let at = at.to_lowercase();
176 at == "script" || at == "style"
178 for (last_tag_name, last_tag_span) in tags.drain(pos + 1..) {
182 let last_tag_name_low = last_tag_name.to_lowercase();
183 if ALLOWED_UNCLOSED.contains(&last_tag_name_low.as_str()) {
186 // `tags` is used as a queue, meaning that everything after `pos` is included inside it.
187 // So `<h2><h3></h2>` will look like `["h2", "h3"]`. So when closing `h2`, we will still
188 // have `h3`, meaning the tag wasn't closed as it should have.
189 f(&format!("unclosed HTML tag `{}`", last_tag_name), &last_tag_span, true);
191 // Remove the `tag_name` that was originally closed
194 // It can happen for example in this case: `<h2></script></h2>` (the `h2` tag isn't required
195 // but it helps for the visualization).
196 f(&format!("unopened HTML tag `{}`", tag_name), &range, false);
200 fn extract_path_backwards(text: &str, end_pos: usize) -> Option<usize> {
201 use rustc_lexer::{is_id_continue, is_id_start};
202 let mut current_pos = end_pos;
204 if current_pos >= 2 && text[..current_pos].ends_with("::") {
207 let new_pos = text[..current_pos]
210 .take_while(|(_, c)| is_id_start(*c) || is_id_continue(*c))
211 .reduce(|_accum, item| item)
212 .and_then(|(new_pos, c)| is_id_start(c).then_some(new_pos));
213 if let Some(new_pos) = new_pos {
214 if current_pos != new_pos {
215 current_pos = new_pos;
221 if current_pos == end_pos { None } else { Some(current_pos) }
224 fn extract_path_forward(text: &str, start_pos: usize) -> Option<usize> {
225 use rustc_lexer::{is_id_continue, is_id_start};
226 let mut current_pos = start_pos;
228 if current_pos < text.len() && text[current_pos..].starts_with("::") {
233 let mut chars = text[current_pos..].chars();
234 if let Some(c) = chars.next() {
236 current_pos += c.len_utf8();
241 while let Some(c) = chars.next() {
242 if is_id_continue(c) {
243 current_pos += c.len_utf8();
249 if current_pos == start_pos { None } else { Some(current_pos) }
252 fn is_valid_for_html_tag_name(c: char, is_empty: bool) -> bool {
253 // https://spec.commonmark.org/0.30/#raw-html
255 // > A tag name consists of an ASCII letter followed by zero or more ASCII letters, digits, or
257 c.is_ascii_alphabetic() || !is_empty && (c == '-' || c.is_ascii_digit())
261 tags: &mut Vec<(String, Range<usize>)>,
263 range: &Range<usize>,
265 iter: &mut Peekable<CharIndices<'_>>,
266 f: &impl Fn(&str, &Range<usize>, bool),
268 let mut tag_name = String::new();
269 let mut is_closing = false;
270 let mut prev_pos = start_pos;
273 let (pos, c) = match iter.peek() {
274 Some((pos, c)) => (*pos, *c),
275 // In case we reached the of the doc comment, we want to check that it's an
276 // unclosed HTML tag. For example "/// <h3".
277 None => (prev_pos, '\0'),
280 // Checking if this is a closing tag (like `</a>` for `<a>`).
281 if c == '/' && tag_name.is_empty() {
283 } else if is_valid_for_html_tag_name(c, tag_name.is_empty()) {
286 if !tag_name.is_empty() {
287 let mut r = Range { start: range.start + start_pos, end: range.start + pos };
289 // In case we have a tag without attribute, we can consider the span to
290 // refer to it fully.
294 // In case we have "</div >" or even "</div >".
296 if !c.is_whitespace() {
297 // It seems like it's not a valid HTML tag.
300 let mut found = false;
301 for (new_pos, c) in text[pos..].char_indices() {
302 if !c.is_whitespace() {
304 r.end = range.start + new_pos + 1;
314 drop_tag(tags, tag_name, r, f);
316 let mut is_self_closing = false;
317 let mut quote_pos = None;
319 let mut quote = None;
320 let mut after_eq = false;
321 for (i, c) in text[pos..].char_indices() {
322 if !c.is_whitespace() {
323 if let Some(q) = quote {
331 } else if c == '/' && !after_eq {
332 is_self_closing = true;
335 is_self_closing = false;
337 if (c == '"' || c == '\'') && after_eq {
339 quote_pos = Some(pos + i);
344 } else if quote.is_none() {
349 if let Some(quote_pos) = quote_pos {
350 let qr = Range { start: quote_pos, end: quote_pos };
352 &format!("unclosed quoted HTML attribute on tag `{}`", tag_name),
358 // https://html.spec.whatwg.org/#parse-error-non-void-html-element-start-tag-with-trailing-solidus
359 let valid = ALLOWED_UNCLOSED.contains(&&tag_name[..])
360 || tags.iter().take(pos + 1).any(|(at, _)| {
361 let at = at.to_lowercase();
362 at == "svg" || at == "math"
365 f(&format!("invalid self-closing HTML tag `{}`", tag_name), &r, false);
368 tags.push((tag_name, r));
379 tags: &mut Vec<(String, Range<usize>)>,
382 is_in_comment: &mut Option<Range<usize>>,
383 f: &impl Fn(&str, &Range<usize>, bool),
385 let mut iter = text.char_indices().peekable();
387 while let Some((start_pos, c)) = iter.next() {
388 if is_in_comment.is_some() {
389 if text[start_pos..].starts_with("-->") {
390 *is_in_comment = None;
393 if text[start_pos..].starts_with("<!--") {
394 // We skip the "!--" part. (Once `advance_by` is stable, might be nice to use it!)
398 *is_in_comment = Some(Range {
399 start: range.start + start_pos,
400 end: range.start + start_pos + 3,
403 extract_html_tag(tags, text, &range, start_pos, &mut iter, f);