src/librustdoc/passes/check_code_block_syntax.rs

   1 use rustc_data_structures::sync::{Lock, Lrc};
   2 use rustc_errors::{emitter::Emitter, Applicability, Diagnostic, Handler};
   3 use rustc_parse::lexer::StringReader as Lexer;
   4 use rustc_span::source_map::{FilePathMapping, SourceMap};
   5 use rustc_span::{FileName, InnerSpan};
   6 use syntax::sess::ParseSess;
   7 use syntax::token;
   8
   9 use crate::clean;
  10 use crate::core::DocContext;
  11 use crate::fold::DocFolder;
  12 use crate::html::markdown::{self, RustCodeBlock};
  13 use crate::passes::Pass;
  14
  15 pub const CHECK_CODE_BLOCK_SYNTAX: Pass = Pass {
  16     name: "check-code-block-syntax",
  17     run: check_code_block_syntax,
  18     description: "validates syntax inside Rust code blocks",
  19 };
  20
  21 pub fn check_code_block_syntax(krate: clean::Crate, cx: &DocContext<'_>) -> clean::Crate {
  22     SyntaxChecker { cx }.fold_crate(krate)
  23 }
  24
  25 struct SyntaxChecker<'a, 'tcx> {
  26     cx: &'a DocContext<'tcx>,
  27 }
  28
  29 impl<'a, 'tcx> SyntaxChecker<'a, 'tcx> {
  30     fn check_rust_syntax(&self, item: &clean::Item, dox: &str, code_block: RustCodeBlock) {
  31         let buffered_messages = Lrc::new(Lock::new(vec![]));
  32
  33         let emitter = BufferEmitter { messages: Lrc::clone(&buffered_messages) };
  34
  35         let cm = Lrc::new(SourceMap::new(FilePathMapping::empty()));
  36         let handler = Handler::with_emitter(false, None, Box::new(emitter));
  37         let sess = ParseSess::with_span_handler(handler, cm);
  38         let source_file = sess.source_map().new_source_file(
  39             FileName::Custom(String::from("doctest")),
  40             dox[code_block.code].to_owned(),
  41         );
  42
  43         let validation_status = {
  44             let mut has_syntax_errors = false;
  45             let mut only_whitespace = true;
  46             // even if there is a syntax error, we need to run the lexer over the whole file
  47             let mut lexer = Lexer::new(&sess, source_file, None);
  48             loop {
  49                 match lexer.next_token().kind {
  50                     token::Eof => break,
  51                     token::Whitespace => (),
  52                     token::Unknown(..) => has_syntax_errors = true,
  53                     _ => only_whitespace = false,
  54                 }
  55             }
  56
  57             if has_syntax_errors {
  58                 Some(CodeBlockInvalid::SyntaxError)
  59             } else if only_whitespace {
  60                 Some(CodeBlockInvalid::Empty)
  61             } else {
  62                 None
  63             }
  64         };
  65
  66         if let Some(code_block_invalid) = validation_status {
  67             let mut diag = if let Some(sp) =
  68                 super::source_span_for_markdown_range(self.cx, &dox, &code_block.range, &item.attrs)
  69             {
  70                 let warning_message = match code_block_invalid {
  71                     CodeBlockInvalid::SyntaxError => "could not parse code block as Rust code",
  72                     CodeBlockInvalid::Empty => "Rust code block is empty",
  73                 };
  74
  75                 let mut diag = self.cx.sess().struct_span_warn(sp, warning_message);
  76
  77                 if code_block.syntax.is_none() && code_block.is_fenced {
  78                     let sp = sp.from_inner(InnerSpan::new(0, 3));
  79                     diag.span_suggestion(
  80                         sp,
  81                         "mark blocks that do not contain Rust code as text",
  82                         String::from("```text"),
  83                         Applicability::MachineApplicable,
  84                     );
  85                 }
  86
  87                 diag
  88             } else {
  89                 // We couldn't calculate the span of the markdown block that had the error, so our
  90                 // diagnostics are going to be a bit lacking.
  91                 let mut diag = self.cx.sess().struct_span_warn(
  92                     super::span_of_attrs(&item.attrs).unwrap_or(item.source.span()),
  93                     "doc comment contains an invalid Rust code block",
  94                 );
  95
  96                 if code_block.syntax.is_none() && code_block.is_fenced {
  97                     diag.help("mark blocks that do not contain Rust code as text: ```text");
  98                 }
  99
 100                 diag
 101             };
 102
 103             // FIXME(#67563): Provide more context for these errors by displaying the spans inline.
 104             for message in buffered_messages.borrow().iter() {
 105                 diag.note(&message);
 106             }
 107
 108             diag.emit();
 109         }
 110     }
 111 }
 112
 113 impl<'a, 'tcx> DocFolder for SyntaxChecker<'a, 'tcx> {
 114     fn fold_item(&mut self, item: clean::Item) -> Option<clean::Item> {
 115         if let Some(dox) = &item.attrs.collapsed_doc_value() {
 116             for code_block in markdown::rust_code_blocks(&dox) {
 117                 self.check_rust_syntax(&item, &dox, code_block);
 118             }
 119         }
 120
 121         self.fold_item_recur(item)
 122     }
 123 }
 124
 125 struct BufferEmitter {
 126     messages: Lrc<Lock<Vec<String>>>,
 127 }
 128
 129 impl Emitter for BufferEmitter {
 130     fn emit_diagnostic(&mut self, diag: &Diagnostic) {
 131         self.messages.borrow_mut().push(format!("error from rustc: {}", diag.message[0].0));
 132     }
 133
 134     fn source_map(&self) -> Option<&Lrc<SourceMap>> {
 135         None
 136     }
 137 }
 138
 139 enum CodeBlockInvalid {
 140     SyntaxError,
 141     Empty,
 142 }