1 //! Validates syntax inside Rust code blocks (\`\`\`rust).
2 use rustc_data_structures::sync::{Lock, Lrc};
4 emitter::Emitter, translation::Translate, Applicability, Diagnostic, Handler,
5 LazyFallbackBundle, LintDiagnosticBuilder,
7 use rustc_parse::parse_stream_from_source_str;
8 use rustc_session::parse::ParseSess;
9 use rustc_span::hygiene::{AstPass, ExpnData, ExpnKind, LocalExpnId};
10 use rustc_span::source_map::{FilePathMapping, SourceMap};
11 use rustc_span::{FileName, InnerSpan, DUMMY_SP};
14 use crate::core::DocContext;
15 use crate::html::markdown::{self, RustCodeBlock};
16 use crate::passes::Pass;
17 use crate::visit::DocVisitor;
19 pub(crate) const CHECK_CODE_BLOCK_SYNTAX: Pass = Pass {
20 name: "check-code-block-syntax",
21 run: check_code_block_syntax,
22 description: "validates syntax inside Rust code blocks",
25 pub(crate) fn check_code_block_syntax(
27 cx: &mut DocContext<'_>,
29 SyntaxChecker { cx }.visit_crate(&krate);
33 struct SyntaxChecker<'a, 'tcx> {
34 cx: &'a DocContext<'tcx>,
37 impl<'a, 'tcx> SyntaxChecker<'a, 'tcx> {
38 fn check_rust_syntax(&self, item: &clean::Item, dox: &str, code_block: RustCodeBlock) {
39 let buffer = Lrc::new(Lock::new(Buffer::default()));
41 rustc_errors::fallback_fluent_bundle(rustc_errors::DEFAULT_LOCALE_RESOURCES, false);
42 let emitter = BufferEmitter { buffer: Lrc::clone(&buffer), fallback_bundle };
44 let sm = Lrc::new(SourceMap::new(FilePathMapping::empty()));
45 let handler = Handler::with_emitter(false, None, Box::new(emitter));
46 let source = dox[code_block.code].to_owned();
47 let sess = ParseSess::with_span_handler(handler, sm);
49 let edition = code_block.lang_string.edition.unwrap_or_else(|| self.cx.tcx.sess.edition());
50 let expn_data = ExpnData::default(
51 ExpnKind::AstPass(AstPass::TestHarness),
58 self.cx.tcx.with_stable_hashing_context(|hcx| LocalExpnId::fresh(expn_data, hcx));
59 let span = DUMMY_SP.fresh_expansion(expn_id);
61 let is_empty = rustc_driver::catch_fatal_errors(|| {
62 parse_stream_from_source_str(
63 FileName::Custom(String::from("doctest")),
71 let buffer = buffer.borrow();
73 if !buffer.has_errors && !is_empty {
74 // No errors in a non-empty program.
78 let Some(local_id) = item.item_id.as_def_id().and_then(|x| x.as_local())
80 // We don't need to check the syntax for other crates so returning
81 // without doing anything should not be a problem.
85 let hir_id = self.cx.tcx.hir().local_def_id_to_hir_id(local_id);
86 let empty_block = code_block.lang_string == Default::default() && code_block.is_fenced;
87 let is_ignore = code_block.lang_string.ignore != markdown::Ignore::None;
89 // The span and whether it is precise or not.
90 let (sp, precise_span) = match super::source_span_for_markdown_range(
96 Some(sp) => (sp, true),
97 None => (item.attr_span(self.cx.tcx), false),
100 // lambda that will use the lint to start a new diagnostic and add
101 // a suggestion to it when needed.
102 let diag_builder = |lint: LintDiagnosticBuilder<'_, ()>| {
103 let explanation = if is_ignore {
104 "`ignore` code blocks require valid Rust code for syntax highlighting; \
105 mark blocks that do not contain Rust code as text"
107 "mark blocks that do not contain Rust code as text"
109 let msg = if buffer.has_errors {
110 "could not parse code block as Rust code"
112 "Rust code block is empty"
114 let mut diag = lint.build(msg);
118 // giving an accurate suggestion is hard because `ignore` might not have come first in the list.
119 // just give a `help` instead.
121 sp.from_inner(InnerSpan::new(0, 3)),
122 &format!("{}: ```text", explanation),
124 } else if empty_block {
125 diag.span_suggestion(
126 sp.from_inner(InnerSpan::new(0, 3)).shrink_to_hi(),
129 Applicability::MachineApplicable,
132 } else if empty_block || is_ignore {
133 diag.help(&format!("{}: ```text", explanation));
136 // FIXME(#67563): Provide more context for these errors by displaying the spans inline.
137 for message in buffer.messages.iter() {
144 // Finally build and emit the completed diagnostic.
145 // All points of divergence have been handled earlier so this can be
146 // done the same way whether the span is precise or not.
147 self.cx.tcx.struct_span_lint_hir(
148 crate::lint::INVALID_RUST_CODEBLOCKS,
156 impl<'a, 'tcx> DocVisitor for SyntaxChecker<'a, 'tcx> {
157 fn visit_item(&mut self, item: &clean::Item) {
158 if let Some(dox) = &item.attrs.collapsed_doc_value() {
159 let sp = item.attr_span(self.cx.tcx);
160 let extra = crate::html::markdown::ExtraInfo::new_did(
162 item.item_id.expect_def_id(),
165 for code_block in markdown::rust_code_blocks(dox, &extra) {
166 self.check_rust_syntax(item, dox, code_block);
170 self.visit_item_recur(item)
176 messages: Vec<String>,
180 struct BufferEmitter {
181 buffer: Lrc<Lock<Buffer>>,
182 fallback_bundle: LazyFallbackBundle,
185 impl Translate for BufferEmitter {
186 fn fluent_bundle(&self) -> Option<&Lrc<rustc_errors::FluentBundle>> {
190 fn fallback_fluent_bundle(&self) -> &rustc_errors::FluentBundle {
191 &**self.fallback_bundle
195 impl Emitter for BufferEmitter {
196 fn emit_diagnostic(&mut self, diag: &Diagnostic) {
197 let mut buffer = self.buffer.borrow_mut();
198 // FIXME(davidtwco): need to support translation here eventually
199 buffer.messages.push(format!("error from rustc: {}", diag.message[0].0.expect_str()));
201 buffer.has_errors = true;
205 fn source_map(&self) -> Option<&Lrc<SourceMap>> {