Create xtask module to generate diagnostics docs

.gitignore

@@ -9,3 +9,4 @@ crates/*/target
 .vscode/settings.json
 generated_assists.adoc
 generated_features.adoc
+generated_diagnostic.adoc

xtask/src/codegen.rs

@@ -10,6 +10,7 @@
 mod gen_assists_docs;
 mod gen_feature_docs;
 mod gen_features;
+mod gen_diagnostic_docs;
 
 use std::{
     fmt, mem,
@@ -21,6 +22,7 @@
 
 pub use self::{
     gen_assists_docs::{generate_assists_docs, generate_assists_tests},
+    gen_diagnostic_docs::generate_diagnostic_docs,
     gen_feature_docs::generate_feature_docs,
     gen_features::generate_features,
     gen_parser_tests::generate_parser_tests,
@@ -47,6 +49,7 @@ pub fn run(self) -> Result<()> {
         generate_assists_tests(Mode::Overwrite)?;
         generate_assists_docs(Mode::Overwrite)?;
         generate_feature_docs(Mode::Overwrite)?;
+        generate_diagnostic_docs(Mode::Overwrite)?;
         Ok(())
     }
 }

xtask/src/codegen/gen_diagnostic_docs.rs

@@ -0,0 +1,73 @@
+//! Generates `assists.md` documentation.
+
+use std::{fmt, fs, path::PathBuf};
+
+use crate::{
+    codegen::{self, extract_comment_blocks_with_empty_lines, Location, Mode, PREAMBLE},
+    project_root, rust_files, Result,
+};
+
+pub fn generate_diagnostic_docs(mode: Mode) -> Result<()> {
+    let features = Diagnostic::collect()?;
+    let contents = features.into_iter().map(|it| it.to_string()).collect::<Vec<_>>().join("\n\n");
+    let contents = format!("//{}\n{}\n", PREAMBLE, contents.trim());
+    let dst = project_root().join("docs/user/generated_diagnostic.adoc");
+    codegen::update(&dst, &contents, mode)?;
+    Ok(())
+}
+
+#[derive(Debug)]
+struct Diagnostic {
+    id: String,
+    location: Location,
+    doc: String,
+}
+
+impl Diagnostic {
+    fn collect() -> Result<Vec<Diagnostic>> {
+        let mut res = Vec::new();
+        for path in rust_files(&project_root()) {
+            collect_file(&mut res, path)?;
+        }
+        res.sort_by(|lhs, rhs| lhs.id.cmp(&rhs.id));
+        return Ok(res);
+
+        fn collect_file(acc: &mut Vec<Diagnostic>, path: PathBuf) -> Result<()> {
+            let text = fs::read_to_string(&path)?;
+            let comment_blocks = extract_comment_blocks_with_empty_lines("Diagnostic", &text);
+
+            for block in comment_blocks {
+                let id = block.id;
+                if let Err(msg) = is_valid_diagnostic_name(&id) {
+                    panic!("invalid diagnostic name: {:?}:\n  {}", id, msg)
+                }
+                let doc = block.contents.join("\n");
+                let location = Location::new(path.clone(), block.line);
+                acc.push(Diagnostic { id, location, doc })
+            }
+
+            Ok(())
+        }
+    }
+}
+
+fn is_valid_diagnostic_name(diagnostic: &str) -> Result<(), String> {
+    let diagnostic = diagnostic.trim();
+    if diagnostic.find(char::is_whitespace).is_some() {
+        return Err("Diagnostic names can't contain whitespace symbols".into());
+    }
+    if diagnostic.chars().any(|c| c.is_ascii_uppercase()) {
+        return Err("Diagnostic names can't contain uppercase symbols".into());
+    }
+    if diagnostic.chars().any(|c| !c.is_ascii()) {
+        return Err("Diagnostic can't contain non-ASCII symbols".into());
+    }
+
+    Ok(())
+}
+
+impl fmt::Display for Diagnostic {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        writeln!(f, "=== {}\n**Source:** {}\n{}", self.id, self.location, self.doc)
+    }
+}