ephemeris_report/

report.rs

use std::fs;
use std::path::Path;

use facet::Facet;

use crate::{Details, Outcome, ReportError, SkipReason};

const FILE: &str = "report.json";

/// A file stored next to the report.
#[derive(Clone, Debug, Eq, Facet, PartialEq)]
pub struct Attachment {
    /// The attachment name.
    pub name: String,
    /// The path relative to the report directory.
    pub path: String,
}

impl Attachment {
    /// The name of the attachment that holds the captured command output.
    pub const OUTPUT: &str = "output";
}

/// The result of one check run.
#[derive(Clone, Debug, Eq, Facet, PartialEq)]
pub struct Report {
    /// The check name.
    pub check: String,
    /// How the check ended.
    pub outcome: Outcome,
    /// Why the check did not run.
    #[facet(default, skip_serializing_if = Option::is_none)]
    pub skipped: Option<SkipReason>,
    /// The exit status of the command, when it ran.
    #[facet(default, skip_serializing_if = Option::is_none)]
    pub status: Option<i32>,
    /// The structured result, when a converter produced one.
    #[facet(default, skip_serializing_if = Option::is_none)]
    pub details: Option<Details>,
    /// Files stored next to the report.
    #[facet(default)]
    pub attachments: Vec<Attachment>,
}

impl Report {
    /// A report with an outcome and an exit status and nothing else.
    #[must_use]
    pub fn plain(check: &str, outcome: Outcome, status: Option<i32>) -> Self {
        Self {
            check: check.to_owned(),
            outcome,
            skipped: None,
            status,
            details: None,
            attachments: Vec::new(),
        }
    }

    /// A report for a check that did not run.
    #[must_use]
    pub fn skipped(check: &str, reason: SkipReason) -> Self {
        Self {
            skipped: Some(reason),
            ..Self::plain(check, Outcome::Skip, None)
        }
    }

    /// Whether the check did not fail. A skipped check passes.
    #[must_use]
    pub fn passed(&self) -> bool {
        self.outcome != Outcome::Fail
    }

    /// Store `contents` as `file` in `directory` and list it as an attachment.
    ///
    /// The directory is created when it is missing.
    ///
    /// # Errors
    ///
    /// Returns an error when the directory or the file cannot be written.
    pub fn attach(
        &mut self,
        directory: &Path,
        name: &str,
        file: &str,
        contents: &[u8],
    ) -> Result<(), ReportError> {
        fs::create_dir_all(directory).map_err(|source| ReportError::io(directory, source))?;
        let path = directory.join(file);
        fs::write(&path, contents).map_err(|source| ReportError::io(path, source))?;
        self.attachments.push(Attachment {
            name: name.to_owned(),
            path: file.to_owned(),
        });
        Ok(())
    }

    /// Write `report.json` into `directory` and create the directory first.
    ///
    /// # Errors
    ///
    /// Returns an error when the directory or the file cannot be written.
    pub fn write(&self, directory: &Path) -> Result<(), ReportError> {
        fs::create_dir_all(directory).map_err(|source| ReportError::io(directory, source))?;
        let path = directory.join(FILE);
        let mut text =
            facet_json::to_string_pretty(self).map_err(|source| ReportError::Encode {
                source: Box::new(source),
            })?;
        text.push('\n');
        fs::write(&path, text).map_err(|source| ReportError::io(path, source))
    }

    /// Read `report.json` from `directory`.
    ///
    /// # Errors
    ///
    /// Returns an error when the file is missing or is not a valid report.
    pub fn read(directory: &Path) -> Result<Self, ReportError> {
        let path = directory.join(FILE);
        let text = fs::read_to_string(&path).map_err(|source| ReportError::io(&path, source))?;
        facet_json::from_str(&text).map_err(|source| ReportError::Decode {
            path,
            source: Box::new(source),
        })
    }
}

#[cfg(test)]
mod tests {
    use std::fs;

    use super::Report;
    use crate::{Outcome, ReportError};

    #[test]
    fn a_tests_report_round_trips_through_its_json() {
        let json = r#"{
  "check": "nextest",
  "outcome": "pass",
  "details": {
    "kind": "tests",
    "summary": {
      "passed": 1,
      "failed": 1,
      "skipped": 0
    },
    "items": [
      {
        "name": "a::b",
        "outcome": "pass"
      },
      {
        "name": "a::c",
        "outcome": "fail",
        "message": "boom"
      }
    ]
  },
  "attachments": [
    {
      "name": "junit.xml",
      "path": "junit.xml"
    }
  ]
}"#;
        let report: Report = facet_json::from_str(json).expect("decodes");
        let directory = tempfile::tempdir().expect("directory");
        report.write(directory.path()).expect("writes");
        assert_eq!(Report::read(directory.path()).expect("reads"), report);
        let written = fs::read_to_string(directory.path().join("report.json")).expect("file");
        assert_eq!(written, format!("{json}\n"));
    }

    #[test]
    fn a_plain_report_round_trips_without_optional_fields() {
        let report = Report::plain("lint", Outcome::Fail, Some(42));
        let directory = tempfile::tempdir().expect("directory");
        let nested = directory.path().join("reports").join("lint");
        report.write(&nested).expect("writes");
        let written = fs::read_to_string(nested.join("report.json")).expect("file");
        assert_eq!(
            written,
            "{\n  \"check\": \"lint\",\n  \"outcome\": \"fail\",\n  \"status\": 42,\n  \
             \"attachments\": []\n}\n"
        );
        assert_eq!(Report::read(&nested).expect("reads"), report);
    }

    #[test]
    fn reading_a_missing_directory_is_an_io_error() {
        let directory = tempfile::tempdir().expect("directory");
        let error = Report::read(&directory.path().join("missing")).unwrap_err();
        assert!(
            matches!(error, ReportError::Io { path: _, source: _ }),
            "{error:?}"
        );
    }
}