tix-tracker 0.12.0

//! `tix time`: the CLI adapter over the shared time service and aggregation
//! (mission `per-issue-time-tracking-01M3C9A4`, WP04, T019–T023).
//!
//! Parse, call, print. Nothing here sums a minute, validates an entry, resolves a
//! period, or reads a `## History` grammar. The mutations are
//! [`crate::time_tracking::service::apply`]'s — the one seam that resolves the issue,
//! validates the intent, stages the projection and the single event, and writes once —
//! and everything the read verbs print is a field of
//! [`crate::time_tracking::aggregate::TimeSnapshot`]'s DTOs or of the shared rendering
//! beside them ([`TimeFilter::describe`], [`TimeGroup::label`],
//! [`TimeTotalState::as_str`], [`TimeDiagnostic::render`]). That is C-006's one-DTO
//! rule and NFR-003's parity claim: a number the CLI prints is a number the shared
//! calculation held, so the CLI, the TUI, MCP and the portable mapping cannot word one
//! total four ways (T021).
//!
//! # The commands
//!
//! * `tix time add <ISSUE> --minutes <N> --author <IDENTITY> [--date YYYY-MM-DD]
//!   [--note <TEXT>]` — one create, through [`apply`].
//! * `tix time edit <ISSUE> --entry <ID> [--minutes <N>] [--date <D> | --clear-date]
//!   [--note <TEXT> | --clear-note] [--author <IDENTITY>] --reason <TEXT>` — one
//!   correction, naming only the fields it replaces.
//! * `tix time delete <ISSUE> --entry <ID> --reason <TEXT> --confirm` — one deletion,
//!   from the current projection only.
//! * `tix time show <ISSUE>` — the issue's current entries and its total.
//! * `tix time history <ISSUE>` — the audit view: current entries beside what History
//!   retains.
//! * `tix time total [ISSUE] [--issue <N>] [--assignee <IDENTITY>] [--from <D>]
//!   [--to <D>] [--audit] [--by <DIMENSION>]` — the scope's total and, opt-in, its
//!   breakdown by issue, identity or calendar date.
//!
//! # The caller supplies the dates
//!
//! There is no `today` here and no default period. Every date this surface knows is one
//! the caller typed, either as an entry's `--date` or as a period bound; the only other
//! instant in a mutation is the crate's own clock inside [`apply`], which the caller may
//! not move and this surface never reads (C-002, C-005).
//!
//! # `--confirm`, the reason, and what a refusal leaves behind
//!
//! `delete` is the one destructive verb — it removes an entry from the issue's current
//! projection — so it is the one that requires `--confirm`, exactly as the contract
//! spells (`contracts/cli-surface.md`) and as `tix view delete` and the cycle-schedule
//! lifecycle verbs require it. An unconfirmed delete is refused before the store is even
//! read.
//!
//! A correction and a deletion also require `--reason`: the reason is what the audit
//! trail keeps once the prior value is replaced or removed, and it is *not* re-checked
//! here — [`apply`] refuses a missing or blank reason with `missing_reason`, so the
//! requirement has one owner rather than two. Every refusal this file can raise (bad
//! arguments are `clap`'s) reaches the caller as a non-zero exit carrying a reason and a
//! remedy, and none of them writes anything: the service refuses before its write seam,
//! and this file's own refusals — the unconfirmed delete, the two ways to name one
//! issue — are raised before any write is attempted.
//!
//! # An absent value is `-`, never `0`
//!
//! `nothing` (the scope selected no entry) and `unknown` (it selected entries and none
//! carried a usable duration) are different facts, and both are visibly different from a
//! recorded `0`: the total's [`TimeTotalState`] is printed by name beside a
//! `total_minutes` of `-`. The same convention renders an entry's absent minutes, date,
//! note or author in `show`'s table **and** on a mutation's line (`values`), so a
//! malformed entry reads as absent rather than as zero everywhere this surface prints it,
//! and is explained by its own finding on stderr (C-005). That is deliberately not
//! WP02's `entry_summary`, whose `?m` marks the value slot of a `## History` detail line
//! — evidence, not user-facing text.
//!
//! # stdout is the result, stderr is the diagnostic
//!
//! Values go to stdout, one `key: value` line per field (the shape `tix capacity show`
//! uses) or one tab-separated row per entry, because that is what a script reads.
//! Findings render through [`TimeDiagnostic::render`] to stderr, exactly as
//! `tix capacity` renders its warnings: a finding interleaved into the value lines would
//! be a parse error rather than a warning. A finding about an entry means the total is
//! **partial**, so it always renders; the scope's own findings tell the whole selection's
//! story, so a breakdown does not repeat them (the groups partition one selection).
//!
//! # A refused scope is a refusal, not a total
//!
//! An invalid filter and an issue the snapshot does not hold are the two states where
//! no total exists at all, and they are answered as a refusal rather than as a `-`
//! total: "unknown" and "nothing" are answers, but "your `--from` is not a date" is a
//! request to fix the request. The refusal exits `1` — the frozen exit-code table's
//! `usage/config` bucket, which is where [`TixError::Refused`] and
//! [`TixError::InvalidInput`] land (`exit_code_for`'s catch-all) — and the mission
//! requires a non-zero exit with a reason and a remedy, not a particular code.
//!
//! One refusal is this family's own rather than the aggregation's: a selector that names
//! an **archived** issue, which `total`'s active-issue enumeration cannot answer for
//! while `show` and `history` can (see `selected_number`). The MCP's `time_total` reads
//! the same project total over the same active enumeration, so it renders that refusal
//! through the same [`archived_refusal`] rather than inventing its own answer (C-006).
//!
//! [`apply`]: crate::time_tracking::service::apply
//! [`TimeTotalState`]: crate::time_tracking::aggregate::TimeTotalState
//! [`TimeGroup::label`]: crate::time_tracking::aggregate::TimeGroup::label
//! [`TimeFilter::describe`]: crate::time_tracking::filters::TimeFilter::describe

use crate::cli::{TimeCommand, TimeEditArgs, TimeTotalArgs};
use crate::diagnostics::Diagnostic;
use crate::error::{Result, TixError};
use crate::model::Issue;
use crate::storage::{IssueSelector, Store};
use crate::time_tracking::aggregate::{TimeSnapshot, TimeTotal, TimeTotalState};
use crate::time_tracking::diagnostics::TimeDiagnostic;
use crate::time_tracking::entry::TimeEntry;
use crate::time_tracking::filters::TimeFilter;
use crate::time_tracking::service::{
    AppliedTimeMutation, NewTimeEntry, TimeEntryEdit, TimeMutationRequest, apply,
};

/// Route one `tix time` subcommand.
///
/// The configuration is deliberately not taken: nothing in this family reads a
/// registry — the section, the flags and the arithmetic all live behind the service and
/// the snapshot — and a parameter a command does not use is a claim it does.
pub fn run(store: &Store, command: &TimeCommand) -> Result<()> {
    match command {
        TimeCommand::Add {
            issue,
            minutes,
            date,
            author,
            note,
        } => add(
            store,
            issue,
            *minutes,
            date.as_deref(),
            author,
            note.as_deref(),
        ),
        TimeCommand::Edit {
            issue,
            entry,
            change,
        } => edit(store, issue, entry, change),
        TimeCommand::Delete {
            issue,
            entry,
            reason,
            confirm,
        } => delete(store, issue, entry, reason.as_deref(), *confirm),
        TimeCommand::Show { issue } => show(store, issue),
        TimeCommand::History { issue } => history(store, issue),
        TimeCommand::Total { selector, filter } => total(store, selector.as_deref(), filter),
    }
}

// ---------------------------------------------------------------------------
// T020 — the mutations
// ---------------------------------------------------------------------------

/// `tix time add`: one create, through the shared service.
///
/// The date, the note and the identity are carried as the caller typed them — an
/// unreadable date is refused by the one entry validator, not by a second one here —
/// and the entry's id is the service's to mint.
fn add(
    store: &Store,
    issue: &str,
    minutes: i64,
    date: Option<&str>,
    author: &str,
    note: Option<&str>,
) -> Result<()> {
    let mut entry = NewTimeEntry::new(minutes, author);
    if let Some(date) = date {
        entry = entry.on(date);
    }
    if let Some(note) = note {
        entry = entry.with_note(note);
    }
    let applied = apply(store, &TimeMutationRequest::create(issue, entry))?;
    println!("{}", mutation_sentence(&applied));
    Ok(())
}

/// `tix time edit`: one correction, naming only the fields the caller replaced.
///
/// The patch is built from exactly the flags that were given — an edit that names no
/// field stays an empty edit and is refused by the service with `empty_edit`, rather
/// than here — and the reason rides on the request, where the service requires it.
fn edit(store: &Store, issue: &str, entry_id: &str, args: &TimeEditArgs) -> Result<()> {
    let mut change = TimeEntryEdit::new();
    if let Some(minutes) = args.minutes {
        change = change.duration(minutes);
    }
    if let Some(date) = args.date.as_deref() {
        change = change.date(date);
    }
    if args.clear_date {
        change = change.clear_date();
    }
    if let Some(note) = args.note.as_deref() {
        change = change.note(note);
    }
    if args.clear_note {
        change = change.clear_note();
    }
    if let Some(author) = args.author.as_deref() {
        change = change.author(author);
    }
    let request = TimeMutationRequest::edit(
        issue,
        entry_id,
        change,
        args.reason.clone().unwrap_or_default(),
    );
    let applied = apply(store, &request)?;
    println!("{}", mutation_sentence(&applied));
    Ok(())
}

/// The one sentence an unconfirmed deletion is refused with.
///
/// `pub(crate)` because the MCP surface refuses the same call in the same words: the
/// sentence is a refusal both surfaces owe the caller, so one owner is what keeps them
/// from wording it twice (C-006). The CLI reaches it through `delete`'s `--confirm`
/// gate and the MCP tool through its `confirm` argument.
pub(crate) const TIME_DELETE_CONFIRMATION: &str = "deleting a time entry needs --confirm: it removes the entry from the issue's \
     current entries, while its value and its event stay in History (`tix time history` \
     reads them back)";

/// `tix time delete`: remove one entry from the current projection.
///
/// The confirmation is checked **first**, so an unconfirmed deletion does not even read
/// the issue; the value and its event stay in History, where `tix time history` reads
/// them back.
fn delete(
    store: &Store,
    issue: &str,
    entry_id: &str,
    reason: Option<&str>,
    confirm: bool,
) -> Result<()> {
    if !confirm {
        return Err(TixError::InvalidInput(TIME_DELETE_CONFIRMATION.to_string()));
    }
    let request =
        TimeMutationRequest::delete(issue, entry_id, reason.unwrap_or_default().to_string());
    let applied = apply(store, &request)?;
    println!("{}", mutation_sentence(&applied));
    Ok(())
}

// ---------------------------------------------------------------------------
// T020/T022 — show and history
// ---------------------------------------------------------------------------

/// `tix time show <ISSUE>`: the issue's current entries and its total.
///
/// The issue is resolved by the crate's own selector grammar and then indexed by itself,
/// so an archived or otherwise off-view issue is still readable by the selector that
/// names it. Every current entry is listed, malformed ones included — a malformed entry
/// is *reported*, never hidden, and never blocks the read (C-005) — with each absent
/// value as `-`, and the total's `state` says whether the answer is `recorded`,
/// `nothing` (no entry) or `unknown` (entries, none usable).
fn show(store: &Store, selector: &str) -> Result<()> {
    let issue = store.resolve_issue(selector)?;
    let snapshot = TimeSnapshot::of(std::slice::from_ref(&issue));
    let filter = TimeFilter::new().for_issue(issue.number);
    println!("id\tminutes\tdate\tauthor\tnote");
    for indexed in snapshot.entries() {
        let entry = &indexed.entry;
        if !filter.selects(indexed.issue, entry) {
            continue;
        }
        println!(
            "{}\t{}\t{}\t{}\t{}",
            entry.id,
            number(entry.minutes()),
            cell(entry.date.as_deref()),
            cell(Some(entry.author.as_str())),
            cell(entry.note.as_deref()),
        );
    }
    let total = snapshot.total(&filter);
    print_scope(&total)?;
    render_findings(&total.diagnostics);
    Ok(())
}

/// `tix time history <ISSUE>`: the explicit audit view for one issue (T017, FR-005).
///
/// Current entries beside what History retains: how many entries the issue holds now,
/// and every prior value a deletion left behind, with the entry it named and who recorded
/// it when. Corrections are counted rather than re-rendered: the prior values live in the
/// `## History` line the mutation wrote, and re-parsing that grammar here would make this
/// file a second owner of a grammar WP02 already owns — so the count says a correction is
/// auditable and the file stays the one place its text is read.
fn history(store: &Store, selector: &str) -> Result<()> {
    let issue = store.resolve_issue(selector)?;
    let snapshot = TimeSnapshot::of(std::slice::from_ref(&issue));
    let filter = TimeFilter::new().for_issue(issue.number);
    let audit = snapshot.audit(&filter);
    println!("scope: {}", audit.filter.describe());
    println!(
        "current: {}",
        audit.issues.first().map_or(0, |issue| issue.current)
    );
    println!("deleted_count: {}", audit.deleted_count);
    println!("corrected_count: {}", audit.corrected_count);
    println!("entry\tdeleted_at\tdeleted_by");
    for issue in &audit.issues {
        for deletion in &issue.deletions {
            println!(
                "{}\t{}\t{}",
                cell(deletion.entry_id.as_deref()),
                cell(Some(deletion.deleted_at.as_str())),
                cell(Some(deletion.deleted_by.as_str())),
            );
        }
    }
    render_findings(&audit.diagnostics);
    Ok(())
}

// ---------------------------------------------------------------------------
// T021 — the totals, with the filters and the breakdown
// ---------------------------------------------------------------------------

/// `tix time total`: the scope's shared total, and optionally its breakdown.
///
/// The scope is the caller's: an issue (either spelling, never both), an identity, an
/// inclusive period, or any conjunction of them — all of it a [`TimeFilter`], which is
/// also what every total's `scope` line renders. The scope's own total is printed first
/// (so an empty breakdown still reads as the answer it is: `nothing`), then one block per
/// group when `--by` names a dimension. The whole read is one [`TimeSnapshot`] over the
/// project's **active** issues — the same enumeration `tix list` and `tix capacity`
/// use — so no two blocks can count a different membership (NFR-001). An explicit
/// selector that names an archived issue is refused rather than silently dropped, since
/// the two halves of that read would otherwise disagree (see [`selected_number`]).
fn total(store: &Store, selector: Option<&str>, args: &TimeTotalArgs) -> Result<()> {
    let selected = match (selector, args.issue) {
        (Some(_), Some(_)) => {
            return Err(TixError::InvalidInput(
                "a time total names its issue once: pass either the positional <ISSUE> or \
                 `--issue`, not both"
                    .to_string(),
            ));
        }
        (Some(selector), None) => Some(selected_number(store, selector)?),
        (None, Some(number)) => Some(stable_number(store, number)?),
        (None, None) => None,
    };
    // Every argument is checked before anything is printed, so a refusal never leaves a
    // half-total on stdout.
    let breakdown = parse_breakdown(args.by.as_deref())?;
    let mut filter = TimeFilter::new();
    if let Some(number) = selected {
        filter = filter.for_issue(number);
    }
    if let Some(assignee) = args.assignee.as_deref() {
        filter = filter.for_assignee(assignee);
    }
    if let Some(from) = args.from.as_deref() {
        filter = filter.since(from);
    }
    if let Some(to) = args.to.as_deref() {
        filter = filter.until(to);
    }
    if args.audit {
        filter = filter.including_deleted();
    }
    let snapshot = TimeSnapshot::of(&store.list()?);
    let scope = snapshot.total(&filter);
    print_scope(&scope)?;
    if let Some(breakdown) = breakdown {
        let groups = match breakdown {
            Breakdown::Issue => snapshot.by_issue(&filter),
            Breakdown::Assignee => snapshot.by_assignee(&filter),
            Breakdown::Date => snapshot.by_date(&filter),
        };
        for group in &groups {
            println!();
            print_scope(group)?;
        }
    }
    // The scope's findings already name every entry the selection reported — the groups
    // are a partition of the very same selection — so they render once, from the scope.
    render_findings(&scope.diagnostics);
    Ok(())
}

/// The stable number a positional selector names, refusing one the project scope cannot
/// answer for.
///
/// The selector resolves against **every** issue the store holds — an archived one
/// included — while [`total`]'s snapshot is the active enumeration. Those two halves
/// disagree for exactly one case, and it is refused here rather than reported as the
/// shared `unknown_issue` finding: the issue is neither unknown (it exists, and holds
/// the entries the caller is asking about) nor absent from the snapshot by accident, and
/// that finding's remedy — "read that issue into the scope, or drop the selector" — asks
/// for something the caller has already done and cannot do again from here.
///
/// A selector naming nothing at all is *not* refused here: the store's own `not_found`
/// (exit 2) is what a selector that resolves to no record gets, exactly as it does for
/// every other `tix` command.
fn selected_number(store: &Store, selector: &str) -> Result<u32> {
    let issue = store.resolve_issue(selector)?;
    if issue.archived {
        return Err(archived_refusal(&issue, selector));
    }
    Ok(issue.number)
}

/// The stable number `--issue` names, refusing an archived issue the same way.
///
/// A number no issue answers to is left alone: the snapshot will not hold it, and the
/// aggregation reports that as its own `unknown_issue` finding. Only the archived case —
/// an issue the snapshot *could* have held but deliberately does not — is this surface's
/// to name. A genuine read failure is propagated rather than being read as "not
/// archived".
fn stable_number(store: &Store, number: u32) -> Result<u32> {
    match store.get(IssueSelector::Number(number)) {
        Ok(issue) if issue.archived => Err(archived_refusal(&issue, &number.to_string())),
        Ok(_) => Ok(number),
        Err(TixError::NotFound(_)) => Ok(number),
        Err(other) => Err(other),
    }
}

/// Refuse an archived issue a project total cannot answer for, with a followable remedy.
///
/// The condition is named as it is — the issue is archived — and the remedy names the two
/// verbs that do read a single issue whatever its view: `show` indexes the one issue a
/// selector resolves, and `history` reads that issue's audit view.
///
/// `kind: archived_issue` is a **command-level** name rather than a new member of
/// [`crate::time_tracking::diagnostics::TimeDiagnosticKind`]: that vocabulary is WP03's
/// file, and none of its kinds says "archived" (`unknown_issue` is the closest and would
/// be false here). It is spelled in the same `kind: <snake_case>` note the shared findings
/// use, so nothing downstream has to learn a second shape.
///
/// `pub(crate)` because the MCP's `time_total` resolves the same selector against the
/// same enumeration and owes the caller the same refusal: the condition is one, and so
/// is the sentence (C-006).
pub(crate) fn archived_refusal(issue: &Issue, selector: &str) -> TixError {
    TixError::Refused(refusal_block(
        "archived_issue",
        &format!(
            "issue #{} is archived, and a project time total counts the active issues — exactly \
             as `tix list` and `tix capacity` do — so it cannot answer for one that is out of \
             the board",
            issue.number
        ),
        &[format!("issue: #{}", issue.number)],
        &format!(
            "read it by naming it: `tix time show {selector}` indexes the one issue a selector \
             resolves, and `tix time history {selector}` reads that issue's audit view"
        ),
    ))
}

/// The dimension a breakdown groups by (`--by`).
///
/// `pub(crate)` with [`parse_breakdown`] because the MCP's `time_total` groups by the
/// same three dimensions and refuses an unknown word with the same sentence: one
/// vocabulary, one parse (C-006).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum Breakdown {
    /// One total per issue.
    Issue,
    /// One total per identity that did work.
    Assignee,
    /// One total per calendar date.
    Date,
}

/// Parse `--by`. A well-formed but unknown word is a refusal naming the vocabulary, not a
/// guess — the shape [`crate::commands::capacity::parse_scope_kind`] uses. `all` is the
/// explicit spelling of "no breakdown": the scope's one ungrouped total, which is also
/// what the flag's absence means.
///
/// `pub(crate)` because the MCP's `time_total` takes the same `by` and owes the same
/// refusal for a word outside the vocabulary (C-006).
pub(crate) fn parse_breakdown(raw: Option<&str>) -> Result<Option<Breakdown>> {
    let Some(raw) = raw else {
        return Ok(None);
    };
    match raw.trim() {
        "all" => Ok(None),
        "issue" => Ok(Some(Breakdown::Issue)),
        "assignee" => Ok(Some(Breakdown::Assignee)),
        "date" => Ok(Some(Breakdown::Date)),
        other => Err(TixError::InvalidInput(format!(
            "unknown --by dimension {other:?}: the breakdown dimensions are `issue`, `assignee` \
             and `date` (or `all` for the scope's one ungrouped total)"
        ))),
    }
}

// ---------------------------------------------------------------------------
// Shared rendering
// ---------------------------------------------------------------------------

/// Print one total's own fields, or refuse the scope it could not answer.
///
/// A `state` of `invalid_filter` or `unknown_issue` is a *refusal*, not an answer: no
/// entry was evaluated, so there is no total to print, and the findings say what to fix.
/// Otherwise the block is [`scope_block`]'s, printed as the one thing this line owns.
fn print_scope(total: &TimeTotal) -> Result<()> {
    if matches!(
        total.state(),
        TimeTotalState::InvalidFilter | TimeTotalState::UnknownIssue
    ) {
        return Err(refusal(&total.diagnostics));
    }
    println!("{}", scope_block(total));
    Ok(())
}

/// The one block a total prints, whichever surface prints it.
///
/// Every line is a DTO field or a DTO's own rendering: the group's label, the filter's
/// scope, the state's stable spelling, the integer-minute sum, the counts beside it, and
/// the audit context — which is `-` unless `--audit` asked for it, because an
/// unrequested count and a zero count are different facts. `pub(crate)` because the MCP's
/// time reads print the same block: a total cannot be worded two ways (C-006).
pub(crate) fn scope_block(total: &TimeTotal) -> String {
    [
        format!("group: {}", total.group.label()),
        format!("scope: {}", total.filter.describe()),
        format!("state: {}", total.state().as_str()),
        format!("total_minutes: {}", number(total.total_minutes)),
        format!("entry_count: {}", total.entry_count),
        format!("malformed_count: {}", total.malformed_count),
        format!("undated_count: {}", total.undated_count),
        format!("deleted_count: {}", number(total.deleted_count)),
    ]
    .join("\n")
}

/// The scope refusals as one [`TixError::Refused`], carrying [`refusal_blocks`]' bytes.
fn refusal(diagnostics: &[TimeDiagnostic]) -> TixError {
    TixError::Refused(refusal_blocks(diagnostics))
}

/// The scope refusals as one rendered block, with their remedies.
///
/// Rendered at **error** severity, because the crate's own rule is that the rendered
/// level and the exit code agree (#1361, `commands::lint`): a refused scope exits
/// non-zero — no entry was evaluated, so there is no total to read — while a finding
/// beside a total is a warning that exits zero. [`TimeDiagnostic::render`] is therefore
/// deliberately *not* used here; its `warning[...]` level would print a warning and exit
/// non-zero, which is exactly the drift the rule exists to prevent. Everything else is
/// shared: the kind and the context come from the DTO's own fields, and the `help:` footer
/// is WP03's own remedy string, so a refusal still says what is wrong and what to do about
/// it in the vocabulary one place declares.
///
/// `pub(crate)` because the MCP's time reads refuse the same two states with the same
/// block: the CLI hands these bytes to `TixError::Refused` (which carries them verbatim,
/// keeping the block from being wrapped in a second, non-rustc prefix at the error
/// boundary) and the MCP tool returns them as its error text (C-006).
pub(crate) fn refusal_blocks(diagnostics: &[TimeDiagnostic]) -> String {
    diagnostics
        .iter()
        .map(|finding| {
            let mut notes = Vec::new();
            if let Some(field) = finding.field {
                notes.push(format!("field: {field}"));
            }
            if let Some(issue) = finding.issue {
                notes.push(format!("issue: #{issue}"));
            }
            refusal_block(
                finding.kind.as_str(),
                &finding.reason,
                &notes,
                &finding.remedy,
            )
        })
        .collect::<Vec<String>>()
        .join("\n")
}

/// One refusal as a rustc-style error block.
///
/// The reason is the headline, the `kind:` note names the condition machine-readably, the
/// caller's notes carry whatever context it has, and the remedy is the `help:` footer —
/// the shape every refuse-or-explain value in the crate renders.
fn refusal_block(kind: &str, reason: &str, notes: &[String], remedy: &str) -> String {
    let mut diagnostic =
        Diagnostic::error("E-tix-time", reason.to_string()).with_note(format!("kind: {kind}"));
    for note in notes {
        diagnostic = diagnostic.with_note(note.clone());
    }
    diagnostic.with_help(remedy.to_string()).render()
}

/// Render findings through the shared renderer, to stderr.
fn render_findings(diagnostics: &[TimeDiagnostic]) {
    for finding in diagnostics {
        eprintln!("{}", finding.render());
    }
}

/// One side of a mutation line: an entry's own values, in the surface's own rendering.
///
/// Deliberately **not** WP02's `entry_summary`, which is the `## History` detail line's
/// value slot: there an absent duration must be marked `?m` (the slot has to hold
/// something, and a zero would be a lie), a missing author is `?`, and an absent date is
/// omitted. This line is user-facing and prints beside `show`'s table and the totals,
/// which mark an absent value `-`; one surface, one mark, and every line the same shape —
/// `120m on 2026-09-25 by alice: note`, and `- on - by -` for an entry the file left
/// empty. The minute unit is the documented precision both renderings share.
///
/// `None` is the untouched side of an edit, which no mutation line reaches with values to
/// print.
fn values(entry: Option<&TimeEntry>) -> String {
    let Some(entry) = entry else {
        return "-".to_string();
    };
    let mut out = entry
        .minutes()
        .map_or_else(|| "-".to_string(), |minutes| format!("{minutes}m"));
    out.push_str(&format!(" on {}", cell(entry.date.as_deref())));
    out.push_str(&format!(" by {}", cell(Some(entry.author.as_str()))));
    if let Some(note) = entry.note.as_deref() {
        out.push_str(&format!(": {}", cell(Some(note))));
    }
    out
}

/// The one sentence a time mutation prints, from the service's own outcome.
///
/// The verb is the outcome's shape rather than a parameter: a create has no prior value,
/// a correction carries both sides, a deletion only the prior one, and the one no-op — a
/// request that asked for exactly what was already there, so no event was appended and
/// `updated` was not bumped — is `changed: false` and prints `Unchanged`.
///
/// `pub(crate)` because the MCP's mutation tools answer with this sentence as their own
/// text: a mutation cannot be worded two ways (C-006). The values are [`values`]' own
/// rendering, which is the user-facing one — an absent minute, date, author or note prints
/// as `-` and never as a zero — and deliberately not WP02's `entry_summary`, which marks
/// the value slot of a `## History` detail line.
pub(crate) fn mutation_sentence(applied: &AppliedTimeMutation) -> String {
    let outcome = &applied.outcome;
    let number = applied.issue.number;
    if !outcome.changed {
        return format!(
            "Unchanged {} on #{number}: {}",
            outcome.entry_id,
            values(outcome.after.as_ref()),
        );
    }
    if outcome.before.is_none() {
        return format!(
            "Added {} to #{number}: {}",
            outcome.entry_id,
            values(outcome.after.as_ref()),
        );
    }
    if outcome.after.is_some() {
        return format!(
            "Updated {} on #{number}: {} -> {}",
            outcome.entry_id,
            values(outcome.before.as_ref()),
            values(outcome.after.as_ref()),
        );
    }
    format!(
        "Deleted {} from #{number}: {}",
        outcome.entry_id,
        values(outcome.before.as_ref()),
    )
}

/// An absent number as `-`, the crate's convention for "no value" — and the reason a
/// zero total and a scope with nothing to total do not print the same bytes.
///
/// `pub(crate)` because the MCP's time tables print the same mark in the same cell
/// (C-006).
pub(crate) fn number<T: std::fmt::Display>(value: Option<T>) -> String {
    value.map_or_else(|| "-".to_string(), |value| value.to_string())
}

/// One table cell: `-` when the value is absent or blank, and one line whatever the file
/// holds.
///
/// The collapse is the renderer's own guarantee, not the caller's: a hand-edited note
/// that is a YAML literal block round-trips a line break, and a table row that broke
/// across two lines would misread as a field nobody wrote. The finding beside the row
/// still reports the value as malformed, so nothing is hidden by rendering it on one line.
///
/// `pub(crate)` because the MCP's entry and audit tables collapse a cell the same way
/// (C-006).
pub(crate) fn cell(value: Option<&str>) -> String {
    let value = value.unwrap_or_default().trim();
    if value.is_empty() {
        return "-".to_string();
    }
    value
        .chars()
        .map(|ch| if ch == '\n' || ch == '\r' { ' ' } else { ch })
        .collect()
}