tix/views/

service.rs

//! The saved-view service: CRUD, definition-only delete, read-only apply, and
//! the active marker (WP03; mission `saved-issue-views-01M3C926`).
//!
//! This module is the **operation layer** over WP01's registry and WP02's plan.
//! It adds no storage, no query grammar, and no second result formula:
//!
//! - every write goes through [`ViewRegistry::commit`], the one atomic path, so
//!   an accepted mutation is a durable `tix.toml` change and a refused one writes
//!   no config and no History (C-008);
//! - every apply goes through [`ViewPlan::apply_as`], the one
//!   `BoardState::build_filtered` pass, so the result is the existing query
//!   result and the corpus/config are only borrowed (C-005/C-007);
//! - the active marker and its divergence live in [`crate::views::divergence`]
//!   and are informational: selecting a view never rewrites live filters (C-006).
//!
//! # Read-only versus write operations
//!
//! The split is deliberate and visible in the signatures:
//!
//! | operation | returns | writes |
//! |---|---|---|
//! | `list`, `show`, `apply`, `divergence` | `ViewResult<..>` | nothing |
//! | `create`, `update`, `duplicate`, `delete` | `ViewMutation<..>` | one `tix.toml` commit |
//! | `mark_active`, `clear_active` | `ViewResult` / `()` | nothing (in-memory marker) |
//!
//! A read can only be refused (a `ViewRefusal` with diagnostics). A write can also
//! *fail* (the atomic save could not complete) — the registry already models that
//! as [`ViewWriteError`], and the service keeps the distinction rather than
//! flattening it.
//!
//! # Auditable, idempotent mutations (T017/C-008)
//!
//! An accepted mutation returns a [`ViewOutcome`] carrying exactly one
//! [`ViewAuditEvent`] — what changed, for which stable id, under which name. A
//! refused or failed operation returns `Err` and carries **no** event, because
//! nothing happened. A mutation whose candidate equals the current registry (a
//! same-content `update`) is a **no-op**: no commit is issued, and the outcome
//! reports `is_noop()` with no event. Committing the same registry twice writes
//! the same bytes, so "apply the same operation again" converges.
//!
//! There is no separate audit *file*. The existing registry commit is the
//! persistence, and the event is the structured record the operation returns; a
//! surface renders it without this module inventing a second log (research R10,
//! data-model §8).
//!
//! # Definition-only delete (T014/C-005)
//!
//! [`ViewService::delete`] cannot be called without a [`DeleteConfirmed`], a
//! token whose field is private so "I forgot to confirm" is a compile error
//! rather than a defaulted `true`. It removes the definition and nothing else:
//! no issue, comment, relationship, or board data is touched, and the outcome
//! reports whether the active marker named the deleted view so the caller can
//! clear it.

use std::path::Path;

use crate::config::{BoardConfiguration, Config};
use crate::search::Corpus;
use crate::views::divergence::{ActiveViewMarker, ViewDivergence, ViewSurface};
use crate::views::plan::{ViewApplyResult, ViewPlan};
use crate::views::registry::{
    ProjectDirectory, SavedView, ViewDiagnostic, ViewDiagnosticKind, ViewId, ViewRefusal,
    ViewRegistry, ViewResult, ViewScope, ViewWriteResult,
};
use crate::workflow::CategoryResolution;

/// The outcome of a service **write**: an accepted value plus its audit event, or
/// a refusal/failure that wrote nothing.
pub type ViewMutation<T> = ViewWriteResult<ViewOutcome<T>>;

/// What kind of registry mutation an accepted operation performed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ViewMutationKind {
    /// A new definition was added under a freshly allocated stable id.
    Create,
    /// An existing definition's name, scope, or plan was replaced.
    Update,
    /// A new definition was copied from an existing one under a new stable id.
    Duplicate,
    /// A definition was removed. Only the definition.
    Delete,
}

impl ViewMutationKind {
    /// The stable name of this mutation, for output and matching.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Create => "create",
            Self::Update => "update",
            Self::Duplicate => "duplicate",
            Self::Delete => "delete",
        }
    }
}

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

/// The auditable record of one **accepted** registry mutation (T017).
///
/// Emitted once per accepted change, and never for a refusal or a no-op. The view
/// id is the identity; the name is the display label *at the time of the
/// operation*, kept for a readable history even after a later rename.
#[derive(Debug, Clone, PartialEq)]
pub struct ViewAuditEvent {
    kind: ViewMutationKind,
    view_id: ViewId,
    view_name: String,
}

impl ViewAuditEvent {
    fn new(kind: ViewMutationKind, view_id: ViewId, view_name: String) -> Self {
        Self {
            kind,
            view_id,
            view_name,
        }
    }

    /// What kind of mutation this was.
    #[must_use]
    pub const fn kind(&self) -> ViewMutationKind {
        self.kind
    }

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

    /// The display name the definition carried when the mutation was accepted.
    #[must_use]
    pub fn view_name(&self) -> &str {
        &self.view_name
    }
}

/// An accepted operation's value and its audit event.
///
/// `audit` is `None` exactly when the candidate registry equalled the current one
/// — an idempotent no-op that issued no commit.
#[derive(Debug, Clone, PartialEq)]
pub struct ViewOutcome<T> {
    value: T,
    audit: Option<ViewAuditEvent>,
}

impl<T> ViewOutcome<T> {
    fn accepted(value: T, audit: ViewAuditEvent) -> Self {
        Self {
            value,
            audit: Some(audit),
        }
    }

    fn unchanged(value: T) -> Self {
        Self { value, audit: None }
    }

    /// The operation's result value.
    #[must_use]
    pub fn value(&self) -> &T {
        &self.value
    }

    /// Consume the outcome for its value.
    #[must_use]
    pub fn into_value(self) -> T {
        self.value
    }

    /// The one audit event, or `None` for an idempotent no-op.
    #[must_use]
    pub fn audit(&self) -> Option<&ViewAuditEvent> {
        self.audit.as_ref()
    }

    /// Whether the operation changed nothing (no commit, no event).
    #[must_use]
    pub fn is_noop(&self) -> bool {
        self.audit.is_none()
    }
}

/// Explicit confirmation for a definition-only delete (T014).
///
/// The private field is the whole point: the token cannot be built outside this
/// module, so [`ViewService::delete`] is not callable without a deliberate
/// confirmation. There is no `Default` and no `From<bool>`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DeleteConfirmed(());

impl DeleteConfirmed {
    /// Acknowledge that only the view **definition** is being removed — never its
    /// issues, comments, relationships, or board data.
    #[must_use]
    pub const fn confirmed() -> Self {
        Self(())
    }
}

/// A full definition handed to `create`/`update`: the mutable fields of a record.
///
/// The id and the preserved extension fields are **not** here: identity is
/// allocated by the registry and extensions survive an update untouched, so a
/// caller cannot accidentally drop either (NFR-002).
#[derive(Debug, Clone, PartialEq)]
pub struct ViewDefinition {
    name: String,
    scope: ViewScope,
    plan: ViewPlan,
}

impl ViewDefinition {
    /// A named, scoped, normalized plan.
    #[must_use]
    pub fn new(name: impl Into<String>, scope: ViewScope, plan: ViewPlan) -> Self {
        Self {
            name: name.into(),
            scope,
            plan,
        }
    }

    /// The display label.
    #[must_use]
    pub fn name(&self) -> &str {
        &self.name
    }

    /// The explicit scope metadata.
    #[must_use]
    pub fn scope(&self) -> &ViewScope {
        &self.scope
    }

    /// The normalized query/board plan.
    #[must_use]
    pub fn plan(&self) -> &ViewPlan {
        &self.plan
    }
}

/// A definition shown to a caller, with its plan interpreted and any preserved
/// unknown metadata surfaced (T013).
#[derive(Debug, Clone, PartialEq)]
pub struct ViewDetail {
    view: SavedView,
    plan: ViewPlan,
    diagnostics: Vec<ViewDiagnostic>,
}

impl ViewDetail {
    /// The stored record (id, name, scope, raw plan, extensions).
    #[must_use]
    pub fn view(&self) -> &SavedView {
        &self.view
    }

    /// The plan, parsed and normalized.
    #[must_use]
    pub fn plan(&self) -> &ViewPlan {
        &self.plan
    }

    /// Unknown-metadata notices for the record and its plan; never a refusal.
    #[must_use]
    pub fn diagnostics(&self) -> &[ViewDiagnostic] {
        &self.diagnostics
    }
}

/// The value of a successful delete: the removed definition, and whether the
/// active marker named it (T014).
#[derive(Debug, Clone, PartialEq)]
pub struct DeletedView {
    view: SavedView,
    marker_cleared: bool,
}

impl DeletedView {
    /// The definition that was removed. Issues and comments are untouched.
    #[must_use]
    pub fn view(&self) -> &SavedView {
        &self.view
    }

    /// Whether the service's active marker pointed at the deleted view and was
    /// cleared as a result.
    #[must_use]
    pub const fn marker_cleared(&self) -> bool {
        self.marker_cleared
    }
}

/// The saved-view service: the registry, the caller's config, and the project
/// directory the scope checks resolve against.
///
/// The service borrows the caller's [`Config`] mutably because an accepted
/// mutation *is* `config.views` changing; it never reaches around the registry to
/// write anything else. The active marker is in-memory state beside the config —
/// data-model §4's "if explicitly persisted" — so marking a view writes no file.
pub struct ViewService<'a, P: ProjectDirectory + ?Sized> {
    config: &'a mut Config,
    projects: &'a P,
    path: &'a Path,
    active: Option<ActiveViewMarker>,
}

impl<'a, P: ProjectDirectory + ?Sized> ViewService<'a, P> {
    /// A service over a caller's config, project directory, and `tix.toml` path.
    #[must_use]
    pub fn new(config: &'a mut Config, projects: &'a P, path: &'a Path) -> Self {
        Self {
            config,
            projects,
            path,
            active: None,
        }
    }

    /// The registry, for a surface that needs to enumerate or render it directly.
    #[must_use]
    pub fn registry(&self) -> &ViewRegistry {
        &self.config.views
    }

    // -- read-only --------------------------------------------------------

    /// Every stored view, in declaration order (T013).
    #[must_use]
    pub fn list(&self) -> Vec<SavedView> {
        self.config.views.iter().cloned().collect()
    }

    /// Resolve one view by stable id or display name, parse and validate its plan,
    /// and return it with any unknown-metadata diagnostics (T013).
    ///
    /// A malformed plan is refused here, before a caller could try to apply or
    /// re-save it: "show" is the first place a stored-but-unsupported field would
    /// otherwise slip through.
    pub fn show(&self, reference: &str) -> ViewResult<ViewDetail> {
        let view = self.config.views.select(reference, self.projects)?;
        let plan = ViewPlan::from_toml(&view.plan)?;
        self.validate_plan(&plan)?;

        let mut diagnostics: Vec<ViewDiagnostic> = self
            .config
            .views
            .diagnostics(self.projects)
            .into_iter()
            .filter(|diagnostic| diagnostic.view_id() == Some(&view.id))
            .collect();
        diagnostics.extend(plan.diagnostics());
        Ok(ViewDetail {
            view: view.clone(),
            plan,
            diagnostics,
        })
    }

    /// Apply a saved view: resolve it, then build the board **once** through the
    /// existing filter path (T015/C-005).
    ///
    /// Read-only: `board`, `corpus`, and `config` are borrowed, and the result
    /// owns only derived copies. Nothing is written, and a refused or unsupported
    /// plan produces no board.
    pub fn apply(
        &self,
        reference: &str,
        board: &BoardConfiguration,
        corpus: &Corpus,
        resolution: &CategoryResolution,
    ) -> ViewResult<ViewApplyResult> {
        let view = self.config.views.select(reference, self.projects)?;
        let plan = ViewPlan::from_toml(&view.plan)?;
        plan.apply_as(&view.id, board, self.config, corpus, resolution)
    }

    // -- active marker (informational) ------------------------------------

    /// The active marker, when a view has been selected.
    #[must_use]
    pub fn active(&self) -> Option<&ActiveViewMarker> {
        self.active.as_ref()
    }

    /// Select a saved view as the active marker (T016).
    ///
    /// The plan is parsed and validated first, so an unsupported definition
    /// cannot be marked. Selecting is **informational and idempotent**: it writes
    /// no config and does not touch live filters, and selecting the same view
    /// twice leaves an equal marker (C-006).
    pub fn mark_active(&mut self, reference: &str, source: Option<ViewSurface>) -> ViewResult<()> {
        let (id, plan) = {
            let view = self.config.views.select(reference, self.projects)?;
            let plan = ViewPlan::from_toml(&view.plan)?;
            self.validate_plan(&plan)?;
            (view.id.clone(), plan)
        };
        self.active = Some(ActiveViewMarker::new(id, plan, source));
        Ok(())
    }

    /// Install a marker directly, for a surface restoring one it persisted.
    ///
    /// Still informational: this writes nothing, and a marker whose view has since
    /// been deleted is reported (not repaired) by [`Self::divergence`].
    pub fn set_active(&mut self, marker: ActiveViewMarker) {
        self.active = Some(marker);
    }

    /// Clear the active marker. Informational, writes nothing.
    pub fn clear_active(&mut self) {
        self.active = None;
    }

    /// Compare the live plan against the active view's **saved** definition
    /// (T016).
    ///
    /// Never mutates anything. A missing marker, a deleted view, or an
    /// uninterpretable saved plan is an explicit diagnostic rather than a
    /// `in_sync = true`.
    #[must_use]
    pub fn divergence(&self, live: &ViewPlan) -> ViewDivergence {
        let Some(marker) = &self.active else {
            return ViewDivergence::missing_marker(live);
        };
        match self.config.views.get(marker.view_id()) {
            None => ViewDivergence::deleted(marker.view_id(), live),
            Some(view) => match ViewPlan::from_toml(&view.plan) {
                Ok(saved) => marker.divergence(&saved, live),
                Err(refusal) => ViewDivergence::unreadable(
                    marker.view_id(),
                    live,
                    refusal.diagnostics().to_vec(),
                ),
            },
        }
    }

    // -- mutations --------------------------------------------------------

    /// Create a definition under a freshly allocated stable id (T013).
    ///
    /// The complete definition is validated — name, scope, and every plan field —
    /// **before** the candidate registry is committed, so a rejected create
    /// writes nothing.
    pub fn create(&mut self, definition: ViewDefinition) -> ViewMutation<ViewId> {
        self.validate_definition(&definition)?;

        let mut candidate = self.config.views.clone();
        let id = candidate.allocate_id();
        let view = SavedView::new(id.clone(), definition.name(), definition.scope.clone())?
            .with_plan(definition.plan().to_toml());
        candidate.insert(view)?;

        candidate.commit(self.config, self.projects, self.path)?;
        let name = definition.name().trim().to_string();
        Ok(ViewOutcome::accepted(
            id.clone(),
            ViewAuditEvent::new(ViewMutationKind::Create, id, name),
        ))
    }

    /// Replace an existing definition's name, scope, and plan in place (T013).
    ///
    /// The stable id never changes (identity survives a rename, C-002) and the
    /// record's preserved extension fields are left untouched (NFR-002). A
    /// same-content update is a no-op: no commit, no audit event.
    pub fn update(&mut self, reference: &str, definition: ViewDefinition) -> ViewMutation<ViewId> {
        let id = self
            .config
            .views
            .select(reference, self.projects)?
            .id
            .clone();
        self.validate_definition(&definition)?;

        let mut candidate = self.config.views.clone();
        candidate.rename(&id, definition.name())?;
        candidate.set_scope(&id, definition.scope.clone())?;
        candidate.set_plan(&id, definition.plan().to_toml())?;

        let name = definition.name().trim().to_string();
        if candidate == self.config.views {
            return Ok(ViewOutcome::unchanged(id));
        }
        candidate.commit(self.config, self.projects, self.path)?;
        Ok(ViewOutcome::accepted(
            id.clone(),
            ViewAuditEvent::new(ViewMutationKind::Update, id, name),
        ))
    }

    /// Duplicate a definition under a new stable id (T013).
    ///
    /// The copy carries the source's scope, plan, and preserved extensions
    /// verbatim; only the id is new. `name` overrides the label when given.
    pub fn duplicate(&mut self, reference: &str, name: Option<&str>) -> ViewMutation<ViewId> {
        let source = self.config.views.select(reference, self.projects)?.clone();
        // A duplicate is a create under a new id, so it runs the same plan
        // validation as create/update (C-008): a loadable-but-invalid plan must
        // not be duplicated into the registry, where `show`/`apply` would refuse
        // it. Without this, `duplicate` was the one path that could persist a
        // definition the other two refuse.
        self.validate_plan(&ViewPlan::from_toml(&source.plan)?)?;

        let mut candidate = self.config.views.clone();
        let id = candidate.allocate_id();
        let label = name.map_or_else(|| source.name.clone(), str::to_string);
        let copy = SavedView {
            id: id.clone(),
            name: label.trim().to_string(),
            scope: source.scope.clone(),
            plan: source.plan.clone(),
            extensions: source.extensions.clone(),
        };
        candidate.insert(copy)?;
        candidate.commit(self.config, self.projects, self.path)?;

        let stored = candidate
            .get(&id)
            .map_or_else(|| label.trim().to_string(), |view| view.name.clone());
        Ok(ViewOutcome::accepted(
            id.clone(),
            ViewAuditEvent::new(ViewMutationKind::Duplicate, id, stored),
        ))
    }

    /// Delete a view **definition** after explicit confirmation (T014/C-005).
    ///
    /// Only the definition is removed; issues, comments, relationships, and board
    /// data are never touched. If the active marker named this view it is cleared,
    /// and the outcome reports that so the caller can surface it. Deleting an
    /// unknown reference is refused (nothing was stored to remove).
    pub fn delete(
        &mut self,
        reference: &str,
        _confirmation: DeleteConfirmed,
    ) -> ViewMutation<DeletedView> {
        let view = self.config.views.select(reference, self.projects)?.clone();

        let mut candidate = self.config.views.clone();
        let removed = candidate
            .remove(&view.id)
            .expect("the selected view is in the registry");
        let marker_cleared = self
            .active
            .as_ref()
            .is_some_and(|marker| marker.view_id() == &removed.id);

        candidate.commit(self.config, self.projects, self.path)?;
        if marker_cleared {
            self.active = None;
        }

        let value = DeletedView {
            view: removed.clone(),
            marker_cleared,
        };
        Ok(ViewOutcome::accepted(
            value,
            ViewAuditEvent::new(
                ViewMutationKind::Delete,
                removed.id.clone(),
                removed.name.clone(),
            ),
        ))
    }

    // -- internals --------------------------------------------------------

    /// Validate a caller-supplied definition: a non-blank name, a
    /// self-consistent scope, and a plan every field of which this board and
    /// config accept.
    fn validate_definition(&self, definition: &ViewDefinition) -> ViewResult<()> {
        if definition.name.trim().is_empty() {
            return Err(ViewDiagnostic::new(
                ViewDiagnosticKind::InvalidView,
                "a saved view needs a name; the id is not a substitute for a label",
            )
            .with_field("name")
            .with_remedy("give the view a display name")
            .into());
        }
        let scope_conflicts = definition.scope.conflicts();
        if !scope_conflicts.is_empty() {
            return Err(ViewRefusal::from_diagnostics(scope_conflicts));
        }
        self.validate_plan(definition.plan())
    }

    /// Validate a plan against the active board and category vocabulary.
    fn validate_plan(&self, plan: &ViewPlan) -> ViewResult<()> {
        let board = self.config.default_config().clone();
        plan.validate(&board, self.config)
    }
}

#[cfg(test)]
mod tests {
    #[allow(clippy::wildcard_imports)]
    use super::*;
    use crate::search::StructuredFilter;
    use std::collections::BTreeSet;
    use std::fs;

    fn projects(ids: &[&str]) -> BTreeSet<String> {
        ids.iter().map(|id| (*id).to_string()).collect()
    }

    fn service_fixture(raw: &str) -> (tempfile::TempDir, Config, BTreeSet<String>) {
        let dir = tempfile::TempDir::new().unwrap();
        let path = dir.path().join("tix.toml");
        fs::write(&path, raw).unwrap();
        let config = Config::load(dir.path()).unwrap();
        (dir, config, projects(&[]))
    }

    #[test]
    fn create_then_show_round_trips_the_normalized_plan() {
        let (dir, mut config, known) = service_fixture("issues_dir = \"docs/issues\"\n");
        let path = dir.path().join("tix.toml");
        let definition = ViewDefinition::new(
            "Active",
            ViewScope::repository(),
            ViewPlan::from_parts(
                StructuredFilter {
                    label: Some("urgent".into()),
                    ..StructuredFilter::default()
                },
                "sort:due",
            ),
        );

        let mut service = ViewService::new(&mut config, &known, &path);
        let outcome = service.create(definition.clone()).unwrap();
        assert_eq!(outcome.audit().unwrap().kind(), ViewMutationKind::Create);
        let id = outcome.into_value();

        let detail = service.show(id.as_str()).unwrap();
        assert_eq!(detail.plan().sort(), Some("due"));
        assert_eq!(detail.plan().filter().label.as_deref(), Some("urgent"));
        assert_eq!(detail.view().id, id);
    }
}