tix-tracker 0.8.0

//! The Health event grammar and the frontmatter projection it feeds (mission
//! `project-issue-health-status-01M3C8HX`, WP02 T008-T012).
//!
//! # Two shapes, one log
//!
//! An **update** says what an issue's health is now, and an **override** says that a
//! person is overruling a value the policy derived. Both are the same append-only
//! History entry, distinguished by their
//! [`HistoryEventKind`](crate::model::HistoryEventKind) — `health_updated` or
//! `health_overridden` — because the kind is what an audit reader branches on. The
//! current value in the frontmatter is a **projection** of those events: convenient
//! to read, and never the record.
//!
//! # Nothing is written that cannot be attributed
//!
//! C-004 is absolute: every change carries an actor, a timestamp and a rationale,
//! and a change that lacks one is **refused before the first write** rather than
//! stored with a blank field to be explained later. A blank string is not a value —
//! `validate` treats it exactly like an absent one — and the rationale lives in the
//! event, so there is no way to record a change in the frontmatter alone.
//!
//! # Legacy is `unknown`, loudly
//!
//! A file with no `health:` block projects `unknown` (C-006), and a file whose block
//! carries a state this build does not know projects `unknown` **and reports the
//! value it could not read**: the file still loads, and the surface that shows the
//! state says why it cannot say more.

use std::fmt;

use crate::model::{HistoryEventKind, Issue};

use super::policy::{HealthPolicy, HealthPolicyError};
use super::state::{HealthState, StateParseError};

/// How a displayed value was obtained.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum HealthSource {
    /// A value somebody set on the issue itself.
    Current,
    /// A value derived from what contributes to the scope.
    Derived,
    /// A person's override of a derived value.
    Override,
}

impl HealthSource {
    /// The stable spelling written to the frontmatter and printed by a surface.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Current => "current",
            Self::Derived => "derived",
            Self::Override => "override",
        }
    }

    /// Parse a stored source; `None` for anything this build does not know, which the
    /// projection reports rather than guessing.
    pub fn parse(raw: &str) -> Option<Self> {
        match raw.trim().to_ascii_lowercase().as_str() {
            "current" => Some(Self::Current),
            "derived" => Some(Self::Derived),
            "override" => Some(Self::Override),
            _ => None,
        }
    }
}

/// The entity a health value belongs to.
///
/// The **stable id** in every arm (C-002): an issue by number, a project, epic, cycle
/// or milestone by its id, never by a display name — a name is a label that moves, and
/// a health value attached to a moving label is a value attached to nothing.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum HealthScope {
    /// An issue, by number.
    Issue(u32),
    /// A project, by stable id.
    Project(String),
    /// An epic, by stable id.
    Epic(String),
    /// A cycle, by stable id.
    Cycle(String),
    /// A milestone, by stable id.
    Milestone(String),
}

impl HealthScope {
    /// The canonical spelling: `<kind>:<id>`, e.g. `issue:42`, `project:alpha`.
    pub fn as_str(&self) -> String {
        match self {
            Self::Issue(number) => format!("issue:{number}"),
            Self::Project(id) => format!("project:{id}"),
            Self::Epic(id) => format!("epic:{id}"),
            Self::Cycle(id) => format!("cycle:{id}"),
            Self::Milestone(id) => format!("milestone:{id}"),
        }
    }

    /// The scope an issue's own health belongs to.
    pub const fn of_issue(number: u32) -> Self {
        Self::Issue(number)
    }

    /// Parse the canonical spelling.
    pub fn parse(raw: &str) -> Option<Self> {
        let (kind, id) = raw.trim().split_once(':')?;
        let id = id.trim();
        if id.is_empty() {
            return None;
        }
        match kind.trim().to_ascii_lowercase().as_str() {
            "issue" => id.parse::<u32>().ok().map(Self::Issue),
            "project" => Some(Self::Project(id.to_string())),
            "epic" => Some(Self::Epic(id.to_string())),
            "cycle" => Some(Self::Cycle(id.to_string())),
            "milestone" => Some(Self::Milestone(id.to_string())),
            _ => None,
        }
    }
}

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

/// A dated state change, as a caller asks for it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HealthUpdate {
    /// What the value is about.
    pub scope: HealthScope,
    /// The state it had, when the caller knows it.
    pub from: Option<HealthState>,
    /// The state it should have.
    pub to: HealthState,
    /// Who is making the change. Required.
    pub actor: String,
    /// When, as the caller states it — never read from a clock here.
    pub timestamp: String,
    /// Why. Required, and recorded verbatim.
    pub rationale: String,
    /// The policy version the change was made under.
    pub policy_version: String,
    /// How the value was obtained.
    pub source: HealthSource,
}

impl HealthUpdate {
    /// A change to `state` on `scope`, with the actor, timestamp and rationale that
    /// make it attributable.
    pub fn new(
        scope: HealthScope,
        to: HealthState,
        actor: impl Into<String>,
        timestamp: impl Into<String>,
        rationale: impl Into<String>,
    ) -> Self {
        Self {
            scope,
            from: None,
            to,
            actor: actor.into(),
            timestamp: timestamp.into(),
            rationale: rationale.into(),
            policy_version: super::policy::HEALTH_POLICY_VERSION.to_string(),
            source: HealthSource::Current,
        }
    }

    /// Record the state the caller believes it is changing **from**.
    pub fn from(mut self, from: HealthState) -> Self {
        self.from = Some(from);
        self
    }

    /// Mark the value as derived from the scope's contributors.
    pub fn derived(mut self) -> Self {
        self.source = HealthSource::Derived;
        self
    }

    /// Mark the value as a person's override of a derived one.
    pub fn overriding(mut self) -> Self {
        self.source = HealthSource::Override;
        self
    }
}

/// A manual override, which is an update that says so (T009).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HealthOverride {
    /// The change itself, whose `source` must be `override`.
    pub update: HealthUpdate,
    /// The derived value it overrules, when the caller knows it.
    pub derived_value: Option<HealthState>,
}

impl HealthOverride {
    /// Override `scope`'s derived health with `state`.
    pub fn new(
        scope: HealthScope,
        state: HealthState,
        actor: impl Into<String>,
        timestamp: impl Into<String>,
        rationale: impl Into<String>,
    ) -> Self {
        Self {
            update: HealthUpdate::new(scope, state, actor, timestamp, rationale).overriding(),
            derived_value: None,
        }
    }

    /// Record the derived value this override layers over.
    pub fn over(mut self, derived: HealthState) -> Self {
        self.derived_value = Some(derived);
        self
    }
}

/// Why a health change cannot be applied.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum HealthError {
    /// The change names no actor.
    BlankActor,
    /// The change names no time.
    BlankTimestamp,
    /// The change states no rationale.
    BlankRationale,
    /// The scope is not one this build resolves.
    InvalidScope(String),
    /// The policy version is not one this build implements.
    UnknownPolicy(HealthPolicyError),
    /// A stored state this build cannot read.
    InvalidState(StateParseError),
}

impl HealthError {
    /// The one sentence a surface shows.
    pub fn render(&self) -> String {
        match self {
            Self::BlankActor => {
                "a health change needs an actor; a blank one is not an actor".to_string()
            }
            Self::BlankTimestamp => {
                "a health change needs a timestamp; a blank one is not a moment".to_string()
            }
            Self::BlankRationale => {
                "a health change needs a rationale; a blank one is not a reason (C-004)".to_string()
            }
            Self::InvalidScope(raw) => format!(
                "`{raw}` is not a health scope; scopes are `issue:<n>`, `project:<id>`, \
                 `epic:<id>`, `cycle:<id>`, `milestone:<id>`"
            ),
            Self::UnknownPolicy(error) => error.render(),
            Self::InvalidState(error) => error.render(),
        }
    }
}

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

impl std::error::Error for HealthError {}

/// The one History entry an accepted change appends (T011).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HealthEvent {
    /// `health_updated` or `health_overridden`.
    pub kind: HistoryEventKind,
    /// Who made the change.
    pub actor: String,
    /// When, as the update stated it.
    pub timestamp: String,
    /// The one sentence: the scope, both states, the policy, and the rationale.
    pub detail: String,
}

/// Validate a change **before anything is written** (T010).
///
/// Every finding is a refusal, not a default: an actor, a timestamp and a rationale
/// that are missing or blank, a policy version this build does not implement, and a
/// state that is not in the vocabulary. Nothing here touches a store, so a rejected
/// change provably writes neither frontmatter nor History.
pub fn validate(
    update: &HealthUpdate,
    policy: &HealthPolicy,
) -> std::result::Result<(), HealthError> {
    for (value, error) in [
        (update.actor.trim(), HealthError::BlankActor),
        (update.timestamp.trim(), HealthError::BlankTimestamp),
        (update.rationale.trim(), HealthError::BlankRationale),
    ] {
        if value.is_empty() {
            return Err(error);
        }
    }
    if update.policy_version.trim() != policy.version() {
        return Err(HealthError::UnknownPolicy(HealthPolicyError {
            version: update.policy_version.clone(),
        }));
    }
    Ok(())
}

/// The event an accepted change appends (T011).
///
/// One event per accepted mutation, and the *same* function for an update and an
/// override, so the two can never record different amounts of context.
pub fn event(
    update: &HealthUpdate,
    policy: &HealthPolicy,
) -> std::result::Result<HealthEvent, HealthError> {
    validate(update, policy)?;
    let kind = match update.source {
        HealthSource::Override => HistoryEventKind::HealthOverridden,
        HealthSource::Current | HealthSource::Derived => HistoryEventKind::HealthUpdated,
    };
    let mut detail = format!(
        "health {} -> {} on `{}` (policy {}, source {})",
        update
            .from
            .map_or("(unset)".to_string(), |state| state.as_str().to_string()),
        update.to.as_str(),
        update.scope,
        update.policy_version,
        update.source.as_str(),
    );
    detail.push_str(&format!(": {}", update.rationale.trim()));
    Ok(HealthEvent {
        kind,
        actor: update.actor.trim().to_string(),
        timestamp: update.timestamp.trim().to_string(),
        detail,
    })
}

/// An accepted change that has been written.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AppliedHealth {
    /// The issue as it now reads on disk.
    pub issue: Issue,
    /// The one History entry that was appended.
    pub event: HealthEvent,
}

/// Apply an accepted change: validate, append **one** event, project the current
/// value, and write once (T011/T012).
///
/// The whole change is one store write, so a refused change leaves neither the
/// frontmatter nor the History touched — the two halves of C-004's "never untracked"
/// rule are the same write or neither. A change that cannot be attributed propagates
/// as a refusal having written nothing.
///
/// This is the only writer: the CLI, the TUI and MCP all call it, so there is exactly
/// one place that decides what a health mutation does to a file.
pub fn apply(
    store: &crate::storage::Store,
    number: u32,
    update: &HealthUpdate,
    policy: &HealthPolicy,
) -> crate::error::Result<AppliedHealth> {
    let event =
        event(update, policy).map_err(|error| crate::error::TixError::Refused(error.render()))?;
    let mut issue = store.get(crate::storage::IssueSelector::Number(number))?;
    issue.history.append(crate::model::HistoryEvent::new(
        event.timestamp.clone(),
        &event.actor,
        event.kind,
        &event.detail,
    ));
    issue.health = Some(crate::model::HealthRef {
        state: Some(update.to.as_str().to_string()),
        source: Some(update.source.as_str().to_string()),
        policy_version: Some(update.policy_version.clone()),
        updated_at: Some(event.timestamp.clone()),
    });
    issue.bump_updated();
    issue.filename = store.update(&issue.filename, &issue)?;
    Ok(AppliedHealth { issue, event })
}

/// What a file's `health:` block says, with everything a surface needs to render it
/// honestly (T012).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HealthView {
    /// The state to display: the stored one, or `unknown` when there is none or it
    /// cannot be read (C-006).
    pub state: HealthState,
    /// How the value was obtained. `Current` when the file does not say.
    pub source: HealthSource,
    /// The stored state string, when the file carries one — including one this build
    /// cannot read, so a surface can report exactly what is there.
    pub recorded: Option<String>,
    /// The policy version the file records, when it records one.
    pub policy_version: Option<String>,
    /// When the value was last updated, when the file says.
    pub updated_at: Option<String>,
    /// Why the state is `unknown`, when it is because the value could not be read.
    pub diagnostic: Option<HealthError>,
}

impl HealthView {
    /// Whether anything is known: `false` for a legacy file, and for a file whose
    /// state this build cannot read.
    pub fn is_known(&self) -> bool {
        self.state != HealthState::Unknown
    }

    /// The one line a surface shows.
    pub fn render(&self) -> String {
        if let Some(error) = &self.diagnostic {
            return error.render();
        }
        match self.updated_at.as_deref() {
            Some(when) => format!(
                "{} ({} since {when})",
                self.state.label(),
                self.source.as_str()
            ),
            None => format!("{} ({})", self.state.label(), self.source.as_str()),
        }
    }
}

/// Project a file's current health (T012).
///
/// Total: a file with no block, a partial block, and a block whose state or source
/// this build cannot read all produce a view, with `unknown` where nothing is known
/// and a diagnostic explaining a value that is there but unreadable. A projection
/// never fails, because a surface that cannot show a value still has to show
/// *something* — and "unknown, and here is why" is the something.
pub fn project(issue: &Issue, _policy: &HealthPolicy) -> HealthView {
    let Some(reference) = issue.health.as_ref() else {
        return HealthView {
            state: HealthState::Unknown,
            source: HealthSource::Current,
            recorded: None,
            policy_version: None,
            updated_at: None,
            diagnostic: None,
        };
    };
    let source = reference
        .source
        .as_deref()
        .and_then(HealthSource::parse)
        .unwrap_or(HealthSource::Current);
    let state = match reference.state.as_deref() {
        None => HealthState::Unknown,
        Some(raw) => match HealthState::parse(raw) {
            Ok(state) => state,
            Err(error) => {
                return HealthView {
                    state: HealthState::Unknown,
                    source,
                    recorded: Some(raw.to_string()),
                    policy_version: reference.policy_version.clone(),
                    updated_at: reference.updated_at.clone(),
                    diagnostic: Some(HealthError::InvalidState(error)),
                };
            }
        },
    };
    // A `derived` value without a policy version cannot be compared with anything
    // derived elsewhere, so it is reported rather than presented as a plain value.
    let diagnostic = match (source, reference.policy_version.as_deref()) {
        (HealthSource::Derived | HealthSource::Override, None) => {
            Some(HealthError::UnknownPolicy(HealthPolicyError {
                version: "(none recorded)".to_string(),
            }))
        }
        _ => None,
    };
    HealthView {
        state,
        source,
        recorded: reference.state.clone(),
        policy_version: reference.policy_version.clone(),
        updated_at: reference.updated_at.clone(),
        diagnostic,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::model::{HealthRef, Issue};

    fn issue_with(health: Option<HealthRef>) -> Issue {
        let contents = "---\nnumber: 7\ntitle: \"Fixture\"\nstatus: \"todo\"\n\
                        created: \"2026-01-01\"\nupdated: \"2026-01-01\"\n---\n\nBody.\n";
        let mut issue = Issue::parse(contents).expect("the fixture parses");
        issue.filename = "fixture.md".to_string();
        issue.health = health;
        issue
    }

    fn update() -> HealthUpdate {
        HealthUpdate::new(
            HealthScope::of_issue(7),
            HealthState::AtRisk,
            "alice",
            "2026-01-02T03:04:05Z",
            "the migration slipped",
        )
        .from(HealthState::OnTrack)
    }

    #[test]
    fn health_scopes_round_trip_their_canonical_spelling() {
        for scope in [
            HealthScope::Issue(42),
            HealthScope::Project("alpha".to_string()),
            HealthScope::Epic("epic-1".to_string()),
            HealthScope::Cycle("2026-01".to_string()),
            HealthScope::Milestone("m1".to_string()),
        ] {
            assert_eq!(HealthScope::parse(&scope.as_str()).unwrap(), scope);
        }
        assert_eq!(HealthScope::Issue(42).as_str(), "issue:42");
        assert!(HealthScope::parse("issue:").is_none());
        assert!(HealthScope::parse("sprint:1").is_none());
        assert!(HealthScope::parse("issue:abc").is_none());
    }

    #[test]
    fn health_validation_refuses_a_change_that_cannot_be_attributed() {
        let policy = HealthPolicy::v1();
        assert!(validate(&update(), &policy).is_ok());
        for (mut broken, expected) in [
            (
                {
                    let mut u = update();
                    u.actor = "  ".into();
                    u
                },
                HealthError::BlankActor,
            ),
            (
                {
                    let mut u = update();
                    u.timestamp = String::new();
                    u
                },
                HealthError::BlankTimestamp,
            ),
            (
                {
                    let mut u = update();
                    u.rationale = "\t".into();
                    u
                },
                HealthError::BlankRationale,
            ),
            (
                {
                    let mut u = update();
                    u.policy_version = "health-v2".into();
                    u
                },
                HealthError::UnknownPolicy(HealthPolicyError {
                    version: "health-v2".into(),
                }),
            ),
        ] {
            let error = validate(&broken, &policy).expect_err("refused");
            assert_eq!(error, expected, "{broken:?}");
            assert_ne!(error.render(), "");
            // `event` is the write-side gate, so it refuses the same change.
            assert!(event(&broken, &policy).is_err());
            broken.actor.clear();
        }
    }

    #[test]
    fn health_event_records_the_whole_change_in_one_entry() {
        let policy = HealthPolicy::v1();
        let built = event(&update(), &policy).expect("a complete change");
        assert_eq!(built.kind, HistoryEventKind::HealthUpdated);
        assert_eq!(built.actor, "alice");
        assert_eq!(built.timestamp, "2026-01-02T03:04:05Z");
        for needle in [
            "on_track -> at_risk",
            "`issue:7`",
            "policy health-v1",
            "source current",
            "the migration slipped",
        ] {
            assert!(
                built.detail.contains(needle),
                "{needle:?} in {}",
                built.detail
            );
        }

        let over = HealthOverride::new(
            HealthScope::Project("alpha".to_string()),
            HealthState::OnTrack,
            "bob",
            "2026-01-03T00:00:00Z",
            "we accepted the risk",
        )
        .over(HealthState::AtRisk);
        let built = event(&over.update, &policy).expect("a complete override");
        assert_eq!(built.kind, HistoryEventKind::HealthOverridden);
        assert!(built.detail.contains("source override"), "{}", built.detail);
        assert!(built.detail.contains("`project:alpha`"), "{}", built.detail);
    }

    #[test]
    fn health_projection_is_total_and_explains_what_it_cannot_read() {
        let policy = HealthPolicy::v1();

        // A legacy file: unknown, and nothing to explain.
        let legacy = project(&issue_with(None), &policy);
        assert_eq!(legacy.state, HealthState::Unknown);
        assert!(!legacy.is_known());
        assert!(legacy.recorded.is_none() && legacy.diagnostic.is_none());
        assert!(legacy.render().contains("Unknown"), "{}", legacy.render());

        // A readable block: the state, the source and the time.
        let known = project(
            &issue_with(Some(HealthRef {
                state: Some("on_track".to_string()),
                source: Some("current".to_string()),
                policy_version: None,
                updated_at: Some("2026-01-02".to_string()),
            })),
            &policy,
        );
        assert_eq!(known.state, HealthState::OnTrack);
        assert_eq!(known.source, HealthSource::Current);
        assert!(known.is_known());
        assert!(
            known.render().contains("since 2026-01-02"),
            "{}",
            known.render()
        );

        // A state this build cannot read: unknown, with the value quoted back.
        let unreadable = project(
            &issue_with(Some(HealthRef {
                state: Some("fine".to_string()),
                ..HealthRef::default()
            })),
            &policy,
        );
        assert_eq!(unreadable.state, HealthState::Unknown);
        assert_eq!(unreadable.recorded.as_deref(), Some("fine"));
        assert!(
            unreadable.render().contains("fine"),
            "{}",
            unreadable.render()
        );
        assert!(
            unreadable.render().contains("on_track"),
            "{}",
            unreadable.render()
        );

        // A derived value with no policy version: reported, not presented as plain.
        let derived = project(
            &issue_with(Some(HealthRef {
                state: Some("at_risk".to_string()),
                source: Some("derived".to_string()),
                ..HealthRef::default()
            })),
            &policy,
        );
        assert_eq!(
            derived.state,
            HealthState::AtRisk,
            "the value is still shown"
        );
        assert!(
            derived.diagnostic.is_some(),
            "and the missing version is reported"
        );
        assert!(
            derived.render().contains("health-v1"),
            "{}",
            derived.render()
        );
    }
}