docgen/

main.rs

//! Command-line renderer for generator-owned workspace documentation.

#[global_allocator]
static GLOBAL: mimalloc::MiMalloc = mimalloc::MiMalloc;

use std::process::ExitCode;

use clap::{Args as ClapArgs, Parser, Subcommand};
use rayon::prelude::*;
use wowlab_common::{cli, output};
use wowlab_docgen_cli::{
    RenderCtx, WorkspaceFile, WorkspaceIndex,
    context::collectors::tidy_rules,
    hosted_rustdoc,
    infra::{cache::Cache, dep_graph, metadata, prettier, template, walk},
};
use wowlab_fs::{
    artifact::{GeneratedTextFile, Status},
    checksum::{self, TreeSnapshot},
    file,
    path::{Path, PathBuf},
};

#[derive(Parser)]
#[command(
    name = "docgen",
    about = "Generate markdown docs from .md.in templates"
)]
struct Args {
    /// Only process templates matching these path fragments.
    #[arg(long, short = 'F')]
    filter: Vec<Box<str>>,

    /// Preview what would change without writing files.
    #[arg(long)]
    dry_run: bool,

    /// Check that all generated docs are up-to-date (exits non-zero if any would change).
    #[arg(long)]
    check: bool,

    /// Suppress output except for errors.
    #[arg(long, short)]
    quiet: bool,

    #[command(subcommand)]
    command: Option<Command>,
}

#[derive(Subcommand)]
enum Command {
    /// Generate the hosted Rustdoc homepage and workspace catalogs.
    Rustdoc(RustdocArgs),
}

#[derive(ClapArgs)]
struct RustdocArgs {
    /// Directory produced by `cargo doc`.
    #[arg(long)]
    docs: PathBuf,

    /// JSON export of Sentinel's runtime MCP tool inventory.
    #[arg(long)]
    mcp_catalog: PathBuf,

    /// Git revision represented by the generated documentation.
    #[arg(long)]
    revision: Option<Box<str>>,
}

#[derive(Debug, thiserror::Error)]
enum ProcessError {
    #[error("{0}")]
    Template(String),
    #[error("{0}")]
    Formatter(String),
    #[error(transparent)]
    Artifact(#[from] wowlab_fs::artifact::Error),
}

#[derive(Debug, thiserror::Error)]
#[error("workspace discovery failed: {0}")]
struct WorkspaceLoadError(Box<str>);

#[derive(Debug, thiserror::Error)]
#[error("{}: failed to read: {source}", path.display())]
struct WorkspaceFileLoadError {
    path: PathBuf,
    #[source]
    source: wowlab_fs::error::Error,
}

struct WorkspaceDiscovery {
    paths: Vec<PathBuf>,
    snapshot: Option<TreeSnapshot>,
}

struct ProcessedTemplate<'a> {
    path: &'a Path,
    diagnostics: Vec<metadata::Diagnostic>,
    result: Result<bool, ProcessError>,
}

fn main() -> ExitCode {
    let mut args = Args::parse();

    if args.check {
        args.dry_run = true;
        args.quiet = true;
    }

    let app = cli::boot(
        "docgen",
        env!("CARGO_PKG_VERSION"),
        args.quiet,
        "DOCGEN_ROOT",
    );

    if let Some(Command::Rustdoc(rustdoc)) = args.command {
        return generate_hosted_rustdoc(&app.root, rustdoc, app.quiet);
    }

    let discovery = match discover_workspace(&app.root) {
        Ok(discovery) => discovery,
        Err(error) => {
            output::error(&error.to_string());

            return ExitCode::FAILURE;
        }
    };
    let discovered_templates = template_paths(&app.root, &discovery.paths, &args.filter);

    if discovered_templates.is_empty() {
        if !app.quiet {
            output::warning("no .md.in templates found");
        }

        return ExitCode::SUCCESS;
    }

    let formatter = match prettier::Formatter::load(&app.root, &discovery.paths) {
        Ok(formatter) => formatter,
        Err(error) => {
            output::error(&error.to_string());

            return ExitCode::FAILURE;
        }
    };
    let cache = Cache::load(
        &app.root,
        checksum::current_executable().ok(),
        formatter.identity(),
    );

    if cache.is_current(discovery.snapshot.as_ref(), &args.filter, args.check) {
        return ExitCode::SUCCESS;
    }

    let workspace = match load_workspace_paths(&app.root, &discovery.paths) {
        Ok(workspace) => workspace,
        Err(error) => {
            output::error(&error.to_string());

            return ExitCode::FAILURE;
        }
    };
    let templates = workspace.templates(&args.filter);

    if !app.quiet {
        output::detail(&format!("found {} template(s)", templates.len()));
        output::blank();
    }

    let results: Vec<_> = templates
        .par_iter()
        .map(|tpl_path| {
            let diagnostics = if args.check {
                let dir = tpl_path.parent().expect("template must have parent");
                let rel_dir = dir
                    .strip_prefix(&app.root)
                    .map(|p| p.to_string_lossy().to_string())
                    .unwrap_or_default();
                let meta = metadata::load(&workspace, dir);

                metadata::validate(meta, &rel_dir)
            } else {
                Vec::new()
            };
            let result = process_one(tpl_path, &workspace, &formatter, &args, &cache);

            ProcessedTemplate {
                path: tpl_path,
                diagnostics,
                result,
            }
        })
        .collect();

    finish_run(&app.root, &args, app.quiet, &cache, &templates, results)
}

fn generate_hosted_rustdoc(root: &Path, args: RustdocArgs, quiet: bool) -> ExitCode {
    let revision = args
        .revision
        .or_else(|| std::env::var("GITHUB_SHA").ok().map(String::into_boxed_str))
        .unwrap_or_else(|| "main".into());
    let options = hosted_rustdoc::Options {
        docs: args.docs,
        mcp_catalog: args.mcp_catalog,
        revision,
    };

    match hosted_rustdoc::generate(root, &options) {
        Ok(summary) => {
            if !quiet {
                output::success(&format!(
                    "generated {} hosted Rustdoc pages ({} crates, {} tidy rules, {} manifests, {} MCP tools)",
                    summary.pages,
                    summary.packages,
                    summary.tidy_rules,
                    summary.manifests,
                    summary.mcp_tools,
                ));
            }

            ExitCode::SUCCESS
        }
        Err(error) => {
            output::error(&error.to_string());

            ExitCode::FAILURE
        }
    }
}

fn finish_run(
    root: &Path,
    args: &Args,
    quiet: bool,
    cache: &Cache,
    templates: &[PathBuf],
    results: Vec<ProcessedTemplate<'_>>,
) -> ExitCode {
    let mut changed = 0;
    let mut errors = 0;
    let mut meta_issues = 0;
    let mut changed_files: Vec<Box<str>> = Vec::new();

    for processed in results {
        for diagnostic in &processed.diagnostics {
            output::error(diagnostic.message());
        }

        meta_issues += processed.diagnostics.len();

        match processed.result {
            Ok(true) => {
                changed += 1;

                if args.check {
                    let out = walk::output_path(processed.path);
                    let rel = rel_path(&out, root);

                    changed_files.push(rel.into());
                }

                report_processed(processed.path, root, args, quiet, true);
            }
            Ok(false) => report_processed(processed.path, root, args, quiet, false),
            Err(error) => {
                errors += 1;
                output::error(&error.to_string());
            }
        }
    }

    if !quiet {
        output::blank();
        let verb = if args.dry_run {
            "would update"
        } else {
            "updated"
        };
        let unchanged = templates.len() - changed - errors;

        output::detail(&format!(
            "{changed} {verb}, {unchanged} unchanged, {errors} error(s)"
        ));
    }

    let exit = if args.check && meta_issues > 0 {
        output::error(&format!(
            "{meta_issues} metadata issue(s) — add missing name/description fields"
        ));

        ExitCode::FAILURE
    } else if errors > 0 {
        ExitCode::FAILURE
    } else if args.check && changed > 0 {
        changed_files.sort();

        for f in &changed_files {
            output::warning(&format!("out of date: {f}"));
        }

        output::error(&format!(
            "{changed} file(s) out of date — run `cargo docgen` to fix"
        ));

        ExitCode::FAILURE
    } else {
        ExitCode::SUCCESS
    };

    if exit == ExitCode::SUCCESS && (!args.dry_run || changed == 0) {
        let output_paths = templates
            .iter()
            .map(|template| walk::output_path(template))
            .collect::<Vec<_>>();

        if let Some(snapshot) = workspace_snapshot(root) {
            cache.record_success(&snapshot, &args.filter, &output_paths, args.check);
        }
    }

    cache.persist();

    exit
}

fn process_one(
    tpl_path: &Path,
    workspace: &WorkspaceIndex,
    prettier: &prettier::Formatter,
    args: &Args,
    cache: &Cache,
) -> Result<bool, ProcessError> {
    let root = workspace.root();
    let dir = tpl_path.parent().expect("template must have parent");
    let rel_dir = dir
        .strip_prefix(root)
        .map(|p| p.to_string_lossy().to_string())
        .unwrap_or_default();
    let stem = walk::output_stem(tpl_path);
    let meta = metadata::load(workspace, dir);

    let ctx = RenderCtx {
        workspace: workspace.clone(),
        root,
        dir,
        rel_dir: &rel_dir,
        metadata: meta,
        output_stem: &stem,
    };

    let mut document = template::prepare(tpl_path, &ctx).map_err(|error| {
        ProcessError::Template(format!("{}: {error}", rel_path(tpl_path, root)))
    })?;
    let rendered = document.contents;
    let formatted_contents =
        if let Some(cached_contents) = cache.reuse_formatted(&document.output_path, &rendered) {
            cached_contents
        } else {
            let fresh_contents =
                prettier
                    .format(&rendered, &document.output_path)
                    .map_err(|error| {
                        ProcessError::Formatter(format!("{}: {error}", rel_path(tpl_path, root)))
                    })?;

            cache.record_formatted(&document.output_path, &rendered, &fresh_contents);

            fresh_contents
        };

    document.contents = formatted_contents;
    let artifact = GeneratedTextFile::new(&document.output_path, &document.contents);
    let changed = artifact.status()? != Status::Current;

    if changed && !args.dry_run {
        artifact.persist()?;
    }

    Ok(changed)
}

fn report_processed(tpl_path: &Path, root: &Path, args: &Args, quiet: bool, updated: bool) {
    if quiet {
        return;
    }

    let out_path = walk::output_path(tpl_path);
    let out_rel = rel_path(&out_path, root);

    if updated {
        if args.dry_run {
            output::warning(&format!("would update {out_rel}"));
        } else {
            output::success(&format!("updated {out_rel}"));
        }
    } else {
        output::detail(&format!("unchanged {out_rel}"));
    }
}

fn discover_workspace(root: &Path) -> Result<WorkspaceDiscovery, WorkspaceLoadError> {
    let mut failures = Vec::new();
    let (paths, walk_failures) = wowlab_fs::walk::workspace_source_files(root).into_parts();

    failures.extend(
        walk_failures
            .into_iter()
            .map(|error| format!("walk error: {error}")),
    );

    if !failures.is_empty() {
        failures.sort_unstable();
        failures.dedup();

        return Err(WorkspaceLoadError(failures.join("; ").into_boxed_str()));
    }

    let snapshot = TreeSnapshot::capture(root, &paths).ok();

    Ok(WorkspaceDiscovery { paths, snapshot })
}

fn load_workspace_paths(
    root: &Path,
    paths: &[PathBuf],
) -> Result<WorkspaceIndex, WorkspaceLoadError> {
    let mut entries = Vec::new();
    let mut failures = Vec::new();

    for path in paths {
        let file = match load_workspace_file(path.clone(), root) {
            Ok(file) => file,
            Err(error) => {
                failures.push(error.to_string());
                continue;
            }
        };

        entries.push(file);
    }

    if !failures.is_empty() {
        failures.sort_unstable();
        failures.dedup();

        return Err(WorkspaceLoadError(failures.join("; ").into_boxed_str()));
    }

    Ok(WorkspaceIndex::new(root.to_path_buf(), entries)
        .with_dependency_graph(dep_graph::load(root))
        .with_tidy_rules(tidy_rules::load(root)))
}

#[cfg(test)]
fn load_workspace(root: &Path) -> Result<WorkspaceIndex, WorkspaceLoadError> {
    let discovery = discover_workspace(root)?;

    load_workspace_paths(root, &discovery.paths)
}

fn workspace_snapshot(root: &Path) -> Option<TreeSnapshot> {
    discover_workspace(root).ok()?.snapshot
}

fn template_paths(root: &Path, paths: &[PathBuf], filters: &[Box<str>]) -> Vec<PathBuf> {
    paths
        .iter()
        .filter(|path| {
            path.file_name()
                .is_some_and(|name| name.to_string_lossy().ends_with(".md.in"))
        })
        .filter(|path| {
            filters.is_empty()
                || path.strip_prefix(root).is_ok_and(|relative| {
                    let relative = relative.to_string_lossy();

                    filters
                        .iter()
                        .any(|filter| relative.contains(filter.as_ref()))
                })
        })
        .cloned()
        .collect()
}

fn load_workspace_file(
    path: PathBuf,
    root: &Path,
) -> Result<WorkspaceFile, WorkspaceFileLoadError> {
    let bytes = file::read_bytes(&path).map_err(|source| WorkspaceFileLoadError {
        path: path.strip_prefix(root).unwrap_or(&path).to_path_buf(),
        source,
    })?;
    let contents = String::from_utf8(bytes).ok().map(String::into_boxed_str);

    Ok(WorkspaceFile { path, contents })
}

fn rel_path(path: &Path, root: &Path) -> String {
    path.strip_prefix(root)
        .unwrap_or(path)
        .to_string_lossy()
        .to_string()
}

#[cfg(test)]
mod tests {
    use googletest::prelude::*;
    use wowlab_fs::temporary::Directory;

    use super::*;

    #[gtest]
    fn binary_files_remain_indexed_without_text_contents() -> Result<()> {
        let directory = Directory::new().or_fail()?;
        let path = directory.path().join("image.png");

        file::write_bytes(&path, [0xff]).or_fail()?;
        let workspace = load_workspace(directory.path()).or_fail()?;

        verify_true!(workspace.contains(&path))?;

        verify_eq!(workspace.contents(&path), None)
    }

    #[gtest]
    fn workspace_file_read_errors_are_contextual() -> Result<()> {
        let directory = Directory::new().or_fail()?;
        let path = directory.path().join("missing.md.in");

        let error = load_workspace_file(path, directory.path())
            .unwrap_err()
            .to_string();

        verify_that!(
            error.as_str(),
            starts_with("missing.md.in: failed to read:")
        )
    }

    #[gtest]
    fn workspace_load_fails_when_root_cannot_be_walked() -> Result<()> {
        let directory = Directory::new().or_fail()?;
        let missing = directory.path().join("missing");

        let error = load_workspace(&missing).unwrap_err().to_string();

        verify_that!(
            error.as_str(),
            contains_substring("workspace discovery failed")
        )?;

        verify_that!(error.as_str(), contains_substring("walk error"))
    }
}