markupwright 0.1.3

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

use serde::{Deserialize, Serialize};

use crate::domain::{ContextEntry, Metadata, MetadataContext};

#[derive(Debug)]
pub(crate) struct Domain;

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub(crate) struct Config {
    manifests: crate::config::Patterns,
    #[serde(default, rename = "source-documentation")]
    source_documentation: bool,
}

#[derive(Debug, Serialize)]
struct TemplateContext<'a> {
    requires_python: &'a Option<String>,
}

#[derive(Debug)]
struct Package {
    requires_python: Option<String>,
}

impl crate::domain::registry::Domain for Domain {
    type Config = Config;
    type State = ();

    const NAME: &'static str = "python";

    fn manifests(
        config: &Self::Config,
        _state: &Self::State,
        root: &Path,
        files: &crate::domain::IndexedFiles,
    ) -> Result<Vec<PathBuf>, crate::domain::Error> {
        Ok(crate::config::matching_files(
            root,
            files,
            &config.manifests,
        ))
    }

    fn metadata(
        _config: &Self::Config,
        _state: &Self::State,
        context: &MetadataContext<'_>,
    ) -> Result<Option<Metadata>, crate::domain::Error> {
        let manifest: Manifest = toml::from_str(context.manifest_source).map_err(|error| {
            crate::domain::Error::parse(context.manifest_path, "pyproject.toml", error)
        })?;
        let Some(project) = manifest.project else {
            return Ok(None);
        };

        let mut metadata = Metadata {
            name: project.name,
            description: project.description,
            version: project.version,
            kind: "python",
            ..Metadata::default()
        };

        metadata.insert_data(
            Self::NAME,
            Package {
                requires_python: project.requires_python,
            },
        );

        Ok(Some(metadata))
    }

    fn context(
        _config: &Self::Config,
        _state: &Self::State,
        context: &crate::RenderCtx<'_>,
    ) -> Result<Vec<ContextEntry>, crate::domain::Error> {
        let Some(package) = context.metadata.data::<Package>(Self::NAME) else {
            return Ok(Vec::new());
        };
        let value = TemplateContext {
            requires_python: &package.requires_python,
        };

        Ok(vec![("python".into(), crate::domain::to_value(&value))])
    }

    fn source_description(
        config: &Self::Config,
        _state: &Self::State,
        path: &Path,
        source: &str,
    ) -> Option<String> {
        config.source_documentation.then_some(())?;
        (path.extension()?.to_str()? == "py").then_some(())?;
        extract_docstring(source)
    }

    fn namespaces(_config: &Self::Config) -> Vec<Box<str>> {
        vec![Self::NAME.into()]
    }
}

fn extract_docstring(source: &str) -> Option<String> {
    let mut lines = source.lines().take(10);

    while let Some(line) = lines.next() {
        let line = line.trim();

        if line.is_empty() || line.starts_with('#') {
            continue;
        }

        for fence in ["\"\"\"", "'''"] {
            if let Some(body) = line.strip_prefix(fence) {
                if let Some(description) = docstring_line(body, fence) {
                    return Some(description);
                }

                for line in lines.by_ref() {
                    let line = line.trim();

                    if line.starts_with(fence) {
                        return None;
                    }

                    if let Some(description) = docstring_line(line, fence) {
                        return Some(description);
                    }
                }

                return None;
            }
        }

        return None;
    }

    None
}

fn docstring_line(body: &str, fence: &str) -> Option<String> {
    if body.starts_with(fence) {
        return None;
    }

    let body = body.strip_suffix(fence).unwrap_or(body).trim();

    (!body.is_empty()).then(|| body.lines().next().unwrap_or(body).to_string())
}

#[derive(Deserialize)]
struct Manifest {
    project: Option<Project>,
}

#[derive(Deserialize)]
struct Project {
    name: Option<String>,
    description: Option<String>,
    version: Option<String>,
    #[serde(rename = "requires-python")]
    requires_python: Option<String>,
}

crate::domain::registry::register_domain!(Domain);

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

    use super::*;
    use crate::{WorkspaceFile, WorkspaceIndex};

    #[gtest]
    fn parses_configured_pyproject_metadata() -> Result<()> {
        let root = Path::new("/ws");
        let workspace = WorkspaceIndex::new_domain(
            root.to_path_buf(),
            vec![WorkspaceFile {
                path: root.join("pyproject.toml"),
                contents: Some(
                    "[project]\nname = \"worker\"\ndescription = \"A worker\"\nversion = \"1.0.0\"\nrequires-python = \">=3.13\"\n"
                        .into(),
                ),
            }],
            "python",
            toml::Value::Table(toml::toml! { manifests = ["pyproject.toml"] }),
        );
        let metadata = workspace.metadata(root).or_fail()?;

        verify_eq!(metadata.kind, "python")?;
        verify_eq!(metadata.name.as_deref(), Some("worker"))
    }

    #[gtest]
    fn extracts_docstring_with_description_on_the_next_line() -> Result<()> {
        verify_eq!(
            extract_docstring("\"\"\"\nBackground task worker.\n\"\"\"\n"),
            Some("Background task worker.".to_string())
        )
    }

    #[gtest]
    fn a_tool_only_pyproject_is_still_owned_by_python() -> Result<()> {
        let root = Path::new("/ws");
        let workspace = WorkspaceIndex::new_domain(
            root.to_path_buf(),
            vec![WorkspaceFile {
                path: root.join("pyproject.toml"),
                contents: Some("[tool.ruff]\nline-length = 100\n".into()),
            }],
            "python",
            toml::Value::Table(toml::toml! { manifests = ["pyproject.toml"] }),
        );
        let metadata = workspace.metadata(root).or_fail()?;

        verify_eq!(metadata.domain, Some("python"))
    }
}