blob: 6825a5308bc9a1486d61235d2e53ffb534178e32 [file]
// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
//! doc_checker is a CLI tool to check markdown files for correctness in
//! the Fuchsia project.
pub(crate) use crate::checker::{
DocCheck, DocCheckError, DocLine, DocYamlCheck, ErrorLevel, ExemptionSet, ReachabilityGraph,
};
pub(crate) use crate::md_element::DocContext;
pub(crate) use crate::path_ext::DocPathExt;
use crate::path_ext::normalize_path;
use anyhow::{Context, Result, bail};
use argh::FromArgs;
use glob::glob;
use serde_yaml::Value;
use std::fs::{self, File};
use std::io::BufReader;
use std::path::{Path, PathBuf};
mod checker;
mod code_block_checker;
mod include_checker;
mod link_checker;
mod md_element;
mod mermaid_checker;
mod parser;
pub(crate) mod path_ext;
mod yaml;
static EXEMPT_REGEX: std::sync::LazyLock<regex::Regex> = std::sync::LazyLock::new(|| {
regex::Regex::new(r"(?i)<!-+\s*doc[-_]checker\s*:\s*ignore[-_]unused(?:\s*[:\s-][^>]*)?-+>")
.unwrap()
});
// path_helper includes methods to check path attributes
// so that these methods can be mocked for unit tests.
pub mod path_helper_module {
use std::path::Path;
pub fn exists(path: &Path) -> bool {
path.exists()
}
pub fn is_dir(path: &Path) -> bool {
path.is_dir()
}
}
// Used when testing, the existence and is_dir
// is based on the name.
// Originally, This was attempted using mockall::automock.
// However, since the mocked module is global, and tests
// are run multithreaded, keeping the mocking context exclusive
// was hard. A mutex could be used, but mutex and async code
// do not work nicely together.
//
// As a result, a name based mock is used for all the tests.
#[cfg(test)]
pub(crate) mod mock_path_helper_module {
use std::path::Path;
pub fn exists(path: &Path) -> bool {
let path_str = path.to_string_lossy();
// If the path actually exists, return true. This allows for
// staging test data.
path.exists()
// if is_dir returns true, the directory needs to exist as well.
|| (is_dir(path) && !path_str.ends_with("no-extension"))
// markdown files exist with a couple exceptions.
|| (path_str.ends_with(".md")
&& (!path_str.ends_with("no_readme/README.md")
&& !path_str.ends_with("index.md")
&& !path_str.ends_with("unused/README.md")
&& !path_str.ends_with("missing.md")
&& !path_str.contains("/old")
&& !path_str.ends_with("no-extension")))
// OWNERS file exists.
|| path.ends_with("OWNERS")
}
pub fn is_dir(path: &Path) -> bool {
// If the path is actually a directory, return true. This allows for
// staged test data.
path.is_dir()
// Paths with no extension are directories, except OWNERS.
|| (path.extension().is_none() && !path.ends_with("OWNERS"))
}
}
/// Path on the published site where generated reference docs live. These docs are not part of
/// the source tree, so links under this path are treated as published-site links.
pub(crate) const DEFAULT_REFERENCE_FOLDER: &str = "/reference";
/// Check the markdown documentation using a variety of checks.
#[derive(Clone, Debug, FromArgs)]
pub struct DocCheckerArgs {
/// path to the root of the checkout of the project.
#[argh(option, default = r#"PathBuf::from(".")"#)]
pub root: PathBuf,
/// name of project to check, defaults to fuchsia.
#[argh(option, default = r#"String::from("fuchsia")"#)]
pub project: String,
/// (Experimental) Name of the folder inside the project
/// which contains documents to check. Defaults to 'docs'.
#[argh(option, default = r#"PathBuf::from("docs")"#)]
pub docs_folder: PathBuf,
/// resolve http(s) links
#[argh(switch)]
pub check_external_links: bool,
/// output in JSON format
#[argh(switch)]
pub json: bool,
/// allow links to fuchsia-src. Usually links to
/// fuchsia-src should be written as file paths
/// to /docs.
#[argh(switch)]
pub allow_fuchsia_src_links: bool,
/// path to reference docs. Links to the main docs folder.
#[argh(option)]
pub reference_docs_root: Option<PathBuf>,
/// do not check links between docs,
#[argh(switch)]
pub skip_link_check: bool,
/// allow unreferenced hidden files (files starting with _) from being published.
#[argh(switch)]
pub allow_unreferenced_hidden: bool,
/// path on the published site where generated reference docs live.
/// Defaults to '/reference'.
#[argh(option, default = "PathBuf::from(DEFAULT_REFERENCE_FOLDER)")]
pub reference_folder: PathBuf,
}
#[fuchsia::main]
async fn main() -> Result<()> {
let mut opt: DocCheckerArgs = argh::from_env();
// Canonicalize the root directory so the rest of the code can rely on
// the root directory existing and being a normalized path.
opt.root =
opt.root.canonicalize().context(format!("invalid root dir for source: {:?} ", opt.root))?;
if let Some(reference_root) = opt.reference_docs_root {
opt.reference_docs_root =
Some(reference_root.canonicalize().context(format!(
"could not get canonical reference root for {:?}",
reference_root
))?);
}
if let Some(mut errors) = do_main(&opt).await? {
// Output the result
let mut error_count = 0;
let mut warning_count = 0;
let mut info_count = 0;
errors.sort();
if opt.json {
println!("{}", serde_json::to_string(&errors)?);
if errors.iter().any(|e| e.level == ErrorLevel::Error) {
std::process::exit(1);
}
} else {
for e in &errors {
match e.level {
ErrorLevel::Info => info_count += 1,
ErrorLevel::Warning => warning_count += 1,
ErrorLevel::Error => error_count += 1,
}
println!("{}\n", e);
}
// Only bail if there are errors, warnings should return OK.
if error_count > 0 {
bail!(
"Found {} errors, {} warnings, {} info.",
error_count,
warning_count,
info_count
)
} else {
println!(
"Found {} errors, {} warnings, {} info.",
error_count, warning_count, info_count
)
}
}
} else if opt.json {
println!("[]");
} else {
println!("No errors found");
}
Ok(())
}
/// The actual main function. It is refactored like this to make it easier
/// to run it in a unit test.
async fn do_main(opt: &DocCheckerArgs) -> Result<Option<Vec<DocCheckError>>> {
// Checkers compare root-relative paths component-wise, so make the reference folder
// root-relative and normalized once here (e.g. "reference/" becomes "/reference").
let reference_folder = normalize_path(&Path::new("/").join(&opt.reference_folder))
.with_context(|| format!("invalid reference folder: {:?}", opt.reference_folder))?;
if reference_folder == Path::new("/") {
bail!("invalid reference folder {:?}: must not be root '/'", opt.reference_folder);
}
let opt = &DocCheckerArgs { reference_folder, ..opt.clone() };
let root_dir = &opt.root;
let docs_project = &opt.project;
let docs_dir = root_dir.join(&opt.docs_folder);
eprintln!("Checking Project {} {:?}.", docs_project, docs_dir);
// Find all the markdown in the docs folder.
let pattern = format!("{}/**/*.md", docs_dir.to_string_lossy());
let mut markdown_files: Vec<PathBuf> =
glob(&pattern)?.filter_map(|p| p.ok()).filter(|p| !p.is_macos_hidden_doc()).collect();
// Find all the .yaml files.
let yaml_pattern = format!("{}/**/*.yaml", docs_dir.to_string_lossy());
let mut yaml_files: Vec<PathBuf> =
glob(&yaml_pattern)?.filter_map(|p| p.ok()).filter(|p| !p.is_ignored_doc()).collect();
if let Some(reference_root) = &opt.reference_docs_root {
eprintln!("Also checking reference docs in {reference_root:?}.");
let pattern = format!("{}/**/*.md", reference_root.to_string_lossy());
let reference_markdown =
glob(&pattern)?.filter_map(|p| p.ok()).filter(|p| !p.is_macos_hidden_doc());
markdown_files.extend(reference_markdown);
let yaml_pattern = format!("{}/**/*.yaml", reference_root.to_string_lossy());
yaml_files
.extend(glob(&yaml_pattern)?.filter_map(|p| p.ok()).filter(|p| !p.is_ignored_doc()));
}
eprintln!(
"Checking {} markdown files and {} yaml files",
markdown_files.len(),
yaml_files.len()
);
/*
Doc checking is broken into a couple major phases.
1. Checks are registered from the modules that have structs that implement the DocCheck trait.
2. Each markdown file is parsed into a stream of Elements. Each element is passed to each registered checker.
3. After all the markdown files are parsed, the post-check check is called on each checker. This allows
checkers to perform cross-file checks and checks that used data collected from the individual documents.
4. Each yaml file is checked for each yaml checker registered.
5. After all the yaml is checked, the post-check check is called.
6. All the errors are collected and returned.
*/
let mut markdown_checks: Vec<Box<dyn DocCheck>> = vec![];
let mut errors: Vec<DocCheckError> = vec![];
let reachability_graph: ReachabilityGraph = Default::default();
let exemption_set: ExemptionSet = Default::default();
markdown_checks.extend(code_block_checker::register_markdown_checks(opt)?);
markdown_checks
.extend(link_checker::register_markdown_checks(opt, reachability_graph.clone())?);
markdown_checks
.extend(include_checker::register_markdown_checks(opt, reachability_graph.clone())?);
markdown_checks.extend(mermaid_checker::register_markdown_checks(opt)?);
let mut yaml_checks =
yaml::register_yaml_checks(opt, reachability_graph.clone(), exemption_set.clone())?;
let markdown_errors: Vec<DocCheckError> =
check_markdown(&markdown_files, &mut markdown_checks, exemption_set.clone())?;
errors.extend(markdown_errors);
let yaml_errors = check_yaml(&yaml_files, &mut yaml_checks)?;
errors.extend(yaml_errors);
// Post checks
for c in yaml_checks {
match c.post_check(&markdown_files, &yaml_files).await {
Ok(Some(check_errors)) => errors.extend(check_errors),
Ok(None) => {}
Err(e) => errors.push(DocCheckError::new_error(
0,
"".into(),
&format!("Error {} running check: {} ", e, c.name()),
)),
}
}
for c in markdown_checks {
match c.post_check().await {
Ok(Some(check_errors)) => errors.extend(check_errors),
Ok(None) => {}
Err(e) => errors.push(DocCheckError::new_error(
0,
"".into(),
&format!("Error {} running check: {} ", e, c.name()),
)),
}
}
let result = if errors.is_empty() { None } else { Some(errors) };
Ok(result)
}
/// Given the list of markdown files to check, iterate over each check, collecting any errors.
pub fn check_markdown<'a>(
files: &[PathBuf],
checks: &'a mut [Box<dyn DocCheck + 'static>],
exemption_set: ExemptionSet,
) -> Result<Vec<DocCheckError>> {
let mut errors: Vec<DocCheckError> = vec![];
for mdfile in files {
let mdcontent = fs::read_to_string(mdfile).expect("Unable to read file");
if EXEMPT_REGEX.is_match(&mdcontent) {
exemption_set.lock().unwrap().insert(mdfile.clone());
}
let mut callback = |broken_link: pulldown_cmark::BrokenLink<'_>| {
DocContext::handle_broken_link(broken_link, &mdcontent)
};
let doc_context = DocContext::new(mdfile.clone(), &mdcontent, Some(&mut callback));
for element in doc_context {
for c in &mut *checks {
match c.check(&element) {
Ok(Some(check_errors)) => errors.extend(check_errors),
Ok(None) => {}
Err(e) => errors.push(DocCheckError::new_error(
0,
"".into(),
&format!("Error {} running check: {} ", e, c.name()),
)),
}
}
}
}
Ok(errors)
}
fn check_yaml<'a>(
yaml_files: &[PathBuf],
checks: &'a mut [Box<dyn DocYamlCheck + 'static>],
) -> Result<Vec<DocCheckError>> {
let mut errors: Vec<DocCheckError> = vec![];
for yaml_file in yaml_files {
let f = File::open(yaml_file)?;
let val: Value = match serde_yaml::from_reader(BufReader::new(f)) {
Ok(v) => v,
Err(e) => bail!("Error parsing {:?}: {}", yaml_file, e),
};
for c in &mut *checks {
match c.check(yaml_file, &val) {
Ok(Some(check_errors)) => errors.extend(check_errors),
Ok(None) => {}
Err(e) => errors.push(DocCheckError::new_error(
0,
"".into(),
&format!("Error {} running check: {} ", e, c.name()),
)),
}
}
}
Ok(errors)
}
#[cfg(test)]
mod test {
use super::*;
#[fuchsia::test]
async fn test_project_test() -> Result<()> {
let opt = DocCheckerArgs {
root: PathBuf::from("doc_checker_test_data"),
project: "fuchsia".to_string(),
docs_folder: PathBuf::from("docs"),
check_external_links: false,
json: false,
allow_fuchsia_src_links: false,
reference_docs_root: None,
skip_link_check: false,
allow_unreferenced_hidden: false,
reference_folder: PathBuf::from(DEFAULT_REFERENCE_FOLDER),
};
// Bazel host_test runs in doc_checker_bin_test.runtime_dir, where
// host_test_data_map stages doc_checker_test_data/ directly.
let expected: Vec<DocCheckError> = vec![
DocCheckError::new_error(
10,
PathBuf::from("doc_checker_test_data/docs/README.md"),
"in-tree link to /docs/missing.md could not be found at \"doc_checker_test_data/docs/missing.md\"",
),
DocCheckError::new_error(
12,
PathBuf::from("doc_checker_test_data/docs/README.md"),
"Should not link to https://fuchsia.dev/fuchsia-src/path.md via https, use relative filepath",
),
DocCheckError::new_error(
21,
PathBuf::from("doc_checker_test_data/docs/README.md"),
"Obsolete or invalid project garnet: https://fuchsia.googlesource.com/garnet/+/refs/heads/main/README.md",
),
DocCheckError::new_error(
23,
PathBuf::from("doc_checker_test_data/docs/README.md"),
"Cannot normalize /docs/../../README.md, references parent beyond root.",
),
DocCheckError::new_error_helpful(
30,
PathBuf::from("doc_checker_test_data/docs/README.md"),
"in-tree link to /docs/no-extension could not be found at \"doc_checker_test_data/docs/no-extension\"",
"\"no-extension.md\"",
),
DocCheckError::new_error(
6,
PathBuf::from("doc_checker_test_data/docs/_common/_included.md"),
"in-tree link to /docs/missing.md could not be found at \"doc_checker_test_data/docs/missing.md\"",
),
DocCheckError::new_error(
9,
PathBuf::from("doc_checker_test_data/docs/include_here.md"),
"Included markdown file \"doc_checker_test_data/docs/_common/missing.md\" not found.",
),
DocCheckError::new_error(
13,
PathBuf::from("doc_checker_test_data/docs/include_here.md"),
"Included markdown file \"/docs/_common/_included.md\" must be a relative path.",
),
DocCheckError::new_error(
2,
PathBuf::from("doc_checker_test_data/docs/no_readme/details.md"),
"in-tree link to /docs/no_readme could not be found at \"doc_checker_test_data/docs/no_readme\" or \"doc_checker_test_data/docs/no_readme/README.md\"",
),
DocCheckError::new_error(
4,
PathBuf::from("doc_checker_test_data/docs/path.md"),
"in-tree link to /docs/missing-image.png could not be found at \"doc_checker_test_data/docs/missing-image.png\"",
),
// There are 3 instances of [i] on the same line.
DocCheckError::new_error_helpful(
17,
PathBuf::from("doc_checker_test_data/docs/path.md"),
"Unknown reference link to [i][i]",
"making sure you added a matching [i]: YOUR_LINK_HERE below this reference. If this is in a triple tick code block, consider removing empty lines - see https://fxbug.dev/373449734.",
),
DocCheckError::new_error_helpful(
17,
PathBuf::from("doc_checker_test_data/docs/path.md"),
"Unknown reference link to [i][i]",
"making sure you added a matching [i]: YOUR_LINK_HERE below this reference. If this is in a triple tick code block, consider removing empty lines - see https://fxbug.dev/373449734.",
),
DocCheckError::new_error_helpful(
17,
PathBuf::from("doc_checker_test_data/docs/path.md"),
"Unknown reference link to [i][i]",
"making sure you added a matching [i]: YOUR_LINK_HERE below this reference. If this is in a triple tick code block, consider removing empty lines - see https://fxbug.dev/373449734.",
),
DocCheckError::new_error(
6,
PathBuf::from("doc_checker_test_data/docs/second.md"),
"Invalid link http://{}.com/markdown : invalid uri character",
),
DocCheckError::new_error(
10,
PathBuf::from("doc_checker_test_data/docs/second.md"),
"Cannot normalize /docs/../../missing.md, references parent beyond root.",
),
DocCheckError::new_error(
28,
PathBuf::from("doc_checker_test_data/docs/second.md"),
"Invalid Mermaid diagram type 'invalid_type'. Supported types include: graph, flowchart, sequenceDiagram, pie, mindmap, timeline, etc.",
),
DocCheckError::new_error(
1,
PathBuf::from("doc_checker_test_data/docs/unused/_toc.yaml"),
"in-tree link to /docs/unused could not be found at \"doc_checker_test_data/docs/unused\" or \"doc_checker_test_data/docs/unused/README.md\"",
),
DocCheckError::new_error(
0,
PathBuf::from("doc_checker_test_data/docs/_toc.yaml"),
"Cannot find file \"doc_checker_test_data/docs/missing/_toc.yaml\" included in \"doc_checker_test_data/docs/_toc.yaml\"",
),
DocCheckError::new_error(
0,
PathBuf::from("doc_checker_test_data/docs/cycle/_toc.yaml"),
"YAML files cannot include themselves \"doc_checker_test_data/docs/cycle/_toc.yaml\"",
),
DocCheckError::new_error(
0,
PathBuf::from("doc_checker_test_data/docs/unreachable.md"),
"File not referenced in any _toc.yaml files.",
),
DocCheckError::new_error(
0,
PathBuf::from("doc_checker_test_data/docs/unused/_toc.yaml"),
"File not reachable via _toc include references.",
),
DocCheckError::new_error(
0,
PathBuf::from("doc_checker_test_data/docs/_hidden_dir/unreachable.md"),
"Unused hidden file. If this file is only referenced by external repositories, append '<!-- doc-checker: ignore-unused -->' to the file to exempt it.",
),
DocCheckError::new_error(
0,
PathBuf::from("doc_checker_test_data/docs/_unreachable_hidden.md"),
"Unused hidden file. If this file is only referenced by external repositories, append '<!-- doc-checker: ignore-unused -->' to the file to exempt it.",
),
DocCheckError::new_warning(
0,
PathBuf::from("doc_checker_test_data/docs/README.md"),
"Redundant exemption comment. File is reachable locally; remove '<!-- doc-checker: ignore-unused -->' to clean up.",
),
DocCheckError::new_error(
0,
PathBuf::from("doc_checker_test_data/docs/_toc.yaml"),
"Cannot reference hidden file /docs/_hidden_in_toc.md in _toc.yaml. Hidden files are not published by Devsite.",
),
];
if let Some(mut actual_errors) = do_main(&opt).await? {
let mut expected = expected;
actual_errors.sort();
expected.sort();
let mut expected_iter = expected.iter();
for actual in actual_errors {
if let Some(expected) = expected_iter.next() {
assert_eq!(&actual, expected);
} else {
bail!("Unexpected error: {:?}", actual);
}
}
let expected_errors: Vec<&DocCheckError> = expected_iter.collect();
// Should be no other expected errors
if !expected_errors.is_empty() {
bail!("Expected at least one more error. Missing error(s): {:?}", expected_errors);
}
}
Ok(())
}
#[fuchsia::test]
async fn test_do_main_reference_folder() -> Result<()> {
let temp_root = std::env::temp_dir()
.join(format!("doc_checker_main_ref_folder_{}", std::process::id()));
let docs_dir = temp_root.join("docs");
// Distinct from root/api_docs so post_check must resolve via reference_docs_root.
let ref_dir = temp_root.join("generated_ref");
std::fs::create_dir_all(&docs_dir)?;
std::fs::create_dir_all(&ref_dir)?;
std::fs::write(
docs_dir.join("_toc.yaml"),
"toc:\n- path: /docs/README.md\n title: Docs\n- path: /api_docs/generated.md\n title: API\n- include: /api_docs/_toc.yaml\n",
)?;
std::fs::write(
docs_dir.join("README.md"),
"# Docs\n\nSee [API](/api_docs/missing.md#sec).\n",
)?;
std::fs::write(
ref_dir.join("_toc.yaml"),
"toc:\n- path: /api_docs/generated.md\n title: API\n",
)?;
std::fs::write(ref_dir.join("generated.md"), "# Generated\n")?;
let custom_opt = DocCheckerArgs {
root: temp_root.clone(),
project: "fuchsia".to_string(),
docs_folder: PathBuf::from("docs"),
check_external_links: false,
json: false,
allow_fuchsia_src_links: false,
reference_docs_root: Some(ref_dir),
skip_link_check: false,
allow_unreferenced_hidden: false,
// Relative path with trailing slash must normalize to "/api_docs".
reference_folder: PathBuf::from("api_docs/"),
};
let custom_result = do_main(&custom_opt).await;
let default_opt = DocCheckerArgs {
reference_folder: PathBuf::from(DEFAULT_REFERENCE_FOLDER),
..custom_opt.clone()
};
let default_result = do_main(&default_opt).await;
let root_opt =
DocCheckerArgs { reference_folder: PathBuf::from("/"), ..custom_opt.clone() };
let root_err = do_main(&root_opt).await;
let escape_opt =
DocCheckerArgs { reference_folder: PathBuf::from("../outside"), ..custom_opt };
let escape_err = do_main(&escape_opt).await;
std::fs::remove_dir_all(&temp_root)?;
assert_eq!(custom_result?, None);
let default_errors = default_result?.expect("default /reference must reject /api_docs");
assert!(
default_errors.iter().any(|e| {
e.message
.contains("in-tree link to /api_docs/generated.md must be in '/docs' or '/reference' directory")
}),
"expected _toc.yaml error for unconfigured /api_docs, got {default_errors:?}"
);
assert!(
default_errors.iter().any(|e| {
e.message.contains("in-tree link to /api_docs/missing.md#sec could not be found")
}),
"expected markdown link error for unconfigured /api_docs, got {default_errors:?}"
);
assert!(root_err.is_err());
assert!(escape_err.is_err());
Ok(())
}
}