markupwright 0.1.3

Template-driven workspace documentation generator
Documentation
use minijinja::Error as MiniJinjaError;
use std::{
    collections::BTreeMap,
    path::{Path, PathBuf},
};

use crate::{RenderCtx, context, render::toc};

mod environment;
mod registry;

#[cfg(test)]
use registry::EMBEDDED_TEMPLATES;

#[derive(Debug, thiserror::Error)]
#[error("{kind}")]
pub(crate) struct TemplateError {
    #[source]
    kind: TemplateErrorKind,
}

#[derive(Debug, thiserror::Error)]
enum TemplateErrorKind {
    #[error("base template {name}: {source}")]
    BaseTemplate {
        name: &'static str,
        #[source]
        source: MiniJinjaError,
    },
    #[error("custom template {name}: {source}")]
    CustomTemplate {
        name: Box<str>,
        #[source]
        source: MiniJinjaError,
    },
    #[error("template parse error: {0}")]
    Parse(#[source] MiniJinjaError),
    #[error("template load error: {0}")]
    Load(#[source] MiniJinjaError),
    #[error("render error: {0}")]
    Render(#[source] MiniJinjaError),
    #[error("Markdown format error: {0}")]
    Markdown(#[source] crate::markdown::FormatError),
    #[error("context error: {0}")]
    Context(#[source] crate::domain::Error),
    #[error("{} is not matched by a document rule for domain {domain}", path.display())]
    Selection { path: PathBuf, domain: &'static str },
    #[error("{}: not indexed as text", path.display())]
    NotIndexed { path: PathBuf },
    #[error(
        "{} renders to {}, which is also matched as a document input",
        input.display(),
        output.display()
    )]
    InputOutputOverlap { input: PathBuf, output: PathBuf },
    #[error(
        "{} renders to reserved {kind} path {}; refusing to replace it",
        input.display(),
        output.display()
    )]
    ReservedOutput {
        input: PathBuf,
        output: PathBuf,
        kind: &'static str,
    },
    #[error(
        "{} and {} both render to {}",
        first.display(),
        second.display(),
        output.display()
    )]
    DuplicateOutput {
        first: PathBuf,
        second: PathBuf,
        output: PathBuf,
    },
    #[error("{} renders to non-Markdown path {}", input.display(), output.display())]
    NonMarkdownOutput { input: PathBuf, output: PathBuf },
    #[error("custom template {} is not UTF-8 text", path.display())]
    CustomNotText { path: PathBuf },
    #[error("custom template path {} is not valid UTF-8", path.display())]
    CustomName { path: PathBuf },
}

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

pub(crate) fn render(
    source: &str,
    base: &str,
    ctx: &RenderCtx<'_>,
    formatter: &crate::markdown::Formatter,
) -> Result<String, TemplateError> {
    let mut env = environment::create(ctx.workspace.clone(), ctx.dir)?;
    let data = context::build(ctx)
        .map_err(|source| TemplateError::new(TemplateErrorKind::Context(source)))?;

    let effective_source = if has_extends_directive(source) {
        source.to_string()
    } else {
        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 header = env
        .get_template(ctx.workspace.config().header_template())
        .map_err(|source| TemplateError::new(TemplateErrorKind::Load(source)))?
        .render(&data)
        .map_err(|source| TemplateError::new(TemplateErrorKind::Render(source)))?;
    let body = tmpl
        .render(&data)
        .map_err(|source| TemplateError::new(TemplateErrorKind::Render(source)))?;
    let rendered = if header.trim().is_empty() {
        body
    } else {
        format!("{}\n\n{}", header.trim_end(), body.trim_start())
    };

    let rendered = rendered.replace("\r\n", "\n").replace('\r', "\n");
    let mut result = formatter
        .format(&toc::inject(&rendered))
        .map_err(|source| TemplateError::new(TemplateErrorKind::Markdown(source)))?;
    let trimmed = result.trim_end().len();

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

    Ok(result)
}

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

pub(crate) fn validate_outputs(
    workspace: &crate::WorkspaceIndex,
    template_paths: &[PathBuf],
) -> Result<(), TemplateError> {
    let mut outputs = BTreeMap::<PathBuf, PathBuf>::new();

    for template_path in template_paths {
        let relative = template_path
            .strip_prefix(workspace.root())
            .unwrap_or(template_path);
        let output = validate_output(workspace, relative)?;

        if let Some(first) = outputs.insert(output.clone(), relative.to_path_buf()) {
            return Err(TemplateError::new(TemplateErrorKind::DuplicateOutput {
                first,
                second: relative.to_path_buf(),
                output,
            }));
        }
    }

    Ok(())
}

pub(crate) fn prepare(
    template_path: &Path,
    ctx: &RenderCtx<'_>,
    formatter: &crate::markdown::Formatter,
) -> Result<RenderedDocument, TemplateError> {
    let source = ctx.workspace.contents(template_path).ok_or_else(|| {
        TemplateError::new(TemplateErrorKind::NotIndexed {
            path: template_path.to_path_buf(),
        })
    })?;

    let relative = template_path
        .strip_prefix(ctx.root)
        .unwrap_or(template_path);
    let base = ctx
        .workspace
        .config()
        .document_template(relative, ctx.metadata.domain)
        .ok_or_else(|| {
            TemplateError::new(TemplateErrorKind::Selection {
                path: relative.to_path_buf(),
                domain: ctx.metadata.domain.unwrap_or("directory"),
            })
        })?;

    validate_output(&ctx.workspace, relative)?;

    let rendered = render(source, base, ctx, formatter)?;
    let output_path = ctx.workspace.config().output_path(template_path);

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

fn validate_output(
    workspace: &crate::WorkspaceIndex,
    relative_input: &Path,
) -> Result<PathBuf, TemplateError> {
    let output = workspace.config().output_path(relative_input);
    let absolute_output = workspace.root().join(&output);
    let templates = workspace.config().template_directory();

    let reserved = if output.starts_with(crate::layout::DIRECTORY) {
        Some("Markupwright tool")
    } else if output.starts_with(templates) {
        Some("template")
    } else if workspace.is_manifest(&absolute_output) {
        Some("configured manifest")
    } else if workspace.is_source_input(&absolute_output) {
        Some("configured domain input")
    } else {
        None
    };

    if let Some(kind) = reserved {
        return Err(TemplateError::new(TemplateErrorKind::ReservedOutput {
            input: relative_input.to_path_buf(),
            output,
            kind,
        }));
    }

    let domain = relative_input
        .parent()
        .and_then(|directory| workspace.metadata(&workspace.root().join(directory)))
        .and_then(|metadata| metadata.domain);

    if workspace
        .config()
        .document_template(&output, domain)
        .is_some()
    {
        return Err(TemplateError::new(TemplateErrorKind::InputOutputOverlap {
            input: relative_input.to_path_buf(),
            output,
        }));
    }

    if output.extension().and_then(|extension| extension.to_str()) != Some("md") {
        return Err(TemplateError::new(TemplateErrorKind::NonMarkdownOutput {
            input: relative_input.to_path_buf(),
            output,
        }));
    }

    Ok(output)
}

fn has_extends_directive(source: &str) -> bool {
    source
        .lines()
        .find(|line| !line.trim().is_empty())
        .is_some_and(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)
}

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

    use super::*;

    #[gtest]
    fn embedded_template_catalog_is_unique_and_nonempty() -> Result<()> {
        let names = EMBEDDED_TEMPLATES
            .iter()
            .map(|template| template.name)
            .collect::<std::collections::BTreeSet<_>>();

        verify_eq!(names.len(), EMBEDDED_TEMPLATES.len())?;
        verify_true!(
            EMBEDDED_TEMPLATES
                .iter()
                .all(|template| !template.name.is_empty() && !template.source.is_empty())
        )
    }

    #[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" %}"#
        ))?;
        verify_false!(has_extends_directive(
            "# Example\n\n```jinja\n{% extends \"example.md.j2\" %}\n```"
        ))
    }
}