Merge bitcoin#30034: ci: add markdown link check job

4b7d984 lint: add markdown hyperlink checker (willcl-ark)

Pull request description:

  Potential followup to: bitcoin#30025

  This should prevent us reintroducing broken markdown links.

  It does not test "online" (external) links, only those within this repo. Both relative and absolute links are parsed successfully if they resolve.

ACKs for top commit:
  maflcko:
    re-utACK 4b7d984
  davidgumberg:
    reACK bitcoin@4b7d984

Tree-SHA512: 9bc40d700b73499c046bb76157bc139f32ec3850f64ef813bbf7f18f9c01a253abe6a857d6f559890165f2bd26e7742c05d86232cd9b8efb33ff85d735f4f095

ci/lint/04_install.sh

@@ -57,3 +57,8 @@ SHELLCHECK_VERSION=v0.8.0
 curl -sL "https://github.com/koalaman/shellcheck/releases/download/${SHELLCHECK_VERSION}/shellcheck-${SHELLCHECK_VERSION}.linux.x86_64.tar.xz" | \
     tar --xz -xf - --directory /tmp/
 mv "/tmp/shellcheck-${SHELLCHECK_VERSION}/shellcheck" /usr/bin/
+
+MLC_VERSION=v0.16.3
+MLC_BIN=mlc-x86_64-linux
+curl -sL "https://github.com/becheran/mlc/releases/download/${MLC_VERSION}/${MLC_BIN}" -o "/usr/bin/mlc"
+chmod +x /usr/bin/mlc

test/lint/README.md

@@ -37,6 +37,7 @@ Then you can use:
 | [`lint-python-dead-code.py`](/test/lint/lint-python-dead-code.py) | [vulture](https://github.com/jendrikseipp/vulture)
 | [`lint-shell.py`](/test/lint/lint-shell.py) | [ShellCheck](https://github.com/koalaman/shellcheck)
 | [`lint-spelling.py`](/test/lint/lint-spelling.py) | [codespell](https://github.com/codespell-project/codespell)
+| markdown link check | [mlc](https://github.com/becheran/mlc)
 
 In use versions and install instructions are available in the [CI setup](../../ci/lint/04_install.sh).
 

test/lint/test_runner/src/main.rs

@@ -4,9 +4,9 @@
 
 use std::env;
 use std::fs;
+use std::io::ErrorKind;
 use std::path::{Path, PathBuf};
-use std::process::Command;
-use std::process::ExitCode;
+use std::process::{Command, ExitCode, Stdio};
 
 type LintError = String;
 type LintResult = Result<(), LintError>;
@@ -292,6 +292,51 @@ fn lint_doc() -> LintResult {
     }
 }
 
+fn lint_markdown() -> LintResult {
+    let bin_name = "mlc";
+    let mut md_ignore_paths = get_subtrees();
+    md_ignore_paths.push("./doc/README_doxygen.md");
+    let md_ignore_path_str = md_ignore_paths.join(",");
+
+    let mut cmd = Command::new(bin_name);
+    cmd.args([
+        "--offline",
+        "--ignore-path",
+        md_ignore_path_str.as_str(),
+        "--root-dir",
+        ".",
+    ])
+    .stdout(Stdio::null()); // Suppress overly-verbose output
+
+    match cmd.output() {
+        Ok(output) if output.status.success() => Ok(()),
+        Ok(output) => {
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            let filtered_stderr: String = stderr // Filter out this annoying trailing line
+                .lines()
+                .filter(|&line| line != "The following links could not be resolved:")
+                .collect::<Vec<&str>>()
+                .join("\n");
+            Err(format!(
+                r#"
+One or more markdown links are broken.
+
+Relative links are preferred (but not required) as jumping to file works natively within Emacs.
+
+Markdown link errors found:
+{}
+                "#,
+                filtered_stderr
+            ))
+        }
+        Err(e) if e.kind() == ErrorKind::NotFound => {
+            println!("`mlc` was not found in $PATH, skipping markdown lint check.");
+            Ok(())
+        }
+        Err(e) => Err(format!("Error running mlc: {}", e)), // Misc errors
+    }
+}
+
 fn lint_all() -> LintResult {
     let mut good = true;
     let lint_dir = get_git_root().join("test/lint");
@@ -325,6 +370,7 @@ fn main() -> ExitCode {
         ("no-tabs check", lint_tabs_whitespace),
         ("build config includes check", lint_includes_build_config),
         ("-help=1 documentation check", lint_doc),
+        ("markdown hyperlink check", lint_markdown),
         ("lint-*.py scripts", lint_all),
     ];