markupwright 0.1.3

Template-driven workspace documentation generator
Documentation
use std::{collections::BTreeMap, path::Path};

use minijinja::{
    Environment, Error as MiniJinjaError, ErrorKind,
    value::{Kwargs, Rest},
};

use super::{TemplateError, TemplateErrorKind, registry::EMBEDDED_TEMPLATES};
use crate::{
    render::{index_of, mermaid, tree},
    workspace::normalize,
};

pub(super) fn create(
    workspace: crate::WorkspaceIndex,
    directory: &Path,
) -> Result<Environment<'static>, TemplateError> {
    let mut environment = Environment::new();
    let extension_root = workspace
        .root()
        .join(workspace.config().template_directory());
    let extensions = load_extensions(&workspace, &extension_root)?;

    environment.set_auto_escape_callback(|_| minijinja::AutoEscape::None);
    environment.set_keep_trailing_newline(true);
    environment.set_lstrip_blocks(true);
    environment.set_trim_blocks(false);

    register_markdown_helpers(&mut environment);
    register_templates(&mut environment, extensions)?;
    register_workspace_helpers(&mut environment, workspace, directory);

    Ok(environment)
}

fn load_extensions(
    workspace: &crate::WorkspaceIndex,
    extension_root: &Path,
) -> Result<BTreeMap<String, String>, TemplateError> {
    let mut extensions = BTreeMap::new();

    for (path, source) in workspace.files_below(extension_root) {
        if !path
            .file_name()
            .is_some_and(|name| name.to_string_lossy().ends_with(".j2"))
        {
            continue;
        }

        let name = path
            .strip_prefix(extension_root)
            .ok()
            .and_then(Path::to_str)
            .ok_or_else(|| {
                TemplateError::new(TemplateErrorKind::CustomName {
                    path: path.to_path_buf(),
                })
            })?;
        let source = source.ok_or_else(|| {
            TemplateError::new(TemplateErrorKind::CustomNotText {
                path: path.to_path_buf(),
            })
        })?;

        extensions.insert(name.replace('\\', "/"), source.to_string());
    }

    Ok(extensions)
}

fn register_markdown_helpers(environment: &mut Environment<'static>) {
    environment.add_function(
        "table_head",
        |headers: Rest<String>| -> Result<String, MiniJinjaError> {
            if headers.is_empty() {
                return Err(MiniJinjaError::new(
                    ErrorKind::InvalidOperation,
                    "table_head requires at least one column",
                ));
            }

            Ok(crate::markdown::Table::new()
                .headers(headers.iter())
                .build_markdown())
        },
    );

    environment.add_function(
        "table_row",
        |cells: Rest<String>| -> Result<String, MiniJinjaError> {
            if cells.is_empty() {
                return Err(MiniJinjaError::new(
                    ErrorKind::InvalidOperation,
                    "table_row requires at least one cell",
                ));
            }

            Ok(crate::markdown::render_table_row(&cells))
        },
    );
}

fn register_templates(
    environment: &mut Environment<'static>,
    extensions: BTreeMap<String, String>,
) -> Result<(), TemplateError> {
    for template in EMBEDDED_TEMPLATES {
        if extensions.contains_key(template.name) {
            continue;
        }

        environment
            .add_template(template.name, template.source)
            .map_err(|source| {
                TemplateError::new(TemplateErrorKind::BaseTemplate {
                    name: template.name,
                    source,
                })
            })?;
    }

    for (name, source) in extensions {
        environment
            .add_template_owned(name.clone(), source)
            .map_err(|source| {
                TemplateError::new(TemplateErrorKind::CustomTemplate {
                    name: name.into_boxed_str(),
                    source,
                })
            })?;
    }

    Ok(())
}

fn register_workspace_helpers(
    environment: &mut Environment<'static>,
    workspace: crate::WorkspaceIndex,
    directory: &Path,
) {
    let index_workspace = workspace.clone();
    let index_directory = directory.to_path_buf();

    environment.add_function(
        "index_of",
        move |file: String,
              patterns: Rest<String>,
              kwargs: Kwargs|
              -> Result<String, MiniJinjaError> {
            let show_kind = kwargs.get::<Option<bool>>("kind")?.unwrap_or(false);

            kwargs.assert_all_used()?;

            Ok(index_of::build(
                &index_workspace,
                &index_directory,
                &file,
                &patterns,
                show_kind,
            ))
        },
    );

    let tree_workspace = workspace.clone();
    let tree_directory = directory.to_path_buf();

    environment.add_function(
        "tree",
        move |paths: Rest<String>, kwargs: Kwargs| -> Result<String, MiniJinjaError> {
            let depth = kwargs.get::<Option<u32>>("depth")?;

            kwargs.assert_all_used()?;

            Ok(tree::build(&tree_workspace, &tree_directory, &paths, depth))
        },
    );

    let mermaid_workspace = workspace.clone();
    let mermaid_directory = directory.to_path_buf();

    environment.add_function("mermaid", move |name: String| -> String {
        mermaid::build(&mermaid_workspace, &mermaid_directory, &name)
    });

    let read_workspace = workspace;
    let read_directory = directory.to_path_buf();

    environment.add_function(
        "read_file",
        move |path: String| -> Result<String, MiniJinjaError> {
            read_file(&read_workspace, &read_directory, &path)
        },
    );
}

fn read_file(
    workspace: &crate::WorkspaceIndex,
    directory: &Path,
    path: &str,
) -> Result<String, MiniJinjaError> {
    let target = normalize(&directory.join(path));

    if !target.starts_with(workspace.root()) {
        return Err(MiniJinjaError::new(
            ErrorKind::InvalidOperation,
            format!("read_file path escapes the repository: {path}"),
        ));
    }

    workspace
        .contents(&target)
        .map(str::to_owned)
        .ok_or_else(|| {
            let reason = if workspace.contains(&target) {
                "is not UTF-8 text"
            } else {
                "does not exist"
            };

            MiniJinjaError::new(
                ErrorKind::InvalidOperation,
                format!("read_file {path}: {reason}"),
            )
        })
}