Add new tidy check to ensure that rustdoc DOM IDs are all declared as expected

Author: GuillaumeGomez

src/tools/tidy/src/lib.rs

@@ -47,6 +47,7 @@ pub mod extdeps;
 pub mod features;
 pub mod pal;
 pub mod primitive_docs;
+pub mod rustdoc_html_ids;
 pub mod style;
 pub mod target_specific_tests;
 pub mod ui_tests;

src/tools/tidy/src/main.rs

@@ -69,6 +69,9 @@ fn main() {
         check!(errors, &compiler_path);
         check!(error_codes_check, &[&src_path, &compiler_path]);
 
+        // Checks for rustdoc.
+        check!(rustdoc_html_ids, &src_path);
+
         // Checks that only make sense for the std libs.
         check!(pal, &library_path);
         check!(primitive_docs, &library_path);

src/tools/tidy/src/rustdoc_html_ids.rs

@@ -0,0 +1,166 @@
+//! Checks that the rustdoc ID map is up-to-date. The goal here is to check a few things:
+//!
+//! * All IDs created by rustdoc (through JS or files generation) are declared in the ID map.
+//! * There are no unused IDs.
+
+use std::collections::HashMap;
+use std::ffi::OsStr;
+use std::fs::File;
+use std::io::{BufRead, BufReader};
+use std::path::Path;
+
+use regex::Regex;
+
+const ID_MAP_PATH: &str = "librustdoc/html/markdown.rs";
+const IDS_USED_IN_JS: &[&str] = &[
+    // This one is created in the JS and therefore cannot be found in rust files.
+    "help",
+    // This one is used when we need to use a "default" ID.
+    "deref-methods",
+];
+
+fn extract_ids(path: &Path, bad: &mut bool) -> HashMap<String, usize> {
+    let file = File::open(path).expect("failed to open file to extract rustdoc IDs");
+    let buf_reader = BufReader::new(file);
+    let mut iter = buf_reader.lines();
+    let mut ids = HashMap::new();
+
+    while let Some(Ok(line)) = iter.next() {
+        if line.trim_start().starts_with("html_id_map!(") {
+            break;
+        }
+    }
+    // We're now in the function body, time to retrieve the IDs!
+    while let Some(Ok(line)) = iter.next() {
+        let line = line.trim_start();
+        if line.starts_with("// ") {
+            // It's a comment, ignoring this line...
+            continue;
+        } else if line.starts_with(")") {
+            // We reached the end of the IDs declaration list.
+            break;
+        }
+        let id = line.split('"').skip(1).next().unwrap();
+        if ids.insert(id.to_owned(), 0).is_some() {
+            eprintln!(
+                "=> ID `{}` is defined more than once in the ID map in file `{}`",
+                id, ID_MAP_PATH
+            );
+            *bad = true;
+        }
+    }
+    if ids.is_empty() {
+        eprintln!("=> No IDs were found in rustdoc in file `{}`...", ID_MAP_PATH);
+        *bad = true;
+    }
+    ids
+}
+
+fn check_id(
+    path: &Path,
+    id: &str,
+    ids: &mut HashMap<String, usize>,
+    line_nb: usize,
+    bad: &mut bool,
+) {
+    if id.contains('{') {
+        // This is a formatted ID, no need to check it!
+        return;
+    }
+    let id = id.to_owned();
+    match ids.get_mut(&id) {
+        Some(nb) => *nb += 1,
+        None => {
+            eprintln!(
+                "=> ID `{}` in file `{}` at line {} is missing from `init_id_map`",
+                id,
+                path.display(),
+                line_nb + 1,
+            );
+            *bad = true;
+        }
+    }
+}
+
+fn check_ids(
+    path: &Path,
+    f: &str,
+    ids: &mut HashMap<String, usize>,
+    regex: &Regex,
+    bad: &mut bool,
+    small_section_header_checked: &mut usize,
+) {
+    let mut is_checking_small_section_header = None;
+
+    for (line_nb, line) in f.lines().enumerate() {
+        let trimmed = line.trim_start();
+        // We're not interested in comments or doc comments.
+        if trimmed.starts_with("//") {
+            continue;
+        } else if let Some(start_line) = is_checking_small_section_header {
+            if line_nb == start_line + 2 {
+                check_id(path, trimmed.split('"').skip(1).next().unwrap(), ids, line_nb, bad);
+                is_checking_small_section_header = None;
+            }
+        } else if trimmed.starts_with("write_small_section_header(") {
+            // This function is used to create section: the second argument of the function is an
+            // ID and we need to check it as well, hence this specific check...
+            if trimmed.contains(',') {
+                // This is a call made on one line, so we can simply check it!
+                check_id(path, trimmed.split('"').skip(1).next().unwrap(), ids, line_nb, bad);
+            } else {
+                is_checking_small_section_header = Some(line_nb);
+            }
+            *small_section_header_checked += 1;
+            continue;
+        }
+        for cap in regex.captures_iter(line) {
+            check_id(path, &cap[1], ids, line_nb, bad);
+        }
+    }
+}
+
+pub fn check(path: &Path, bad: &mut bool) {
+    // matches ` id="blabla"`
+    let regex = Regex::new(r#"[\s"]id=\\?["']([^\s\\]+)\\?["'][\s\\>"{]"#).unwrap();
+
+    println!("Checking rustdoc IDs...");
+    let mut ids = extract_ids(&path.join(ID_MAP_PATH), bad);
+    let mut small_section_header_checked = 0;
+    if *bad {
+        return;
+    }
+    super::walk(
+        &path.join("librustdoc/html"),
+        &mut |path| super::filter_dirs(path),
+        &mut |entry, contents| {
+            let path = entry.path();
+            let file_name = entry.file_name();
+            if path.extension() == Some(OsStr::new("html"))
+                || (path.extension() == Some(OsStr::new("rs")) && file_name != "tests.rs")
+            {
+                check_ids(path, contents, &mut ids, &regex, bad, &mut small_section_header_checked);
+            }
+        },
+    );
+    if small_section_header_checked == 0 {
+        eprintln!(
+            "No call to the `write_small_section_header` function was found. Was it renamed?",
+        );
+        *bad = true;
+    }
+    for (id, nb) in ids {
+        if IDS_USED_IN_JS.iter().any(|i| i == &id) {
+            if nb != 0 {
+                eprintln!("=> ID `{}` is not supposed to be used in Rust code but in the JS!", id);
+                *bad = true;
+            }
+        } else if nb == 0 {
+            eprintln!(
+                "=> ID `{}` is unused, it should be removed from `init_id_map` in file `{}`",
+                id, ID_MAP_PATH
+            );
+            *bad = true;
+        }
+    }
+}