cargo-deadlinks.rs

use std::env;
use std::ffi::{OsStr, OsString};
use std::io::BufReader;
use std::process::{self, Command};

use cargo_metadata::{Message, MetadataCommand};
use serde_derive::Deserialize;

use cargo_deadlinks::{walk_dir, CheckContext, HttpCheck};

mod shared;

const MAIN_USAGE: &str = "
Check your package's documentation for dead links.

Usage:
    cargo deadlinks [--dir <directory>] [--cargo-dir <directory>] [options] [-- <CARGO_ARGS>]

Options:
    -h --help               Print this message.
    --dir                   Specify a directory to check (default is all paths that have documentation generated by cargo).
    --cargo-dir             Specify which directory to look in for the Cargo manifest (default is the current directory).
    --check-http            Check 'http' and 'https' scheme links.
    --forbid-http           Give an error if HTTP links are found. This is incompatible with --check-http.
    --check-intra-doc-links Check for broken intra-doc links.
    --ignore-fragments      Don't check URL fragments.
    --no-build              Do not call `cargo doc` before running link checking. By default, deadlinks will call `cargo doc` if `--dir` is not passed.
    --debug                 Use debug output. This option is deprecated; use `RUST_LOG=debug` instead.
    -v --verbose            Use verbose output. This option is deprecated; use `RUST_LOG=info` instead.
    -V --version            Print version info and exit.

CARGO_ARGS will be passed verbatim to `cargo doc` (as long as `--no-build` is not passed).
";

#[derive(Debug, Deserialize)]
struct MainArgs {
    arg_directory: Option<String>,
    arg_cargo_directory: Option<OsString>,
    flag_verbose: bool,
    flag_debug: bool,
    flag_check_http: bool,
    flag_forbid_http: bool,
    flag_check_intra_doc_links: bool,
    flag_no_build: bool,
    flag_ignore_fragments: bool,
    cargo_args: Vec<OsString>,
}

impl From<&MainArgs> for CheckContext {
    fn from(args: &MainArgs) -> CheckContext {
        let check_http = if args.flag_check_http {
            HttpCheck::Enabled
        } else if args.flag_forbid_http {
            HttpCheck::Forbidden
        } else {
            HttpCheck::Ignored
        };
        CheckContext {
            check_http,
            verbose: args.flag_debug,
            check_fragments: !args.flag_ignore_fragments,
            check_intra_doc_links: args.flag_check_intra_doc_links,
        }
    }
}

fn parse_args() -> Result<MainArgs, shared::PicoError> {
    use pico_args::*;

    let mut args: Vec<_> = std::env::args_os().collect();
    args.remove(0);
    if args.get(0).map_or(true, |arg| arg != "deadlinks") {
        return Err(Error::ArgumentParsingFailed {
            cause: "cargo-deadlinks should be run as `cargo deadlinks`".into(),
        }
        .into());
    }
    args.remove(0);

    let cargo_args = if let Some(dash_dash) = args.iter().position(|arg| arg == "--") {
        let c = args.drain(dash_dash + 1..).collect();
        args.pop();
        c
    } else {
        Vec::new()
    };

    let mut args = Arguments::from_vec(args);
    if args.contains(["-V", "--version"]) {
        println!(concat!("cargo-deadlinks ", env!("CARGO_PKG_VERSION")));
        std::process::exit(0);
    } else if args.contains(["-h", "--help"]) {
        println!("{}", MAIN_USAGE);
        std::process::exit(0);
    }
    let main_args = MainArgs {
        arg_directory: args.opt_value_from_str("--dir")?,
        arg_cargo_directory: args
            .opt_value_from_os_str("--cargo-dir", |s| Result::<_, Error>::Ok(s.to_owned()))?,
        flag_verbose: args.contains(["-v", "--verbose"]),
        flag_debug: args.contains("--debug"),
        flag_no_build: args.contains("--no-build"),
        flag_ignore_fragments: args.contains("--ignore-fragments"),
        flag_check_intra_doc_links: args.contains("--check-intra-doc-links"),
        flag_check_http: args.contains("--check-http"),
        flag_forbid_http: args.contains("--forbid-http"),
        cargo_args,
    };
    args.finish()?;
    if main_args.flag_forbid_http && main_args.flag_check_http {
        Err(pico_args::Error::ArgumentParsingFailed {
            cause: "--check-http and --forbid-http are mutually incompatible".into(),
        }
        .into())
    } else {
        Ok(main_args)
    }
}

fn main() {
    let args: MainArgs = match parse_args() {
        Ok(args) => args,
        Err(err) => {
            eprintln!("error: {}", err);
            std::process::exit(1)
        }
    };

    shared::init_logger(args.flag_debug, args.flag_verbose, "cargo_deadlinks");

    let dirs = args.arg_directory.as_ref().map_or_else(
        || {
            let dir = args.arg_cargo_directory.as_deref();
            determine_dir(args.flag_no_build, &args.cargo_args, dir)
        },
        |dir| vec![dir.into()],
    );

    let ctx = CheckContext::from(&args);
    let mut errors = false;
    for dir in &dirs {
        let dir = match dir.canonicalize() {
            Ok(dir) => dir,
            Err(_) => {
                eprintln!("error: could not find directory {:?}.", dir);
                if args.arg_directory.is_none() {
                    assert!(
                        args.flag_no_build,
                        "cargo said it built a directory it didn't build"
                    );
                    eprintln!(
                        "help: consider removing `--no-build`, or running `cargo doc` yourself."
                    );
                }
                process::exit(1);
            }
        };
        log::info!("checking directory {:?}", dir);
        if walk_dir(&dir, &ctx) {
            errors = true;
        }
    }
    if errors {
        process::exit(1);
    } else if dirs.is_empty() {
        assert!(args.arg_directory.is_none());
        eprintln!("warning: no directories were detected");
    }
}

/// Returns the directories to use as root of the documentation.
///
/// If an directory has been provided as CLI argument that one is used.
/// Otherwise, if `no_build` is passed, we try to find the `Cargo.toml` and
/// construct the documentation path from the package name found there.
/// Otherwise, build the documentation and have cargo itself tell us where it is.
///
/// All *.html files under the root directory will be checked.
fn determine_dir(
    no_build: bool,
    cargo_args: &[OsString],
    cargo_dir: Option<&OsStr>,
) -> Vec<cargo_metadata::camino::Utf8PathBuf> {
    if no_build {
        eprintln!("warning: --no-build ignores `doc = false` and may have other bugs");
        let manifest = MetadataCommand::new()
            .no_deps()
            .exec()
            .unwrap_or_else(|err| {
                println!("error: {}", err);
                println!("help: if this is not a cargo directory, use `--dir`");
                process::exit(1);
            });
        let doc = manifest.target_directory.join("doc");

        // originally written with this impressively bad jq query:
        // `.packages[] |select(.source == null) | .targets[] | select(.kind[] | contains("test") | not) | .name`
        let iter = manifest
            .packages
            .into_iter()
            .filter(|package| package.source.is_none())
            .map(|package| package.targets)
            .flatten()
            .filter(has_docs)
            .map(move |target| doc.join(target.name.replace('-', "_")));
        return iter.collect();
    }

    // Build the documentation, collecting info about the build at the same time.
    log::info!("building documentation using cargo");
    let cargo = env::var("CARGO").unwrap_or_else(|_| {
        println!("error: `cargo-deadlinks` must be run as either `cargo deadlinks` or with the `--dir` flag");
        process::exit(1);
    });
    // Stolen from https://docs.rs/cargo_metadata/0.12.0/cargo_metadata/#examples
    let mut cargo_process = Command::new(cargo);
    cargo_process
        .args(&[
            "doc",
            "--no-deps",
            "--message-format",
            "json-render-diagnostics",
        ])
        .args(cargo_args)
        .stdout(process::Stdio::piped());
    if let Some(dir) = cargo_dir {
        cargo_process.current_dir(dir);
    }
    // spawn instead of output() allows running deadlinks and cargo in parallel;
    // this is helpful when you have many dependencies that take a while to document
    let mut cargo_process = cargo_process.spawn().unwrap();
    let reader = BufReader::new(cargo_process.stdout.take().unwrap());
    // Originally written with jq:
    // `select(.reason == "compiler-artifact") | .filenames[] | select(endswith("/index.html")) | rtrimstr("/index.html")`
    let directories = Message::parse_stream(reader)
        .filter_map(|message| match message {
            Ok(Message::CompilerArtifact(artifact)) => Some(artifact.filenames),
            _ => None,
        })
        .flatten()
        .filter(|path| path.file_name() == Some("index.html"))
        .map(|mut path| {
            path.pop();
            path
        })
        // TODO: run this in parallel, which should speed up builds a fair bit.
        // This will be hard because either cargo's progress bar will overlap with our output,
        // or we'll have to recreate the progress bar somehow.
        // See https://discord.com/channels/273534239310479360/335502067432947748/778636447154044948 for discussion.
        .collect();
    let status = cargo_process.wait().unwrap();
    if !status.success() {
        eprintln!("help: if this is not a cargo directory, use `--dir`");
        process::exit(status.code().unwrap_or(2));
    }
    directories
}

fn has_docs(target: &cargo_metadata::Target) -> bool {
    // Ignore tests, examples, and benchmarks, but still document binaries

    // See https://doc.rust-lang.org/cargo/reference/external-tools.html#compiler-messages
    // and https://github.com/rust-lang/docs.rs/issues/503#issuecomment-562797599
    // for the difference between `kind` and `crate_type`

    let mut kinds = target.kind.iter();
    // By default, ignore binaries
    if target.crate_types.contains(&"bin".into()) {
        // But allow them if this is a literal bin, and not a test or example
        kinds.all(|kind| kind == "bin")
    } else {
        // We also have to consider examples and tests that are libraries
        // (e.g. because of `cdylib`).
        kinds.all(|kind| !["example", "test", "bench"].contains(&kind.as_str()))
    }
}

#[cfg(test)]
mod test {
    use super::has_docs;
    use cargo_metadata::Target;

    fn target(crate_types: &str, kind: &str) -> Target {
        serde_json::from_str(&format!(
            r#"{{
            "crate_types": ["{}"],
            "kind": ["{}"],
            "name": "simple",
            "src_path": "",
            "edition": "2018",
            "doctest": false,
            "test": false
        }}"#,
            crate_types, kind
        ))
        .unwrap()
    }

    #[test]
    fn finds_right_docs() {
        assert!(!has_docs(&target("cdylib", "example")));
        assert!(!has_docs(&target("bin", "example")));
        assert!(!has_docs(&target("bin", "test")));
        assert!(!has_docs(&target("bin", "bench")));
        assert!(!has_docs(&target("bin", "custom-build")));

        assert!(has_docs(&target("bin", "bin")));
        assert!(has_docs(&target("dylib", "dylib")));
        assert!(has_docs(&target("rlib", "rlib")));
        assert!(has_docs(&target("lib", "lib")));
        assert!(has_docs(&target("proc-macro", "proc-macro")));
    }
}