vivac 0.12.0

//! What a write returns, instead of printing it.
//!
//! `t106`: the CLI is not the only caller any more, and a caller over MCP
//! cannot read stdout. Every write op is moving from printing straight to a
//! terminal to returning an `Outcome`, so a second surface can read the same
//! answer the CLI does. `main.rs` and the MCP server both turn one into
//! text through `to_text` below -- a mirror of `brief::to_text`, which
//! already proved the split works: the data is built once, and the
//! rendering into a sentence is a formatting step over it, not a second
//! source of truth.
//!
//! **A variant carries the value an operation computed, never the sentence it
//! would have printed.** Where today's code interpolates a value into a
//! string -- `r.phrase()`, `kind.prefix()`, an anchor's short hash -- the
//! field here is that value, and `to_text` does the interpolating. Where
//! today's code prints a fixed sentence that names no data of its own, the
//! field is the `bool` or `Option` that decides whether it appears, and the
//! sentence itself lives in `to_text`. A model rule such as the depth
//! threshold `push` warns past, or whether a close needed `--force`, is
//! decided once, by the operation that knows the rule; `to_text` only knows
//! how to say what was already decided.

use crate::anchor::AnchorRef;
use crate::model::Counts;

/// A node closed, win or by force. Shared by `pop` and `done`, which both
/// wrap it: closing itself is one rule (`ops::close_node`) applied from two
/// places.
#[derive(Debug, Clone, serde::Serialize)]
pub struct Closed {
    pub alias: String,
    pub title: String,
    pub force: bool,
    /// `f552` (`t533` §2.2): the word it already was, when `pop` reaches a
    /// focus that was not open to begin with -- `done`/`park` closed it while
    /// it sat below the top of the stack, and nothing here closes it again.
    /// Always present; `None` for an ordinary close, on both `pop` and
    /// `done`.
    pub already: Option<String>,
}

/// `push`'s advice to reconsider the root, past a stack four deep. `MODEL.md`
/// §6.1: intervene, never block, so it is advice and never a refusal.
#[derive(Debug, Clone, serde::Serialize)]
pub struct DepthAdvice {
    pub depth: usize,
    pub root_alias: String,
    pub root_title: String,
    /// `t533` §2.5: the bottom of the stack can now be closed or parked --
    /// `done`/`park` no longer unstack a node that is not the top -- and the
    /// advice carries its word rather than calling it open when it is not.
    /// `None` while it is still open.
    pub root_mark: Option<String>,
}

/// Where `pop` lands: the parent that becomes the new focus, with what is
/// still open below it.
#[derive(Debug, Clone, serde::Serialize)]
pub struct PoppedTo {
    pub alias: String,
    pub title: String,
    pub counts: Counts,
}

/// The parent `add` filed a node under, when it did not land at the root.
#[derive(Debug, Clone, serde::Serialize)]
pub struct AddedUnder {
    pub alias: String,
    pub title: String,
}

/// The parent `promote` leaves behind. Provenance does not move: the node
/// promoted is still born from here, only its rank changed (`d33`'s sibling
/// rule for goals).
#[derive(Debug, Clone, serde::Serialize)]
pub struct StillBornFrom {
    pub alias: String,
    pub title: String,
}

/// A node `abandon` saved out of the fall, still born where it was.
#[derive(Debug, Clone, serde::Serialize)]
pub struct RescuedNode {
    pub alias: String,
    pub title: String,
}

/// The decision `decide --supersedes` retires.
#[derive(Debug, Clone, serde::Serialize)]
pub struct SupersededNode {
    pub alias: String,
}

/// The two shapes `flag` can leave: cleared, or raised with the reason that
/// justified it. `BRIEF-SPEC.md` §10 makes the reason mandatory on the way in;
/// this is what comes back out.
#[derive(Debug, Clone, serde::Serialize)]
#[serde(tag = "change")]
pub enum FlagChange {
    Off,
    Raised { title: String, reason: String },
}

/// The two shapes `arm` can leave, mirroring `FlagChange`: `d415`.
#[derive(Debug, Clone, serde::Serialize)]
#[serde(tag = "change")]
pub enum ArmChange {
    Added,
    Removed,
}

/// One declaration `declare` recorded: the pillar or rule's own alias and
/// the sentence on how the decision holds against it. `t426` §2.2.
#[derive(Debug, Clone, serde::Serialize)]
pub struct DeclaredPair {
    pub node: String,
    pub why: String,
}

/// `false` is never serialized: otherwise `d445`'s `no_against` would
/// change the JSON of every write that is not a decision, which `t426` §2.3
/// keeps byte for byte what it already was.
fn is_false(b: &bool) -> bool {
    !*b
}

/// A node `restore` cannot put back on the stack, and why: it closed, it was
/// abandoned, or it no longer exists at all.
#[derive(Debug, Clone, serde::Serialize)]
pub struct LostNode {
    pub alias: String,
    pub title: String,
    /// Already resolved to a word (`n.state.word(n.kind)`, or the literal
    /// `"gone"`): there is no live node left to ask, past this point, for a
    /// node that no longer resolves at all.
    pub state: String,
}

/// A node `restore` keeps on the rebuilt path even though it is not open:
/// `t533` §2.3. Same shape as [`LostNode`], because both name a node and the
/// word for the state it is in -- the difference is which one still counts
/// as part of the stack.
#[derive(Debug, Clone, serde::Serialize)]
pub struct KeptNode {
    pub alias: String,
    pub title: String,
    pub state: String,
}

/// One path that changed since a vivac's anchor, and how many times.
#[derive(Debug, Clone, serde::Serialize)]
pub struct ChangeLine {
    pub file_path: String,
    pub times: usize,
}

/// The three shapes `restore`'s diff can take. Which one applies is a fact
/// about the anchor and the repository, decided once by the operation; the
/// render only knows how to say each of the three.
#[derive(Debug, Clone, serde::Serialize)]
#[serde(tag = "anchor")]
pub enum RestoreAnchor {
    /// `Null`: there was never anything to diff against (`MODEL.md` §8).
    Empty,
    NoChanges {
        anchor_short: String,
    },
    Changed {
        anchor_short: String,
        changes: Vec<ChangeLine>,
        /// The `governs` globs the stack declared at save time. Empty unless
        /// something on it declared one, and that is what decides whether
        /// the "touch what the stack governed" count is worth saying at all.
        working_set: Vec<String>,
    },
}

/// What a write handed back, instead of a line on a terminal.
#[derive(Debug, Clone, serde::Serialize)]
#[serde(tag = "op")]
pub enum Outcome {
    Pushed {
        alias: String,
        title: String,
        blocks: bool,
        advice: Option<DepthAdvice>,
        #[serde(skip_serializing_if = "is_false")]
        no_against: bool,
        /// `--root` (`t533` §1.4): the aliases that left the stack, bottom to
        /// top. Always present; `[]` when nothing left, `--root` or not.
        left_stack: Vec<String>,
        /// The deepest of `left_stack` that is still open or parked, the one
        /// worth naming to get back to. Always present; `null` when nothing
        /// left, or everything that did is closed or abandoned.
        back_to: Option<String>,
    },
    Popped {
        closed: Closed,
        parent: Option<PoppedTo>,
    },
    Done {
        closed: Closed,
    },
    Added {
        alias: String,
        title: String,
        parent: Option<AddedUnder>,
        blocks: bool,
        #[serde(skip_serializing_if = "is_false")]
        no_against: bool,
    },
    Noted {
        alias: String,
    },
    Blocked {
        alias: String,
        blocks: bool,
        parent_alias: String,
        parent_title: String,
    },
    Promoted {
        alias: String,
        title: String,
        parent: Option<StillBornFrom>,
    },
    Abandoned {
        alias: String,
        title: String,
        cascaded: Option<usize>,
        rescued: Vec<RescuedNode>,
    },
    Parked {
        alias: String,
        title: String,
    },
    Focused {
        alias: String,
        revived: bool,
    },
    Flagged {
        alias: String,
        flag: String,
        change: FlagChange,
    },
    Armed {
        alias: String,
        /// The folder the arm runs in, already normalized -- `.` for the
        /// tree's own folder. `d441`: a pair with no folder is exactly what
        /// it retired, so the confirmation shows both halves.
        dir: String,
        arm: String,
        change: ArmChange,
    },
    Decided {
        alias: String,
        title: String,
        superseded: Option<SupersededNode>,
        no_alternatives: bool,
        #[serde(skip_serializing_if = "is_false")]
        no_against: bool,
    },
    /// `declare`'s own write: what a decision was judged against, recorded
    /// after the fact. `t426` §2.2.
    Declared {
        alias: String,
        against: Vec<DeclaredPair>,
    },
    Saved {
        num: u64,
        label: String,
        anchor: AnchorRef,
        /// What the lane's own repositories anchored this stop to. Empty
        /// for a lane that declared none, where `anchor` still answers.
        anchors: Vec<crate::event::RepoAnchor>,
        next: String,
    },
    Restored {
        alias: String,
        kind: String,
        ts: String,
        label: String,
        next_intent: String,
        /// Closed or parked nodes the rebuilt path still runs through:
        /// `t533` §2.3. Always present; `[]` when the whole path is open.
        kept: Vec<KeptNode>,
        lost: Vec<LostNode>,
        anchor: RestoreAnchor,
    },
    /// The end-of-session hook's automatic stop. Silent today, the same way
    /// `auto_vivac` prints nothing: a segment nobody was asked to summarize
    /// is not a place to start inventing prose.
    AutoStopped,
    /// A session opened, for the start hook. Silent for the same reason: the
    /// brief is what the hook actually shows, and this is not it.
    SessionOpened,
}

/// `d445`'s warning: a pillar or a rule judged in silence reads the same
/// as one nobody checked at all, so a decision born while something governs
/// and declaring nothing says so, and says how to fix it. `t426` §2.3.
fn no_against_lines(out: &mut Vec<String>, alias: &str) {
    out.push(
        "        no --against: a pillar judged in silence reads the same as one skipped"
            .to_string(),
    );
    out.push(format!("        vivac declare {alias} adds one"));
}

fn closed_lines(out: &mut Vec<String>, c: &Closed) {
    if let Some(word) = &c.already {
        // `f552` (`t533` §2.2): nothing closed here, so there is nothing to
        // say about `--force` either.
        out.push(format!(
            "  {}  {}  -> already {word}, left as it was",
            c.alias, c.title
        ));
        return;
    }
    out.push(format!(
        "  {}  {}  -> {}",
        c.alias,
        c.title,
        if c.force { "closed BY FORCE" } else { "closed" }
    ));
    if c.force {
        out.push("        recorded as a false close in every render".to_string());
    }
}

/// The `Outcome` as plain text, the way the CLI has always printed it.
///
/// A mirror of `brief::to_text`: the data is already final by the time it
/// gets here, so this only ever formats, never decides.
pub fn to_text(o: &Outcome) -> String {
    let mut lines: Vec<String> = Vec::new();
    match o {
        Outcome::Pushed {
            alias,
            title,
            blocks,
            advice,
            no_against,
            left_stack,
            back_to,
        } => {
            lines.push(format!("  {alias}  {title}"));
            if *blocks {
                lines.push("        blocks its parent from closing".to_string());
            }
            // `--root` (`t533` §1.4): what the stack held before is reported
            // here, right after the node born and what it blocks.
            if let [bottom, .., top] = left_stack.as_slice() {
                lines.push(format!(
                    "        at the root: {} left the stack, {bottom} to {top}, none closed by this",
                    left_stack.len()
                ));
            } else if let [only] = left_stack.as_slice() {
                lines.push(format!(
                    "        at the root: {only} left the stack, not closed by this"
                ));
            }
            if let Some(b) = back_to {
                lines.push(format!("        back there with:  vivac focus {b}"));
            }
            if let Some(a) = advice {
                lines.push(String::new());
                let mark = a
                    .root_mark
                    .as_deref()
                    .map(|w| format!(" [{w}]"))
                    .unwrap_or_default();
                lines.push(format!(
                    "  You are {} levels away from {} \"{}\"{mark}.",
                    a.depth, a.root_alias, a.root_title
                ));
                lines.push("  Is this still a detour, or did the real goal move?".to_string());
                lines.push("  If it moved:  vivac promote".to_string());
            }
            if *no_against {
                no_against_lines(&mut lines, alias);
            }
        }
        Outcome::Popped { closed, parent } => {
            closed_lines(&mut lines, closed);
            match parent {
                Some(p) => {
                    lines.push(format!("  back to {}  {}", p.alias, p.title));
                    let f = p.counts.phrase();
                    if !f.is_empty() {
                        lines.push(format!("        ({f} below it)"));
                    }
                }
                None => lines.push("  empty stack".to_string()),
            }
        }
        Outcome::Done { closed } => closed_lines(&mut lines, closed),
        Outcome::Added {
            alias,
            title,
            parent,
            blocks,
            no_against,
        } => {
            let where_at = match parent {
                Some(p) => format!(" under {}", p.alias),
                None => " (root)".to_string(),
            };
            lines.push(format!("  {alias}  {title}{where_at}"));
            if *blocks {
                lines.push("        blocks its parent from closing".to_string());
            }
            if *no_against {
                no_against_lines(&mut lines, alias);
            }
        }
        Outcome::Noted { alias } => lines.push(format!("  {alias} noted")),
        Outcome::Blocked {
            alias,
            blocks,
            parent_alias,
            parent_title,
        } => {
            let verb = if *blocks {
                "blocks"
            } else {
                "no longer blocks"
            };
            lines.push(format!(
                "  {alias} {verb} the close of {parent_alias}  {parent_title}"
            ));
        }
        Outcome::Promoted {
            alias,
            title,
            parent,
        } => {
            lines.push(format!("  {alias}  {title}  -> a goal of its own"));
            if let Some(p) = parent {
                lines.push(format!("        still born from {}  {}", p.alias, p.title));
            }
        }
        Outcome::Abandoned {
            alias,
            title,
            cascaded,
            rescued,
        } => {
            lines.push(format!("  {alias}  {title}  -> abandoned"));
            if let Some(n) = cascaded {
                lines.push(format!("        and {n} descendant(s) with it"));
            }
            if !rescued.is_empty() {
                lines.push(String::new());
                lines.push(format!("  Rescued, and still born from {alias}:"));
                for r in rescued {
                    lines.push(format!("      {:<6} {}", r.alias, r.title));
                }
                lines.push(String::new());
                lines.push(
                    "  Their lineage crosses an abandoned node on purpose: where they".to_string(),
                );
                lines.push("  were born does not change because it got discarded.".to_string());
            }
        }
        Outcome::Parked { alias, title } => {
            lines.push(format!("  {alias}  {title}  -> parked"));
            lines.push("        shows up in:  vivac parked".to_string());
        }
        Outcome::Focused { alias, revived } => {
            if *revived {
                lines.push(format!("  {alias} is open again"));
            }
        }
        Outcome::Flagged {
            alias,
            flag,
            change,
        } => match change {
            FlagChange::Off => lines.push(format!("  {alias}  is no longer {flag}")),
            FlagChange::Raised { title, reason } => {
                lines.push(format!("  {alias}  {title}  -> {flag}"));
                lines.push(format!("        {reason}"));
            }
        },
        Outcome::Armed {
            alias,
            dir,
            arm,
            change,
        } => match change {
            ArmChange::Added => lines.push(format!("  {alias}  armed in {dir}/: {arm}")),
            ArmChange::Removed => {
                lines.push(format!("  {alias}  no longer armed in {dir}/: {arm}"))
            }
        },
        Outcome::Decided {
            alias,
            title,
            superseded,
            no_alternatives,
            no_against,
        } => {
            lines.push(format!("  {alias}  {title}"));
            if let Some(s) = superseded {
                lines.push(format!("        {} becomes superseded", s.alias));
            }
            if *no_alternatives {
                lines.push(
                    "        no alternatives recorded: in a month they get proposed again"
                        .to_string(),
                );
            }
            if *no_against {
                no_against_lines(&mut lines, alias);
            }
        }
        Outcome::Declared { alias, against } => {
            for a in against {
                lines.push(format!("  {alias}  judged against {}: {}", a.node, a.why));
            }
        }
        Outcome::Saved {
            num,
            label,
            anchor,
            anchors,
            next,
        } => {
            let shown = if label.is_empty() { "no label" } else { label };
            lines.push(format!("  v{num}  {shown}"));
            if let Some(a) = crate::model::anchoring(anchor, anchors) {
                lines.push(format!("        anchored to {a}"));
            } else {
                lines.push("        no anchor: there is no version control here".to_string());
            }
            if next.is_empty() {
                lines.push(
                    "        no --next: coming back there will be nothing to pick up".to_string(),
                );
            }
        }
        Outcome::Restored {
            alias,
            kind,
            ts,
            label,
            next_intent,
            kept,
            lost,
            anchor,
        } => {
            lines.push(String::new());
            lines.push(format!(
                "  {alias} · {kind} · {}",
                crate::clock::date_of(ts)
            ));
            if !label.is_empty() {
                lines.push(format!("  {label}"));
            }
            lines.push(String::new());
            if !next_intent.is_empty() {
                lines.push(format!("  you were about to:  {next_intent}"));
                lines.push(String::new());
            }
            // `t533` §2.3: closed or parked, but still part of the rebuilt
            // path -- reported apart from what actually left the stack.
            for k in kept {
                lines.push(format!(
                    "  still on the path:  {} {} [{}]",
                    k.alias, k.title, k.state
                ));
            }
            if !kept.is_empty() {
                lines.push(String::new());
            }
            for p in lost {
                lines.push(format!(
                    "  no longer on the stack:  {} {} [{}]",
                    p.alias, p.title, p.state
                ));
            }
            if !lost.is_empty() {
                lines.push(String::new());
            }
            match anchor {
                RestoreAnchor::Empty => {
                    lines.push(
                        "  No anchor: there is no diff to show, only the date above.".to_string(),
                    );
                    lines.push(String::new());
                }
                RestoreAnchor::NoChanges { anchor_short } => {
                    lines.push(format!("  Nothing changed since {anchor_short}."));
                    lines.push(String::new());
                }
                RestoreAnchor::Changed {
                    anchor_short,
                    changes,
                    working_set,
                } => {
                    let touching = changes
                        .iter()
                        .filter(|c| {
                            working_set
                                .iter()
                                .any(|g| crate::glob::covers(g, &c.file_path))
                        })
                        .count();
                    let suffix = if working_set.is_empty() {
                        String::new()
                    } else {
                        format!(", {touching} of them touch what the stack governed")
                    };
                    lines.push(format!(
                        "  {} changes since {anchor_short}{suffix}",
                        changes.len()
                    ));
                    for c in changes.iter().take(6) {
                        lines.push(format!("      {:<52} ({})", c.file_path, c.times));
                    }
                    if changes.len() > 6 {
                        lines.push(format!("      ... and {} more", changes.len() - 6));
                    }
                    lines.push(String::new());
                }
            }
        }
        // Neither hook op has ever printed anything: both fire from a Claude
        // Code hook, never from a terminal, so there is nobody to tell.
        Outcome::AutoStopped | Outcome::SessionOpened => {}
    }
    // `Outcome::Focused { revived: false, .. }` and the two hook outcomes
    // just above are the shapes with nothing to say: the CLI printed no
    // line at all for them, and an empty `Vec` here has to come out as an
    // empty string and not as a single blank line.
    if lines.is_empty() {
        return String::new();
    }
    let mut s = lines.join("\n");
    s.push('\n');
    s
}