tix-tracker 0.12.0

//! The stable-ID template registry: model, scopes, references and atomic
//! persistence (`[issue_templates.<id>]` in `tix.toml`).
//!
//! Everything here is **data**. A template carries normal create defaults, an
//! ordered list of structured prompts, and typed references to labels,
//! assignees, files, cycles, milestones, or relation kinds. None of it is
//! executable, and none of it is interpreted as an action (C-004).
//!
//! # Identity
//!
//! The map key is the **immutable stable ID**; [`Template::name`] is a mutable
//! display label. A rename changes only the label, so selection by ID keeps
//! scope, defaults, prompts and references intact (C-002).
//!
//! # Scope
//!
//! [`TemplateScope`] is an explicit `repository`, `board:<name>` or
//! `team:<label>` selection with **no implicit inheritance** (C-003). A board or
//! team scope that names something the config does not define is a field-aware
//! validation error.
//!
//! # Persistence
//!
//! The registry is a `[issue_templates]` table in `tix.toml`, omitted when
//! empty, ordered by declaration, and written through the existing atomic
//! [`crate::config::Config::save`]. Unknown metadata is captured in
//! [`TemplateMetadata`] and round-trips byte-stably (C-006); an absent registry
//! is valid and gains no section on save.

use std::collections::HashSet;
use std::fmt;
use std::str::FromStr;

use indexmap::IndexMap;
use serde::{Deserialize, Serialize};

use crate::config::Config;
use crate::error::{Result, TixError};
use crate::relationships::RelationKind;

/// The create-request fields a template default or prompt may target.
///
/// Exactly the parameters the shared [`crate::commands::create::create`] core
/// accepts, so a template can never introduce a field the normal create path
/// does not understand — that would be a second issue schema (C-004/C-008).
pub const CREATE_FIELDS: &[&str] = &[
    "title",
    "body",
    "status",
    "priority",
    "assignee",
    "labels",
    "files",
    "estimate",
    "cycles",
    "milestones",
    "reviewer",
    "start_date",
    "due_date",
    "parent",
    "related_issues",
    "type",
];

/// The picker/registry sources a `select`/`multi-select` prompt may reference.
///
/// These name existing registries and built-in vocabularies, never a new one;
/// a prompt that needs choices it cannot name is the escalation the contract
/// calls out, not something to invent here.
pub const OPTIONS_SOURCES: &[&str] = &[
    "statuses",
    "priorities",
    "labels",
    "assignees",
    "cycles",
    "milestones",
];

/// Whether a scope is the repository-wide one, for `skip_serializing_if`.
///
/// The repository scope is the default, so a config that means "everywhere"
/// writes no `scope` key and a legacy-shaped file stays quiet.
fn is_repository_scope(scope: &TemplateScope) -> bool {
    scope.is_repository()
}

/// `skip_serializing_if` for a boolean whose default is `false`: only an
/// explicit `true` is written.
#[allow(clippy::trivially_copy_pass_by_ref)] // serde requires `fn(&bool) -> bool`
fn is_false(value: &bool) -> bool {
    !*value
}

/// Build a field-aware config error naming `issue_templates.<id>.<field>`.
fn field_error(id: &str, field: &str, message: impl fmt::Display) -> TixError {
    TixError::Config(format!("`issue_templates.{id}.{field}` {message}"))
}

/// Validate a stable template ID: a non-blank handle that can be a TOML table
/// key without quoting and that [`super::registry`] order restoration can parse
/// (no dots, no whitespace, no quotes).
fn validate_id(id: &str) -> Result<()> {
    if id.trim().is_empty() {
        return Err(TixError::Config("a template id must not be blank".into()));
    }
    if !id
        .chars()
        .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_')
    {
        return Err(TixError::Config(format!(
            "template id `{id}` must be a stable handle of ASCII letters, digits, `-` or `_`"
        )));
    }
    Ok(())
}

// ---------------------------------------------------------------------------
// T001 — stable ID/name/scope model
// ---------------------------------------------------------------------------

/// The kind of an explicit template scope.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub enum TemplateScopeKind {
    /// Applies repository-wide (the default).
    #[default]
    Repository,
    /// Applies to one named board configuration.
    Board,
    /// Applies to one named team.
    Team,
}

impl fmt::Display for TemplateScopeKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(match self {
            TemplateScopeKind::Repository => "repository",
            TemplateScopeKind::Board => "board",
            TemplateScopeKind::Team => "team",
        })
    }
}

impl FromStr for TemplateScopeKind {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "repository" => Ok(TemplateScopeKind::Repository),
            "board" => Ok(TemplateScopeKind::Board),
            "team" => Ok(TemplateScopeKind::Team),
            other => Err(format!(
                "unknown scope kind `{other}`; expected `repository`, `board:<name>` or `team:<label>`"
            )),
        }
    }
}

/// An explicit template scope: repository, board or team, with no inheritance.
///
/// Serialized as one string — `repository`, `board:<name>`, `team:<label>` — so
/// a config reads declaratively and the CLI can accept the same spelling. The
/// kind and qualifier are kept apart in memory so validation can name the exact
/// problem (`scope` with no qualifier vs. a qualifier that names nothing).
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct TemplateScope {
    kind: TemplateScopeKind,
    qualifier: Option<String>,
}

impl TemplateScope {
    /// The repository-wide scope (the default; writes no `scope` key).
    #[must_use]
    pub fn repository() -> Self {
        Self {
            kind: TemplateScopeKind::Repository,
            qualifier: None,
        }
    }

    /// A board-scoped template.
    #[must_use]
    pub fn board(name: impl Into<String>) -> Self {
        Self {
            kind: TemplateScopeKind::Board,
            qualifier: Some(name.into()),
        }
    }

    /// A team-scoped template.
    #[must_use]
    pub fn team(label: impl Into<String>) -> Self {
        Self {
            kind: TemplateScopeKind::Team,
            qualifier: Some(label.into()),
        }
    }

    /// The scope kind.
    #[must_use]
    pub fn kind(&self) -> TemplateScopeKind {
        self.kind
    }

    /// The board name or team label, absent for the repository scope.
    #[must_use]
    pub fn qualifier(&self) -> Option<&str> {
        self.qualifier.as_deref()
    }

    /// Whether this is the repository-wide scope.
    #[must_use]
    pub fn is_repository(&self) -> bool {
        self.kind == TemplateScopeKind::Repository
    }

    /// Validate the scope against the config's board and team registries.
    ///
    /// Existence is checked here rather than at resolution time because a scope
    /// is a *binding*: a template pointed at a board that does not exist can
    /// never be selected, and catching it at load names the exact key.
    fn validate(&self, id: &str, config: &Config) -> Result<()> {
        let qualifier = match self.kind {
            TemplateScopeKind::Repository => return Ok(()),
            TemplateScopeKind::Board => self.qualifier.as_deref().unwrap_or_default(),
            TemplateScopeKind::Team => self.qualifier.as_deref().unwrap_or_default(),
        };
        if qualifier.trim().is_empty() {
            let expected = match self.kind {
                TemplateScopeKind::Team => "team:<label>",
                _ => "board:<name>",
            };
            return Err(field_error(
                id,
                "scope",
                format!("must name its {} scope as `{expected}`", self.kind),
            ));
        }
        match self.kind {
            TemplateScopeKind::Board if !config.kanban.configurations.contains_key(qualifier) => {
                Err(field_error(
                    id,
                    "scope",
                    format!("references unknown board `{qualifier}`"),
                ))
            }
            TemplateScopeKind::Team if !config.teams.contains_key(qualifier) => Err(field_error(
                id,
                "scope",
                format!("references unknown team `{qualifier}`"),
            )),
            _ => Ok(()),
        }
    }
}

impl fmt::Display for TemplateScope {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match (self.kind, self.qualifier.as_deref()) {
            (TemplateScopeKind::Board, Some(name)) => write!(f, "board:{name}"),
            (TemplateScopeKind::Team, Some(label)) => write!(f, "team:{label}"),
            (kind, _) => write!(f, "{kind}"),
        }
    }
}

impl FromStr for TemplateScope {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let (kind, qualifier) = match s.split_once(':') {
            Some((kind, qualifier)) => (kind, Some(qualifier)),
            None => (s, None),
        };
        match kind {
            "repository" => Ok(TemplateScope::repository()),
            "board" => Ok(Self {
                kind: TemplateScopeKind::Board,
                qualifier: qualifier.map(str::trim).map(str::to_string),
            }),
            "team" => Ok(Self {
                kind: TemplateScopeKind::Team,
                qualifier: qualifier.map(str::trim).map(str::to_string),
            }),
            other => Err(format!(
                "unknown scope `{s}` (kind `{other}`); expected `repository`, `board:<name>` or `team:<label>`"
            )),
        }
    }
}

impl Serialize for TemplateScope {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(&self.to_string())
    }
}

impl<'de> Deserialize<'de> for TemplateScope {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        String::deserialize(deserializer)?
            .parse()
            .map_err(serde::de::Error::custom)
    }
}

// ---------------------------------------------------------------------------
// T002 — defaults, prompts and typed references
// ---------------------------------------------------------------------------

/// Normal create-request defaults applied before user input.
///
/// Every field is a normal create field (see [`CREATE_FIELDS`]); the struct
/// denies unknown keys so a typo is a load error naming the field rather than a
/// default that silently does nothing. A blank value is refused for the same
/// reason the form filters blanks: a template that "sets" an empty value sets
/// nothing.
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct TemplateDefaults {
    /// Pre-filled title.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    /// Pre-filled issue body (Markdown).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub body: Option<String>,
    /// Pre-filled status column.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub status: Option<String>,
    /// Pre-filled priority.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub priority: Option<String>,
    /// Pre-filled assignee.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub assignee: Option<String>,
    /// Pre-filled labels.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub labels: Vec<String>,
    /// Pre-filled attached files.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub files: Vec<String>,
    /// Pre-filled estimate.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub estimate: Option<String>,
    /// Pre-filled cycles.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub cycles: Vec<String>,
    /// Pre-filled milestones.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub milestones: Vec<String>,
    /// Pre-filled reviewer.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reviewer: Option<String>,
    /// Pre-filled start date (`YYYY-MM-DD`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub start_date: Option<String>,
    /// Pre-filled due date (`YYYY-MM-DD`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub due_date: Option<String>,
    /// Pre-filled decomposition parent selector.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub parent: Option<String>,
    /// Pre-filled cross-repository references.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub related_issues: Vec<String>,
    /// Pre-filled issue type. Stored under the TOML key `type`.
    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
    pub type_: Option<String>,
}

impl TemplateDefaults {
    /// Whether nothing is defaulted, for `skip_serializing_if`.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        *self == Self::default()
    }
}

/// The data type of a structured prompt. A type, never a behavior.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum PromptKind {
    /// Single-line free text.
    #[default]
    Text,
    /// One choice from a named registry source.
    Select,
    /// Zero or more choices from a named registry source.
    MultiSelect,
    /// A `YYYY-MM-DD` calendar date.
    Date,
}

/// A structured prompt: a named input field with a declared type/requiredness.
///
/// `key` must be a create field ([`CREATE_FIELDS`]) so the answer can be merged
/// into a normal create request. `options_ref`, when present, names an existing
/// registry or built-in vocabulary ([`OPTIONS_SOURCES`]). A prompt is data — it
/// can never carry a command, script, or arbitrary behavior (C-004).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TemplatePrompt {
    /// Stable field key; maps to a normal create/form field.
    pub key: String,
    /// Display label (falls back to `key` in a UI).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub label: Option<String>,
    /// Input type.
    pub kind: PromptKind,
    /// Whether a value must be present before an issue is written.
    #[serde(default, skip_serializing_if = "is_false")]
    pub required: bool,
    /// Optional default merged before user input.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub default: Option<String>,
    /// Optional choice source for `select`/`multi-select`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub options_ref: Option<String>,
}

/// The kind of a typed reference.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ReferenceKind {
    /// A label (free-form under the current model).
    Label,
    /// An assignee identity.
    Assignee,
    /// An attached file path.
    File,
    /// A named cycle.
    Cycle,
    /// A named milestone.
    Milestone,
    /// A typed relation kind (the closed [`RelationKind`] vocabulary).
    Relationship,
}

impl ReferenceKind {
    /// Validate a reference's *value* against the existing model vocabulary.
    ///
    /// Labels, assignees and files are free-form under the current model
    /// (research R5), so only blankness is refused for them. A relationship
    /// reference must name a kind from the closed [`RelationKind`] set.
    fn validate_value(self, id: &str, index: usize, value: &str) -> Result<()> {
        let path = format!("references[{index}].value");
        if value.trim().is_empty() {
            return Err(field_error(id, &path, "must not be blank"));
        }
        if self == ReferenceKind::Relationship && RelationKind::from_str(value).is_err() {
            let kinds: Vec<&str> = RelationKind::ALL.iter().map(|k| k.as_str()).collect();
            return Err(field_error(
                id,
                &path,
                format!(
                    "`{value}` is not a relation kind; expected one of {}",
                    kinds.join(", ")
                ),
            ));
        }
        Ok(())
    }
}

/// A typed reference a template declares before creation.
///
/// References name existing registries/model vocabulary; a template never
/// defines a second relationship schema.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TemplateReference {
    /// The reference kind.
    pub kind: ReferenceKind,
    /// The referenced value (label, identity, path, name, or relation kind).
    pub value: String,
    /// Whether absence rejects resolution.
    #[serde(default, skip_serializing_if = "is_false")]
    pub required: bool,
}

// ---------------------------------------------------------------------------
// T003 — unknown metadata representation
// ---------------------------------------------------------------------------

/// Preserved unknown metadata: a data-only extension area.
///
/// Anything under `[issue_templates.<id>]` the current schema does not know
/// lands here and round-trips verbatim. It is never interpreted as a default,
/// prompt, reference, command, or issue field (C-006/C-004).
///
/// Compared by its canonical serialization because [`toml::Value`] carries
/// `f64` and so is not `Eq`; two extension areas are the same data exactly when
/// they serialize to the same TOML.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(transparent)]
pub struct TemplateMetadata(toml::Table);

impl TemplateMetadata {
    /// Whether no unknown metadata is present.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }

    /// The number of preserved keys.
    #[must_use]
    pub fn len(&self) -> usize {
        self.0.len()
    }

    /// Look up a preserved key.
    #[must_use]
    pub fn get(&self, key: &str) -> Option<&toml::Value> {
        self.0.get(key)
    }

    /// Iterate the preserved `(key, value)` pairs in canonical order.
    pub fn iter(&self) -> impl Iterator<Item = (&str, &toml::Value)> {
        self.0.iter().map(|(k, v)| (k.as_str(), v))
    }

    /// The underlying table, for a caller that must serialize it whole.
    #[must_use]
    pub fn table(&self) -> &toml::Table {
        &self.0
    }
}

impl PartialEq for TemplateMetadata {
    fn eq(&self, other: &Self) -> bool {
        toml::Value::Table(self.0.clone()).to_string()
            == toml::Value::Table(other.0.clone()).to_string()
    }
}

impl Eq for TemplateMetadata {}

impl From<toml::Table> for TemplateMetadata {
    fn from(table: toml::Table) -> Self {
        Self(table)
    }
}

// ---------------------------------------------------------------------------
// The template record
// ---------------------------------------------------------------------------

/// One template: a stable ID (the registry key), a display name, a scope,
/// defaults, ordered prompts, typed references, and preserved metadata.
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(default)]
pub struct Template {
    /// Mutable display label. Not identity: rename leaves the ID untouched.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Explicit scope; repository is the default and writes no key.
    #[serde(skip_serializing_if = "is_repository_scope")]
    pub scope: TemplateScope,
    /// Normal create-request defaults.
    #[serde(skip_serializing_if = "TemplateDefaults::is_empty")]
    pub defaults: TemplateDefaults,
    /// Ordered structured prompts.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub prompts: Vec<TemplatePrompt>,
    /// Typed references.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub references: Vec<TemplateReference>,
    /// Unknown metadata, preserved verbatim.
    #[serde(flatten)]
    pub extensions: TemplateMetadata,
}

impl Template {
    /// The display label, falling back to the stable ID when no name is set.
    #[must_use]
    pub fn display_name<'a>(&'a self, id: &'a str) -> &'a str {
        self.name.as_deref().unwrap_or(id)
    }

    /// Validate this template's structure against `config`.
    ///
    /// Checks the name, the scope binding, the prompt shape, the defaults, and
    /// the reference kinds. A failure is a field-aware
    /// `issue_templates.<id>.<field>` error and means **no issue is created**
    /// (C-005).
    pub fn validate(&self, id: &str, config: &Config) -> Result<()> {
        validate_id(id)?;
        if let Some(name) = &self.name
            && name.trim().is_empty()
        {
            return Err(field_error(id, "name", "must not be blank when present"));
        }
        self.scope.validate(id, config)?;
        validate_defaults(id, &self.defaults)?;
        validate_prompts(id, &self.prompts)?;
        for (index, reference) in self.references.iter().enumerate() {
            reference.kind.validate_value(id, index, &reference.value)?;
        }
        Ok(())
    }
}

/// Validate a defaults block: no blank value, and parseable dates.
fn validate_defaults(id: &str, defaults: &TemplateDefaults) -> Result<()> {
    for (field, value) in [
        ("title", &defaults.title),
        ("body", &defaults.body),
        ("status", &defaults.status),
        ("priority", &defaults.priority),
        ("assignee", &defaults.assignee),
        ("estimate", &defaults.estimate),
        ("reviewer", &defaults.reviewer),
        ("parent", &defaults.parent),
        ("type", &defaults.type_),
    ] {
        if let Some(value) = value
            && value.trim().is_empty()
        {
            return Err(field_error(
                id,
                &format!("defaults.{field}"),
                "must not be blank when present",
            ));
        }
    }
    for (field, values) in [
        ("labels", &defaults.labels),
        ("files", &defaults.files),
        ("cycles", &defaults.cycles),
        ("milestones", &defaults.milestones),
        ("related_issues", &defaults.related_issues),
    ] {
        for value in values {
            if value.trim().is_empty() {
                return Err(field_error(
                    id,
                    &format!("defaults.{field}"),
                    "must not contain a blank value",
                ));
            }
        }
    }
    for (field, value) in [
        ("start_date", &defaults.start_date),
        ("due_date", &defaults.due_date),
    ] {
        if let Some(value) = value
            && !crate::model::validate_date(value)
        {
            return Err(field_error(
                id,
                &format!("defaults.{field}"),
                format!("`{value}` must be a `YYYY-MM-DD` calendar date"),
            ));
        }
    }
    Ok(())
}

/// Validate ordered prompts: known create field, unique, well-shaped.
fn validate_prompts(id: &str, prompts: &[TemplatePrompt]) -> Result<()> {
    let mut seen: HashSet<&str> = HashSet::new();
    for (index, prompt) in prompts.iter().enumerate() {
        let key_path = format!("prompts[{index}].key");
        if prompt.key.trim().is_empty() {
            return Err(field_error(id, &key_path, "must not be blank"));
        }
        if !CREATE_FIELDS.contains(&prompt.key.as_str()) {
            return Err(field_error(
                id,
                &key_path,
                format!(
                    "`{}` is not a create field; expected one of {}",
                    prompt.key,
                    CREATE_FIELDS.join(", ")
                ),
            ));
        }
        if !seen.insert(prompt.key.as_str()) {
            return Err(field_error(
                id,
                &key_path,
                format!("duplicates the prompt for `{}`", prompt.key),
            ));
        }
        if let Some(label) = &prompt.label
            && label.trim().is_empty()
        {
            return Err(field_error(
                id,
                &format!("prompts[{index}].label"),
                "must not be blank when present",
            ));
        }
        if let Some(options) = &prompt.options_ref {
            if options.trim().is_empty() {
                return Err(field_error(
                    id,
                    &format!("prompts[{index}].options_ref"),
                    "must not be blank when present",
                ));
            }
            if !OPTIONS_SOURCES.contains(&options.as_str()) {
                return Err(field_error(
                    id,
                    &format!("prompts[{index}].options_ref"),
                    format!(
                        "`{options}` is not a known options source; expected one of {}",
                        OPTIONS_SOURCES.join(", ")
                    ),
                ));
            }
        }
        if let Some(default) = &prompt.default {
            if default.trim().is_empty() {
                return Err(field_error(
                    id,
                    &format!("prompts[{index}].default"),
                    "must not be blank when present",
                ));
            }
            if prompt.kind == PromptKind::Date && !crate::model::validate_date(default) {
                return Err(field_error(
                    id,
                    &format!("prompts[{index}].default"),
                    format!("`{default}` must be a `YYYY-MM-DD` calendar date"),
                ));
            }
        }
    }
    Ok(())
}

// ---------------------------------------------------------------------------
// T004 — registry persistence
// ---------------------------------------------------------------------------

/// The stable-ID template registry, keyed by immutable ID in declaration order.
///
/// Serialized transparently as `[issue_templates.<id>]`. An empty registry
/// writes no section, so a project with no templates keeps `tix.toml`
/// unchanged, and a legacy config without one loads as empty (C-006).
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(default, transparent)]
pub struct TemplateRegistry {
    /// Templates by stable ID, in declaration/display order.
    pub templates: IndexMap<String, Template>,
}

impl TemplateRegistry {
    /// Whether the registry holds no templates, for `skip_serializing_if`.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.templates.is_empty()
    }

    /// The number of templates.
    #[must_use]
    pub fn len(&self) -> usize {
        self.templates.len()
    }

    /// Whether an ID is present.
    #[must_use]
    pub fn contains(&self, id: &str) -> bool {
        self.templates.contains_key(id)
    }

    /// Look up a template by stable ID.
    #[must_use]
    pub fn get(&self, id: &str) -> Option<&Template> {
        self.templates.get(id)
    }

    /// Mutably look up a template by stable ID (used by update operations).
    pub fn get_mut(&mut self, id: &str) -> Option<&mut Template> {
        self.templates.get_mut(id)
    }

    /// The stable IDs in declaration order.
    pub fn ids(&self) -> impl Iterator<Item = &str> {
        self.templates.keys().map(String::as_str)
    }

    /// The `(id, template)` pairs in declaration order.
    pub fn iter(&self) -> impl Iterator<Item = (&str, &Template)> {
        self.templates.iter().map(|(id, t)| (id.as_str(), t))
    }

    /// Insert a new template under `id`, refusing a blank/malformed or
    /// duplicate ID and leaving the registry untouched on refusal.
    ///
    /// This checks identity only; run [`Self::validate`] before saving so the
    /// whole registry is structurally sound (C-006, "structural validation
    /// before the existing atomic save").
    pub fn insert(&mut self, id: impl Into<String>, template: Template) -> Result<()> {
        let id = id.into();
        validate_id(&id)?;
        if self.templates.contains_key(&id) {
            return Err(TixError::Config(format!(
                "a template with id `{id}` already exists"
            )));
        }
        self.templates.insert(id, template);
        Ok(())
    }

    /// Remove the definition for `id`, if present, returning it.
    ///
    /// Remove is definition-only: issues created from the template are never
    /// touched (the registry stores no issue state).
    pub fn remove(&mut self, id: &str) -> Option<Template> {
        self.templates.shift_remove(id)
    }

    /// Validate every template against `config`, in declaration order.
    ///
    /// A failure is a field-aware error and means **nothing is written**; an
    /// empty registry is always valid.
    pub fn validate(&self, config: &Config) -> Result<()> {
        for (id, template) in &self.templates {
            template.validate(id, config)?;
        }
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    #[allow(clippy::wildcard_imports)]
    use super::*;

    fn prompt(key: &str, kind: PromptKind) -> TemplatePrompt {
        TemplatePrompt {
            key: key.to_string(),
            label: None,
            kind,
            required: false,
            default: None,
            options_ref: None,
        }
    }

    #[test]
    fn a_rename_keeps_the_stable_id() {
        let mut registry = TemplateRegistry::default();
        registry
            .insert(
                "bug",
                Template {
                    name: Some("Bug report".to_string()),
                    defaults: TemplateDefaults {
                        labels: vec!["bug".to_string()],
                        ..TemplateDefaults::default()
                    },
                    prompts: vec![prompt("priority", PromptKind::Select)],
                    ..Template::default()
                },
            )
            .unwrap();

        // The display name is a label; changing it does not touch identity.
        registry.get_mut("bug").unwrap().name = Some("Incident report".to_string());

        let bug = registry
            .get("bug")
            .expect("the stable ID survives a rename");
        assert_eq!(bug.display_name("bug"), "Incident report");
        assert_eq!(bug.defaults.labels, ["bug".to_string()]);
        assert_eq!(bug.prompts[0].key, "priority");
        assert_eq!(registry.ids().collect::<Vec<_>>(), ["bug"]);
    }

    #[test]
    fn every_scope_kind_parses_and_round_trips() {
        for (text, kind) in [
            ("repository", TemplateScopeKind::Repository),
            ("board:default", TemplateScopeKind::Board),
            ("team:core", TemplateScopeKind::Team),
        ] {
            let scope = TemplateScope::from_str(text).unwrap();
            assert_eq!(scope.kind(), kind, "{text}");
            assert_eq!(scope.to_string(), text, "{text}");
        }
        assert!(!TemplateScope::from_str("board").unwrap().is_repository());
        assert!(TemplateScope::from_str("sparkles").is_err());
    }

    #[test]
    fn a_known_board_scope_validates() {
        let config = Config::default();
        assert!(config.kanban.configurations.contains_key("default"));
        let template = Template {
            scope: TemplateScope::board("default"),
            ..Template::default()
        };
        template.validate("bug", &config).unwrap();
    }

    #[test]
    fn an_unknown_board_scope_is_rejected() {
        let err = Template {
            scope: TemplateScope::board("no-such-board"),
            ..Template::default()
        }
        .validate("bug", &Config::default())
        .unwrap_err()
        .to_string();
        assert!(err.contains("issue_templates.bug.scope"), "{err}");
        assert!(err.contains("unknown board `no-such-board`"), "{err}");
    }

    #[test]
    fn an_unknown_team_scope_is_rejected() {
        let config = Config::default();
        let template = Template {
            scope: TemplateScope::team("core"),
            ..Template::default()
        };
        let err = template.validate("bug", &config).unwrap_err().to_string();
        assert!(err.contains("unknown team `core`"), "{err}");

        // A team the config defines is accepted.
        let mut with_team = config;
        with_team.teams.insert(
            "core".to_string(),
            crate::config::Team {
                members: vec!["ada".to_string()],
            },
        );
        template.validate("bug", &with_team).unwrap();
    }

    #[test]
    fn a_scope_without_a_qualifier_is_rejected() {
        let config = Config::default();
        for text in ["board", "team", "board:   ", "team:"] {
            let scope = TemplateScope::from_str(text).unwrap();
            let template = Template {
                scope,
                ..Template::default()
            };
            let err = template.validate("bug", &config).unwrap_err().to_string();
            assert!(err.contains("must name its"), "{text}: {err}");
        }
    }

    #[test]
    fn a_duplicate_or_malformed_id_is_refused_without_mutating() {
        let mut registry = TemplateRegistry::default();
        registry.insert("bug", Template::default()).unwrap();

        let err = registry
            .insert("bug", Template::default())
            .unwrap_err()
            .to_string();
        assert!(err.contains("already exists"), "{err}");

        for bad in ["", "   ", "has space", "has.dot", "quoted\""] {
            assert!(
                registry.insert(bad, Template::default()).is_err(),
                "{bad:?}"
            );
        }
        assert_eq!(registry.len(), 1);
        assert!(registry.contains("bug"));
    }

    #[test]
    fn remove_is_definition_only() {
        let mut registry = TemplateRegistry::default();
        registry.insert("bug", Template::default()).unwrap();
        assert!(registry.remove("bug").is_some());
        assert!(registry.is_empty());
        // Removing an absent ID is a no-op, not an error.
        assert!(registry.remove("bug").is_none());
    }

    #[test]
    fn prompts_and_references_round_trip_in_order() {
        let mut registry = TemplateRegistry::default();
        registry
            .insert(
                "bug",
                Template {
                    name: Some("Bug report".to_string()),
                    prompts: vec![
                        prompt("priority", PromptKind::Select),
                        prompt("labels", PromptKind::MultiSelect),
                        prompt("title", PromptKind::Text),
                    ],
                    references: vec![
                        TemplateReference {
                            kind: ReferenceKind::Label,
                            value: "bug".to_string(),
                            required: true,
                        },
                        TemplateReference {
                            kind: ReferenceKind::Cycle,
                            value: "Cycle 1".to_string(),
                            required: false,
                        },
                    ],
                    ..Template::default()
                },
            )
            .unwrap();

        let text = toml::to_string_pretty(&registry).unwrap();
        let back: TemplateRegistry = toml::from_str(&text).unwrap();
        assert_eq!(back, registry);
        let bug = back.get("bug").unwrap();
        assert_eq!(
            bug.prompts
                .iter()
                .map(|p| p.key.as_str())
                .collect::<Vec<_>>(),
            ["priority", "labels", "title"],
            "prompt order is data"
        );
        assert_eq!(
            bug.references.iter().map(|r| r.kind).collect::<Vec<_>>(),
            [ReferenceKind::Label, ReferenceKind::Cycle]
        );
        assert!(bug.references[0].required);
        assert!(!bug.references[1].required);
    }

    #[test]
    fn an_unknown_prompt_key_is_rejected() {
        let config = Config::default();
        let ok = Template {
            prompts: vec![prompt("priority", PromptKind::Select)],
            ..Template::default()
        };
        ok.validate("bug", &config).unwrap();

        let err = Template {
            prompts: vec![prompt("sparkles", PromptKind::Text)],
            ..Template::default()
        }
        .validate("bug", &config)
        .unwrap_err()
        .to_string();
        assert!(err.contains("issue_templates.bug.prompts[0].key"), "{err}");
        assert!(err.contains("is not a create field"), "{err}");
    }

    #[test]
    fn a_duplicate_prompt_key_is_rejected() {
        let err = Template {
            prompts: vec![
                prompt("priority", PromptKind::Select),
                prompt("priority", PromptKind::Text),
            ],
            ..Template::default()
        }
        .validate("bug", &Config::default())
        .unwrap_err()
        .to_string();
        assert!(err.contains("duplicates the prompt"), "{err}");
    }

    #[test]
    fn an_unknown_options_source_is_rejected() {
        let template = Template {
            prompts: vec![TemplatePrompt {
                options_ref: Some("sparkles".to_string()),
                ..prompt("status", PromptKind::Select)
            }],
            ..Template::default()
        };
        let err = template
            .validate("bug", &Config::default())
            .unwrap_err()
            .to_string();
        assert!(err.contains("is not a known options source"), "{err}");
    }

    #[test]
    fn dates_in_defaults_and_prompts_are_validated() {
        let bad_default = Template {
            defaults: TemplateDefaults {
                due_date: Some("not-a-date".to_string()),
                ..TemplateDefaults::default()
            },
            ..Template::default()
        };
        assert!(
            bad_default
                .validate("bug", &Config::default())
                .unwrap_err()
                .to_string()
                .contains("defaults.due_date")
        );

        let bad_prompt = Template {
            prompts: vec![TemplatePrompt {
                kind: PromptKind::Date,
                default: Some("2026-13-40".to_string()),
                ..prompt("due_date", PromptKind::Date)
            }],
            ..Template::default()
        };
        assert!(
            bad_prompt
                .validate("bug", &Config::default())
                .unwrap_err()
                .to_string()
                .contains("YYYY-MM-DD")
        );
    }

    #[test]
    fn a_relationship_reference_must_name_a_relation_kind() {
        let config = Config::default();
        let ok = Template {
            references: vec![TemplateReference {
                kind: ReferenceKind::Relationship,
                value: "blocks".to_string(),
                required: false,
            }],
            ..Template::default()
        };
        ok.validate("bug", &config).unwrap();

        // Labels are free-form under the current model, so any non-blank value
        // is accepted.
        Template {
            references: vec![TemplateReference {
                kind: ReferenceKind::Label,
                value: "whatever-this-project-uses".to_string(),
                required: false,
            }],
            ..Template::default()
        }
        .validate("bug", &config)
        .unwrap();

        let err = Template {
            references: vec![TemplateReference {
                kind: ReferenceKind::Relationship,
                value: "sparkles".to_string(),
                required: false,
            }],
            ..Template::default()
        }
        .validate("bug", &config)
        .unwrap_err()
        .to_string();
        assert!(err.contains("is not a relation kind"), "{err}");
    }

    #[test]
    fn unknown_metadata_survives_a_round_trip() {
        let text =
            "[bug]\nname = \"Bug report\"\ncustom_field = \"keep me\"\n\n[bug.future]\nlevel = 3\n";
        let registry: TemplateRegistry = toml::from_str(text).unwrap();
        let bug = registry.get("bug").unwrap();
        assert_eq!(
            bug.extensions
                .get("custom_field")
                .and_then(toml::Value::as_str),
            Some("keep me")
        );
        assert!(bug.extensions.get("future").is_some());

        let serialized = toml::to_string_pretty(&registry).unwrap();
        let back: TemplateRegistry = toml::from_str(&serialized).unwrap();
        assert_eq!(back, registry, "unknown metadata survives a round trip");
        assert_eq!(toml::to_string_pretty(&back).unwrap(), serialized);
    }

    #[test]
    fn an_unknown_default_field_is_diagnosed() {
        let text = "[bug]\nname = \"Bug\"\n\n[bug.defaults]\nlabes = [\"typo\"]\n";
        let err = toml::from_str::<TemplateRegistry>(text)
            .unwrap_err()
            .to_string();
        assert!(err.contains("unknown field"), "{err}");
    }
}