docattest 0.1.3

Documentation that CI can fail, for Rust projects: the docattest command and its Rust adapter.
Documentation
//! What is read from a project's syntax, with nothing run: its surfaces and what they
//! export, the symbols an attestation names, the tests a file declares, what a change
//! affects, and the setup module's names. Nothing is compiled either, but for the one
//! thing syntax cannot say: what a module exports when a macro writes some of it
//! ([`documented`]).

mod affected;
mod documented;
pub(crate) mod modules;
mod setup;
pub(crate) mod surfaces;
mod symbols;
mod tests;

use crate::project::{Package, Project};
use documented::Documented;
use modules::{Crate, Summary};
use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex};
use surfaces::{Configured, Surface};

/// A project as its syntax shows it, for one docattest invocation.
pub(crate) struct Analysis {
    /// The project's directory.
    pub(crate) root: PathBuf,
    pub(crate) project: Project,
    /// The setup module's path in the project, when the config names one.
    pub(crate) setup: Option<String>,
    surfaces: Vec<Surface>,
    crates: Mutex<HashMap<String, Arc<Summary>>>,
    /// Each library the compiler was asked to list, or why it could not.
    documented: Mutex<HashMap<String, Result<Arc<Documented>, String>>>,
}

impl Analysis {
    /// Reads a project's configured surfaces from its workspace.
    pub(crate) fn new(
        root: PathBuf,
        project: Project,
        setup: Option<String>,
        configured: &[Configured],
    ) -> Self {
        let mut analysis = Analysis {
            root,
            project,
            setup,
            surfaces: Vec::new(),
            crates: Mutex::default(),
            documented: Mutex::default(),
        };
        analysis.surfaces = configured.iter().map(|configured| analysis.resolve(configured)).collect();
        analysis
    }

    /// The absolute path of a project path.
    pub(crate) fn abs(&self, rel: &str) -> PathBuf {
        self.root.join(rel)
    }

    /// A path relative to the project root with `/` separators, or the path itself when
    /// it is outside the project.
    fn rel(&self, path: &Path) -> String {
        match path.strip_prefix(&self.root) {
            Ok(rel) if rel.as_os_str().is_empty() => ".".to_string(),
            Ok(rel) => rel.to_string_lossy().replace('\\', "/"),
            Err(_) => path.to_string_lossy().into_owned(),
        }
    }

    /// A package's library, as far as a session asks about it: read once.
    fn krate(&self, package: &Package) -> Arc<Summary> {
        let mut crates = self.crates.lock().unwrap_or_else(|p| p.into_inner());
        let read = |path: &Path| std::fs::read_to_string(path).ok();
        let loaded = crates
            .entry(package.lib.clone())
            .or_insert_with(|| Arc::new(Summary::of(&Crate::load(&package.lib, &package.root, &read))));
        Arc::clone(loaded)
    }

    /// Which of some names still occur as an identifier in the project's code: the files
    /// given, and the files of the surfaces' modules.
    pub(crate) fn in_code(&self, names: &[String], files: &[String]) -> Vec<String> {
        let mut paths: Vec<PathBuf> = files.iter().map(|file| self.abs(file)).collect();
        paths.extend(self.surfaces.iter().filter_map(|surface| surface.file.clone()));
        let texts: Vec<String> = paths.iter().filter_map(|path| std::fs::read_to_string(path).ok()).collect();
        let held = |name: &String| {
            texts.iter().any(|text| crate::language::text::identifiers(text).contains(&name.as_str()))
        };
        names.iter().filter(|name| held(name)).cloned().collect()
    }
}