//! Detects invalid HTML (like an unclosed ``) in doc comments.
use crate::clean::*;
use crate::core::DocContext;
use crate::html::markdown::main_body_opts;
use pulldown_cmark::{BrokenLink, Event, LinkType, Parser, Tag};
use rustc_resolve::rustdoc::source_span_for_markdown_range;
use std::iter::Peekable;
use std::ops::Range;
use std::str::CharIndices;
pub(crate) fn visit_item(cx: &DocContext<'_>, item: &Item) {
let tcx = cx.tcx;
let Some(hir_id) = DocContext::as_local_hir_id(tcx, item.item_id)
// If non-local, no need to check anything.
else {
return;
};
let dox = item.doc_value();
if !dox.is_empty() {
let report_diag = |msg: String, range: &Range, is_open_tag: bool| {
let sp = match source_span_for_markdown_range(tcx, &dox, range, &item.attrs.doc_strings)
{
Some(sp) => sp,
None => item.attr_span(tcx),
};
tcx.struct_span_lint_hir(crate::lint::INVALID_HTML_TAGS, hir_id, sp, msg, |lint| {
use rustc_lint_defs::Applicability;
// If a tag looks like ``, it might actually be a generic.
// We don't try to detect stuff `` because that's not valid HTML,
// and we don't try to detect stuff `` because that's not valid Rust.
let mut generics_end = range.end;
if let Some(Some(mut generics_start)) = (is_open_tag
&& dox[..generics_end].ends_with('>'))
.then(|| extract_path_backwards(&dox, range.start))
{
while generics_start != 0
&& generics_end < dox.len()
&& dox.as_bytes()[generics_start - 1] == b'<'
&& dox.as_bytes()[generics_end] == b'>'
{
generics_end += 1;
generics_start -= 1;
if let Some(new_start) = extract_path_backwards(&dox, generics_start) {
generics_start = new_start;
}
if let Some(new_end) = extract_path_forward(&dox, generics_end) {
generics_end = new_end;
}
}
if let Some(new_end) = extract_path_forward(&dox, generics_end) {
generics_end = new_end;
}
let generics_sp = match source_span_for_markdown_range(
tcx,
&dox,
&(generics_start..generics_end),
&item.attrs.doc_strings,
) {
Some(sp) => sp,
None => item.attr_span(tcx),
};
// Sometimes, we only extract part of a path. For example, consider this:
//
// <[u32] as IntoIter>::Item
// ^^^^^ unclosed HTML tag `u32`
//
// We don't have any code for parsing fully-qualified trait paths.
// In theory, we could add it, but doing it correctly would require
// parsing the entire path grammar, which is problematic because of
// overlap between the path grammar and Markdown.
//
// The example above shows that ambiguity. Is `[u32]` intended to be an
// intra-doc link to the u32 primitive, or is it intended to be a slice?
//
// If the below conditional were removed, we would suggest this, which is
// not what the user probably wants.
//
// <[u32] as `IntoIter`>::Item
//
// We know that the user actually wants to wrap the whole thing in a code
// block, but the only reason we know that is because `u32` does not, in
// fact, implement IntoIter. If the example looks like this:
//
// <[Vec] as IntoIter::Item
//
// The ideal fix would be significantly different.
if (generics_start > 0 && dox.as_bytes()[generics_start - 1] == b'<')
|| (generics_end < dox.len() && dox.as_bytes()[generics_end] == b'>')
{
return lint;
}
// multipart form is chosen here because ``Vec`` would be confusing.
lint.multipart_suggestion(
"try marking as source code",
vec![
(generics_sp.shrink_to_lo(), String::from("`")),
(generics_sp.shrink_to_hi(), String::from("`")),
],
Applicability::MaybeIncorrect,
);
}
lint
});
};
let mut tags = Vec::new();
let mut is_in_comment = None;
let mut in_code_block = false;
let link_names = item.link_names(&cx.cache);
let mut replacer = |broken_link: BrokenLink<'_>| {
if let Some(link) =
link_names.iter().find(|link| *link.original_text == *broken_link.reference)
{
Some((link.href.as_str().into(), link.new_text.to_string().into()))
} else if matches!(
&broken_link.link_type,
LinkType::Reference | LinkType::ReferenceUnknown
) {
// If the link is shaped [like][this], suppress any broken HTML in the [this] part.
// The `broken_intra_doc_links` will report typos in there anyway.
Some((
broken_link.reference.to_string().into(),
broken_link.reference.to_string().into(),
))
} else {
None
}
};
let p = Parser::new_with_broken_link_callback(&dox, main_body_opts(), Some(&mut replacer))
.into_offset_iter();
for (event, range) in p {
match event {
Event::Start(Tag::CodeBlock(_)) => in_code_block = true,
Event::Html(text) if !in_code_block => {
extract_tags(&mut tags, &text, range, &mut is_in_comment, &report_diag)
}
Event::End(Tag::CodeBlock(_)) => in_code_block = false,
_ => {}
}
}
for (tag, range) in tags.iter().filter(|(t, _)| {
let t = t.to_lowercase();
!ALLOWED_UNCLOSED.contains(&t.as_str())
}) {
report_diag(format!("unclosed HTML tag `{tag}`"), range, true);
}
if let Some(range) = is_in_comment {
report_diag("Unclosed HTML comment".to_string(), &range, false);
}
}
}
const ALLOWED_UNCLOSED: &[&str] = &[
"area", "base", "br", "col", "embed", "hr", "img", "input", "keygen", "link", "meta", "param",
"source", "track", "wbr",
];
fn drop_tag(
tags: &mut Vec<(String, Range)>,
tag_name: String,
range: Range,
f: &impl Fn(String, &Range, bool),
) {
let tag_name_low = tag_name.to_lowercase();
if let Some(pos) = tags.iter().rposition(|(t, _)| t.to_lowercase() == tag_name_low) {
// If the tag is nested inside a "` (the `h2` tag isn't required
// but it helps for the visualization).
f(format!("unopened HTML tag `{tag_name}`"), &range, false);
}
}
fn extract_path_backwards(text: &str, end_pos: usize) -> Option {
use rustc_lexer::{is_id_continue, is_id_start};
let mut current_pos = end_pos;
loop {
if current_pos >= 2 && text[..current_pos].ends_with("::") {
current_pos -= 2;
}
let new_pos = text[..current_pos]
.char_indices()
.rev()
.take_while(|(_, c)| is_id_start(*c) || is_id_continue(*c))
.reduce(|_accum, item| item)
.and_then(|(new_pos, c)| is_id_start(c).then_some(new_pos));
if let Some(new_pos) = new_pos && current_pos != new_pos {
current_pos = new_pos;
continue;
}
break;
}
if current_pos == end_pos { None } else { Some(current_pos) }
}
fn extract_path_forward(text: &str, start_pos: usize) -> Option {
use rustc_lexer::{is_id_continue, is_id_start};
let mut current_pos = start_pos;
loop {
if current_pos < text.len() && text[current_pos..].starts_with("::") {
current_pos += 2;
} else {
break;
}
let mut chars = text[current_pos..].chars();
if let Some(c) = chars.next() {
if is_id_start(c) {
current_pos += c.len_utf8();
} else {
break;
}
}
while let Some(c) = chars.next() {
if is_id_continue(c) {
current_pos += c.len_utf8();
} else {
break;
}
}
}
if current_pos == start_pos { None } else { Some(current_pos) }
}
fn is_valid_for_html_tag_name(c: char, is_empty: bool) -> bool {
// https://spec.commonmark.org/0.30/#raw-html
//
// > A tag name consists of an ASCII letter followed by zero or more ASCII letters, digits, or
// > hyphens (-).
c.is_ascii_alphabetic() || !is_empty && (c == '-' || c.is_ascii_digit())
}
fn extract_html_tag(
tags: &mut Vec<(String, Range)>,
text: &str,
range: &Range,
start_pos: usize,
iter: &mut Peekable>,
f: &impl Fn(String, &Range, bool),
) {
let mut tag_name = String::new();
let mut is_closing = false;
let mut prev_pos = start_pos;
loop {
let (pos, c) = match iter.peek() {
Some((pos, c)) => (*pos, *c),
// In case we reached the of the doc comment, we want to check that it's an
// unclosed HTML tag. For example "///