tix-tracker 0.12.0

//! `tix capacity`: the CLI adapter over the shared capacity service (mission
//! `cycle-capacity-planning-01M3C85C`, WP05, T025–T029).
//!
//! Parse, call, print. Nothing here computes a total, rounds a percentage, folds a scope
//! identity, or writes a file. The section and its refusals are
//! [`crate::capacity::config`]'s (`set_capacity`, `validate`, `validate_cycle_references`,
//! `ensure_cycle_editable`), the one-pass index and a scope's membership are
//! [`crate::capacity::scope`]'s, the only formula and the only rounding policy are
//! [`crate::capacity::calculate`]'s, the findings are [`crate::capacity::warning`]'s, and
//! the close evidence is [`crate::capacity::snapshot`]'s. A number this module prints is a
//! number the DTO held — C-007's one-DTO rule, and the reason `calculate` has no
//! arithmetic in it at all.
//!
//! # The commands
//!
//! * `tix capacity list` — one tab-separated row per configured entry.
//! * `tix capacity show <REFERENCE> [--scope <KIND>]` — one entry, by the reference it
//!   names (a cycle's name or stable id, a team label, an assignee identity).
//! * `tix capacity set --scope <KIND> --id <REFERENCE> --value <N> --unit <UNIT>
//!   [--disabled]` — configure one scope's ceiling, through [`set_capacity`].
//! * `tix capacity delete --scope <KIND> --id <REFERENCE>` — remove one entry.
//! * `tix capacity calculate --scope <KIND> --id <REFERENCE> [--warnings]` — the shared
//!   [`CapacityCalculation`], every field of it.
//! * `tix capacity snapshot <CYCLE> [--warnings]` — read back a closed cycle's immutable
//!   evidence.
//!
//! # stdout is the result, stderr is the diagnostic
//!
//! The values go to stdout, one `key: value` per line (the shape `tix cycle schedule
//! show` uses), because that is the text a script reads. Findings render through
//! [`CapacityWarning::render`] to **stderr**, the way `tix wip show` renders its own
//! snapshot diagnostics: a diagnostic interleaved into the value lines would be a parse
//! error rather than a warning.
//!
//! A finding about one issue's estimate or about a reference that did not resolve means
//! the numbers are **incomplete** — an issue that could not be counted in the scope's
//! unit contributes nothing and is not a zero (C-004) — so it always renders. The
//! overflow report is a report about a complete calculation, so it renders only when
//! `--warnings` is given (FR-003; the `overflow:` value itself is always on stdout).
//!
//! # The entry handle, and the identity it is derived from
//!
//! An entry's `[capacity.<id>]` key is derived from the **identity** its scope resolves
//! to: `<kind>-<slug(identity)>`, where the identity is the label
//! [`CapacityScope::new`] yields (a generated instance's *name* for its stable id, an
//! assignee's canonical handle, a team label, a hand-written cycle's name). The crate's
//! one [`crate::slug::slugify`] turns that into a key, so the two spellings of one
//! generated cycle — its stable id and its name — derive one handle, and re-running
//! `set` for that scope updates that entry rather than adding a second one.
//!
//! The handle is a **naming** choice, never an identity: nothing reads a scope back
//! through it. `show` and `delete` match on the resolved label itself, so a hand-written
//! entry whose key this CLI never derived is reachable by the scope it declares, and a
//! generated instance is readable and removable under either spelling. Two *different*
//! labels can still slug to one key (`Platform` and `platform`); `set` refuses that case
//! naming the scope it would have replaced, so the collision can never silently destroy
//! a ceiling.
//!
//! # Nothing is written when a command is refused
//!
//! `set` goes through [`set_capacity`], which stages the change on a copy, runs the
//! closed-cycle gate and both validation halves, and commits only once they pass — so a
//! refusal leaves `tix.toml` byte-identical. `delete` mirrors that shape (gate, stage,
//! validate, save, commit) with the same [`CapacityEdit::Configure`] authorization, so
//! deleting a closed cycle's ceiling is refused exactly as setting one is. A `set` whose
//! derived handle is already another scope's is refused before anything is staged. No
//! command here opens a snapshot or an issue for writing: `calculate` and `snapshot` are
//! reads, and an overflow is a report, never a mutation (C-006).
//!
//! # The close seam
//!
//! `with_close_capacity` is the other half of this file's job (T028): the one rule a
//! **close** passes its lifecycle request through. The calculation is computed there —
//! a close site owns the project configuration and the issue store, while the
//! lifecycle's `apply` deliberately owns neither
//! ([`LifecycleRequest::capacity`] is the caller's) — and it is never recomputed inside
//! the store. Routing every surface's close through that one seam is what keeps the
//! CLI, the TUI and MCP capturing one payload (NFR-003) rather than three.

use std::path::{Path, PathBuf};

use crate::capacity::calculate::{CapacityCalculation, CapacityScope};
use crate::capacity::config::{
    CapacityEdit, CapacityEntry, CapacityExtensions, CapacityScopeKind, ensure_cycle_editable,
    set_capacity, validate, validate_cycle_references,
};
use crate::capacity::scope::IssueSnapshot;
use crate::capacity::snapshot::CapacitySnapshot;
use crate::capacity::warning::{CapacityWarning, CapacityWarningKind};
use crate::capacity::{resolve_cycle, schedule_index};
use crate::cli::CapacityCommand;
use crate::config::Config;
use crate::cycle_schedule::identity::{CycleReference, ScheduleIndex};
use crate::cycle_schedule::lifecycle::{LifecycleAction, LifecycleRequest};
use crate::cycle_schedule::snapshot::CycleSnapshotStore;
use crate::cycle_store::CycleStore;
use crate::error::{Result, TixError};
use crate::storage::Store;

/// Route one `tix capacity` subcommand.
pub fn run(config: &mut Config, store: &Store, command: &CapacityCommand) -> Result<()> {
    let root = root_from_store(store);
    match command {
        CapacityCommand::List => list(config, &root),
        CapacityCommand::Show { reference, scope } => {
            show(config, &root, scope.as_deref(), reference)
        }
        CapacityCommand::Set {
            scope,
            id,
            value,
            unit,
            disabled,
        } => set(config, &root, scope, id, *value, unit, *disabled),
        CapacityCommand::Delete { scope, id } => delete(config, &root, scope, id),
        CapacityCommand::Calculate {
            scope,
            id,
            warnings,
        } => calculate(config, store, &root, scope, id, *warnings),
        CapacityCommand::Snapshot { cycle, warnings } => {
            read_snapshot(config, &root, cycle, *warnings)
        }
    }
}

/// The project root the cycle records, the snapshots and `tix.toml` resolve against —
/// the same walk `commands::cycle` and `commands::views` do, so a subcommand writes the
/// file every other command reads.
fn root_from_store(store: &Store) -> PathBuf {
    Config::project_root(&store.issues_dir).unwrap_or_else(|| PathBuf::from("."))
}

// ---------------------------------------------------------------------------
// The snapshot + index pair every calculation reads (WP02/WP03)
// ---------------------------------------------------------------------------

/// The schedule index and the one-pass issue snapshot a capacity calculation reads.
///
/// The snapshot is built **with** the index that produced it, so the pair a caller hands
/// to [`CapacityCalculation::for_scope`] is the reading the numbers were indexed
/// against — never a second pass that could count a different membership (NFR-001).
pub(crate) fn snapshot_for(
    config: &Config,
    root: &Path,
    store: &Store,
) -> Result<(ScheduleIndex, IssueSnapshot)> {
    let index = schedule_index(config, root)?;
    let snapshot = IssueSnapshot::build(config, &index, &store.list()?);
    Ok((index, snapshot))
}

/// The shared calculation for one scope — the single entry point both `tix capacity
/// calculate` and the cycle-close site call, so the two cannot run different arithmetic.
pub(crate) fn calculation_for(
    config: &Config,
    root: &Path,
    store: &Store,
    kind: CapacityScopeKind,
    reference: &str,
) -> Result<CapacityCalculation> {
    let (index, snapshot) = snapshot_for(config, root, store)?;
    let scope = CapacityScope::new(kind, reference, &index);
    Ok(CapacityCalculation::for_scope(
        &snapshot, &index, config, scope,
    ))
}

/// Attach the capacity evidence a **close** records — the one seam every surface's
/// close site passes its request through (WP05, T028).
///
/// The calculation is computed here because the close sites own the project
/// configuration and the issue store, while the lifecycle's `apply` deliberately owns
/// neither ([`LifecycleRequest::capacity`]). The rule lives in **one** place so the CLI,
/// the TUI and the MCP tool cannot drift into capturing three different payloads
/// (NFR-003), which is why the signature needs nothing a close site does not already
/// hold. The scope is the instance's own name, which the identity adapter folds with its
/// stable id — a ceiling declared under either spelling is the one this close captures.
///
/// Nothing is read for any other action, and a close that named no instance, or named
/// one no record answers to, is returned unchanged — the lifecycle refuses both before
/// writing anything.
pub(crate) fn with_close_capacity(
    request: LifecycleRequest,
    config: &Config,
    root: &Path,
    store: &Store,
) -> Result<LifecycleRequest> {
    if request.action != LifecycleAction::Close {
        return Ok(request);
    }
    let Some(cycle_id) = request.cycle_id.clone() else {
        return Ok(request);
    };
    let (index, snapshot) = snapshot_for(config, root, store)?;
    let Some(cycle) = index.cycle(&cycle_id) else {
        return Ok(request);
    };
    let scope = CapacityScope::new(CapacityScopeKind::Cycle, &cycle.name, &index);
    Ok(request.with_capacity(CapacityCalculation::for_scope(
        &snapshot, &index, config, scope,
    )))
}

// ---------------------------------------------------------------------------
// T025/T026 — list, show, set, delete
// ---------------------------------------------------------------------------

/// `tix capacity list`: every configured entry, in declaration order.
///
/// The `display` column is the label the reference resolves to
/// ([`CapacityScope::new`]) — the same resolution the calculation matches a ceiling by,
/// so a reader can see that a stable id and a name are one scope.
fn list(config: &Config, root: &Path) -> Result<()> {
    let index = schedule_index(config, root)?;
    println!("id\tscope\treference\tdisplay\tcapacity\tunit\tenabled");
    for (id, entry) in config.capacity.iter() {
        // A loaded section is validated, so every entry names exactly one scope.
        let Some(kind) = entry.scope_kind() else {
            continue;
        };
        let reference = entry.scope_id().unwrap_or_default();
        let display = scope_label(kind, reference, &index);
        println!(
            "{id}\t{kind}\t{reference}\t{display}\t{ceiling}\t{unit}\t{enabled}",
            kind = kind.as_str(),
            ceiling = number(entry.capacity),
            unit = entry.unit.as_deref().unwrap_or("-"),
            enabled = entry.enabled,
        );
    }
    Ok(())
}

/// `tix capacity show <REFERENCE>`: one entry, by the scope the reference resolves to.
fn show(config: &Config, root: &Path, scope: Option<&str>, reference: &str) -> Result<()> {
    let wanted = scope.map(parse_scope_kind).transpose()?;
    let index = schedule_index(config, root)?;
    let (id, kind, entry) = one_entry(config, wanted, reference, &index)?;
    let display = scope_label(kind, entry.scope_id().unwrap_or_default(), &index);
    println!("id: {id}");
    println!("scope: {}", kind.as_str());
    println!("reference: {}", entry.scope_id().unwrap_or_default());
    println!("display: {display}");
    println!("capacity: {}", number(entry.capacity));
    println!("unit: {}", entry.unit.as_deref().unwrap_or("-"));
    println!("enabled: {}", entry.enabled);
    Ok(())
}

/// `tix capacity set`: configure one scope's ceiling through the shared write path.
///
/// The entry's handle is derived from the **identity** the reference resolves to, its
/// unknown metadata is carried over from an entry already under that handle, and
/// everything else — the scope's resolution, the unit's declaration, the one-ceiling
/// rule, the closed-cycle refusal — is [`set_capacity`]'s. A handle already held by a
/// *different* scope is refused before anything is staged: two labels can slug to one
/// handle (`Platform` and `platform`), and one scope's ceiling must never silently
/// become another's.
fn set(
    config: &mut Config,
    root: &Path,
    scope: &str,
    id: &str,
    value: i64,
    unit: &str,
    disabled: bool,
) -> Result<()> {
    let kind = parse_scope_kind(scope)?;
    let reference = required("--id", id)?;
    let unit = required("--unit", unit)?;
    let index = schedule_index(config, root)?;
    let label = scope_label(kind, reference, &index);
    let key = capacity_key(kind, &label);
    // The handle is a naming choice, so a collision is this surface's to refuse: the
    // library's one-ceiling rule keys on identity and would not see two *different*
    // scopes that slug alike — nor a hand-written entry of another kind that happens to
    // sit on this handle.
    let occupied = config.capacity.get(&key).map(|entry| {
        (
            entry.scope_kind(),
            entry.scope_id().unwrap_or_default().to_string(),
        )
    });
    if let Some((occupied_kind, occupied_scope)) = occupied {
        let same_scope =
            occupied_kind == Some(kind) && scope_label(kind, &occupied_scope, &index) == label;
        if !same_scope {
            let occupied = occupied_kind.map_or_else(
                || format!("an entry naming no single scope (`{occupied_scope}`)"),
                |occupied_kind| format!("{kind} `{occupied_scope}`", kind = occupied_kind.as_str()),
            );
            let remedy = occupied_kind.map_or_else(
                || "Remove that entry first".to_string(),
                |occupied_kind| {
                    format!(
                        "Update the configured scope by naming it exactly (`--id \
                         {occupied_scope}`), or remove it first (`tix capacity delete --scope \
                         {kind} --id {occupied_scope}`)",
                        kind = occupied_kind.as_str(),
                    )
                },
            );
            return Err(TixError::Config(format!(
                "`capacity.{key}` already configures {occupied}, which resolves to the same entry \
                 handle as `--id {reference}`; writing it would replace that ceiling. {remedy}"
            )));
        }
    }
    let mut entry = CapacityEntry {
        capacity: Some(value),
        unit: Some(unit.to_string()),
        enabled: !disabled,
        // A key this section already uses keeps its unknown metadata: the section's
        // promise is that a key a newer `tix` added survives an edit, and this edit is
        // no exception. The value is read by handle, never re-derived from the scope.
        extensions: config
            .capacity
            .get(&key)
            .map_or_else(CapacityExtensions::default, |entry| {
                entry.extensions.clone()
            }),
        ..CapacityEntry::default()
    };
    match kind {
        CapacityScopeKind::Cycle => entry.cycle = Some(reference.to_string()),
        CapacityScopeKind::Team => entry.team = Some(reference.to_string()),
        CapacityScopeKind::Assignee => entry.assignee = Some(reference.to_string()),
    }
    set_capacity(config, &key, entry, &CapacityEdit::Configure, root)?;
    println!(
        "Set capacity for {kind} `{reference}`: {value}{unit}{disabled}",
        kind = kind.as_str(),
        disabled = if disabled { " (disabled)" } else { "" },
    );
    Ok(())
}

/// `tix capacity delete`: remove one entry, through the same boundary a set passes.
fn delete(config: &mut Config, root: &Path, scope: &str, id: &str) -> Result<()> {
    let kind = parse_scope_kind(scope)?;
    let reference = required("--id", id)?;
    let index = schedule_index(config, root)?;
    let (key, _, target) = one_entry(config, Some(kind), reference, &index)?;
    // C-008: a closed cycle's capacity is the historical record, and removing its
    // ceiling is an ordinary configuration change, so it passes the same gate a `set`
    // does — before anything is staged.
    if kind == CapacityScopeKind::Cycle
        && let Some(reference) = target.scope_id()
    {
        ensure_cycle_editable_for(config, root, reference)?;
    }
    let key = key.to_string();
    // The shape `set_capacity` uses: stage on a copy, validate both halves, commit only
    // once they pass, so a refusal cannot leave a half-applied section behind.
    let mut candidate = config.clone();
    candidate.capacity.entries_mut().shift_remove(&key);
    validate(&candidate.capacity, &candidate)?;
    validate_cycle_references(&candidate.capacity, &candidate, root)?;
    candidate.save(&root.join("tix.toml"))?;
    *config = candidate;
    println!("Removed capacity for {kind} `{reference}`");
    Ok(())
}

// ---------------------------------------------------------------------------
// T027 — calculate, and the one warning policy
// ---------------------------------------------------------------------------

/// `tix capacity calculate`: the shared DTO, every field of it, and the findings.
///
/// There is no arithmetic here: `committed`, `completed`, `remaining`, `overflow` and
/// `utilization` are the values [`CapacityCalculation::for_scope`] derived, and an
/// absent one prints as `-` rather than as a zero (an unconfigured scope is not a scope
/// with zero capacity, and an uncountable one is not a zero total).
fn calculate(
    config: &Config,
    store: &Store,
    root: &Path,
    scope: &str,
    id: &str,
    warnings: bool,
) -> Result<()> {
    let kind = parse_scope_kind(scope)?;
    let reference = required("--id", id)?;
    let calculation = calculation_for(config, root, store, kind, reference)?;
    print_calculation(&calculation);
    render_findings(&calculation.diagnostics, warnings);
    Ok(())
}

/// The DTO's own fields as one text block, in the shape `tix cycle schedule show` prints
/// — the exact bytes [`print_calculation`] writes to stdout, and the text the MCP surface
/// returns, so the two cannot word one calculation two ways (C-007/NFR-003). A number
/// this prints is a number the DTO held.
pub(crate) fn calculation_text(calculation: &CapacityCalculation) -> String {
    format!(
        "scope: {scope}\nreference: {reference}\ndisplay: {display}\nstate: {state}\n\
         capacity: {capacity}\nunit: {unit}\ncommitted: {committed}\ncompleted: {completed}\n\
         remaining: {remaining}\noverflow: {overflow}\nutilization: {utilization}\n\
         counted_issues: {counted}\nuncounted_issues: {uncounted}\n\
         unestimated_issues: {unestimated}\nsource_issues: {source_issues}\n\
         source_units: {source_units}\ndiagnostics: {diagnostics}\n",
        scope = calculation.scope.kind.as_str(),
        reference = calculation.scope.reference,
        display = calculation.scope.display,
        state = calculation.state().as_str(),
        capacity = number(calculation.capacity),
        unit = calculation.unit.as_deref().unwrap_or("-"),
        committed = number(calculation.committed),
        completed = number(calculation.completed),
        remaining = number(calculation.remaining),
        overflow = number(calculation.overflow),
        utilization = utilization(calculation.utilization),
        counted = number(calculation.counted_issues),
        uncounted = number(calculation.uncounted_issues),
        unestimated = number(calculation.unestimated_issues),
        source_issues = calculation.source.issues,
        source_units = joined(&calculation.source.units),
        diagnostics = calculation.diagnostics.len(),
    )
}

/// The DTO's own fields, in the shape `tix cycle schedule show` prints.
fn print_calculation(calculation: &CapacityCalculation) {
    print!("{}", calculation_text(calculation));
}

/// Render the findings, through the shared [`CapacityWarning::render`].
///
/// A finding about an estimate or a reference explains why a total is short, so it is
/// always printed; the overflow report is the opt-in half of the same set, and carries
/// the scope, the committed value, the ceiling, the excess and the unit (C-006).
fn render_findings(diagnostics: &[CapacityWarning], overflow: bool) {
    for warning in diagnostics {
        if overflow || !matches!(warning.kind, CapacityWarningKind::Overflow) {
            eprintln!("{}", warning.render());
        }
    }
}

// ---------------------------------------------------------------------------
// T028 — the close evidence, read back
// ---------------------------------------------------------------------------

/// `tix capacity snapshot <CYCLE>`: a closed cycle's immutable capacity evidence.
///
/// A pure read through the existing snapshot store and the WP04 reader. A cycle with no
/// snapshot at all is a `not_found` (the command asked for something that is not there);
/// a snapshot that carries no capacity payload — written before this mission, or by a
/// close whose request carried no calculation — is `evidence: none`, a value and never
/// an error, so a legacy record stays readable.
fn read_snapshot(config: &Config, root: &Path, cycle: &str, warnings: bool) -> Result<()> {
    let index = schedule_index(config, root)?;
    let cycle_id = match resolve_cycle(&index, cycle) {
        CycleReference::Generated { id, .. } => id,
        CycleReference::Legacy { .. } => {
            return Err(TixError::NotFound(format!(
                "cycle `{cycle}` is a hand-written cycle and has no generated snapshot; \
                 `tix capacity snapshot` reads the evidence a generated cycle's close captured"
            )));
        }
        CycleReference::Unknown { .. } => {
            return Err(TixError::NotFound(format!(
                "no cycle `{cycle}` resolves to a record, so there is no snapshot to read"
            )));
        }
    };
    let store = CycleSnapshotStore::new(root);
    let Some(stored) = store.read(&cycle_id)? else {
        return Err(TixError::NotFound(format!(
            "cycle `{cycle_id}` has no snapshot: it has not been closed, or its snapshot was \
             removed"
        )));
    };
    println!("cycle: {cycle_id}");
    println!(
        "snapshot: docs/cycle_snapshots/{filename}",
        filename = CycleSnapshotStore::filename_for(&cycle_id)
    );
    match CapacitySnapshot::from_cycle_snapshot(&stored)? {
        None => {
            println!("evidence: none");
            eprintln!(
                "note: this snapshot carries no capacity payload; it was written before capacity \
                 evidence was captured, and it is not an error — nothing is migrated in place"
            );
        }
        Some(evidence) => {
            println!("evidence: present");
            print_evidence(&evidence);
            render_findings(&evidence.diagnostics, warnings);
        }
    }
    Ok(())
}

/// The stored evidence's own fields as one text block, exactly as the close wrote them —
/// the bytes [`print_evidence`] appends to stdout, and the text the MCP surface returns,
/// so the two cannot word one snapshot two ways (C-007/NFR-003).
pub(crate) fn evidence_text(evidence: &CapacitySnapshot) -> String {
    format!(
        "snapshot_id: {snapshot_id}\nclosed_at: {closed_at}\nclosed_by: {closed_by}\n\
         scope: {scope}\nreference: {reference}\ndisplay: {display}\nstate: {state}\n\
         capacity: {capacity}\nunit: {unit}\ncommitted: {committed}\ncompleted: {completed}\n\
         remaining: {remaining}\noverflow: {overflow}\nutilization: {utilization}\n\
         counted_issues: {counted}\nuncounted_issues: {uncounted}\n\
         unestimated_issues: {unestimated}\nsource_issues: {source_issues}\n\
         source_units: {source_units}\ndiagnostics: {diagnostics}\n",
        snapshot_id = evidence.snapshot_id,
        closed_at = evidence.closed_at,
        closed_by = evidence.closed_by,
        scope = evidence.scope.kind.as_str(),
        reference = evidence.scope.reference,
        display = evidence.scope.display,
        state = evidence.state.as_str(),
        capacity = number(evidence.capacity),
        unit = evidence.unit.as_deref().unwrap_or("-"),
        committed = number(evidence.committed),
        completed = number(evidence.completed),
        remaining = number(evidence.remaining),
        overflow = number(evidence.overflow),
        utilization = utilization(evidence.utilization),
        counted = number(evidence.counted_issues),
        uncounted = number(evidence.uncounted_issues),
        unestimated = number(evidence.unestimated_issues),
        source_issues = evidence.source.issues,
        source_units = joined(&evidence.source.units),
        diagnostics = evidence.diagnostics.len(),
    )
}

/// The stored evidence's own fields, exactly as the close wrote them.
fn print_evidence(evidence: &CapacitySnapshot) {
    print!("{}", evidence_text(evidence));
}

// ---------------------------------------------------------------------------
// Shared helpers
// ---------------------------------------------------------------------------

/// Parse `--scope`. A well-formed but unknown word is a refusal naming the vocabulary,
/// not a guess (the shape `commands::views::parse_scope_kind` uses).
pub(crate) fn parse_scope_kind(raw: &str) -> Result<CapacityScopeKind> {
    match raw {
        "cycle" => Ok(CapacityScopeKind::Cycle),
        "team" => Ok(CapacityScopeKind::Team),
        "assignee" => Ok(CapacityScopeKind::Assignee),
        other => Err(TixError::InvalidInput(format!(
            "`{other}` is not a capacity scope; expected one of `{}`",
            CapacityScopeKind::all()
                .iter()
                .map(|kind| kind.as_str())
                .collect::<Vec<_>>()
                .join("`, `")
        ))),
    }
}

/// A flag value that must be present and non-blank, named as the user typed it.
pub(crate) fn required<'a>(flag: &str, value: &'a str) -> Result<&'a str> {
    let trimmed = value.trim();
    if trimmed.is_empty() {
        return Err(TixError::InvalidInput(format!(
            "`{flag}` must not be blank"
        )));
    }
    if trimmed != value {
        return Err(TixError::InvalidInput(format!(
            "`{flag}` (`{value}`) has leading or trailing whitespace"
        )));
    }
    Ok(value)
}

/// The identity label a scope reference resolves to — **the library's own resolution**.
///
/// [`CapacityScope::new`] is the crate's reference-to-scope adapter for a capacity scope:
/// a generated cycle's stable id resolves to the instance's name, an assignee handle is
/// canonicalised by the model's own parser, a team label and a hand-written cycle name
/// stay themselves, and a reference nothing answers to keeps the text the caller wrote.
/// Two spellings of one scope therefore yield one label here, which is what makes a
/// ceiling configured under a stable id readable, updatable and removable under the
/// instance's name (C-003's "a legacy cycle name and generated stable cycle ID are
/// resolved through one adapter"), while two genuinely unresolvable names stay distinct.
pub(crate) fn scope_label(
    kind: CapacityScopeKind,
    reference: &str,
    index: &ScheduleIndex,
) -> String {
    CapacityScope::new(kind, reference, index).display
}

/// The `[capacity.<id>]` handle a scope's **resolved identity** derives.
///
/// Derived, never resolved: nothing reads a scope back through the handle
/// ([`CapacityCalculation::for_scope`] folds the reference itself), so this is a naming
/// choice that exists to make `set` idempotent for one scope across its spellings — the
/// instance's stable id and its name derive one handle, because they resolve to one
/// label. [`crate::slug::slugify`] is the crate's one slug, so two *different* labels can
/// still collide on one handle (`Platform` and `platform`); `set` refuses that case
/// rather than letting one scope's ceiling become another's.
fn capacity_key(kind: CapacityScopeKind, label: &str) -> String {
    format!(
        "{kind}-{slug}",
        kind = kind.as_str(),
        slug = crate::slug::slugify(label)
    )
}

/// Every entry that answers to `reference`, by the **identity** its scope resolves to,
/// optionally restricted to one scope kind. The entry's kind and reference are resolved
/// here, so a caller never has to ask a validated section's entry again.
///
/// Matching on the resolved label — not on the entry's key and not on its scope text — is
/// what lets a generated instance's id and its name select one ceiling, and it keeps a
/// hand-written entry (whose key this CLI never derived) reachable by the scope it
/// declares.
pub(crate) fn entries_matching<'a>(
    config: &'a Config,
    kind: Option<CapacityScopeKind>,
    reference: &str,
    index: &ScheduleIndex,
) -> Vec<(&'a str, CapacityScopeKind, &'a CapacityEntry)> {
    config
        .capacity
        .iter()
        .filter_map(|(id, entry)| {
            let entry_kind = entry.scope_kind()?;
            if kind.is_some_and(|wanted| wanted != entry_kind) {
                return None;
            }
            let entry_label = scope_label(entry_kind, entry.scope_id()?, index);
            (entry_label == scope_label(entry_kind, reference, index))
                .then_some((id, entry_kind, entry))
        })
        .collect()
}

/// The one entry a reference names, or the refusal saying why it is none or several.
pub(crate) fn one_entry<'a>(
    config: &'a Config,
    kind: Option<CapacityScopeKind>,
    reference: &str,
    index: &ScheduleIndex,
) -> Result<(&'a str, CapacityScopeKind, &'a CapacityEntry)> {
    let matches = entries_matching(config, kind, reference, index);
    match matches.as_slice() {
        [] => Err(TixError::NotFound(match kind {
            Some(kind) => format!(
                "no capacity entry for {kind} `{reference}`; configure one with `tix capacity \
                 set --scope {kind} --id {reference} --value <N> --unit <UNIT>`"
            ),
            None => format!(
                "no capacity entry names `{reference}`; `tix capacity list` shows the configured \
                 scopes"
            ),
        })),
        [(id, kind, entry)] => Ok((*id, *kind, *entry)),
        many => {
            let listed = many
                .iter()
                .map(|(id, kind, entry)| {
                    format!(
                        "`{id}` ({kind} `{scope}`)",
                        kind = kind.as_str(),
                        scope = entry.scope_id().unwrap_or_default()
                    )
                })
                .collect::<Vec<_>>()
                .join(", ");
            Err(TixError::InvalidInput(format!(
                "`{reference}` matches {} capacity entries: {listed}; pass `--scope` to name one",
                many.len()
            )))
        }
    }
}

/// The closed-cycle boundary for a delete, through the library's own resolution.
///
/// [`set_capacity`] gates a `set` on its own; a `delete` is the other ordinary
/// configuration change, so it consults the same [`ensure_cycle_editable`] with the same
/// [`CapacityEdit::Configure`]. The record is found by the identity
/// [`resolve_cycle`] answers with — the reference is never re-folded here. A reference
/// no record answers to has no lifecycle state to consult, which is the same answer
/// [`set_capacity`] reaches.
fn ensure_cycle_editable_for(config: &Config, root: &Path, reference: &str) -> Result<()> {
    let records = CycleStore::new(root).list()?;
    let index = ScheduleIndex::build(config, &records);
    let name = match resolve_cycle(&index, reference) {
        CycleReference::Generated { name, .. } | CycleReference::Legacy { name } => name,
        CycleReference::Unknown { .. } => return Ok(()),
    };
    if let Some(record) = records.iter().find(|record| record.name == name) {
        ensure_cycle_editable(record, &CapacityEdit::Configure)?;
    }
    Ok(())
}

/// An absent number as `-`, the crate's convention for "no value" (never a zero).
pub(crate) fn number<T: std::fmt::Display>(value: Option<T>) -> String {
    value.map_or_else(|| "-".to_string(), |value| value.to_string())
}

/// A utilization percentage as the DTO's `u32` — `-` when the ceiling was zero or absent.
pub(crate) fn utilization(value: Option<u32>) -> String {
    value.map_or_else(|| "-".to_string(), |value| format!("{value}%"))
}

/// A unit list as one cell; an empty list is `-`.
pub(crate) fn joined(units: &[String]) -> String {
    if units.is_empty() {
        "-".to_string()
    } else {
        units.join(", ")
    }
}