markupwright 0.1.3

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

use minijinja::Value;
use serde::Serialize;

use crate::{RenderCtx, config::Config};

pub(crate) mod cargo;
pub(crate) mod collection;
pub(crate) mod dotenv;
pub(crate) mod frontmatter;
pub(crate) mod github_workflows;
pub(crate) mod go;
pub(crate) mod lua;
mod model;
pub(crate) mod node;
pub(crate) mod php;
pub(crate) mod python;
pub(crate) mod registry;

pub(crate) use model::Metadata;

pub(crate) type IndexedFiles = BTreeMap<PathBuf, Option<Box<str>>>;
pub(crate) type ContextEntry = (Box<str>, Value);

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

#[derive(Debug, thiserror::Error)]
enum ErrorKind {
    #[error("{}: failed to parse {format}: {source}", path.display())]
    Parse {
        path: PathBuf,
        format: &'static str,
        #[source]
        source: Box<dyn std::error::Error + Send + Sync>,
    },
    #[error("{}: {format}: {message}", path.display())]
    Message {
        path: PathBuf,
        format: &'static str,
        message: Box<str>,
    },
}

impl Error {
    fn new(kind: ErrorKind) -> Self {
        Self { kind }
    }

    pub(crate) fn parse<E>(path: impl Into<PathBuf>, format: &'static str, source: E) -> Self
    where
        E: std::error::Error + Send + Sync + 'static,
    {
        Self::new(ErrorKind::Parse {
            path: path.into(),
            format,
            source: Box::new(source),
        })
    }

    pub(crate) fn message(
        path: impl Into<PathBuf>,
        format: &'static str,
        message: impl Into<Box<str>>,
    ) -> Self {
        Self::new(ErrorKind::Message {
            path: path.into(),
            format,
            message: message.into(),
        })
    }
}

pub(crate) struct MetadataContext<'a> {
    pub(crate) directory: &'a Path,
    pub(crate) manifest_path: &'a Path,
    pub(crate) manifest_source: &'a str,
}

pub(crate) struct ProjectContext<'a> {
    pub(crate) runtime: &'a registry::Runtime,
    pub(crate) manifest_path: &'a Path,
    pub(crate) manifest_source: &'a str,
}

pub(crate) fn workspace_source<'a>(
    workspace: &'a crate::WorkspaceIndex,
    path: &Path,
    format: &'static str,
) -> Result<Option<&'a str>, Error> {
    match workspace.contents(path) {
        Some(source) => Ok(Some(source)),

        None if workspace.contains(path) => {
            Err(Error::message(path, format, "file is not UTF-8 text"))
        }

        None => Ok(None),
    }
}

pub(crate) fn resolve(
    root: &Path,
    directory: &Path,
    directories: &BTreeSet<PathBuf>,
    config: &Config,
    projects: &[ProjectContext<'_>],
) -> Result<Metadata, Error> {
    let relative = directory.strip_prefix(root).unwrap_or(directory);
    let configured_primary = config.primary_domain(relative);

    if projects.is_empty() {
        if let Some(domain) = configured_primary {
            return Err(Error::message(
                crate::layout::CONFIG,
                "domain selection",
                format!(
                    "{} selects domain {domain:?} but has no configured manifest",
                    relative.display()
                ),
            ));
        }

        return Ok(apply_config_metadata(
            fallback_metadata(directory, directories),
            root,
            directory,
            config,
        ));
    }

    let primary = match configured_primary {
        Some(domain) => projects
            .iter()
            .position(|project| project.runtime.name() == domain)
            .ok_or_else(|| {
                Error::message(
                    crate::layout::CONFIG,
                    "domain selection",
                    format!(
                        "{} selects domain {domain:?} but that domain has no configured manifest there",
                        relative.display()
                    ),
                )
            })?,

        None if projects.len() == 1 => 0,

        None => {
            let domains = projects
                .iter()
                .map(|project| project.runtime.name())
                .collect::<Vec<_>>()
                .join(", ");

            return Err(Error::message(
                crate::layout::CONFIG,
                "domain selection",
                format!(
                    "{} has multiple project domains ({domains}); configure its primary domain",
                    relative.display()
                ),
            ));
        }
    };
    let mut resolved = Vec::with_capacity(projects.len());

    for project in projects {
        let context = MetadataContext {
            directory,
            manifest_path: project.manifest_path,
            manifest_source: project.manifest_source,
        };

        let mut metadata = project
            .runtime
            .metadata(&context)?
            .unwrap_or_else(|| fallback_metadata(directory, directories));

        metadata.domain = Some(project.runtime.name());
        metadata.manifest_path = Some(project.manifest_path.to_path_buf());
        resolved.push(metadata);
    }

    let mut metadata = resolved.swap_remove(primary);

    for secondary in resolved {
        metadata.merge_data(secondary);
    }

    metadata = apply_config_metadata(metadata, root, directory, config);

    Ok(metadata)
}

pub(crate) fn collect(context: &RenderCtx<'_>) -> Result<Vec<ContextEntry>, Error> {
    let mut entries = Vec::new();

    for runtime in context.workspace.domains() {
        entries.extend(runtime.context(context)?);
    }

    entries.sort_by(|left, right| left.0.cmp(&right.0));

    for pair in entries.windows(2) {
        if pair[0].0 == pair[1].0 {
            return Err(Error::message(
                crate::layout::CONFIG,
                "domain context",
                format!("duplicate context namespace {:?}", pair[0].0),
            ));
        }
    }

    Ok(entries)
}

fn apply_config_metadata(
    mut metadata: Metadata,
    root: &Path,
    directory: &Path,
    config: &Config,
) -> Metadata {
    let relative = directory.strip_prefix(root).unwrap_or(directory);

    if let Some(configured) = config.metadata(relative) {
        if configured.name.is_some() {
            metadata.name.clone_from(&configured.name);
        }

        if configured.description.is_some() {
            metadata.description.clone_from(&configured.description);
        }
    }

    metadata
}

fn fallback_metadata(directory: &Path, directories: &BTreeSet<PathBuf>) -> Metadata {
    Metadata {
        name: directory_name(directory),
        kind: if directories.contains(directory) {
            "directory"
        } else {
            "unknown"
        },
        ..Metadata::default()
    }
}

pub(crate) fn load<'a>(workspace: &'a crate::WorkspaceIndex, directory: &Path) -> &'a Metadata {
    workspace.metadata(directory).unwrap_or_else(|| {
        workspace
            .metadata(workspace.root())
            .expect("workspace root metadata must be indexed")
    })
}

pub(crate) fn to_value(value: &impl Serialize) -> Value {
    Value::from_serialize(value)
}

pub(crate) fn directory_name(directory: &Path) -> Option<String> {
    directory
        .file_name()
        .map(|name| name.to_string_lossy().into_owned())
}

pub(crate) fn file_description(workspace: &crate::WorkspaceIndex, path: &Path) -> Option<String> {
    let source = workspace.contents(path)?;

    workspace
        .domains()
        .find_map(|runtime| runtime.source_description(path, source))
}