tix/views/

divergence.rs

//! The active-view marker and its informational divergence report (WP03;
//! mission `saved-issue-views-01M3C926`).
//!
//! Two values, both **read-only and derived**:
//!
//! - [`ActiveViewMarker`] records *which* saved definition the live board was
//!   last associated with: the stable [`ViewId`] (never the name — C-002), the
//!   normalized [`ViewPlan`] that was applied, an optional display timestamp, and
//!   the surface it came from. The marker is **metadata**: it grants nothing,
//!   proves nothing, and is never consulted by the registry's scope resolution.
//!   `source` is provenance for display, not authorization (data-model §4).
//! - [`ViewDivergence`] compares the live normalized plan with the saved
//!   definition's plan, field by field, and returns the differences in a fixed
//!   order plus an `in_sync` summary.
//!
//! # Informational, never mutating (C-006)
//!
//! Comparing two [`ViewPlan`]s cannot write: both are borrowed, and the result
//! owns copies only. Nothing here reconciles live state to the saved plan or the
//! saved plan to live state — a divergent board is *reported*, and the caller
//! decides what to do. That is the whole point of the distinction decision
//! `01M3C93PMG4WAWERRJ8YVPSQ0J` draws between "last applied" and "now saved": the
//! definition can change under a live board, and the difference between them is
//! exactly what a user needs to see.
//!
//! # Normalized comparison, not display formatting
//!
//! [`ViewPlan`] normalization happens at construction, so two plans that *mean*
//! the same thing compare equal field by field even if their TOML spellings
//! differ. The comparison walks the typed accessors, never the serialized table,
//! which is why an unknown extension key does not register as divergence
//! (unknown metadata is neither live state nor a supported setting).
//!
//! # A missing marker or a deleted view (data-model §5)
//!
//! "No active view" and "the active view no longer exists" are explicit
//! diagnostics, not silently `in_sync = true`. A caller learns the comparison had
//! nothing to compare, which is different from learning the board matches.

use crate::views::plan::ViewPlan;
use crate::views::registry::{ViewDiagnostic, ViewDiagnosticKind, ViewId};

/// The surface a marker was set from (data-model §4).
///
/// Provenance for display only. The value is never compared against anything to
/// decide what a user may do — it is not an identity, an account, or a
/// permission (C-003/C-009).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ViewSurface {
    /// The command-line surface.
    Cli,
    /// The terminal UI.
    Tui,
    /// The MCP tool surface.
    Mcp,
}

impl ViewSurface {
    /// The stable display name of this surface.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Cli => "cli",
            Self::Tui => "tui",
            Self::Mcp => "mcp",
        }
    }
}

impl std::fmt::Display for ViewSurface {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

/// The selected saved view associated with live board state (data-model §4).
///
/// The marker identifies a definition; it does not own the live filter state and
/// cannot overwrite it. Reapplying the same view produces an equal marker, which
/// is what makes "mark active" idempotent.
#[derive(Debug, Clone, PartialEq)]
pub struct ActiveViewMarker {
    view_id: ViewId,
    applied_plan: ViewPlan,
    applied_at: Option<String>,
    source: Option<ViewSurface>,
}

impl ActiveViewMarker {
    /// A marker for a view, carrying the normalized plan that was applied.
    #[must_use]
    pub fn new(view_id: ViewId, applied_plan: ViewPlan, source: Option<ViewSurface>) -> Self {
        Self {
            view_id,
            applied_plan,
            applied_at: None,
            source,
        }
    }

    /// Attach an audit/display timestamp. Caller-supplied so the marker stays
    /// deterministic and the service needs no clock.
    #[must_use]
    pub fn with_applied_at(mut self, applied_at: impl Into<String>) -> Self {
        self.applied_at = Some(applied_at.into());
        self
    }

    /// The stable id of the selected definition.
    #[must_use]
    pub fn view_id(&self) -> &ViewId {
        &self.view_id
    }

    /// The normalized plan that was applied when the marker was set.
    #[must_use]
    pub fn applied_plan(&self) -> &ViewPlan {
        &self.applied_plan
    }

    /// The optional timestamp, for display.
    #[must_use]
    pub fn applied_at(&self) -> Option<&str> {
        self.applied_at.as_deref()
    }

    /// The surface the marker came from, when it is known.
    #[must_use]
    pub const fn source(&self) -> Option<ViewSurface> {
        self.source
    }

    /// Compare live state against the **saved definition's** plan, keeping this
    /// marker's identity on the report.
    #[must_use]
    pub fn divergence(&self, saved: &ViewPlan, live: &ViewPlan) -> ViewDivergence {
        ViewDivergence::for_marker(self, saved, live)
    }
}

/// One divergent field: its record-relative path, and the saved/live values.
///
/// `saved` and `live` are the normalized spellings of the field. `None` means the
/// field is unset, which is why an absent visibility snapshot (inherit the live
/// board) is distinct from a present-but-empty one (show every column).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ViewDifference {
    field: String,
    saved: Option<String>,
    live: Option<String>,
}

impl ViewDifference {
    fn new(field: impl Into<String>, saved: Option<String>, live: Option<String>) -> Self {
        Self {
            field: field.into(),
            saved,
            live,
        }
    }

    /// The record-relative field path (`plan.sort`, `plan.visibility.hidden_columns`).
    #[must_use]
    pub fn field(&self) -> &str {
        &self.field
    }

    /// The saved definition's normalized value, or `None` when unset.
    #[must_use]
    pub fn saved(&self) -> Option<&str> {
        self.saved.as_deref()
    }

    /// The live normalized value, or `None` when unset.
    #[must_use]
    pub fn live(&self) -> Option<&str> {
        self.live.as_deref()
    }
}

/// The read-only comparison of live state to a saved plan (data-model §5).
///
/// `differences` is ordered by the field walk in [`fields`], so two runs over the
/// same inputs report the same list in the same order. `in_sync` is a convenience
/// summary: it is true exactly when there are no differences **and** no
/// diagnostics.
#[derive(Debug, Clone, PartialEq)]
pub struct ViewDivergence {
    view_id: Option<ViewId>,
    saved_plan: Option<ViewPlan>,
    live_plan: ViewPlan,
    differences: Vec<ViewDifference>,
    diagnostics: Vec<ViewDiagnostic>,
}

impl ViewDivergence {
    /// Compare two plans directly, with no marker identity.
    #[must_use]
    pub fn between(saved: &ViewPlan, live: &ViewPlan) -> Self {
        Self {
            view_id: None,
            saved_plan: Some(saved.clone()),
            live_plan: live.clone(),
            differences: differences(saved, live),
            diagnostics: Vec::new(),
        }
    }

    /// Compare live state to a saved plan, keeping the marker's identity.
    #[must_use]
    pub fn for_marker(marker: &ActiveViewMarker, saved: &ViewPlan, live: &ViewPlan) -> Self {
        let mut divergence = Self::between(saved, live);
        divergence.view_id = Some(marker.view_id.clone());
        divergence
    }

    /// No active view is selected: an explicit diagnostic, never a silent match.
    #[must_use]
    pub fn missing_marker(live: &ViewPlan) -> Self {
        Self {
            view_id: None,
            saved_plan: None,
            live_plan: live.clone(),
            differences: Vec::new(),
            diagnostics: vec![
                ViewDiagnostic::new(
                    ViewDiagnosticKind::UnknownView,
                    "no active saved view is selected, so there is nothing to compare",
                )
                .with_field("active")
                .with_remedy("select a view with `tix view use <id>` before checking divergence"),
            ],
        }
    }

    /// The marker's view is no longer in the registry (it was deleted).
    #[must_use]
    pub fn deleted(view_id: &ViewId, live: &ViewPlan) -> Self {
        Self {
            view_id: Some(view_id.clone()),
            saved_plan: None,
            live_plan: live.clone(),
            differences: Vec::new(),
            diagnostics: vec![
                ViewDiagnostic::for_view(
                    ViewDiagnosticKind::UnknownView,
                    view_id,
                    format!(
                        "the active view `{view_id}` no longer exists; its definition was deleted"
                    ),
                )
                .with_field("active")
                .with_remedy("select another view, or clear the active marker"),
            ],
        }
    }

    /// The saved definition's plan could not be interpreted, so no comparison was
    /// possible. The refusal's own diagnostics are carried through verbatim.
    #[must_use]
    pub fn unreadable(view_id: &ViewId, live: &ViewPlan, diagnostics: Vec<ViewDiagnostic>) -> Self {
        Self {
            view_id: Some(view_id.clone()),
            saved_plan: None,
            live_plan: live.clone(),
            differences: Vec::new(),
            diagnostics,
        }
    }

    /// The saved view the comparison is about, when a marker identified one.
    #[must_use]
    pub fn view_id(&self) -> Option<&ViewId> {
        self.view_id.as_ref()
    }

    /// The saved definition's normalized plan, when it could be read.
    #[must_use]
    pub fn saved_plan(&self) -> Option<&ViewPlan> {
        self.saved_plan.as_ref()
    }

    /// The live normalized plan that was compared.
    #[must_use]
    pub fn live_plan(&self) -> &ViewPlan {
        &self.live_plan
    }

    /// The divergent fields, in a fixed field order.
    #[must_use]
    pub fn differences(&self) -> &[ViewDifference] {
        &self.differences
    }

    /// Problems that prevented or qualified the comparison.
    #[must_use]
    pub fn diagnostics(&self) -> &[ViewDiagnostic] {
        &self.diagnostics
    }

    /// Whether the live plan matches the saved plan, with no diagnostics.
    ///
    /// False for a missing marker or a deleted view: "nothing to compare" is not
    /// "in sync".
    #[must_use]
    pub fn in_sync(&self) -> bool {
        self.diagnostics.is_empty() && self.differences.is_empty()
    }
}

/// The ordered field walk. Each entry reads one normalized field from both plans
/// and records a difference when they disagree. The order here *is* the order of
/// [`ViewDivergence::differences`], so it never depends on map iteration.
fn differences(saved: &ViewPlan, live: &ViewPlan) -> Vec<ViewDifference> {
    let mut out = Vec::new();

    let saved_filter = saved.filter();
    let live_filter = live.filter();

    let mut compare = |field: &str, saved: Option<String>, live: Option<String>| {
        if saved != live {
            out.push(ViewDifference::new(field, saved, live));
        }
    };

    compare(
        "plan.filter.assignee",
        saved_filter.assignee.clone(),
        live_filter.assignee.clone(),
    );
    compare(
        "plan.filter.label",
        saved_filter.label.clone(),
        live_filter.label.clone(),
    );
    compare(
        "plan.filter.status",
        saved_filter.status.clone(),
        live_filter.status.clone(),
    );
    compare(
        "plan.filter.priority",
        saved_filter.priority.clone(),
        live_filter.priority.clone(),
    );
    compare(
        "plan.filter.cycle",
        saved_filter.cycle.clone(),
        live_filter.cycle.clone(),
    );
    compare(
        "plan.filter.milestone",
        saved_filter.milestone.clone(),
        live_filter.milestone.clone(),
    );
    compare(
        "plan.filter.reviewer",
        saved_filter.reviewer.clone(),
        live_filter.reviewer.clone(),
    );
    compare(
        "plan.filter.start_date",
        saved_filter.start_date.clone(),
        live_filter.start_date.clone(),
    );
    compare(
        "plan.filter.due_date",
        saved_filter.due_date.clone(),
        live_filter.due_date.clone(),
    );
    compare(
        "plan.filter.overdue",
        saved_filter.overdue.map(|value| value.to_string()),
        live_filter.overdue.map(|value| value.to_string()),
    );
    compare(
        "plan.filter.parent",
        saved_filter.parent.clone(),
        live_filter.parent.clone(),
    );
    compare(
        "plan.filter.category",
        saved_filter.category.clone(),
        live_filter.category.clone(),
    );
    compare(
        "plan.filter.scope",
        saved_filter.scope.as_ref().map(|scope| scope.join(",")),
        live_filter.scope.as_ref().map(|scope| scope.join(",")),
    );
    compare(
        "plan.text_query",
        saved.text_query().map(str::to_string),
        live.text_query().map(str::to_string),
    );
    compare(
        "plan.sort",
        saved.sort().map(str::to_string),
        live.sort().map(str::to_string),
    );
    compare(
        "plan.group",
        saved.group().map(str::to_string),
        live.group().map(str::to_string),
    );
    compare(
        "plan.visibility.hidden_columns",
        saved
            .visibility()
            .map(|visibility| visibility.hidden_columns().join(",")),
        live.visibility()
            .map(|visibility| visibility.hidden_columns().join(",")),
    );
    compare(
        "plan.visibility.show_mismatch",
        saved
            .visibility()
            .and_then(crate::views::plan::ViewVisibility::show_mismatch)
            .map(|value| value.to_string()),
        live.visibility()
            .and_then(crate::views::plan::ViewVisibility::show_mismatch)
            .map(|value| value.to_string()),
    );

    out
}

#[cfg(test)]
mod tests {
    #[allow(clippy::wildcard_imports)]
    use super::*;
    use crate::search::StructuredFilter;
    use crate::views::plan::ViewVisibility;
    use crate::views::registry::ViewId;

    fn id(raw: &str) -> ViewId {
        ViewId::new(raw).unwrap()
    }

    #[test]
    fn identical_plans_are_in_sync_with_no_differences() {
        let plan = ViewPlan::from_query("label:urgent sort:due");
        let divergence = ViewDivergence::between(&plan, &plan.clone());
        assert!(divergence.in_sync());
        assert_eq!(divergence.differences(), []);
        assert_eq!(divergence.diagnostics(), []);
    }

    #[test]
    fn differences_are_reported_in_a_fixed_field_order() {
        let saved = ViewPlan::from_parts(
            StructuredFilter {
                label: Some("a".into()),
                ..StructuredFilter::default()
            },
            "sort:due",
        )
        .with_visibility(ViewVisibility::new(vec!["mismatch".into()], Some(true)));
        let live = ViewPlan::from_parts(
            StructuredFilter {
                category: Some("active".into()),
                ..StructuredFilter::default()
            },
            "label:b",
        )
        .with_group("cycle");

        let divergence = ViewDivergence::between(&saved, &live);
        let fields: Vec<&str> = divergence
            .differences()
            .iter()
            .map(ViewDifference::field)
            .collect();
        assert_eq!(
            fields,
            vec![
                "plan.filter.label",
                "plan.filter.category",
                "plan.text_query",
                "plan.sort",
                "plan.group",
                "plan.visibility.hidden_columns",
                "plan.visibility.show_mismatch",
            ]
        );
        assert!(!divergence.in_sync());
    }

    #[test]
    fn an_absent_visibility_snapshot_differs_from_an_empty_one() {
        let saved = ViewPlan::from_query("label:a");
        let live = saved
            .clone()
            .with_visibility(ViewVisibility::new(vec![], None));
        let divergence = ViewDivergence::between(&saved, &live);
        let difference = divergence
            .differences()
            .iter()
            .find(|difference| difference.field() == "plan.visibility.hidden_columns")
            .expect("an empty snapshot still differs from inheriting the live board");
        assert_eq!(difference.saved(), None);
        assert_eq!(difference.live(), Some(""));
    }

    #[test]
    fn a_marker_keeps_the_view_identity_on_the_report() {
        let plan = ViewPlan::from_query("label:a");
        let marker = ActiveViewMarker::new(id("v-one"), plan.clone(), Some(ViewSurface::Cli));
        let divergence = marker.divergence(&plan, &ViewPlan::from_query("label:b"));
        assert_eq!(divergence.view_id(), Some(&id("v-one")));
        assert_eq!(divergence.live_plan().text_query(), Some("label:b"));
        assert_eq!(
            divergence
                .saved_plan()
                .and_then(ViewPlan::text_query)
                .map(str::to_string)
                .as_deref(),
            Some("label:a")
        );
    }

    #[test]
    fn a_missing_marker_is_an_explicit_diagnostic_not_a_silent_match() {
        let divergence = ViewDivergence::missing_marker(&ViewPlan::default());
        assert!(!divergence.in_sync());
        assert_eq!(divergence.differences(), []);
        assert_eq!(divergence.diagnostics().len(), 1);
        assert_eq!(
            divergence.diagnostics()[0].kind(),
            ViewDiagnosticKind::UnknownView
        );
    }

    #[test]
    fn a_deleted_view_is_an_explicit_diagnostic() {
        let divergence = ViewDivergence::deleted(&id("v-gone"), &ViewPlan::default());
        assert!(!divergence.in_sync());
        assert_eq!(divergence.diagnostics().len(), 1);
        assert!(
            divergence.diagnostics()[0].message().contains("v-gone"),
            "the diagnostic names the deleted view"
        );
    }
}