markupwright 0.1.3

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

use serde::{Deserialize, Serialize};

use crate::fs::checksum::{self, Checksum};

const SCHEMA: u32 = 1;
const SELECTION_DOMAIN: &[u8] = b"markupwright:selection:v1\0";

#[derive(Debug, Default, Deserialize, Serialize)]
struct State {
    schema: u32,
    runs: BTreeMap<Box<str>, Run>,
}

#[derive(Debug, Deserialize, Serialize)]
struct Run {
    workspace: Checksum,
    executable: Checksum,
    outputs: BTreeMap<Box<str>, Checksum>,
}

#[derive(Debug)]
pub(crate) struct Cache {
    root: PathBuf,
    path: PathBuf,
    executable: OnceLock<Option<Checksum>>,
    enabled: bool,
    state: State,
}

impl Cache {
    #[must_use]
    pub(crate) fn load(root: &Path) -> Self {
        let path = root.join(crate::layout::CACHE_STATE);
        let enabled = crate::fs::tool_layout::ensure_safe(root).is_ok();
        let mut state = if enabled {
            crate::fs::read_to_string(&path)
                .ok()
                .and_then(|contents| serde_json::from_str::<State>(&contents).ok())
                .filter(|state| state.schema == SCHEMA)
                .unwrap_or_else(empty_state)
        } else {
            empty_state()
        };

        state.runs.retain(|_, run| run.valid());

        Self {
            root: root.to_path_buf(),
            path,
            executable: OnceLock::new(),
            enabled,
            state,
        }
    }

    #[must_use]
    pub(crate) fn is_current(&self, workspace: Option<Checksum>, filters: &[Box<str>]) -> bool {
        if !self.enabled {
            return false;
        }

        let Some(workspace) = workspace else {
            return false;
        };
        let key = selection_key(filters);
        let Some(run) = self.state.runs.get(key.as_str()) else {
            return false;
        };

        if run.workspace != workspace {
            return false;
        }

        let Some(executable) = self.executable() else {
            return false;
        };

        run.executable == executable
            && run.outputs.iter().all(|(relative, expected)| {
                let path = self.root.join(relative.as_ref());

                crate::fs::is_regular_file(&path)
                    && checksum::file(&path).is_ok_and(|actual| actual == *expected)
            })
    }

    pub(crate) fn record(
        &mut self,
        workspace: Checksum,
        filters: &[Box<str>],
        outputs: &[(PathBuf, checksum::FileChecksum)],
    ) {
        if !self.enabled {
            return;
        }

        let Some(executable) = self.executable() else {
            return;
        };
        let Some(outputs) = expected_output_checksums(&self.root, outputs) else {
            return;
        };

        self.state.runs.insert(
            selection_key(filters).into_boxed_str(),
            Run {
                workspace,
                executable,
                outputs,
            },
        );
    }

    pub(crate) fn persist(&self) {
        if !self.enabled || crate::fs::tool_layout::ensure_safe(&self.root).is_err() {
            return;
        }

        let Ok(contents) = serde_json::to_vec(&self.state) else {
            return;
        };
        let Some(parent) = self.path.parent() else {
            return;
        };

        if crate::fs::create_dir_all(parent).is_ok() {
            let _result = crate::fs::atomic::replace(&self.path, contents);
        }
    }

    fn executable(&self) -> Option<Checksum> {
        *self.executable.get_or_init(|| checksum::executable().ok())
    }
}

fn empty_state() -> State {
    State {
        schema: SCHEMA,
        ..State::default()
    }
}

impl Run {
    fn valid(&self) -> bool {
        !self.outputs.is_empty()
            && self
                .outputs
                .keys()
                .all(|path| crate::config::value::validate_path(path).is_ok())
    }
}

fn expected_output_checksums(
    root: &Path,
    outputs: &[(PathBuf, checksum::FileChecksum)],
) -> Option<BTreeMap<Box<str>, Checksum>> {
    if outputs.is_empty() {
        return None;
    }

    outputs
        .iter()
        .map(|(path, expected)| {
            let relative = path.strip_prefix(root).ok()?.to_str()?;
            let relative = relative.replace('\\', "/");

            crate::config::value::validate_path(&relative).ok()?;

            if !crate::fs::is_regular_file(path)
                || checksum::file(path).ok()? != expected.checksum()
            {
                return None;
            }

            Some((relative.into_boxed_str(), expected.checksum()))
        })
        .collect()
}

fn selection_key(filters: &[Box<str>]) -> String {
    let mut filters = filters.iter().map(AsRef::as_ref).collect::<Vec<&str>>();

    filters.sort_unstable();
    filters.dedup();
    let mut material = Vec::from(SELECTION_DOMAIN);

    for filter in filters {
        material.extend_from_slice(&filter.len().to_le_bytes());
        material.extend_from_slice(filter.as_bytes());
    }

    checksum::bytes(material).to_string()
}

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

    use super::*;

    #[gtest]
    fn hit_requires_workspace_tool_selection_and_untampered_outputs() -> Result<()> {
        let directory = tempfile::tempdir().or_fail()?;
        let output = directory.path().join("README.md");
        let workspace = checksum::bytes("workspace");
        let mut cache = Cache::load(directory.path());

        std::fs::write(&output, "generated").or_fail()?;
        cache.record(
            workspace,
            &[],
            &[(output.clone(), checksum::contents("generated"))],
        );

        verify_true!(cache.is_current(Some(workspace), &[]))?;
        verify_false!(cache.is_current(Some(checksum::bytes("changed")), &[]))?;
        verify_false!(cache.is_current(Some(workspace), &["filter".into()]))?;

        std::fs::write(&output, "tampered").or_fail()?;

        verify_false!(cache.is_current(Some(workspace), &[]))
    }

    #[gtest]
    fn invalid_or_empty_cached_output_paths_are_rejected() -> Result<()> {
        let checksum = checksum::bytes("value");
        let empty = Run {
            workspace: checksum,
            executable: checksum,
            outputs: BTreeMap::new(),
        };
        let traversal = Run {
            workspace: checksum,
            executable: checksum,
            outputs: BTreeMap::from([("../../outside".into(), checksum)]),
        };

        verify_false!(empty.valid())?;
        verify_false!(traversal.valid())
    }

    #[gtest]
    fn missing_cache_entry_does_not_hash_the_executable() -> Result<()> {
        let directory = tempfile::tempdir().or_fail()?;
        let cache = Cache::load(directory.path());

        verify_eq!(cache.executable.get(), None)?;
        verify_false!(cache.is_current(Some(checksum::bytes("workspace")), &[]))?;
        verify_eq!(cache.executable.get(), None)
    }
}