wowlab_docgen_cli/infra/

template.rs

// #t(file: rust_alloc_in_loop) template rendering uses format! and push_str in loops by design

use minijinja::{
    Environment,
    value::{Kwargs, Rest},
};
use wowlab_fs::path::{Path, PathBuf};

use crate::{
    RenderCtx, context,
    infra::{badge, dep_graph, index_of, mermaid, toc, tree},
};

const MAX_CONSECUTIVE_BLANKS: u32 = 2;

/// Failure to register, load, or render a documentation template.
#[derive(Debug, thiserror::Error)]
#[error("{kind}")]
pub struct TemplateError {
    #[source]
    kind: TemplateErrorKind,
}

#[derive(Debug, thiserror::Error)]
enum TemplateErrorKind {
    #[error("base template {name}: {source}")]
    BaseTemplate {
        name: &'static str,
        #[source]
        source: minijinja::Error,
    },
    #[error("template parse error: {0}")]
    Parse(#[source] minijinja::Error),
    #[error("template load error: {0}")]
    Load(#[source] minijinja::Error),
    #[error("render error: {0}")]
    Render(#[source] minijinja::Error),
    #[error("{}: not indexed as text", path.display())]
    NotIndexed { path: PathBuf },
}

impl TemplateError {
    const fn new(kind: TemplateErrorKind) -> Self {
        Self { kind }
    }
}

const BASE_TEMPLATES: &[(&str, &str)] = &[
    (
        "claude-crate.md.j2",
        include_str!("../../templates/claude-crate.md.j2"),
    ),
    (
        "claude-directory.md.j2",
        include_str!("../../templates/claude-directory.md.j2"),
    ),
    (
        "claude-package.md.j2",
        include_str!("../../templates/claude-package.md.j2"),
    ),
    (
        "claude-root.md.j2",
        include_str!("../../templates/claude-root.md.j2"),
    ),
    ("crate.md.j2", include_str!("../../templates/crate.md.j2")),
    (
        "directory.md.j2",
        include_str!("../../templates/directory.md.j2"),
    ),
    (
        "package.md.j2",
        include_str!("../../templates/package.md.j2"),
    ),
    ("root.md.j2", include_str!("../../templates/root.md.j2")),
];

fn create_env(
    workspace: crate::WorkspaceIndex,
    dir: &Path,
) -> Result<Environment<'static>, TemplateError> {
    let mut env = Environment::new();

    env.set_auto_escape_callback(|_| minijinja::AutoEscape::None);

    env.add_function("table_head", |headers: Rest<String>| -> String {
        wowlab_common::markdown::Table::new()
            .headers(headers.iter())
            .build_markdown()
    });

    env.add_function("table_row", |cells: Rest<String>| -> String {
        wowlab_common::markdown::render_table_row(&cells)
    });

    for (name, source) in BASE_TEMPLATES {
        env.add_template(name, source).map_err(|source| {
            TemplateError::new(TemplateErrorKind::BaseTemplate { name, source })
        })?;
    }

    let index_workspace = workspace.clone();
    let index_dir = dir.to_path_buf();

    env.add_function(
        "index_of",
        move |file: String, patterns: Rest<String>, kwargs: Kwargs| -> String {
            let show_kind: bool = kwargs.get("kind").ok().flatten().unwrap_or(false);
            let _ = kwargs.assert_all_used();

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

    let dir_buf = dir.to_path_buf();
    let tree_workspace = workspace.clone();

    env.add_function(
        "tree",
        move |paths: Rest<String>, kwargs: Kwargs| -> String {
            let depth: Option<u32> = kwargs.get("depth").ok().flatten();
            let _ = kwargs.assert_all_used();

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

    let badge_workspace = workspace.clone();

    env.add_function("badge", move |names: Rest<String>| -> String {
        badge::build(&badge_workspace, &names)
    });

    let dir_for_mermaid = dir.to_path_buf();
    let mermaid_workspace = workspace.clone();

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

    let graph_workspace = workspace.clone();

    env.add_function("dep_graph", move || -> String {
        dep_graph::build(&graph_workspace)
    });

    let dir_for_include = dir.to_path_buf();
    let include_workspace = workspace;

    env.add_function("include", move |path: String| -> String {
        let target = dir_for_include.join(&path);

        include_workspace
            .contents(&target)
            .unwrap_or_default()
            .to_string()
    });

    Ok(env)
}

/// Render a `.md.in` template with full context.
///
/// # Errors
/// Returns an error if the base or requested template cannot be registered, parsed, loaded, or rendered.
pub fn render(source: &str, ctx: &RenderCtx<'_>) -> Result<String, TemplateError> {
    let mut env = create_env(ctx.workspace.clone(), ctx.dir)?;
    let data = context::build(ctx);

    let effective_source = if has_extends_directive(source) {
        source.to_string()
    } else {
        let base = context::default_base(ctx);

        format!("{{% extends \"{base}\" %}}\n{{% block content %}}\n{source}\n{{% endblock %}}")
    };

    env.add_template("_current", &effective_source)
        .map_err(|source| TemplateError::new(TemplateErrorKind::Parse(source)))?;

    let tmpl = env
        .get_template("_current")
        .map_err(|source| TemplateError::new(TemplateErrorKind::Load(source)))?;

    let rendered = tmpl
        .render(&data)
        .map_err(|source| TemplateError::new(TemplateErrorKind::Render(source)))?;

    let rendered = toc::inject(&rendered);
    let rendered = inject_badges(&rendered, &ctx.workspace);
    let mut result = collapse_blank_lines(&rendered);
    let trimmed = result.trim_end().len();

    result.truncate(trimmed);
    result.push('\n');

    Ok(result)
}

#[derive(Debug)]
pub struct RenderedDocument {
    pub output_path: PathBuf,
    pub contents: String,
}

/// Prepare an unformatted rendered document.
///
/// # Errors
/// Returns an error if the template is not indexed as text or cannot be rendered.
pub fn prepare(
    template_path: &Path,
    ctx: &RenderCtx<'_>,
) -> Result<RenderedDocument, TemplateError> {
    let source = ctx.workspace.contents(template_path).ok_or_else(|| {
        TemplateError::new(TemplateErrorKind::NotIndexed {
            path: template_path.to_path_buf(),
        })
    })?;

    let rendered = render(source, ctx)?;
    let output_path = crate::infra::walk::output_path(template_path);

    Ok(RenderedDocument {
        output_path,
        contents: rendered,
    })
}

fn inject_badges(rendered: &str, workspace: &crate::WorkspaceIndex) -> String {
    if !rendered.contains("<!-- block:badges -->") {
        return rendered.to_string();
    }

    let badges = badge::build(
        workspace,
        &[
            "ci".to_string(),
            "discord".to_string(),
            "license".to_string(),
            "website".to_string(),
        ],
    );

    rendered.replace("<!-- block:badges -->", &badges)
}

fn has_extends_directive(source: &str) -> bool {
    source.lines().any(is_extends_directive)
}

fn is_extends_directive(line: &str) -> bool {
    let Some(body) = line.trim().strip_prefix("{%") else {
        return false;
    };
    let Some(body) = body.strip_suffix("%}") else {
        return false;
    };
    let body = body.strip_prefix('-').unwrap_or(body);
    let body = body.strip_suffix('-').unwrap_or(body);
    let Some(rest) = body.trim_start().strip_prefix("extends") else {
        return false;
    };

    rest.chars().next().is_some_and(char::is_whitespace)
}

fn collapse_blank_lines(s: &str) -> String {
    let mut result = String::with_capacity(s.len());
    let mut blank_count = 0u32;

    for line in s.lines() {
        if line.trim().is_empty() {
            blank_count += 1;

            if blank_count <= MAX_CONSECUTIVE_BLANKS {
                result.push('\n');
            }
        } else {
            blank_count = 0;

            if !result.is_empty() {
                result.push('\n');
            }

            result.push_str(line);
        }
    }

    result
}

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

    use super::*;

    #[gtest]
    fn collapse_blanks() -> Result<()> {
        verify_eq!(collapse_blank_lines("a\n\n\n\n\nb\n\nc"), "a\n\n\nb\n\nc")
    }

    #[gtest]
    fn detects_extends() -> Result<()> {
        verify_true!(has_extends_directive(
            r#"{% extends "bases/crate.md.j2" %}"#
        ))?;
        verify_true!(has_extends_directive(
            "{%\textends\t\"bases/crate.md.j2\"\t%}"
        ))?;
        verify_true!(has_extends_directive(
            r#"{%- extends "bases/crate.md.j2" -%}"#
        ))?;
        verify_false!(has_extends_directive("# Title\nSome text"))?;
        verify_false!(has_extends_directive(
            r#"{% extension = "bases/crate.md.j2" %}"#
        ))?;

        verify_false!(has_extends_directive(
            r#"{% set description = "this extends the docs" %}"#
        ))
    }
}