[wip]

Author: fmease

Cargo.lock

@@ -1721,6 +1721,16 @@ dependencies = [
  "syn 1.0.109",
 ]
 
+[[package]]
+name = "htmldocck"
+version = "0.1.0"
+dependencies = [
+ "getopts",
+ "regex",
+ "shlex",
+ "unicode-width",
+]
+
 [[package]]
 name = "http"
 version = "0.2.12"

Cargo.toml

@@ -31,6 +31,7 @@ members = [
   "src/tools/miri/cargo-miri",
   "src/tools/rustdoc-themes",
   "src/tools/unicode-table-generator",
+  "src/tools/htmldocck",
   "src/tools/jsondocck",
   "src/tools/jsondoclint",
   "src/tools/llvm-bitcode-linker",

src/bootstrap/src/core/build_steps/clippy.rs

@@ -311,7 +311,8 @@ lint_any!(
     CollectLicenseMetadata, "src/tools/collect-license-metadata", "collect-license-metadata";
     Compiletest, "src/tools/compiletest", "compiletest";
     CoverageDump, "src/tools/coverage-dump", "coverage-dump";
-    Jsondocck, "src/tools/jsondocck", "jsondocck";
+    HtmldocCk, "src/tools/htmldocck", "htmldocck";
+    JsondocCk, "src/tools/jsondocck", "jsondocck";
     Jsondoclint, "src/tools/jsondoclint", "jsondoclint";
     LintDocs, "src/tools/lint-docs", "lint-docs";
     LlvmBitcodeLinker, "src/tools/llvm-bitcode-linker", "llvm-bitcode-linker";

src/bootstrap/src/core/build_steps/test.rs

@@ -1766,13 +1766,18 @@ NOTE: if you're sure you want to do this, please open an issue as to why. In the
             cmd.arg("--rustdoc-path").arg(builder.rustdoc(compiler));
         }
 
+        if mode == "rustdoc" {
+            // Use the beta compiler for htmldocck.
+            let compiler = compiler.with_stage(0);
+            cmd.arg("--htmldocck-path").arg(builder.ensure(tool::HtmlDocCk { compiler, target }));
+        }
+
         if mode == "rustdoc-json" {
-            // Use the beta compiler for jsondocck
-            let json_compiler = compiler.with_stage(0);
-            cmd.arg("--jsondocck-path")
-                .arg(builder.ensure(tool::JsonDocCk { compiler: json_compiler, target }));
+            // Use the beta compiler for jsondocck.
+            let compiler = compiler.with_stage(0);
+            cmd.arg("--jsondocck-path").arg(builder.ensure(tool::JsonDocCk { compiler, target }));
             cmd.arg("--jsondoclint-path")
-                .arg(builder.ensure(tool::JsonDocLint { compiler: json_compiler, target }));
+                .arg(builder.ensure(tool::JsonDocLint { compiler, target }));
         }
 
         if mode == "coverage-map" {

src/bootstrap/src/core/build_steps/tool.rs

@@ -303,6 +303,7 @@ bootstrap_tool!(
     RustInstaller, "src/tools/rust-installer", "rust-installer";
     RustdocTheme, "src/tools/rustdoc-themes", "rustdoc-themes";
     LintDocs, "src/tools/lint-docs", "lint-docs";
+    HtmlDocCk, "src/tools/htmldocck", "htmldocck";
     JsonDocCk, "src/tools/jsondocck", "jsondocck";
     JsonDocLint, "src/tools/jsondoclint", "jsondoclint";
     HtmlChecker, "src/tools/html-checker", "html-checker";

src/bootstrap/src/core/builder.rs

@@ -758,7 +758,8 @@ impl<'a> Builder<'a> {
                 clippy::CollectLicenseMetadata,
                 clippy::Compiletest,
                 clippy::CoverageDump,
-                clippy::Jsondocck,
+                clippy::HtmldocCk,
+                clippy::JsondocCk,
                 clippy::Jsondoclint,
                 clippy::LintDocs,
                 clippy::LlvmBitcodeLinker,

src/tools/compiletest/src/common.rs

@@ -193,9 +193,12 @@ pub struct Config {
     /// The coverage-dump executable.
     pub coverage_dump_path: Option<PathBuf>,
 
-    /// The Python executable to use for LLDB and htmldocck.
+    /// The Python executable to use for LLDB.
     pub python: String,
 
+    /// The htmldocck executable.
+    pub htmldocck_path: Option<String>,
+
     /// The jsondocck executable.
     pub jsondocck_path: Option<String>,
 

src/tools/compiletest/src/header/tests.rs

@@ -131,6 +131,7 @@ impl ConfigBuilder {
             "--compile-lib-path=",
             "--run-lib-path=",
             "--python=",
+            // FIXME(fmease): Do we need to set htmldocck-path to "", too?
             "--jsondocck-path=",
             "--src-base=",
             "--build-base=",

src/tools/compiletest/src/lib.rs

@@ -48,7 +48,9 @@ pub fn parse_config(args: Vec<String>) -> Config {
         .optopt("", "rustdoc-path", "path to rustdoc to use for compiling", "PATH")
         .optopt("", "rust-demangler-path", "path to rust-demangler to use in tests", "PATH")
         .optopt("", "coverage-dump-path", "path to coverage-dump to use in tests", "PATH")
+        // FIXME(fmease): fix docs here
         .reqopt("", "python", "path to python to use for doc tests", "PATH")
+        .optopt("", "htmldocck-path", "path to htmldocck to use for doc tests", "PATH")
         .optopt("", "jsondocck-path", "path to jsondocck to use for doc tests", "PATH")
         .optopt("", "jsondoclint-path", "path to jsondoclint to use for doc tests", "PATH")
         .optopt("", "valgrind-path", "path to Valgrind executable for Valgrind tests", "PROGRAM")
@@ -235,6 +237,7 @@ pub fn parse_config(args: Vec<String>) -> Config {
         rust_demangler_path: matches.opt_str("rust-demangler-path").map(PathBuf::from),
         coverage_dump_path: matches.opt_str("coverage-dump-path").map(PathBuf::from),
         python: matches.opt_str("python").unwrap(),
+        htmldocck_path: matches.opt_str("htmldocck-path"),
         jsondocck_path: matches.opt_str("jsondocck-path"),
         jsondoclint_path: matches.opt_str("jsondoclint-path"),
         valgrind_path: matches.opt_str("valgrind-path"),
@@ -617,6 +620,7 @@ fn common_inputs_stamp(config: &Config) -> Stamp {
 
     if let Some(ref rustdoc_path) = config.rustdoc_path {
         stamp.add_path(&rustdoc_path);
+        // FIXME(fmease): Update to `src/tools/htmldocck` or rm entirely
         stamp.add_path(&rust_src_dir.join("src/etc/htmldocck.py"));
     }
 

src/tools/compiletest/src/runtest.rs

@@ -3024,9 +3024,16 @@ impl<'test> TestCx<'test> {
         if self.props.check_test_line_numbers_match {
             self.check_rustdoc_test_option(proc_res);
         } else {
-            let root = self.config.find_rust_src_root().unwrap();
-            let mut cmd = Command::new(&self.config.python);
-            cmd.arg(root.join("src/etc/htmldocck.py")).arg(&out_dir).arg(&self.testpaths.file);
+            // FIXME(fmease): Temporary commented out code:
+            // FIXME(fmease): I don't like this unwrap!
+            let mut cmd = Command::new(self.config.htmldocck_path.as_ref().unwrap());
+            cmd.arg("--doc-dir").arg(&out_dir).arg("--template").arg(&self.testpaths.file);
+
+            // let root = self.config.find_rust_src_root().unwrap();
+            // let mut cmd = Command::new(&self.config.python);
+            // cmd.arg(root.join("src/etc/htmldocck.py"));
+            // cmd.arg(&out_dir).arg(&self.testpaths.file);
+
             if self.config.bless {
                 cmd.arg("--bless");
             }

src/tools/htmldocck/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "htmldocck"
+version = "0.1.0"
+description = "A test framework for rustdoc's HTML backend"
+edition = "2021"
+
+[dependencies]
+getopts = "0.2"
+regex = "1.8" # 1.8 to avoid memchr 2.6.0, as 2.5.0 is pinned in the workspace
+shlex = "1.3.0"
+unicode-width = "0.1.4"

src/tools/htmldocck/src/cache.rs

@@ -0,0 +1,40 @@
+use std::{collections::HashMap, path::Path};
+
+pub(crate) struct Cache<'a> {
+    root: &'a Path,
+    // FIXME: `&'a str`s
+    files: HashMap<String, String>,
+    // FIXME: `&'a str`, comment what this is for -- `-`
+    last_path: Option<String>,
+}
+
+impl<'a> Cache<'a> {
+    pub(crate) fn new(root: &'a Path) -> Self {
+        Self { root, files: HashMap::new(), last_path: None }
+    }
+
+    pub(crate) fn read_file(&mut self, path: String) -> &str {
+        let path = self.resolve_path(path);
+
+        self.files.entry(path).or_insert_with_key(|path| {
+            std::fs::read_to_string(self.root.join(path)).expect("failed to read file") // FIXME
+        })
+    }
+
+    // FIXME: &str -> &str if possible
+    fn resolve_path(&mut self, path: String) -> String {
+        if path == "-" {
+            // FIXME: proper error handling
+            // FIXME: no cloning
+            return self
+                .last_path
+                .clone()
+                .expect("attempt to use `-` ('previous path') in the very first command");
+        }
+
+        // While we could normalize the `path` at this point by
+        // using `std::path::absolute`, it's likely not worth it.
+        self.last_path = Some(path.clone());
+        path
+    }
+}

src/tools/htmldocck/src/check.rs

@@ -0,0 +1,22 @@
+use crate::cache::Cache;
+use crate::error::DiagCtxt;
+use crate::{Command, CommandKind};
+
+impl Command {
+    pub(crate) fn check(self, cache: &mut Cache<'_>, dcx: &mut DiagCtxt) {
+        match self.kind {
+            CommandKind::HasFile { path } => todo!(),
+            CommandKind::Has { path, pattern, text } => todo!(),
+            CommandKind::HasDir { path } => todo!(),
+            CommandKind::HasRaw { path, pattern } => {
+                let file = cache.read_file(path);
+                todo!()
+            }
+            CommandKind::Matches { path, pattern, text } => todo!(),
+            CommandKind::MatchesRaw { path, pattern } => todo!(),
+            CommandKind::Count { path, pattern, text, count } => todo!(),
+            CommandKind::Files { path, files } => todo!(),
+            CommandKind::Snapshot { name, path, pattern } => todo!(),
+        }
+    }
+}

src/tools/htmldocck/src/config.rs

@@ -0,0 +1,46 @@
+use std::path::PathBuf;
+
+use crate::error::DiagCtxt;
+
+pub(crate) struct Config {
+    /// The path to the directory that contains the generated HTML documentation.
+    pub(crate) doc_dir: PathBuf,
+    /// The path to the test file the docs were generated for and which may contain check commands.
+    pub(crate) template: String,
+    /// Whether to automatically update snapshot files.
+    pub(crate) bless: bool,
+}
+
+impl Config {
+    pub(crate) fn parse(args: &[String], dcx: &mut DiagCtxt) -> Result<Self, ()> {
+        const DOC_DIR_OPT: &str = "doc-dir";
+        const TEMPLATE_OPT: &str = "template";
+        const BLESS_FLAG: &str = "bless";
+
+        let mut opts = getopts::Options::new();
+        opts.reqopt("", DOC_DIR_OPT, "Path to the documentation directory", "<PATH>")
+            .reqopt("", TEMPLATE_OPT, "Path to the template file", "<PATH>")
+            .optflag("", BLESS_FLAG, "Whether to automatically update snapshot files");
+
+        // We may not assume the presence of the first argument. On some platforms,
+        // it's possible to pass an empty array of arguments to `execve`.
+        let program = args.get(0).map(|arg| arg.as_str()).unwrap_or("htmldocck");
+        let args = args.get(1..).unwrap_or_default();
+
+        match opts.parse(args) {
+            Ok(matches) => Ok(Self {
+                doc_dir: matches.opt_str(DOC_DIR_OPT).unwrap().into(),
+                template: matches.opt_str(TEMPLATE_OPT).unwrap(),
+                bless: matches.opt_present(BLESS_FLAG),
+            }),
+            Err(err) => {
+                let mut err = err.to_string();
+                err.push_str("\n\n");
+                err.push_str(&opts.short_usage(program));
+                err.push_str(&opts.usage(""));
+                dcx.emit_noloc(&err);
+                Err(())
+            }
+        }
+    }
+}

src/tools/htmldocck/src/error.rs

@@ -0,0 +1,95 @@
+use std::ops::Range;
+
+use unicode_width::UnicodeWidthStr;
+
+pub(crate) struct DiagCtxt {
+    count: usize,
+}
+
+impl DiagCtxt {
+    pub(crate) fn scope(run: impl FnOnce(&mut Self) -> Result<(), ()>) -> Result<(), ()> {
+        let mut dcx = Self::new();
+        let result = run(&mut dcx);
+        dcx.summarize();
+        result.and(dcx.result())
+    }
+
+    fn new() -> Self {
+        Self { count: 0 }
+    }
+
+    // FIXME: proper API, name
+    pub(crate) fn emit_noloc(&mut self, message: &str) {
+        // FIXME: use proper coloring library
+        eprintln!("\x1b[31merror\x1b[0m: {message}");
+        self.count += 1;
+    }
+
+    // FIXME: proper API
+    pub(crate) fn emit<'a>(
+        &mut self,
+        message: &str,
+        line: &str,
+        location: impl Into<Location>,
+        help: impl Into<Option<&'a str>>,
+    ) {
+        self._emit(message, line, location.into(), help.into())
+    }
+
+    fn _emit(&mut self, message: &str, line: &str, location: Location, help: Option<&str>) {
+        // FIXME: use proper coloring library
+        eprintln!("\x1b[31merror\x1b[0m: {message}");
+        eprintln!("\x1b[1;36m{} | \x1b[0m{line}", location.lineno);
+        if let Some(range) = location.range {
+            let underline_offset = line[..range.start].width();
+            let underline_length = line[range].width();
+            eprintln!(
+                "\x1b[1;36m{}   \x1b[0m\x1b[31m{}{}{}\x1b[0m",
+                " ".repeat(location.lineno.ilog10() as usize + 1),
+                " ".repeat(underline_offset),
+                "^".repeat(underline_length),
+                // FIXME: get rid of format here
+                help.map(|help| format!(" help: {help}")).unwrap_or_default(),
+            );
+        }
+        self.count += 1;
+    }
+
+    pub(crate) fn result(&self) -> Result<(), ()> {
+        match self.count {
+            0 => Ok(()),
+            _ => Err(()),
+        }
+    }
+
+    fn summarize(&self) {
+        if self.count == 0 {
+            return;
+        }
+
+        eprintln!();
+        eprintln!("encountered {} error{}", self.count, if self.count == 1 { "" } else { "s" },);
+    }
+}
+
+pub(crate) struct Location {
+    /// The one-based line number.
+    pub(crate) lineno: usize,
+    // FIXME: docs
+    // FIXME: check if we actually want Option<_> here
+    pub(crate) range: Option<Range<usize>>,
+}
+
+// FIXME: check if we want to keep this
+impl From<usize> for Location {
+    fn from(lineno: usize) -> Self {
+        Self { lineno, range: None }
+    }
+}
+
+// FIXME: check if we want to keep this (this way)
+impl From<(usize, Range<usize>)> for Location {
+    fn from((lineno, range): (usize, Range<usize>)) -> Self {
+        Self { lineno, range: Some(range) }
+    }
+}