fallow_output/

health_coverage_gaps.rs

use std::path::{Path, PathBuf};

use fallow_types::output_health::{
    UntestedExportAction, UntestedExportActionType, UntestedFileAction, UntestedFileActionType,
};
use fallow_types::serde_path;

/// Runtime code that no test dependency path reaches.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct UntestedFile {
    /// Absolute file path.
    #[serde(serialize_with = "serde_path::serialize")]
    pub path: PathBuf,
    /// Number of value exports declared by the file.
    pub value_export_count: usize,
}

/// Runtime export that no test-reachable module references.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct UntestedExport {
    /// Absolute file path.
    #[serde(serialize_with = "serde_path::serialize")]
    pub path: PathBuf,
    /// Export name.
    pub export_name: String,
    /// 1-based source line.
    pub line: u32,
    /// 0-based source column.
    pub col: u32,
}

/// Wire-shape envelope for an [`UntestedFile`] finding. Carries the bare
/// [`UntestedFile`] flattened in plus a typed `actions` array. The action
/// vec is computed at construction time using a project-root-relative path
/// so descriptions match `strip_root_prefix`'s post-pass output on the inner
/// `path` field. Schemars derives the merged shape natively; this retires
/// the `augment_finding_definition` graft for `UntestedFile`.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct UntestedFileFinding {
    /// The underlying coverage-gap entry.
    #[serde(flatten)]
    pub file: UntestedFile,
    /// Suggested next steps: an `add-tests` primary and a `suppress-file`
    /// secondary. Always emitted for the current wire contract.
    pub actions: Vec<UntestedFileAction>,
}

impl UntestedFileFinding {
    /// Build the wrapper from a raw [`UntestedFile`] and the project root.
    #[must_use]
    pub fn with_actions(file: UntestedFile, root: &Path) -> Self {
        let display_path = relative_display(&file.path, root);
        let actions = vec![
            UntestedFileAction {
                kind: UntestedFileActionType::AddTests,
                auto_fixable: false,
                description: format!("Add test coverage for `{display_path}`"),
                note: Some("No test dependency path reaches this runtime file".to_string()),
                comment: None,
            },
            UntestedFileAction {
                kind: UntestedFileActionType::SuppressFile,
                auto_fixable: false,
                description: format!("Suppress coverage gap reporting for `{display_path}`"),
                note: None,
                comment: Some("// fallow-ignore-file coverage-gaps".to_string()),
            },
        ];
        Self { file, actions }
    }
}

/// Wire-shape envelope for an [`UntestedExport`] finding. Same pattern as
/// [`UntestedFileFinding`]: flattens the bare finding and carries a typed
/// `actions` array computed at construction time.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct UntestedExportFinding {
    /// The underlying coverage-gap entry.
    #[serde(flatten)]
    pub export: UntestedExport,
    /// Suggested next steps: an `add-test-import` primary and a
    /// `suppress-file` secondary.
    pub actions: Vec<UntestedExportAction>,
}

impl UntestedExportFinding {
    /// Build the wrapper from a raw [`UntestedExport`] and the project root.
    #[must_use]
    pub fn with_actions(export: UntestedExport, root: &Path) -> Self {
        Self::with_reach_actions(export, root, false)
    }

    /// Build the wrapper and say in the primary note when only tests that
    /// mock the module reference the export.
    #[must_use]
    pub fn with_reach_actions(export: UntestedExport, root: &Path, mocked_only: bool) -> Self {
        let display_path = relative_display(&export.path, root);
        let export_name = export.export_name.clone();
        let note = if mocked_only {
            "This export is runtime-reachable, but only tests that mock this module reference it"
        } else {
            "This export is runtime-reachable but no test-reachable module references it"
        };
        let actions = vec![
            UntestedExportAction {
                kind: UntestedExportActionType::AddTestImport,
                auto_fixable: false,
                description: format!("Import and test `{export_name}` from `{display_path}`"),
                note: Some(note.to_string()),
                comment: None,
            },
            UntestedExportAction {
                kind: UntestedExportActionType::SuppressFile,
                auto_fixable: false,
                description: format!("Suppress coverage gap reporting for `{display_path}`"),
                note: None,
                comment: Some("// fallow-ignore-file coverage-gaps".to_string()),
            },
        ];
        Self { export, actions }
    }
}

fn relative_display(path: &Path, root: &Path) -> String {
    path.strip_prefix(root)
        .unwrap_or(path)
        .display()
        .to_string()
}

/// Aggregate coverage-gap counters for the current analysis scope.
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct CoverageGapSummary {
    /// Runtime-reachable files in scope.
    pub runtime_files: usize,
    /// Runtime-reachable files also reachable from tests.
    pub covered_files: usize,
    /// Percentage of runtime files that are test-reachable.
    pub file_coverage_pct: f64,
    /// Runtime files with no test dependency path.
    pub untested_files: usize,
    /// Runtime exports with no test-reachable reference chain.
    pub untested_exports: usize,
}

/// Static test coverage gaps derived from the module graph. Shows runtime files
/// and exports with no test dependency path.
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
pub struct CoverageGaps {
    /// Summary metrics for the current analysis scope.
    pub summary: CoverageGapSummary,
    /// Runtime files with no test dependency path. Each entry carries its
    /// own `actions` array via [`UntestedFileFinding`].
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    #[cfg_attr(feature = "schema", schemars(default))]
    pub files: Vec<UntestedFileFinding>,
    /// Runtime exports with no test-reachable reference chain. Each entry
    /// carries its own `actions` array via [`UntestedExportFinding`].
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    #[cfg_attr(feature = "schema", schemars(default))]
    pub exports: Vec<UntestedExportFinding>,
}

impl CoverageGaps {
    /// True when no untested files or exports were found; callers omit the
    /// section from output in that case.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.files.is_empty() && self.exports.is_empty()
    }
}

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

    #[test]
    fn untested_file_actions_use_relative_display_path() {
        let root = Path::new("/repo");
        let finding = UntestedFileFinding::with_actions(
            UntestedFile {
                path: PathBuf::from("/repo/src/api.ts"),
                value_export_count: 2,
            },
            root,
        );

        assert_eq!(finding.actions.len(), 2);
        assert!(finding.actions[0].description.contains("src/api.ts"));
    }

    #[test]
    fn mocked_only_export_note_names_the_mock() {
        let export = || UntestedExport {
            path: PathBuf::from("/repo/src/queue.ts"),
            export_name: "enqueue".to_string(),
            line: 1,
            col: 0,
        };
        let root = Path::new("/repo");
        let mocked = UntestedExportFinding::with_reach_actions(export(), root, true);
        let plain = UntestedExportFinding::with_actions(export(), root);

        assert_eq!(
            mocked.actions[0].note.as_deref(),
            Some(
                "This export is runtime-reachable, but only tests that mock this module reference it"
            )
        );
        assert_eq!(
            plain.actions[0].note.as_deref(),
            Some("This export is runtime-reachable but no test-reachable module references it")
        );
    }

    #[test]
    fn empty_coverage_gaps_reports_empty() {
        assert!(CoverageGaps::default().is_empty());
    }
}